Off-ramp Routes

An off-ramp route gives your customer a permanent USDT or USDC deposit address on the network you choose. Every deposit that arrives at the address is converted automatically and paid out to one saved bank account.

It is a Payment Route with workflow_type: "crypto_to_fiat", the same resource as On-ramp Routes (fiat_to_crypto) and fiat routes (fiat_to_fiat) on Payment Routes. You create it once and your customer reuses the same address for every payment.


How it works

  1. Create the route for a verified customer: the stablecoin and network the customer sends from, and the bank account every deposit is paid out to.
  2. Stables returns a permanent deposit address in source_deposit_instructions.
  3. Your customer sends the stablecoin to that address, any amount, as often as they like.
  4. Stables detects each deposit, prices it at the rate at the time it arrives, and pays the converted amount to the route's bank account.
  5. Each deposit is a route transaction. It appears in the route's history with the fees, the rate and the payout amount, and is reported with virtual_account.activity.* webhooks.

Route deposits are not transfers. They never appear in GET /transfers and do not send transfer.* webhooks: read them from the route's history.

The customer needs the payout entitlement for the destination, as for an off-ramp transfer. See Entitlements.


Create an off-ramp route

POST /api/v1/customers/{customerId}/payment-routes

FieldDescription
workflow_typecrypto_to_fiat
source.currencyUSDT or USDC: the stablecoin the customer sends.
source.networkThe network the deposit address is issued on, named as a quote's source.network names it (for example tron or ethereum).
fiat_destinationThe bank account every deposit is paid out to: a saved beneficiary, or bank details in the same shape as a transfer's bank destination.
fiat_destination.networkOptional. How each deposit is paid out, as a quote's destination.network names it (bank, swift, or a named scheme). Defaults to the saved beneficiary's payment method, else bank.
purpose_codeThe purpose every payout carries. Required where an off-ramp transfer to the same destination requires one. See Purpose Codes.
metadataOptional. Your own key-value data, returned on the route.

Send an Idempotency-Key header, as on every create. See Idempotency.

Pay out to one of your saved beneficiaries. Its bank details are copied onto the route when it is created. Archived beneficiaries are refused.

curl -L \
  --request POST \
  --url 'https://api.stables.money/api/v1/customers/{customerId}/payment-routes' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Idempotency-Key: 6c3a1f0e-8a2b-4d5c-9e7f-1a2b3c4d5e6f' \
  --header 'Content-Type: application/json' \
  --data '{
    "workflow_type": "crypto_to_fiat",
    "source": {
      "currency": "USDT",
      "network": "ethereum"
    },
    "fiat_destination": {
      "type": "beneficiary",
      "beneficiary_id": "6f1d2c3e-4b5a-4c6d-8e7f-9a0b1c2d3e4f"
    },
    "metadata": {
      "internal_reference": "client-2041"
    }
  }'

Response

The deposit address is in source_deposit_instructions. fiat_destination holds the bank account deposits are paid out to (for a saved beneficiary, the details copied from it). destination is always null on an off-ramp route.

{
  "id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "status": "activated",
  "deactivation_reason": null,
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-11-15T08:42:10.512Z",
  "source_deposit_instructions": {
    "type": "crypto",
    "wallet_address": "0x8f3a2b1c4d5e6f708192a3b4c5d6e7f809a1b2c3",
    "currency": "usdt",
    "network": "ethereum"
  },
  "deposit_handling_mode": "auto_payout",
  "workflow_type": "crypto_to_fiat",
  "destination": null,
  "fiat_destination": {
    "type": "bank",
    "recipient_type": "individual",
    "account_holder_name": "Somchai Jaidee",
    "account_number": "1234567890",
    "bank_name": "Example Bank",
    "bank_country": "TH",
    "currency": "THB"
  },
  "held_balance": null,
  "metadata": {
    "internal_reference": "client-2041"
  }
}

To read the route again later, including its deposit address, call Get Payment Route (GET /api/v1/customers/{customerId}/payment-routes/{virtualAccountId}).

Send only the route's token on the route's network. Any other token, or the same token on a different network, is not paid out and does not appear in the route's history.

Validation errors

The create is refused with 400 Bad Request when:

  • source.currency is not USDT or USDC
  • source.network is missing
  • fiat_destination is missing, inline bank details lack account_number/iban, or a swift payout lacks swift_code/bic_code
  • the beneficiary does not exist or is archived
  • purpose_code is missing where the payout requires one, or is not accepted for the payout
  • the stablecoin, network and payout destination are not a supported combination

purpose_code, source.network, a saved beneficiary and fiat_destination.network are only accepted on crypto_to_fiat routes.


Track deposits

Each deposit on the route is a route transaction. List them with Get Transactions:

GET /api/v1/customers/{customerId}/payment-routes/{virtualAccountId}/history

Each item carries the amount deposited, the payout amount and currency, the rate (customer_rate, and market_rate where available) and the fees in stables_fees (plus developer_fees when you charge one). Fee amounts on an off-ramp route deposit are in USD. If one on-chain transaction carries more than one token transfer to the address, each transfer is recorded as its own deposit. payout_status moves through pending, processing and completed, or ends in failed with a failure object.

{
  "data": [
    {
      "id": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d",
      "transfer_id": "4e5f6a7b-8c9d-4e0f-9a1b-2c3d4e5f6a7b",
      "virtual_account_id": "3f2b1c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "deposit_amount": "10",
      "deposit_currency": "USDT",
      "sender_name": null,
      "sender_reference": "0x1234567890abcdef1234567890abcdef12345678",
      "handling_mode": "auto_payout",
      "payout_status": "completed",
      "payout_amount": "203.27",
      "payout_currency": "THB",
      "payout_network": "bank",
      "payout_address": null,
      "payout_transaction_hash": null,
      "payout_completed_at": "2026-11-15T09:03:44.120Z",
      "platform_fee_amount": null,
      "platform_fee_currency": null,
      "platform_fee_swept": null,
      "stables_fees": {
        "total": "4.006",
        "conversion_fee": "0.006",
        "processing_fee": "3",
        "orchestration_fee": "1"
      },
      "conversion_fee": "0.006",
      "processing_fee": "3",
      "orchestration_fee": "1",
      "customer_rate": "33.8795",
      "deposited_at": "2026-11-15T09:01:12.000Z",
      "created_at": "2026-11-15T09:01:15.874Z"
    }
  ],
  "has_more": false
}

conversion_fee, processing_fee and orchestration_fee at the top level are deprecated; read stables_fees instead.

Pass deposit_id to read a single deposit. Deposits are also reported with virtual_account.activity.created when they arrive and virtual_account.activity.updated.status_transitioned as the payout progresses. See Webhooks.


Turn a route off

To stop a route accepting deposits, deactivate it with PUT /api/v1/customers/{customerId}/payment-routes/{virtualAccountId}/status and {"status": "deactivated"}. You can reactivate a route your organization deactivated.

On this page