# Off-ramp (https://dev.cosmospay.lat/docs/api/offramp/)

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

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

## Create a payout quote (EVM quote carries the approve contract)

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

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

- `bank_account_id` (string, required): Cosmos Pay bank account id (from POST /v1/kyc/receivers/:id/bank-accounts) that receives the fiat.
- `currency_type` (string, required): Whether `request_amount` is what the sender sends (`sender`) or what the receiver receives (`receiver`). One of: `sender`, `receiver`.
- `cover_fees` (boolean, required): When true, the sender absorbs fees.
- `request_amount` (number, required): Amount in minor units (integer).
- `network` (string, required): The fiat partner network the stablecoin is sent on. One of: `ethereum`, `base`, `arbitrum`, `polygon`, `stellar`, `solana`, `tron`, `sepolia`, `base_sepolia`, `arbitrum_sepolia`, `polygon_amoy`, `stellar_testnet`, `solana_devnet`.
- `token` (string, required): Stablecoin paid out; `USDB` is the test token of the development instance. One of: `USDC`, `USDT`, `USDB`.
- `description` (string, optional): Free-text description of the payout, forwarded to the fiat partner.
- `partner_fee_id` (string, optional): Partner fee id, forwarded as sent.

**Responses**

- `201` (`PayoutQuoteEntity`): Created
  - `id` (string, required): Fiat partner quote id; pass it as `quote_id` to `POST /v1/offramp/payouts/authorize` and `POST /v1/offramp/payouts`.
  - `expires_at` (number, required): Unix expiry (~5 min out).
  - `sender_amount` (number, optional): Amount of stablecoin the sender sends, in minor units.
  - `receiver_amount` (number, optional): Local fiat amount to receive, minor units (e.g. ARS cents).
  - `receiver_local_amount` (number, optional): Local fiat amount (minor units). Normalized from `receiver_amount` when the fiat partner returns 0 here.
  - `contract` (object, optional): EVM approve payload to sign (abi, address, functionName, amount, network).
- `400`: ValidationFailed (see Shared responses)
- `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`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Build the unsigned Stellar/Solana payout tx to sign

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

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

- `quote_id` (string, required): Id of a payout quote from `POST /v1/offramp/quotes`.
- `sender_wallet_address` (string, required): Sender wallet on the selected chain (Stellar G… or Solana base58).
- `chain` (string, required): Chain the payout is sent from: `stellar` or `solana` (EVM payouts skip this step). One of: `stellar`, `solana`.

**Responses**

- `201` (`AuthorizedPayoutEntity`): Created
  - `unsigned_transaction` (string, required): The unsigned transaction the customer signs before `POST /v1/offramp/payouts`. Empty when the fiat partner returned none.
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `quote_expired`: The quote is ours and yours, but past its expiry
  - `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`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## List the consumer's payouts

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

**Query parameters**

- `take` (number, optional): Page size: how many items to return (1 to 100).
- `skip` (number, optional): How many items to skip before this page (offset).

**Responses**

- `200` (`PayoutListEntity`): OK
  - `data` (PayoutEntity[], required): The payouts on this page.
  - `total` (number, required): Matching rows, not the page length.
  - `take` (number, required): The page size applied, from the `take` query parameter (default 100).
  - `skip` (number, required): Rows skipped before this page, from the `skip` query parameter (default 0).
- `400`: ValidationFailed (see Shared responses)
- `401`: Unauthorized (see Shared responses)
- `403`: Forbidden (see Shared responses)
- `500`: InternalError (see Shared responses)

## Create a payout from a quote

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

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

- `quote_id` (string, required): Id of a payout quote from `POST /v1/offramp/quotes`; a quote is paid out at most once.
- `sender_wallet_address` (string, required): Sender wallet on the selected chain (EVM 0x…, Stellar G…, or Solana base58).
- `chain` (string, required): Chain family the payout is sent from: `evm`, `stellar` or `solana`. One of: `evm`, `stellar`, `solana`.
- `signed_transaction` (string, optional): Required for stellar/solana: signed transaction (Stellar XDR / Solana tx) from POST /v1/offramp/payouts/authorize. Not used for evm.

**Responses**

- `201` (`PayoutEntity`): Created
  - `id` (string, required): Cosmos Pay id of the payout.
  - `blindpayId` (string, required): The fiat partner's payout id (`pa_...`).
  - `status` (object, optional): Fiat partner status of the payout (for example `processing`); `completed`, `failed`, `refunded` and `cancelled` mean the money stopped moving.
  - `token` (object, optional): Stablecoin paid out (for example `USDC`).
  - `network` (object, optional): Network the stablecoin is sent from (for example `base`).
  - `rail` (object, optional): Bank rail the fiat settles on (for example `ach`).
  - `senderAmount` (object, optional): Amount of stablecoin sent, in minor units, as a string.
  - `receiverAmount` (object, optional): Fiat amount the bank account receives, in minor units, as a string.
  - `senderWalletAddress` (object, optional): Wallet the stablecoin is sent from.
  - `createdAt` (string (date-time), required): When this service recorded the payout (ISO 8601 date-time).
- `400` (`ApiErrorBodyEntity`): `validation_failed`: The body, query or headers failed validation `quote_expired`: The quote is ours and yours, but past its expiry
- `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`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Get a payout (serves the local mirror; refreshes from the fiat partner when stale)

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

**Path parameters**

- `id` (string, required)

**Responses**

- `200` (`PayoutEntity`): OK
- `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)
- `502`: UpstreamError (see Shared responses)
- `503`: UpstreamUnavailable (see Shared responses)
- `504`: UpstreamTimeout (see Shared responses)

## Attach a compliance document to a payout

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

**Path parameters**

- `id` (string, required)

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

- `transaction_document_type` (string, required): Kind of document (for example `invoice`).
- `transaction_document_id` (string, required): Identifier of the document itself, such as the invoice number.
- `transaction_document_file` (string, required): file_url from POST /v1/kyc/upload
- `description` (string, optional): Free-text description of the document, forwarded to the fiat partner.

**Responses**

- `201`: Created
- `400`: ValidationFailed (see Shared responses)
- `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

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