API Reference

Cross-chain Swaps

Swaps between every network Cosmos Pay works with: quote, get a deposit address made for the swap, pay it, and follow the swap to its outcome.

GET
/v1/cross-chain-swaps/assets

Only what the cross-chain route still trades. A token it tags deprecated is left out, and so is one it lists with no price, because it answers no quote for such a token.

Requires the swaps:read scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <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.

Example Request
curl -X GET 'https://api.cosmospay.lat/cosmos-api/v1/cross-chain-swaps/assets'
Example Response
{  "data": [    {      "chain": "stellar",      "chainName": "Stellar",      "symbol": "USDC",      "assetId": "nep245:v2_1.omni.hot.tg:1100_111bzQBB65GxAPAVoxqmMcgYo5oS3txhqs1Uh1cgahKQUeTUq1TJu",      "decimals": 7,      "contract": "GA5ZSEJYB37JRC5AVCIA5MOP4RHTM335X2KGX3IHOJAPP5RE34K4KZVN",      "priceUsd": 0.999538    }  ]}
POST
/v1/cross-chain-swaps/quote

A dry cross-chain quote for amount of originAsset on originChain into destinationAsset on destinationChain: the expected and minimum output, the plan commission (fee, in the origin asset), any merchantFee (its wallet a NEAR account) and a time estimate. Prices are mainnet's for every key, a dev key included. A pair on one chain among Stellar, Solana and Monad is validation_failed: those go through POST /v1/swaps. slippageBps defaults to 100 and is capped at 500, unless the deployment configures other values.

Requires the swaps:read scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

application/json
  1. body

A cross-chain swap quote request: sell amount of originAsset on originChain for destinationAsset on destinationChain, paid to recipient. The cross-chain route prices it; a failed swap refunds refundTo.

originChain*string

The network the payer deposits on: a chain from GET /v1/cross-chain-swaps/assets.

Value in"stellar""solana""monad""eth""base""arb""op""bsc""pol""avax""gnosis""bera""scroll""xlayer""abs""plasma""hood""hypercore""btc""ltc""doge""bch""dash""zec""xrp""tron""ton""near""sui""aptos""movement""starknet""cardano""aleo""fogo"
originAsset*string

The asset sold: "native" or the native ticker (XLM, SOL, ETH, BTC), a symbol listed once on the chain (USDC), a contract (SPL mint, ERC-20 address, Stellar issuer, ...) or Stellar CODE:ISSUER. See GET /v1/cross-chain-swaps/assets.

destinationChain*string

The network the recipient is paid on.

Value in"stellar""solana""monad""eth""base""arb""op""bsc""pol""avax""gnosis""bera""scroll""xlayer""abs""plasma""hood""hypercore""btc""ltc""doge""bch""dash""zec""xrp""tron""ton""near""sui""aptos""movement""starknet""cardano""aleo""fogo"
destinationAsset*string

The asset bought, spelled as for originAsset.

amount*string

Gross amount of the origin asset, in its own units (decimal). The plan commission is taken out of it; the quoted output is net of it.

recipient*string

Who receives the output, on destinationChain.

refundTo*string

Where a failed or late deposit is refunded, on originChain: normally the paying wallet.

slippageBps?number

Slippage tolerance in basis points (100 = 1%). Below the resulting minimum, the cross-chain route refunds instead of filling. Defaults to the service setting; capped by it.

merchantFee?

Your own fee on this swap, which the cross-chain route pays as a second app fee to wallet: a NEAR account id (named, e.g. merchant.near, or 64-hex implicit), credited inside the cross-chain route. App fees are whole basis points of the deposit, so the fee is turned into the basis points it amounts to, rounded down. paidBy: recipient takes it from amount (the deposit stays amount); payer adds it to the deposit.

OK

provider_error: the cross-chain route refused the quote (an amount below its minimum, a route it cannot fill); message carries its reason.

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 cross-chain route is down or rate limiting this service; retry. misconfigured: the plan charges a commission and this deployment has no fee recipient for it, or the cross-chain route refused this deployment’s credentials.

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/cross-chain-swaps/quote' \  -H 'Content-Type: application/json' \  -d '{  "originChain": "stellar",  "originAsset": "XLM",  "destinationChain": "solana",  "destinationAsset": "USDC",  "amount": "100",  "recipient": "13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK",  "refundTo": "GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG"}'
Example Response
{  "network": "public",  "origin": {    "chain": "stellar",    "asset": "XLM",    "assetId": "nep245:v2_1.omni.hot.tg:1100_111bzQBB5v7AhLyPMDwS8uJgQV24KaAPXtwyVWu2KXbbfQU6NXRCz",    "contract": null,    "amount": "100",    "amountUsd": "22.57"  },  "destination": {    "chain": "stellar",    "asset": "XLM",    "assetId": "nep245:v2_1.omni.hot.tg:1100_111bzQBB5v7AhLyPMDwS8uJgQV24KaAPXtwyVWu2KXbbfQU6NXRCz",    "contract": null,    "amount": "100",    "amountUsd": "22.57",    "minimum": "21.967571"  },  "fee": {    "bps": 50,    "amount": "0.5",    "asset": "XLM"  },  "merchantFee": {    "bps": 150,    "fixed": "0.25",    "amount": "1.75",    "asset": "XLM",    "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",    "paidBy": "recipient"  },  "slippageBps": 100,  "timeEstimateSeconds": 22}
GET
/v1/cross-chain-swaps

Answered from this service's own table, which the observer keeps current from the cross-chain route: newest first, optionally filtered by status. Paginated with take (default 20, max 100) and skip; the answer is { data, total, take, skip }. Cross-chain swaps run on mainnet only, so a dev key lists none.

Requires the swaps:read scope.

apiKey
headerAuthorizationBearer <API key>

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

status?string

Only cross-chain swaps in this status.

Value in"AWAITING_DEPOSIT""DEPOSIT_DETECTED""INCOMPLETE_DEPOSIT""PROCESSING""SUCCEEDED""REFUNDED""FAILED""EXPIRED"
take?number

How many swaps to return per page (1 to 100).

Rangevalue <= 100
Default20
skip?number

How many swaps to skip before this page, for pagination.

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/cross-chain-swaps'
Example Response
{  "data": [    {      "id": "cm1x2y3z4a5b6c7d8e9f0g1h2",      "status": "AWAITING_DEPOSIT",      "providerStatus": "PENDING_DEPOSIT",      "network": "public",      "originChain": "stellar",      "originAsset": "XLM",      "originContract": null,      "destinationChain": "solana",      "destinationAsset": "USDC",      "destinationContract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",      "amountIn": "100",      "feeBps": 50,      "feeAmount": "0.5",      "merchantFee": {        "bps": 150,        "fixed": "0.25",        "amount": "1.75",        "asset": "XLM",        "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",        "paidBy": "recipient"      },      "amountOutEstimated": "22.189466",      "amountOutMin": "21.967571",      "slippageBps": 100,      "recipient": "13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK",      "refundTo": "GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG",      "depositAddress": "GDJ4JZXZELZD737NVFORH4PSSQDWFDZTKW3AIDKHYQG23ZXBPDGGQBJK",      "depositMemo": "188866795",      "depositUri": "web+stellar:pay?destination=GDJ4…&amount=100&memo=188866795&memo_type=MEMO_TEXT",      "depositTxHash": null,      "amountOut": null,      "refundedAmount": null,      "originTxHashes": [        {          "hash": "0x9a…",          "explorerUrl": "https://solscan.io/tx/…"        }      ],      "destinationTxHashes": [        {          "hash": "0x9a…",          "explorerUrl": "https://solscan.io/tx/…"        }      ],      "timeEstimateSeconds": 22,      "correlationId": "c5928abd-243c-4019-aebd-6cccc185cc96",      "quoteSignature": "ed25519:Ze6U5JbqTTbXNvU5PW2g…",      "idempotencyKey": null,      "expiresAt": "2026-10-02T12:30:00.000Z",      "createdAt": "2019-08-24T14:15:22Z",      "updatedAt": "2019-08-24T14:15:22Z"    }  ],  "total": 1,  "take": 20,  "skip": 0}
POST
/v1/cross-chain-swaps

Asks the cross-chain route for a live quote with a deposit address for this swap alone, stores it as AWAITING_DEPOSIT and emits CROSS_CHAIN_SWAP_CREATED. The payer sends amountIn to depositAddress (with depositMemo when set) before expiresAt; depositUri is a wallet link in the origin chain's standard (SEP-7, Solana Pay, EIP-681, BIP-21, TON, CIP-13) with a QR, or null where the chain has none. The cross-chain route pays recipient or refunds refundTo, and a Stellar recipient must already trust the asset. Mainnet only; an Idempotency-Key (header or body) makes a retry return the same swap and address.

Requires the swaps:write scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

Idempotency-Key?string

Optional idempotency key. A retry with the same key and the same request returns the existing swap (same deposit address); the same key with a different request is 409 idempotency_conflict. Takes precedence over body.idempotencyKey.

application/json
  1. body

A cross-chain swap request: the quote fields plus an optional idempotency key. The answer carries a cross-chain deposit address to pay.

originChain*string

The network the payer deposits on: a chain from GET /v1/cross-chain-swaps/assets.

Value in"stellar""solana""monad""eth""base""arb""op""bsc""pol""avax""gnosis""bera""scroll""xlayer""abs""plasma""hood""hypercore""btc""ltc""doge""bch""dash""zec""xrp""tron""ton""near""sui""aptos""movement""starknet""cardano""aleo""fogo"
originAsset*string

The asset sold: "native" or the native ticker (XLM, SOL, ETH, BTC), a symbol listed once on the chain (USDC), a contract (SPL mint, ERC-20 address, Stellar issuer, ...) or Stellar CODE:ISSUER. See GET /v1/cross-chain-swaps/assets.

destinationChain*string

The network the recipient is paid on.

Value in"stellar""solana""monad""eth""base""arb""op""bsc""pol""avax""gnosis""bera""scroll""xlayer""abs""plasma""hood""hypercore""btc""ltc""doge""bch""dash""zec""xrp""tron""ton""near""sui""aptos""movement""starknet""cardano""aleo""fogo"
destinationAsset*string

The asset bought, spelled as for originAsset.

amount*string

Gross amount of the origin asset, in its own units (decimal). The plan commission is taken out of it; the quoted output is net of it.

recipient*string

Who receives the output, on destinationChain.

refundTo*string

Where a failed or late deposit is refunded, on originChain: normally the paying wallet.

slippageBps?number

Slippage tolerance in basis points (100 = 1%). Below the resulting minimum, the cross-chain route refunds instead of filling. Defaults to the service setting; capped by it.

merchantFee?

Your own fee on this swap, which the cross-chain route pays as a second app fee to wallet: a NEAR account id (named, e.g. merchant.near, or 64-hex implicit), credited inside the cross-chain route. App fees are whole basis points of the deposit, so the fee is turned into the basis points it amounts to, rounded down. paidBy: recipient takes it from amount (the deposit stays amount); payer adds it to the deposit.

idempotencyKey?string

Idempotency key. The Idempotency-Key header takes precedence over this field.

The swap. With the shared public key it carries publicToken: send it as X-Record-Token to read the swap or report its deposit.

network_unsupported: a dev (testnet) key, and the cross-chain route settles on mainnet only. trustline_missing: a Stellar recipient does not trust the destination asset, and only that account can add the trustline. provider_error: the cross-chain route refused the quote.

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.

This Idempotency-Key was already used for a different cross-chain swap request.

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 cross-chain route is down or rate limiting this service; retry. misconfigured: the plan charges a commission and this deployment has no fee recipient for it, or the cross-chain route refused this deployment’s credentials.

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/cross-chain-swaps' \  -H 'Content-Type: application/json' \  -d '{  "originChain": "stellar",  "originAsset": "XLM",  "destinationChain": "solana",  "destinationAsset": "USDC",  "amount": "100",  "recipient": "13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK",  "refundTo": "GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG"}'
Example Response
{  "id": "cm1x2y3z4a5b6c7d8e9f0g1h2",  "status": "AWAITING_DEPOSIT",  "providerStatus": "PENDING_DEPOSIT",  "network": "public",  "originChain": "stellar",  "originAsset": "XLM",  "originContract": null,  "destinationChain": "solana",  "destinationAsset": "USDC",  "destinationContract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  "amountIn": "100",  "feeBps": 50,  "feeAmount": "0.5",  "merchantFee": {    "bps": 150,    "fixed": "0.25",    "amount": "1.75",    "asset": "XLM",    "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",    "paidBy": "recipient"  },  "amountOutEstimated": "22.189466",  "amountOutMin": "21.967571",  "slippageBps": 100,  "recipient": "13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK",  "refundTo": "GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG",  "depositAddress": "GDJ4JZXZELZD737NVFORH4PSSQDWFDZTKW3AIDKHYQG23ZXBPDGGQBJK",  "depositMemo": "188866795",  "depositUri": "web+stellar:pay?destination=GDJ4…&amount=100&memo=188866795&memo_type=MEMO_TEXT",  "qr": "data:image/png;base64,iVBORw0KGgo…",  "depositTxHash": null,  "amountOut": null,  "refundedAmount": null,  "originTxHashes": [    {      "hash": "0x9a…",      "explorerUrl": "https://solscan.io/tx/…"    }  ],  "destinationTxHashes": [    {      "hash": "0x9a…",      "explorerUrl": "https://solscan.io/tx/…"    }  ],  "timeEstimateSeconds": 22,  "correlationId": "c5928abd-243c-4019-aebd-6cccc185cc96",  "quoteSignature": "ed25519:Ze6U5JbqTTbXNvU5PW2g…",  "idempotencyKey": null,  "expiresAt": "2026-10-02T12:30:00.000Z",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z",  "publicToken": "q3Zx0r8vH6c1yJ2bN5mT4kW9sD7fL0aE1gP3uR6iO2w"}
GET
/v1/cross-chain-swaps/{id}

The shared public key may call it, so a swap made without an account can follow its own status, but only with the swap’s publicToken in X-Record-Token: without it, or with another swap’s, the answer is 404. Every other key reads its own swaps as before. Listing swaps stays closed to the public key.

Requires the swaps:read scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

id*string
X-Record-Token?string

Required with the shared public key: the publicToken the create response returned for this record. Without it, or with the token of another record, the answer is 404, as for a record that does not exist. Ignored for every other API key.

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/cross-chain-swaps/string'
Example Response
{  "id": "cm1x2y3z4a5b6c7d8e9f0g1h2",  "status": "AWAITING_DEPOSIT",  "providerStatus": "PENDING_DEPOSIT",  "network": "public",  "originChain": "stellar",  "originAsset": "XLM",  "originContract": null,  "destinationChain": "solana",  "destinationAsset": "USDC",  "destinationContract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  "amountIn": "100",  "feeBps": 50,  "feeAmount": "0.5",  "merchantFee": {    "bps": 150,    "fixed": "0.25",    "amount": "1.75",    "asset": "XLM",    "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",    "paidBy": "recipient"  },  "amountOutEstimated": "22.189466",  "amountOutMin": "21.967571",  "slippageBps": 100,  "recipient": "13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK",  "refundTo": "GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG",  "depositAddress": "GDJ4JZXZELZD737NVFORH4PSSQDWFDZTKW3AIDKHYQG23ZXBPDGGQBJK",  "depositMemo": "188866795",  "depositUri": "web+stellar:pay?destination=GDJ4…&amount=100&memo=188866795&memo_type=MEMO_TEXT",  "qr": "data:image/png;base64,iVBORw0KGgo…",  "depositTxHash": null,  "amountOut": null,  "refundedAmount": null,  "originTxHashes": [    {      "hash": "0x9a…",      "explorerUrl": "https://solscan.io/tx/…"    }  ],  "destinationTxHashes": [    {      "hash": "0x9a…",      "explorerUrl": "https://solscan.io/tx/…"    }  ],  "timeEstimateSeconds": 22,  "correlationId": "c5928abd-243c-4019-aebd-6cccc185cc96",  "quoteSignature": "ed25519:Ze6U5JbqTTbXNvU5PW2g…",  "idempotencyKey": null,  "expiresAt": "2026-10-02T12:30:00.000Z",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}
POST
/v1/cross-chain-swaps/{id}/deposit

txHash must have the shape of a transaction id on the origin chain; the cross-chain route then reads that chain itself and credits only what really arrived at depositAddress. The swap records depositTxHash, moves to the status the cross-chain route reports and emits the matching CROSS_CHAIN_SWAP_* event when that status changes. Reporting is optional, since the observer follows the swap either way; with the shared public key, send the swap's publicToken in X-Record-Token.

Requires the swaps:write scope. The shared public key may call it.

apiKey
headerAuthorizationBearer <API key>

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

id*string
X-Record-Token?string

With the shared public key, send the publicToken the create response returned for this record. A wrong token is 404, as for a record that does not exist. A missing one is still accepted for now (and logged as deprecated) so wallets that do not send it yet keep working; it becomes required here when the deployment sets PUBLIC_RECORD_TOKEN_REQUIRED_ON_LEGACY=true. Ignored for every other API key.

application/json
  1. body

Reports the transaction that paid a cross-chain swap's deposit address, so the cross-chain route can start the swap without waiting for its indexer.

txHash*string

The transaction that paid the deposit address, in the origin chain's own spelling: a 64-hex hash on Stellar and the UTXO chains, 0x + 64 hex on EVM networks, a base58 signature on Solana. A 400 names the shape the origin chain expects.

OK

validation_failed: txHash is not a transaction id of the origin chain. invalid_state_transition: the swap already SUCCEEDED, was REFUNDED or FAILED. provider_error: the cross-chain route refused the hash.

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/cross-chain-swaps/string/deposit' \  -H 'Content-Type: application/json' \  -d '{  "txHash": "5f0e8a1d3c7b9e2f4a6c8d0b1e3f5a7c9d2b4e6f8a0c1d3e5f7a9b2c4d6e8f0a"}'
Example Response
{  "id": "cm1x2y3z4a5b6c7d8e9f0g1h2",  "status": "AWAITING_DEPOSIT",  "providerStatus": "PENDING_DEPOSIT",  "network": "public",  "originChain": "stellar",  "originAsset": "XLM",  "originContract": null,  "destinationChain": "solana",  "destinationAsset": "USDC",  "destinationContract": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",  "amountIn": "100",  "feeBps": 50,  "feeAmount": "0.5",  "merchantFee": {    "bps": 150,    "fixed": "0.25",    "amount": "1.75",    "asset": "XLM",    "wallet": "GBDHAQXQQ75WVBUZ2IX3O7ME7JOKJUOUPUXRNDCORUJODWQCTVUEQ62R",    "paidBy": "recipient"  },  "amountOutEstimated": "22.189466",  "amountOutMin": "21.967571",  "slippageBps": 100,  "recipient": "13QkxhNMrTPxoCkRdYdJ65tFuwXPhL5gLS2Z5Nr6gjRK",  "refundTo": "GCKFBEIYV2U22IO2BJ4KVJOIP7XPWQGQFKKWXR6DOSJBV7STMAQSMTGG",  "depositAddress": "GDJ4JZXZELZD737NVFORH4PSSQDWFDZTKW3AIDKHYQG23ZXBPDGGQBJK",  "depositMemo": "188866795",  "depositUri": "web+stellar:pay?destination=GDJ4…&amount=100&memo=188866795&memo_type=MEMO_TEXT",  "qr": "data:image/png;base64,iVBORw0KGgo…",  "depositTxHash": null,  "amountOut": null,  "refundedAmount": null,  "originTxHashes": [    {      "hash": "0x9a…",      "explorerUrl": "https://solscan.io/tx/…"    }  ],  "destinationTxHashes": [    {      "hash": "0x9a…",      "explorerUrl": "https://solscan.io/tx/…"    }  ],  "timeEstimateSeconds": 22,  "correlationId": "c5928abd-243c-4019-aebd-6cccc185cc96",  "quoteSignature": "ed25519:Ze6U5JbqTTbXNvU5PW2g…",  "idempotencyKey": null,  "expiresAt": "2026-10-02T12:30:00.000Z",  "createdAt": "2019-08-24T14:15:22Z",  "updatedAt": "2019-08-24T14:15:22Z"}