API Reference

Off-ramp

Fiat out: quotes, payout authorization, and payout tracking.

POST
/v1/offramp/quotes

Prices a payout through the fiat partner of token on network to one of your bank accounts (bank_account_id, a Cosmos Pay id) and records the quote as yours, on the fiat partner instance your key selects (a dev key uses the development instance and moves no real money). An EVM quote carries the contract whose approve the customer signs before the payout, and receiver_local_amount is filled from receiver_amount when the fiat partner sends 0. Amounts are integers in minor units. A bank account you do not own is a 404, and one whose receiver's fiat access is disabled is 403 account_disabled.

Requires the offramp:write scope.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

application/json
  1. body

A payout (stablecoin to fiat) to price to one of your bank accounts; the quote expires in about 5 minutes. Amounts are integers in minor units.

bank_account_id*string

Cosmos Pay bank account id (from POST /v1/kyc/receivers/:id/bank-accounts) that receives the fiat.

currency_type*string

Whether request_amount is what the sender sends (sender) or what the receiver receives (receiver).

Value in"sender""receiver"
cover_fees*boolean

When true, the sender absorbs fees.

request_amount*number

Amount in minor units (integer).

network*string

The fiat partner network the stablecoin is sent on.

Value in"ethereum""base""arbitrum""polygon""stellar""solana""tron""sepolia""base_sepolia""arbitrum_sepolia""polygon_amoy""stellar_testnet""solana_devnet"
token*string

Stablecoin paid out; USDB is the test token of the development instance.

Value in"USDC""USDT""USDB"
description?string

Free-text description of the payout, forwarded to the fiat partner.

partner_fee_id?string

Partner fee id, forwarded as sent.

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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/offramp/quotes' \  -H 'Content-Type: application/json' \  -d '{  "bank_account_id": "clz9xbank00001",  "currency_type": "sender",  "cover_fees": false,  "request_amount": 10000,  "network": "base",  "token": "USDC"}'
Example Response
{  "id": "qe_000000000000",  "expires_at": 1782692400,  "sender_amount": 10000,  "receiver_amount": 156129400,  "receiver_local_amount": 156129400,  "contract": {    "abi": [],    "address": "0xToken...",    "functionName": "approve",    "blindpayContractAddress": "0xSpender...",    "amount": "10000",    "network": {      "name": "base",      "chainId": 8453    }  }}
POST
/v1/offramp/payouts/authorize

Step one of a stellar or solana payout (EVM payouts skip it): the fiat partner builds the transaction sender_wallet_address signs for quote_id, returned as unsigned_transaction (Stellar XDR or Solana transaction) beside the fiat partner's own fields. Pass the signed result as signed_transaction to POST /v1/offramp/payouts; nothing is stored. A quote that is not yours, is a payin quote or was minted on the other instance is 404 quote_not_found; a lapsed one is 400 quote_expired.

Requires the offramp:write scope.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

application/json
  1. body

Step one of a Stellar or Solana payout: asks the fiat partner for the transaction the sender signs.

quote_id*string

Id of a payout quote from POST /v1/offramp/quotes.

sender_wallet_address*string

Sender wallet on the selected chain (Stellar G… or Solana base58).

chain*string

Chain the payout is sent from: stellar or solana (EVM payouts skip this step).

Value in"stellar""solana"

Created

validation_failed: The body, query or headers failed validation

quote_expired: The quote is ours and yours, but past its expiry

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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/offramp/payouts/authorize' \  -H 'Content-Type: application/json' \  -d '{  "quote_id": "qe_000000000000",  "sender_wallet_address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO",  "chain": "stellar"}'
Example Response
{  "unsigned_transaction": "AAAAAgAAAAB…"}
GET
/v1/offramp/payouts

Reads this service's mirror only (no fiat partner call), newest first, limited to your key's fiat partner instance; payouts still waiting for the fiat partner's id are left out. Paginated with take (default 100, max 100) and skip; answers { data, total, take, skip }, where total counts every matching payout.

Requires the offramp:read scope.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

take?number

Page size: how many items to return (1 to 100).

Range1 <= value <= 100
Default100
skip?number

How many items to skip before this page (offset).

Range0 <= value
Default0

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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/offramp/payouts'
Example Response
{  "data": [    {      "id": "clz9xpayout001",      "blindpayId": "pa_000000000000",      "status": "processing",      "token": "USDC",      "network": "base",      "rail": "ach",      "senderAmount": "10000",      "receiverAmount": "9900",      "senderWalletAddress": "0x1234abcd...",      "createdAt": "2026-06-28T12:00:00.000Z"    }  ],  "total": 1,  "take": 100,  "skip": 0}
POST
/v1/offramp/payouts

Executes a payout quote at the fiat partner: for evm the customer has already sent the quote's approve, for stellar and solana signed_transaction (from the authorize step) is required. Idempotent per quote: a retry of the same quote reuses its row and its fiat partner Idempotency-Key, so a quote is never paid out twice. A quote that is not yours, is a payin quote or was minted on the other instance is 404 quote_not_found; a lapsed one is 400 quote_expired. Status changes arrive later as PAYOUT_UPDATED and PAYOUT_COMPLETED webhook events.

Requires the offramp:write scope.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

application/json
  1. body

Executes a payout quote. For evm the sender has already sent the quote's approve; for stellar and solana send the signed_transaction from the authorize step.

quote_id*string

Id of a payout quote from POST /v1/offramp/quotes; a quote is paid out at most once.

sender_wallet_address*string

Sender wallet on the selected chain (EVM 0x…, Stellar G…, or Solana base58).

chain*string

Chain family the payout is sent from: evm, stellar or solana.

Value in"evm""stellar""solana"
signed_transaction?string

Required for stellar/solana: signed transaction (Stellar XDR / Solana tx) from POST /v1/offramp/payouts/authorize. Not used for evm.

Created

validation_failed: The body, query or headers failed validation

quote_expired: The quote is ours and yours, but past its expiry

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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/offramp/payouts' \  -H 'Content-Type: application/json' \  -d '{  "quote_id": "qe_000000000000",  "sender_wallet_address": "0x1234567890123456789012345678901234567890",  "chain": "evm"}'
Example Response
{  "id": "clz9xpayout001",  "blindpayId": "pa_000000000000",  "status": "processing",  "token": "USDC",  "network": "base",  "rail": "ach",  "senderAmount": "10000",  "receiverAmount": "9900",  "senderWalletAddress": "0x1234abcd...",  "createdAt": "2026-06-28T12:00:00.000Z"}
GET
/v1/offramp/payouts/{id}

Answers from the mirror while it was updated in the last 60 seconds; an older row is refreshed from the fiat partner first, and when the fiat partner cannot answer the stored row is returned instead of an error. Only payouts of your key's fiat partner instance that the fiat partner already acknowledged; anything else is 404.

Requires the offramp:read scope.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string

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.

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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/offramp/payouts/string'
Example Response
{  "id": "clz9xpayout001",  "blindpayId": "pa_000000000000",  "status": "processing",  "token": "USDC",  "network": "base",  "rail": "ach",  "senderAmount": "10000",  "receiverAmount": "9900",  "senderWalletAddress": "0x1234abcd...",  "createdAt": "2026-06-28T12:00:00.000Z"}
POST
/v1/offramp/payouts/{id}/documents

Forwards a document backing the payout (an invoice, for example) to the fiat partner and returns the fiat partner's answer as is. Upload the file first with POST /v1/kyc/upload and pass its file_url as transaction_document_file. Only a payout of yours on your key's fiat partner instance that the fiat partner already acknowledged; anything else is 404.

Requires the offramp:write scope.

apiKey
headerAuthorizationBearer <API key>

Your Cosmos Pay secret API key, sent as Authorization: Bearer <apiKey>.

id*string
application/json
  1. body

A compliance document backing a payout (an invoice, for example), forwarded to the fiat partner.

transaction_document_type*string

Kind of document (for example invoice).

transaction_document_id*string

Identifier of the document itself, such as the invoice number.

transaction_document_file*string

file_url from POST /v1/kyc/upload

description?string

Free-text description of the document, forwarded to the fiat partner.

201

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.

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.

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.

Example Request
curl -X POST 'https://api.cosmospay.lat/cosmos-api/v1/offramp/payouts/string/documents' \  -H 'Content-Type: application/json' \  -d '{  "transaction_document_type": "invoice",  "transaction_document_id": "INV-2026-001",  "transaction_document_file": "string"}'
Example Response
Empty