P2P Off-ramp
Local money out through P2P buyers: the market, a firm quote, and sale sessions that open a hosted sale the seller sends the stablecoin from.
The currencies a seller can be paid in on the key's network (a prod key reads mainnet, a dev key the sandbox), each with its payment methods, sell price (local money per USD stablecoin) and minimum (in USD), plus the chains a sale can send from (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 offramp: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/offramp/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 offramp: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/offramp/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 sale of amount of the token sent from address on chainId: the local money paid with fees taken, the least it can pay, the rate and the fees, valid until expiresAt. Nothing is stored. The order is checked against the market first (currency, payment method, token 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 offramp: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/offramp/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 sales 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 offramp: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/offramp/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 sale that takes it: open it in a browser tab or window, where the seller signs in, verifies their identity, connects the wallet holding the token and sends it, and a P2P buyer pays the local money with the chosen method. address is recorded as the account it is sent from; the widget does not fix it. estimatedAmountOut is the local money at the market price, rounded down (null for a token with no USD price); the widget quotes the firm figure first. The order is checked against the market (400 validation_failed with the reason), and opened on the key's network.
Requires the offramp: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/offramp/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 sale 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 purchase, is the 404 of a missing one.
Requires the offramp: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/offramp/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"}