# Cross-chain Swaps (https://dev.cosmospay.lat/docs/api/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.

Base URL: `https://api.cosmospay.lat/cosmos-api`

## List the assets the cross-chain route can swap, with an indicative USD price

`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.

**Responses**

- `200` (`CrossChainAssetListEntity`): OK
  - `data` (CrossChainAssetEntity[], required): Every asset the cross-chain route still trades: a token it tags deprecated or lists with no price is left out.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Quote a cross-chain swap through the cross-chain route (price, commission, minimum); persists nothing

`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.

**Request body** (`application/json`, required): `QuoteCrossChainSwapDto`

- `originChain` (string, required): The network the payer deposits on: a `chain` from GET /v1/cross-chain-swaps/assets. One of: `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, required): 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, required): The network the recipient is paid on. One of: `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, required): The asset bought, spelled as for originAsset.
- `amount` (string, required): 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, required): Who receives the output, on destinationChain.
- `refundTo` (string, required): Where a failed or late deposit is refunded, on originChain: normally the paying wallet.
- `slippageBps` (number, optional): 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` (MerchantFeeDto, optional): 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.

**Responses**

- `200` (`CrossChainQuoteEntity`): OK
  - `network` (string, required): Always public: the cross-chain route prices and settles on mainnet.
  - `origin` (CrossChainQuoteLeg, required): The origin leg: what the payer deposits.
  - `destination` (CrossChainQuoteDestination, required): The destination leg: what the recipient receives, with its minimum.
  - `fee` (CrossChainFeeEntity, required): The plan commission, in the origin asset.
  - `merchantFee` (MerchantFeeEntity, required): The merchant fee the cross-chain route will pay, in the origin asset; null without one.
  - `slippageBps` (number, required): Slippage tolerance used for the destination minimum, in basis points (100 = 1%).
  - `timeEstimateSeconds` (number, required): The cross-chain route’s estimate, in seconds after the deposit confirms.
- `400` (`ApiErrorBodyEntity`): `provider_error`: the cross-chain route refused the quote (an amount below its minimum, a route it cannot fill); `message` carries its reason.
  - `statusCode` (number, required): Always the HTTP status of the response itself.
  - `code` (string, required): Stable machine-readable code. Branch on this, never on the message: messages are human-facing and may be reworded; codes are never renamed once published. Each response documents the subset it can return. One of: `insufficient_scope`, `no_authenticated_consumer`, `gateway_required`, `admin_console_only`, `not_found`, `validation_failed`, `payload_too_large`, `idempotency_conflict`, `operation_in_flight`, `invalid_state_transition`, `slippage_exceeded`, `insufficient_balance`, `no_path_found`, `trustline_missing`, `invalid_amount`, `invalid_memo`, `transaction_rejected`, `transaction_already_settled`, `recipient_not_registered`, `payment_transfer_mismatch`, `fee_transfer_mismatch`, `merchant_fee_transfer_mismatch`, `payer_mismatch`, `transaction_not_found`, `expired`, `network_unsupported`, `asset_unsupported`, `merchant_fee_unsupported`, `provider_error`, `provider_unavailable`, `quote_not_found`, `quote_expired`, `kyc_state_invalid`, `kyc_review_required`, `account_disabled`, `payload_expired`, `rate_limited`, `customer_wallet_taken`, `alias_taken`, `alias_name_invalid`, `alias_challenge_invalid`, `alias_signature_invalid`, `alias_recovery_invalid`, `alias_address_conflict`, `wallet_handshake_invalid`, `wallet_verifier_invalid`, `wallet_login_code_invalid`, `wallet_login_code_cooldown`, `wallet_session_invalid`, `wallet_signature_invalid`, `wallet_backup_invalid`, `wallet_backup_limit`, `wallet_account_mismatch`, `wallet_provider_unavailable`, `wallet_return_url_not_allowed`, `wallet_recovery_setup_refused`, `easy_recovery_not_found`, `easy_recovery_already_offered`, `easy_recovery_not_offered`, `easy_recovery_code_invalid`, `easy_recovery_burned`, `plugin_not_installed`, `plugin_consent_mismatch`, `plugin_rejected`, `plugin_quota_exceeded`, `plugin_failed`, `protected_payment_buyer_mismatch`, `protected_payment_signature_invalid`, `misconfigured`, `internal_error`.
  - `error` (string, required): The HTTP reason phrase for `statusCode`.
  - `message` (string | string[], required): Human-readable detail. An array when class-validator rejected the body.
  - `details` (object, optional): Machine-readable facts about this failure, present only on the codes whose example shows it: `easy_recovery_code_invalid` carries `{ "attemptsLeft": 4 }`. Absent everywhere else.
  - `path` (string, required): The path of the request that failed.
  - `timestamp` (string, required): When the envelope was produced, ISO 8601.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503` (`ApiErrorBodyEntity`): `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.
- `504`: UpstreamTimeout (see Shared responses)

## List the consumer's cross-chain swaps

`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.

**Query parameters**

- `status` (string, optional): Only cross-chain swaps in this status. One of: `AWAITING_DEPOSIT`, `DEPOSIT_DETECTED`, `INCOMPLETE_DEPOSIT`, `PROCESSING`, `SUCCEEDED`, `REFUNDED`, `FAILED`, `EXPIRED`.
- `take` (number, optional): How many swaps to return per page (1 to 100).
- `skip` (number, optional): How many swaps to skip before this page, for pagination.

**Responses**

- `200` (`CrossChainSwapListEntity`): OK
  - `data` (CrossChainSwapListItem[], required): This page of swaps, newest first.
  - `total` (number, required): How many swaps match the filter, across every page.
  - `take` (number, required): The page size used.
  - `skip` (number, required): How many swaps were skipped before this page.
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)

## Create a cross-chain swap: a cross-chain deposit address to pay

`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.

**Headers**

- `Idempotency-Key` (string, optional): 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.

**Request body** (`application/json`, required): `CreateCrossChainSwapDto`

- `originChain` (string, required): The network the payer deposits on: a `chain` from GET /v1/cross-chain-swaps/assets. One of: `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, required): 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, required): The network the recipient is paid on. One of: `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, required): The asset bought, spelled as for originAsset.
- `amount` (string, required): 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, required): Who receives the output, on destinationChain.
- `refundTo` (string, required): Where a failed or late deposit is refunded, on originChain: normally the paying wallet.
- `slippageBps` (number, optional): 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` (MerchantFeeDto, optional): 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, optional): Idempotency key. The Idempotency-Key header takes precedence over this field.

**Responses**

- `201` (`CrossChainSwapCreatedEntity`): The swap. With the shared public key it carries `publicToken`: send it as `X-Record-Token` to read the swap or report its deposit.
  - `id` (string, required): The swap's id.
  - `status` (string, required): The swap's status, mapped from the cross-chain route's `providerStatus`; EXPIRED means the deadline passed with nothing deposited. One of: `AWAITING_DEPOSIT`, `DEPOSIT_DETECTED`, `INCOMPLETE_DEPOSIT`, `PROCESSING`, `SUCCEEDED`, `REFUNDED`, `FAILED`, `EXPIRED`.
  - `providerStatus` (string, required): The cross-chain route’s own status word, verbatim.
  - `network` (string, required): Always `public`: the cross-chain route settles on mainnet only.
  - `originChain` (string, required): The network the payer deposits on. One of: `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, required): The sold asset's symbol, as the cross-chain route lists it.
  - `originContract` (object, required): The sold token's contract on its network; null for the native coin.
  - `destinationChain` (string, required): The network the recipient is paid on. One of: `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, required): The bought asset's symbol, as the cross-chain route lists it.
  - `destinationContract` (object, required): The bought token's contract on its network; null for the native coin.
  - `amountIn` (string, required): Gross, in the origin asset.
  - `feeBps` (number, required): The plan commission rate, in basis points of `amountIn`.
  - `feeAmount` (string, required): The plan commission, as a decimal string in the origin asset, which the cross-chain route takes as an app fee.
  - `merchantFee` (MerchantFeeEntity, required): The merchant fee the cross-chain route pays as an app fee; null when the request named none.
  - `amountOutEstimated` (string, required): The quoted output, as a decimal string in the destination asset, net of the commission.
  - `amountOutMin` (string, required): Minimum output after slippage, as a decimal string in the destination asset; below it the swap is refunded.
  - `slippageBps` (number, required): Slippage tolerance used to derive `amountOutMin`, in basis points.
  - `recipient` (string, required): Who receives the output, on `destinationChain`.
  - `refundTo` (string, required): Where a failed or late deposit is refunded, on `originChain`.
  - `depositAddress` (string, required): Send exactly amountIn of the origin asset here.
  - `depositMemo` (object, required): Required whenever it is set: attach it to the deposit or the deposit is lost to the swap. Always set on Stellar (a MEMO_TEXT); on another chain only if the cross-chain route issues one.
  - `depositUri` (string, required): The deposit as a wallet link on the origin chain, where the chain has a wallet-link standard: SEP-7 pay, Solana Pay, EIP-681, BIP-21 style (bitcoin:, litecoin:, dogecoin:, bitcoincash:, dash:, zcash:), ton:// transfer or CIP-13 web+cardano:. Null means: pay depositAddress (and depositMemo, if set) with any wallet of that chain.
  - `qr` (string, required): PNG data URL of a QR code: of depositUri when there is one, else of depositAddress.
  - `depositTxHash` (object, required): The deposit transaction reported through `POST /v1/cross-chain-swaps/{id}/deposit`; null until one is reported.
  - `amountOut` (object, required): Settled output, once the cross-chain route reports it.
  - `refundedAmount` (object, required): The amount refunded to `refundTo`, as a decimal string in the origin asset, once the cross-chain route reports a refund; null otherwise.
  - `originTxHashes` (CrossChainTransactionEntity[], required): Transactions the cross-chain route reports on the origin chain; null until it reports any.
  - `destinationTxHashes` (CrossChainTransactionEntity[], required): Transactions the cross-chain route reports on the destination chain; null until it reports any.
  - `timeEstimateSeconds` (number, required): The cross-chain route's estimate, in seconds after the deposit confirms.
  - `correlationId` (string, required): The cross-chain route’s id for the quote, for support requests.
  - `quoteSignature` (string, required): The cross-chain route’s signature over the quote and deposit address. Keep it: it settles a dispute.
  - `idempotencyKey` (object, required): Client idempotency key when supplied via the Idempotency-Key header or body; null otherwise.
  - `expiresAt` (string (date-time), required): After this the deposit address refunds whatever arrives.
  - `createdAt` (string (date-time), required): When the swap was created (ISO 8601 date-time).
  - `updatedAt` (string (date-time), required): When the swap was last updated (ISO 8601 date-time).
  - `publicToken` (string, optional): Only when the caller is the shared public key: this record’s read token. Send it as `X-Record-Token` on the routes of this one record. Reading it by id (and submitting a USDT0 transfer) answers 404 without it; swap submit and cross-chain deposit still accept a request without it for now, and will require it once the deployment turns `PUBLIC_RECORD_TOKEN_REQUIRED_ON_LEGACY` on. The same create replayed with its Idempotency-Key answers the same token. Keep it like the record id: whoever holds both can read the record.
- `400` (`ApiErrorBodyEntity`): `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.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `409` (`ApiErrorBodyEntity`): This Idempotency-Key was already used for a different cross-chain swap request.
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503` (`ApiErrorBodyEntity`): `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.
- `504`: UpstreamTimeout (see Shared responses)

## Get a cross-chain swap by id

`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.

**Path parameters**

- `id` (string, required)

**Headers**

- `X-Record-Token` (string, optional): 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.

**Responses**

- `200` (`CrossChainSwapEntity`): OK
  - `id` (string, required): The swap's id.
  - `status` (string, required): The swap's status, mapped from the cross-chain route's `providerStatus`; EXPIRED means the deadline passed with nothing deposited. One of: `AWAITING_DEPOSIT`, `DEPOSIT_DETECTED`, `INCOMPLETE_DEPOSIT`, `PROCESSING`, `SUCCEEDED`, `REFUNDED`, `FAILED`, `EXPIRED`.
  - `providerStatus` (string, required): The cross-chain route’s own status word, verbatim.
  - `network` (string, required): Always `public`: the cross-chain route settles on mainnet only.
  - `originChain` (string, required): The network the payer deposits on. One of: `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, required): The sold asset's symbol, as the cross-chain route lists it.
  - `originContract` (object, required): The sold token's contract on its network; null for the native coin.
  - `destinationChain` (string, required): The network the recipient is paid on. One of: `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, required): The bought asset's symbol, as the cross-chain route lists it.
  - `destinationContract` (object, required): The bought token's contract on its network; null for the native coin.
  - `amountIn` (string, required): Gross, in the origin asset.
  - `feeBps` (number, required): The plan commission rate, in basis points of `amountIn`.
  - `feeAmount` (string, required): The plan commission, as a decimal string in the origin asset, which the cross-chain route takes as an app fee.
  - `merchantFee` (MerchantFeeEntity, required): The merchant fee the cross-chain route pays as an app fee; null when the request named none.
  - `amountOutEstimated` (string, required): The quoted output, as a decimal string in the destination asset, net of the commission.
  - `amountOutMin` (string, required): Minimum output after slippage, as a decimal string in the destination asset; below it the swap is refunded.
  - `slippageBps` (number, required): Slippage tolerance used to derive `amountOutMin`, in basis points.
  - `recipient` (string, required): Who receives the output, on `destinationChain`.
  - `refundTo` (string, required): Where a failed or late deposit is refunded, on `originChain`.
  - `depositAddress` (string, required): Send exactly amountIn of the origin asset here.
  - `depositMemo` (object, required): Required whenever it is set: attach it to the deposit or the deposit is lost to the swap. Always set on Stellar (a MEMO_TEXT); on another chain only if the cross-chain route issues one.
  - `depositUri` (string, required): The deposit as a wallet link on the origin chain, where the chain has a wallet-link standard: SEP-7 pay, Solana Pay, EIP-681, BIP-21 style (bitcoin:, litecoin:, dogecoin:, bitcoincash:, dash:, zcash:), ton:// transfer or CIP-13 web+cardano:. Null means: pay depositAddress (and depositMemo, if set) with any wallet of that chain.
  - `qr` (string, required): PNG data URL of a QR code: of depositUri when there is one, else of depositAddress.
  - `depositTxHash` (object, required): The deposit transaction reported through `POST /v1/cross-chain-swaps/{id}/deposit`; null until one is reported.
  - `amountOut` (object, required): Settled output, once the cross-chain route reports it.
  - `refundedAmount` (object, required): The amount refunded to `refundTo`, as a decimal string in the origin asset, once the cross-chain route reports a refund; null otherwise.
  - `originTxHashes` (CrossChainTransactionEntity[], required): Transactions the cross-chain route reports on the origin chain; null until it reports any.
  - `destinationTxHashes` (CrossChainTransactionEntity[], required): Transactions the cross-chain route reports on the destination chain; null until it reports any.
  - `timeEstimateSeconds` (number, required): The cross-chain route's estimate, in seconds after the deposit confirms.
  - `correlationId` (string, required): The cross-chain route’s id for the quote, for support requests.
  - `quoteSignature` (string, required): The cross-chain route’s signature over the quote and deposit address. Keep it: it settles a dispute.
  - `idempotencyKey` (object, required): Client idempotency key when supplied via the Idempotency-Key header or body; null otherwise.
  - `expiresAt` (string (date-time), required): After this the deposit address refunds whatever arrives.
  - `createdAt` (string (date-time), required): When the swap was created (ISO 8601 date-time).
  - `updatedAt` (string (date-time), required): When the swap was last updated (ISO 8601 date-time).
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `500`: InternalError (see Shared responses)

## Report the deposit transaction to the cross-chain route so the swap starts without waiting for its indexer

`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.

**Path parameters**

- `id` (string, required)

**Headers**

- `X-Record-Token` (string, optional): 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.

**Request body** (`application/json`, required): `SubmitDepositDto`

- `txHash` (string, required): 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.

**Responses**

- `200` (`CrossChainSwapEntity`): OK
- `400` (`ApiErrorBodyEntity`): `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.
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `404`: NotFound (see Shared responses)
- `429`: RateLimited (see Shared responses)
- `500`: InternalError (see Shared responses)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Shared responses

- **Unauthorized** (`ApiErrorBodyEntity`): `no_authenticated_consumer`: The gateway forwarded no API key identity
- **Forbidden** (`ApiErrorBodyEntity`): `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.
- **InternalError** (`ApiErrorBodyEntity`): Unexpected server error. The detail is logged server-side and never returned: there is nothing in the body to branch on beyond the code.
- **UpstreamError** (`ApiErrorBodyEntity`): 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`.
- **UpstreamUnavailable** (`ApiErrorBodyEntity`): `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.
- **UpstreamTimeout** (`ApiErrorBodyEntity`): 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.
- **RateLimited** (`ApiErrorBodyEntity`): 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`.
- **ValidationFailed** (`ApiErrorBodyEntity`): 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.
- **NotFound** (`ApiErrorBodyEntity`): 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.
