On-ramp Routes

An on-ramp route gives your customer dedicated bank details in their own name. Every fiat deposit that arrives is reconciled to the customer, converted to a stablecoin and sent to the wallet you set on the route.

It is a Payment Route with workflow_type: "fiat_to_crypto", the default when workflow_type is omitted. It is the same resource as Off-ramp Routes (crypto_to_fiat). You create it once and your customer reuses the same bank details for every payment.


How it works

  1. Create the route for a verified customer: the currency the customer pays in, and the stablecoin, network and wallet address every deposit is delivered to.
  2. Stables returns the deposit details in source_deposit_instructions: an account number and routing details, or an IBAN, depending on the rail.
  3. Your customer pays in from their bank on a supported local rail, any amount above the minimum, as often as they like.
  4. Stables receives and reconciles each deposit, converts it at the rate when it is confirmed, and sends the stablecoin to the route's wallet.
  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.

Currencies

CurrencyDeposit detailsRailsEntitlement
USDU.S. account and routing numbersACH, domestic wire (Fedwire)usd_virtual_account
AEDUAE local bank account detailsIPP, UAEFTSaed_local
SWIFT collection (businesses)An IBAN that receives international SWIFT transfers in 18 currenciesSWIFTbase_pay_in

EUR and GBP local accounts are in the works. Limits, minimums and cut-offs per currency are on Supported currencies.

The customer needs the entitlement for the currency before the route can be created. A USD account also needs the customer's financial profile, including expected monthly payment volume, sent with PATCH /api/v1/customers/{customer_id}/entitlements/usd_virtual_account/requirements. See Entitlements.


Create an on-ramp route

Request

curl -L \
  --request POST \
  --url 'https://api.stables.money/api/v1/customers/{customerId}/payment-routes' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": {
      "currency": "USD"
    },
    "metadata": {
      "internal_reference": "client-2041"
    },
    "destination": {
      "currency": "usdt",
      "payment_rail": "tron",
      "address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7",
      "wallet_type": "hosted",
      "vasp_name": "Binance"
    }
  }'

Set destination.wallet_type to hosted when the address belongs to an exchange or other provider, and name it in vasp_name. Use self_hosted when your customer holds the keys. Omitted means self_hosted. See Travel Rule.

Response

status is typically pending immediately after creation while the provider activates the account (this can take a few seconds), then transitions to activated once confirmed. Poll the virtual account or listen for status-change events rather than assuming activated on creation.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pending",
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-04-01T01:12:37.384Z",
  "source_deposit_instructions": {
    "currency": "USD",
    "payment_rails": [
      "ach_push",
      "wire"
    ],
    "bank_name": "Example Bank",
    "bank_address": "123 Smith Street",
    "bank_beneficiary_name": "John Smith",
    "bank_beneficiary_address": "321 Smith Street",
    "bank_account_number": "1111111111",
    "bank_routing_number": "111111111",
    "account_holder_name": "John Smith"
  },
  "deposit_handling_mode": "auto_payout",
  "destination": {
    "currency": "usdt",
    "payment_rail": "tron",
    "address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7",
    "wallet_type": "hosted",
    "vasp_name": "Binance"
  }
}

Deposits and webhooks

Read a route's deposits with GET /api/v1/customers/{customerId}/payment-routes/{virtualAccountId}/history, and one route with Get Payment Route. Deposits are reported with virtual_account.activity.created when they arrive and virtual_account.activity.updated.status_transitioned as the payout progresses.

In sandbox, create a deposit without a real bank transfer with Simulate deposit.


SWIFT collection accounts

A SWIFT collection account gives a business customer an IBAN that receives international SWIFT transfers. Each deposit is converted and paid out in USDT to the route's wallet, like any other Payment Route.

Use it when your business customers are paid by overseas clients, or in a currency with no local Payment Route.

Who can open one

  • Business customers only. A request for an individual is refused.
  • The business's verification (business_base) must be approved.
  • The customer needs the base_pay_in entitlement.

Currencies

AED, AUD, CAD, CHF, CZK, DKK, EUR, GBP, GEL, HKD, HUF, JPY, NZD, PLN, SEK, SGD, THB and USD, settling in USDT on Tron. See Supported currencies.

How it differs from a local account

  • The account is not in your customer's name. The account holder is a Stables entity, returned in account_holder_name and bank_beneficiary_name. Each account has its own IBAN, which is how a deposit is matched to your customer.
  • payment_rails is ["swift"], and the deposit details include iban and bic in place of a local account and routing number.
  • SWIFT transfers take longer than local payments, and the sender's and intermediary banks may deduct their own charges before the funds arrive.

Open a SWIFT collection account

Set source.payment_rail to swift. Without it, the account is opened on the currency's local rail, or refused if the currency has none.

curl -L \
  --request POST \
  --url 'https://api.stables.money/api/v1/customers/{customerId}/payment-routes' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  --header 'Content-Type: application/json' \
  --data '{
    "source": {
      "currency": "EUR",
      "payment_rail": "swift"
    },
    "workflow_type": "fiat_to_crypto",
    "destination": {
      "currency": "usdt",
      "payment_rail": "tron",
      "address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7"
    }
  }'

Response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "activated",
  "customer_id": "123e4567-e89b-12d3-a456-426614174000",
  "created_at": "2026-11-16T04:30:27.206Z",
  "source_deposit_instructions": {
    "currency": "eur",
    "payment_rails": [
      "swift"
    ],
    "bank_name": "Example Bank",
    "bank_address": "1 Example Street, Example City",
    "bank_beneficiary_name": "Stables Entity Ltd.",
    "bank_beneficiary_address": "2 Example Avenue, Example City",
    "iban": "XX00EXAM00000000000000",
    "bic": "EXAMPLEXXXX",
    "account_holder_name": "Stables Entity Ltd."
  },
  "deposit_handling_mode": "auto_payout",
  "workflow_type": "fiat_to_crypto",
  "destination": {
    "currency": "usdt",
    "payment_rail": "tron",
    "address": "TUVPATBKPjUuN5pBkigmfQtUR9yoYFhvv7"
  }
}

Give your customer's payers every field in source_deposit_instructions, exactly as returned.

Errors

StatusMessageWhat to do
400SWIFT collection accounts are only available for business customersUse a local Payment Route for individuals.
400SWIFT collection accounts are available once the business's verification is approvedWait for business_base to be approved, then retry.
400SWIFT collection is not available for {currency}The currency or destination network has no SWIFT route.
422ROUTING_ENTITLEMENT_MISSING naming base_pay_inRequest base_pay_in for the customer, then retry.

On this page