On-ramp: Fund a stablecoin account with a USD wire

Goal

Fund a customer’s Bastion account with USDC by converting USD wired from their bank account, using an on-ramp conversion via a Virtual Account (VA).

Scope: USD → USDC, Wire only, US customers only, first-party (customer wires from their own bank account).

Key entities

Entity	Description
Your platform	The product integrating Bastion’s APIs
Customer	An individual or business your platform has onboarded (KYC/KYB-verified), with a Bastion account
Identity	The customer’s record in Bastion
Account	A Bastion account linked to the identity that holds balances and transacts
Virtual Account (VA)	A dedicated deposit address at Bastion’s partner bank tied to a specific customer, chain, and destination wallet
Conversion	A value change between assets (e.g., USD wired in → USDC on Ethereum) auto-created when a deposit lands

Flow overview

The steps to fund a stablecoin balance from a bank account are:

Create a Virtual Account
Share deposit instructions with the customer
Customer wires USD
Track conversion status
Show balance

Unlike off-ramps, you do not call POST /v2/conversions. Bastion auto-creates the conversion the moment it detects the incoming wire.

Prerequisites

Customer has a verified identity (KYC or KYB) with fiat_operations_enabled = true
Customer has an active Bastion account on a supported chain
You have an API key and registered webhook

Step 1 – create a virtual account

Create a Virtual Account for the customer. Each VA links to a specific chain, asset, and destination wallet; create one VA per chain and asset you want to support. Request

POST /v2/identities/{identity_id}/virtual-accounts
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "request_id": "903c9e51-51af-4597-9174-0a93ca80dbac",
  "source": {
    "banking_country": "US",
    "currency": "USD"
  },
  "destination": {
    "currency": "USDC",
    "payment_method": "BLOCKCHAIN",
    "chain": "ETHEREUM_MAINNET",
    "account_id": "36hv3yZpsHt7pwgBZom5SXgURYz"
  }
}

Field notes

Field	Description
`source.banking_country`	Determines the banking partner. `US` for US customers
`source.currency`	Fiat currency the VA accepts. `USD` for US Wire
`destination.chain`	Blockchain network for USDC delivery (e.g. `ETHEREUM_MAINNET`)
`destination.account_id`	Customer’s Bastion account that receives USDC

Response

{
  "id": "va_3Cb0rR32xNl2GAHFjJc4EHEcdPw",
  "identity_id": "36RNhc8l8oQLLUS2aJaXZaUbwnC",
  "status": "ACTIVE",
  "source": {
    "banking_country": "US",
    "currency": "USD"
  },
  "destination": {
    "currency": "USDC",
    "payment_method": "BLOCKCHAIN",
    "chain": "ETHEREUM_MAINNET",
    "account_id": "36hv3yZpsHt7pwgBZom5SXgURYz"
  },
  "deposit_instructions": {
    "bank_name": "Partner Bank",
    "bank_address": "123 Banking St, New York, NY 10001",
    "bank_account_number": "9876543210",
    "bank_routing_number": "021000000",
    "bank_beneficiary_name": "John Doe",
    "bank_beneficiary_address": "99 Main St, New York, NY 10001",
    "payment_method": "WIRE",
    "currency": "USD"
  },
  "created_at": "2026-04-19T15:00:00Z",
  "updated_at": "2026-04-19T15:00:00Z"
}

Store the id as virtual_account_id so you can reference this VA later. You can retrieve it again at any time from the GET /v2/identities/{identity_id}/virtual-accounts list endpoint.

Present the deposit_instructions from Step 1 to the customer so they can initiate a wire from their bank. Fields to surface in your UI

Field	Label for the customer
`bank_name`	Bank name
`bank_address`	Bank address
`bank_account_number`	Account number
`bank_routing_number`	Routing number (ABA)
`bank_beneficiary_name`	Beneficiary name
`bank_beneficiary_address`	Beneficiary address

The bank_account_number is unique to this VA. The customer does not need to include a memo or reference. The account number alone routes the deposit to the correct VA.

Step 3 – customer wires USD

The customer initiates a domestic wire from their bank to the deposit instructions shared in Step 2. When the wire lands at Bastion’s banking partner, Bastion detects it and auto-creates a conversion record. No API call is required from your platform at this step. Testing in sandbox? See Test the on-ramp in sandbox.

Step 4 – track conversion status

Once Bastion detects the wire, it creates the conversion and fires webhooks as the conversion progresses. You learn the conversion_id from the first webhook.

Option A: webhooks

Example event (INITIATED)

{
  "id": "cv_334455",
  "request_id": "auto-generated-uuid",
  "amount": "500.00",
  "account_id": "36hv3yZpsHt7pwgBZom5SXgURYz",
  "payment_purpose": "PERSONAL_REMITTANCE",
  "source": {
    "currency": "USD",
    "payment_method": "WIRE",
    "amount": "500.00"
  },
  "destination": {
    "currency": "USDC",
    "payment_method": "BLOCKCHAIN",
    "chain": "ETHEREUM_MAINNET",
    "amount": ""
  },
  "type": "ON_RAMP",
  "status": "INITIATED",
  "created_at": "2026-04-19T15:00:00Z",
  "updated_at": "2026-04-19T15:00:00Z",
  "completed_at": "",
  "exchange_rate": "1.0",
  "fees_total": "14.00",
  "fees_total_currency": "USDC",
  "fees": [
    {
      "amount": "14.00",
      "currency": "USDC",
      "type": "PLATFORM"
    }
  ]
}

Example event (COMPLETED)

{
  "id": "cv_334455",
  "request_id": "auto-generated-uuid",
  "amount": "500.00",
  "account_id": "36hv3yZpsHt7pwgBZom5SXgURYz",
  "payment_purpose": "PERSONAL_REMITTANCE",
  "source": {
    "currency": "USD",
    "payment_method": "WIRE",
    "amount": "500.00"
  },
  "destination": {
    "currency": "USDC",
    "payment_method": "BLOCKCHAIN",
    "chain": "ETHEREUM_MAINNET",
    "amount": "486.00"
  },
  "type": "ON_RAMP",
  "status": "COMPLETED",
  "created_at": "2026-04-19T15:00:00Z",
  "updated_at": "2026-04-19T15:45:00Z",
  "completed_at": "2026-04-19T15:45:00Z",
  "exchange_rate": "1.0",
  "fees_total": "14.00",
  "fees_total_currency": "USDC",
  "fees": [
    {
      "amount": "14.00",
      "currency": "USDC",
      "type": "PLATFORM"
    }
  ]
}

Status progression The on-ramp progression is: INITIATED → PROCESSING → PAYOUT_INITIATED → PAYOUT_IN_PROGRESS → COMPLETED Handle statuses:

Status	Action
`INITIATED`, `PROCESSING`	Show “funding your account” indicator.
`PAYOUT_INITIATED`, `PAYOUT_IN_PROGRESS`	Show “delivering USDC”; USDC is on the way to the customer’s wallet.
`COMPLETED`	Mark on-ramp complete, refresh balances, show as settled.
`FAILED`	Show error, direct to support.

Webhook reliability: Failed deliveries are retried with exponential backoff (15 s base interval, 10 min max). Deduplicate using id + status. If no webhook arrives within a reasonable window, poll GET /v2/conversions/{conversion_id}.

Option B: polling

If webhook delivery fails, list conversions by account to find the record:

GET /v2/conversions?account_id={account_id}&type=ON_RAMP
Authorization: Bearer YOUR_API_KEY

Then poll GET /v2/conversions/{conversion_id} for status updates.

Step 5 – show updated balance

After the conversion completes, refresh balances and show the on-ramp in the customer’s history. Refresh balances

GET /v2/accounts/{account_id}/balances
Authorization: Bearer YOUR_API_KEY

UI recommendations:

Increase visible USDC balance by destination.amount from the completion webhook
Display USD wired (gross), fees, USDC delivered (net), and status
Show source (masked bank account details from the wire)

Fees

fees_total on the conversion reflects the incoming wire fee only. Bastion deducts the fee from the wired USD amount before delivering USDC. Example: customer wires $500 → fees_total = 14.00 → destination.amount = 486.00 USDC delivered. The fees array is populated from the moment the conversion is created (when the wire lands). Developer fees are not supported yet.

Implementation notes

Recommendation	Details
One VA per chain	Create a separate VA for each chain (Ethereum, Solana, Base) you want to support
VAs are reusable	The same VA accepts multiple deposits. Don’t create a new VA per transaction
Learn conversion ID from webhook	You don’t create the conversion; the `id` arrives in the first webhook
Map IDs to your users	Store `identity_id`, `account_id`, and `virtual_account_id` alongside your internal user records so webhooks route to the right customer
Handle failures clearly	Treat `FAILED` as errors requiring customer messaging

Test the on-ramp in sandbox

Sandbox Virtual Accounts can’t receive real deposits. To test the on-ramp end to end, simulate a deposit instead. Bastion then runs the same on-ramp flow a real deposit triggers. How a simulated deposit differs from a real one

No USDC is delivered, so the account balance doesn’t change. Use simulation to test status tracking and webhook handling, not funded balances.
The simulation endpoint is available in sandbox only.

Simulate the deposit

Call the simulation endpoint with the customer’s account and the id of the on-ramp VA from Step 1.

POST https://api.sandbox.bastion.io/v2/simulation/on-ramp-deposit
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "account_id": "36hv3yZpsHt7pwgBZom5SXgURYz",
  "amount": "500.00",
  "virtual_account_id": "va_3Cb0rR32xNl2GAHFjJc4EHEcdPw"
}

The response returns the request_id of the on-ramp conversion the deposit starts.

{
  "request_id": "7f3e2a10-5b8c-4d9e-a1f2-3c4d5e6f7a8b"
}

Find the conversion

Poll the lookup endpoint with the request_id until it returns the conversion. The response includes the conversion’s id.

GET https://api.sandbox.bastion.io/v2/conversions/by-request-id/{request_id}
Authorization: Bearer YOUR_API_KEY

Track the conversion

From here the conversion behaves like a real one: webhooks fire as it moves through each status, and you can poll GET /v2/conversions/{conversion_id} with its id. Track its status as described in Step 4. Balances don’t change in sandbox, so skip the balance updates.

To test failure paths, such as a deposit below the minimum, add the matching label to the identity before simulating. See On-ramp and off-ramp conversion simulations.

Getting Started

Concepts

Quickstarts

Compliance

Security

Bastion Dashboard

LLMs and MCP Server

On-ramp: Fund a stablecoin account with a USD wire

Goal

Key entities

Flow overview

Prerequisites

Step 1 – create a virtual account

Step 3 – customer wires USD

Step 4 – track conversion status

Option A: webhooks

Option B: polling

Step 5 – show updated balance

Fees

Implementation notes

Test the on-ramp in sandbox

​Goal

​Key entities

​Flow overview

​Prerequisites

​Step 1 – create a virtual account

​Step 2 – share deposit instructions with the customer

​Step 3 – customer wires USD

​Step 4 – track conversion status

​Option A: webhooks

​Option B: polling

​Step 5 – show updated balance

​Fees

​Implementation notes

​Test the on-ramp in sandbox

Goal

Key entities

Flow overview

Prerequisites

Step 1 – create a virtual account

Step 2 – share deposit instructions with the customer

Step 3 – customer wires USD

Step 4 – track conversion status

Option A: webhooks

Option B: polling

Step 5 – show updated balance

Fees

Implementation notes

Test the on-ramp in sandbox