API Reference

On-ramp

Fiat in: quotes, payins, virtual accounts, and the trustline for the asset delivered.

POST
/v1/onramp/quotes

Prices a payin through the fiat partner for one of your wallets (blockchain_wallet_id, a Cosmos Pay wallet id) and records the quote as yours, on the fiat partner instance your key selects (a dev key uses the development instance, a prod key production). The quote is the fiat partner's answer as is: create the payin from it before its expires_at. Amounts are integers in minor units, and transfers (AR) and pse (CO) need their payer_rules. A wallet you do not own is a 404, and one whose receiver's fiat access is disabled is 403 account_disabled.

Requires the onramp:write scope.

apiKey
headerAuthorizationBearer <API key>

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

application/json
  1. body

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

blockchain_wallet_id*string

Cosmos Pay wallet id (from POST /v1/kyc/receivers/:id/wallets) that receives the minted stablecoin.

currency_type*string

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

Value in"sender""receiver"
payment_method*string

Fiat-in method. Note: payins use spei/transfers/pse (not the _bitso payout rails).

Value in"ach""wire""pix""ted""spei""transfers""pse""international_swift""rtp"
token*string

Stablecoin the wallet receives; USDB is the test token of the development instance.

Value in"USDC""USDT""USDB"
request_amount*number

Amount in minor units (integer).

cover_fees?boolean

When true, the sender absorbs the fees.

payer_rules?

Required for Transfers (AR): transfers_allowed_tax_id. Required for PSE (CO): pse_full_name, pse_document_type, pse_document_number, pse_email, pse_bank_code. Optional for other methods (e.g. pix).

is_otc?boolean

The fiat partner's OTC flag, forwarded as sent.

partner_fee_id?string

Partner fee id, forwarded as sent.

wallet_id?string

Optional custodial wallet id.

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/onramp/quotes' \  -H 'Content-Type: application/json' \  -d '{  "blockchain_wallet_id": "clz9xwallet001",  "currency_type": "sender",  "payment_method": "pix",  "token": "USDC",  "request_amount": 10000}'
Example Response
{  "id": "pq_000000000000",  "expires_at": 1782692400,  "commercial_quotation": 5.42,  "receiver_amount": 10000,  "sender_amount": 10000}
GET
/v1/onramp/payins

Reads this service's mirror only (no fiat partner call), newest first, limited to your key's fiat partner instance; payins 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 payin.

Requires the onramp: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/onramp/payins'
Example Response
{  "data": [    {      "id": "clz9xpayin0001",      "blindpayId": "pi_000000000000",      "status": "processing",      "token": "USDC",      "network": "stellar",      "paymentMethod": "pix",      "senderAmount": "10000",      "receiverAmount": "9950",      "instructions": {        "pix_code": "00020126...5204000053039865802BR..."      },      "createdAt": "2026-06-28T12:00:00.000Z"    }  ],  "total": 1,  "take": 100,  "skip": 0}
POST
/v1/onramp/payins

Executes a quote from POST /v1/onramp/quotes at the fiat partner and returns the payin with the instructions the payer follows to fund it off-platform; the destination chain is the one of the quote's wallet. Idempotent per quote: a retry of the same quote reuses its row and its the fiat partner Idempotency-Key, so it cannot create a second payin. A quote that is not yours, is a payout 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 PAYIN_UPDATED and PAYIN_COMPLETED webhook events.

Requires the onramp:write scope.

apiKey
headerAuthorizationBearer <API key>

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

application/json
  1. body

Executes a payin quote; the answer carries the instructions the payer follows to fund the payin.

payin_quote_id*string

The id returned by POST /v1/onramp/quotes.

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/onramp/payins' \  -H 'Content-Type: application/json' \  -d '{  "payin_quote_id": "pq_000000000000"}'
Example Response
{  "id": "clz9xpayin0001",  "blindpayId": "pi_000000000000",  "status": "processing",  "token": "USDC",  "network": "stellar",  "paymentMethod": "pix",  "senderAmount": "10000",  "receiverAmount": "9950",  "instructions": {    "pix_code": "00020126...5204000053039865802BR..."  },  "createdAt": "2026-06-28T12:00:00.000Z"}
GET
/v1/onramp/payins/{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 payins of your key's fiat partner instance that the fiat partner already acknowledged; anything else is 404.

Requires the onramp: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/onramp/payins/string'
Example Response
{  "id": "clz9xpayin0001",  "blindpayId": "pi_000000000000",  "status": "processing",  "token": "USDC",  "network": "stellar",  "paymentMethod": "pix",  "senderAmount": "10000",  "receiverAmount": "9950",  "instructions": {    "pix_code": "00020126...5204000053039865802BR..."  },  "createdAt": "2026-06-28T12:00:00.000Z"}
POST
/v1/onramp/trustline

Asks the fiat partner to build the unsigned Stellar transaction that adds the trustline address needs to hold the onramp's stablecoin, and returns the fiat partner's answer as is. The customer signs it: this service never signs. Built on your key's fiat partner instance; nothing is stored.

Requires the onramp:write scope.

apiKey
headerAuthorizationBearer <API key>

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

application/json
  1. body

The Stellar address to build an unsigned trustline transaction for, so it can hold the onramp's stablecoin.

address*string

Stellar address that needs the asset trustline.

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.

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/onramp/trustline' \  -H 'Content-Type: application/json' \  -d '{  "address": "GCALNQQBXAPZ2WIRSDDBMSTAKCUH5SG6U76YBFLQLIXJTF7FE5AX7AOO"}'
Example Response
Empty
GET
/v1/onramp/receivers/{receiverId}/virtual-accounts

Reads this service's mirror only (no fiat partner call), newest first. The receiver must be yours on your key's fiat partner instance, or the answer is 404. Paginated with take (default 100, max 100) and skip; answers { data, total, take, skip }.

Requires the onramp:read scope.

apiKey
headerAuthorizationBearer <API key>

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

receiverId*string
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
200

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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/onramp/receivers/string/virtual-accounts'
Example Response
Empty
POST
/v1/onramp/receivers/{receiverId}/virtual-accounts

Opens a virtual account at the fiat partner: a bank account in the receiver's name at banking_partner whose deposits are converted to token and sent to blockchain_wallet_id, a Cosmos Pay wallet id. The account is mirrored here and the mirrored row is the answer. A receiver or wallet that is not yours on your key's fiat partner instance is a 404, and the answer is 403 account_disabled when the receiver, or the receiver that owns the wallet, has its fiat access disabled.

Requires the onramp:write scope.

apiKey
headerAuthorizationBearer <API key>

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

receiverId*string
application/json
  1. body

A virtual account to open for a receiver: a bank account in its name at banking_partner whose deposits are converted to token and sent to a wallet.

banking_partner*string

Bank the virtual account is opened at.

Value in"jpmorgan""citi""hsbc""cfsb"
token*string

Stablecoin the deposits are converted to; USDB is the test token of the development instance.

Value in"USDC""USDT""USDB"
blockchain_wallet_id*string

Cosmos Pay wallet id that receives the converted stablecoin.

signed_agreement_id?string

Id of a signed agreement, forwarded to the fiat partner.

sole_proprietor_doc_type?string

Type of the sole-proprietor document, forwarded to the fiat partner.

sole_proprietor_doc_file?string

Sole-proprietor document file, 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.

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/onramp/receivers/string/virtual-accounts' \  -H 'Content-Type: application/json' \  -d '{  "banking_partner": "cfsb",  "token": "USDC",  "blockchain_wallet_id": "clz9xwallet001"}'
Example Response
Empty