P2P On-ramp
Local money in through P2P sellers: the market, a firm quote, and purchase sessions that open a hosted purchase delivered to the address you name.
The currencies a buyer can pay with on the key's network (a prod key reads mainnet, a dev key the sandbox), each with its payment methods, buy price (local money per USD stablecoin) and minimum, plus the chains a purchase can deliver on (each with its token count) and the token a form starts from. Read from the P2P marketplace and served from memory for up to a minute; a currency without a price, a minimum or a payment method is left out, and so is a chain whose token list cannot be read right now.
Requires the onramp:read scope. The shared public key may call it.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
OK
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/onramp/p2p/market'{ "currencies": [ { "id": "ARS", "name": "Argentine Pesos", "price": "1677.89", "minAmount": "8389.45", "paymentMethods": [ { "id": "bank_tx_ar", "name": "Bank Transfer (ARS)" } ] } ], "networks": [ { "chainId": 42161, "name": "Arbitrum", "tokenCount": 2768 } ], "defaultToken": { "chainId": 42161, "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "symbol": "USDT0", "decimals": 6 }}One chain of the market (chainId, one of its networks), a page at a time: each token with its contract address, symbol, decimals and USD price. The network’s main assets come first, matched by address (its own coin, its USD stablecoins, the wrapped coin, bitcoin, its token, other stablecoins, DeFi blue chips, liquid staked ether), then every other token in the marketplace’s order. q searches by symbol fragment or exact address. A chain the market does not offer right now is 400 validation_failed.
Requires the onramp:read scope. The shared public key may call it.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
take?numberPage size: how many tokens to return (1 to 200).
1 <= value <= 200100skip?numberHow many items to skip before this page (offset).
0 <= value0chainId*numberEIP-155 id of the chain: a chainId of the market’s networks.
q?stringA symbol fragment (any case) or a token contract address (exact, any case).
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/onramp/p2p/tokens?chainId=42161'{ "data": [ { "chainId": 42161, "address": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "symbol": "USDT0", "decimals": 6, "priceUsd": "0.9975", "logoUrl": "https://static.debank.com/image/arb_token/logo_url/0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9/logo.png", "main": true } ], "total": 2768, "take": 100, "skip": 0}The P2P marketplace prices the order: the token delivered on chainId with fees and the swap taken, the least it can deliver, the rate and the fees, valid until expiresAt. Nothing is stored. The order is checked against the market first (currency, payment method, chain, token, decimals and minimum: 400 validation_failed with the reason). A deployment without the marketplace integrator ids answers 503 misconfigured; the market and the sessions work without them.
Requires the onramp:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- body
An order on the P2P marketplace. On /v1/onramp/p2p a purchase: the local money paid, how, the token bought on its chain and where it is delivered. On /v1/offramp/p2p a sale: the token sold on its chain, the account it is sent from, and the local money received and how.
currency*stringLocal currency paid (purchase) or received (sale): an id from the market of the same route, GET /v1/onramp/p2p/market or GET /v1/offramp/p2p/market.
paymentMethod*stringHow the local money is paid (purchase) or received (sale): one of that currency’s paymentMethods in the market.
chainId*numberEIP-155 id of the chain the token is on: a chainId of the market’s networks.
token*stringThe token bought or sold: its contract address on chainId, from GET .../tokens?chainId= of the same route (the zero address is the chain’s own coin).
amount*stringWhat the order puts in, a decimal string: the local money paid for a purchase (at most two decimals, at least the currency’s minAmount), the token sold for a sale (at most the token’s decimals, worth at least the currency’s minAmount in USD where the token has a USD price).
address*stringAn EVM account on chainId: where a purchase delivers the token, or the account a sale sends it from.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
The budget in x-cosmos-rate-limit is spent for this caller. Honour Retry-After.
The ratelimit-* triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers 503 provider_unavailable.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/onramp/p2p/quotes' \ -H 'Content-Type: application/json' \ -d '{ "currency": "ARS", "paymentMethod": "bank_tx_ar", "chainId": 42161, "token": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "amount": "50000", "address": "0x52908400098527886E0F7030069857D2E4169EE7"}'{ "quoteId": "6f1c0e1a-1b2c-4d5e-8f90-123456789abc", "currency": "ARS", "token": "USDT0", "tokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "chainId": 42161, "amountIn": "54500", "amountOut": "35.04", "minAmountOut": "34.343", "exchangeRate": "1516.5", "fee": { "amountInToken": "0.90", "amountInFiat": "1329.06" }, "expiresAt": "2026-11-05T18:05:00.000Z"}The purchases this key's consumer opened on the key's network, newest first, from this service's records (no call to the marketplace). Paginated with take (default 100, max 100) and skip; answers { data, total, take, skip }, where total counts every matching session.
Requires the onramp:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
take?numberPage size: how many items to return (1 to 100).
1 <= value <= 100100skip?numberHow many items to skip before this page (offset).
0 <= value0OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/onramp/p2p/sessions'{ "data": [ { "id": "clz9xp2p0001", "network": "public", "side": "buy", "currency": "ARS", "paymentMethod": "bank_tx_ar", "amount": "50000", "token": "USDT0", "tokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "chainId": 42161, "address": "0x52908400098527886E0F7030069857D2E4169EE7", "estimatedAmountOut": "29.79", "reference": "cp-clz9xp2p0001", "widgetUrl": "https://p2p-widget.example/exchange?operation=BUY&token=0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9&chain=42161¤cy=ARS&paymentMethod=bank_tx_ar&amount=50000&address=0x52908400098527886E0F7030069857D2E4169EE7&externalReferenceId=cp-clz9xp2p0001", "createdAt": "2026-11-05T18:00:00.000Z" } ], "total": 1, "take": 100, "skip": 0}Records the order and answers widgetUrl, the hosted purchase that takes it: open it in a browser tab or window, where the buyer signs in, verifies their identity and pays a P2P seller. address is fixed as the recipient there, so the token can only be delivered to it, on chainId. estimatedAmountOut is the market price, rounded down (null for a token with no USD price); the widget quotes the firm figure before payment. The order is checked against the market first (400 validation_failed with the reason), and opened on the key's network.
Requires the onramp:write scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
application/json- body
An order on the P2P marketplace. On /v1/onramp/p2p a purchase: the local money paid, how, the token bought on its chain and where it is delivered. On /v1/offramp/p2p a sale: the token sold on its chain, the account it is sent from, and the local money received and how.
currency*stringLocal currency paid (purchase) or received (sale): an id from the market of the same route, GET /v1/onramp/p2p/market or GET /v1/offramp/p2p/market.
paymentMethod*stringHow the local money is paid (purchase) or received (sale): one of that currency’s paymentMethods in the market.
chainId*numberEIP-155 id of the chain the token is on: a chainId of the market’s networks.
token*stringThe token bought or sold: its contract address on chainId, from GET .../tokens?chainId= of the same route (the zero address is the chain’s own coin).
amount*stringWhat the order puts in, a decimal string: the local money paid for a purchase (at most two decimals, at least the currency’s minAmount), the token sold for a sale (at most the token’s decimals, worth at least the currency’s minAmount in USD where the token has a USD price).
address*stringAn EVM account on chainId: where a purchase delivers the token, or the account a sale sends it from.
Created
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
The budget in x-cosmos-rate-limit is spent for this caller. Honour Retry-After.
The ratelimit-* triple rides along on successful responses too, so a client can pace itself instead of being refused. If the counter store itself is unreachable the guard fails closed and answers 503 provider_unavailable.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
The provider named in x-cosmos-upstream refused the request (provider_error) or could not be reached at all (provider_unavailable). Nothing was charged; retry is safe with the same Idempotency-Key.
provider_unavailable: the provider in x-cosmos-upstream is down or unreachable; the message names it. Retry.
misconfigured: this deployment is missing configuration the route needs (a provider instance, a fee wallet, the plan header the gateway must forward). Retrying will not help; it is an operator problem.
The provider in x-cosmos-upstream did not answer in time. Whether it acted on the request is unknown. Retry with the same Idempotency-Key, never with a fresh one.
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/onramp/p2p/sessions' \ -H 'Content-Type: application/json' \ -d '{ "currency": "ARS", "paymentMethod": "bank_tx_ar", "chainId": 42161, "token": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "amount": "50000", "address": "0x52908400098527886E0F7030069857D2E4169EE7"}'{ "id": "clz9xp2p0001", "network": "public", "side": "buy", "currency": "ARS", "paymentMethod": "bank_tx_ar", "amount": "50000", "token": "USDT0", "tokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "chainId": 42161, "address": "0x52908400098527886E0F7030069857D2E4169EE7", "estimatedAmountOut": "29.79", "reference": "cp-clz9xp2p0001", "widgetUrl": "https://p2p-widget.example/exchange?operation=BUY&token=0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9&chain=42161¤cy=ARS&paymentMethod=bank_tx_ar&amount=50000&address=0x52908400098527886E0F7030069857D2E4169EE7&externalReferenceId=cp-clz9xp2p0001", "createdAt": "2026-11-05T18:00:00.000Z"}One purchase of this key's consumer on the key's network, from this service's records, with its widget URL. Another consumer's session, one opened on the other network, or a sale, is the 404 of a missing one.
Requires the onramp:read scope.
apiKeyAuthorizationBearer <API key>Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.
id*stringCosmos Pay id of the session.
OK
The body, query or path failed validation. message is an array of the individual failures.
Routes that reject a valid request for a reason of their own (an amount, a memo, a state) document the code for it on their own 400.
no_authenticated_consumer: The gateway forwarded no API key identity
insufficient_scope: the API key does not hold the scope this route requires. The shared public API key also gets this on every route that is not marked x-cosmos-public-key, with a message saying so; more scopes will not help, the key is the wrong one.
gateway_required: the request did not arrive through APISIX.
No such resource, or it exists and belongs to another consumer. The two are deliberately the same answer: "exists but not yours" is an ownership oracle.
Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/onramp/p2p/sessions/clz9xp2p0001'{ "id": "clz9xp2p0001", "network": "public", "side": "buy", "currency": "ARS", "paymentMethod": "bank_tx_ar", "amount": "50000", "token": "USDT0", "tokenAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9", "chainId": 42161, "address": "0x52908400098527886E0F7030069857D2E4169EE7", "estimatedAmountOut": "29.79", "reference": "cp-clz9xp2p0001", "widgetUrl": "https://p2p-widget.example/exchange?operation=BUY&token=0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9&chain=42161¤cy=ARS&paymentMethod=bank_tx_ar&amount=50000&address=0x52908400098527886E0F7030069857D2E4169EE7&externalReferenceId=cp-clz9xp2p0001", "createdAt": "2026-11-05T18:00:00.000Z"}