> ## Documentation Index
> Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# USD integration guide
> On and offramp with USD using Wire, ACH, and Same Day ACH
## 🇺🇸 What we support
* [Virtual Accounts](https://apidocs.bridge.xyz/platform/orchestration/virtual_accounts/virtual-account#usd) - Deposit USD via ACH or Wire and receive payments from 3rd party businesses.
* [Transfers](https://apidocs.bridge.xyz/platform/orchestration/transfers/transfer#create-transfer) - Onramp USD via Wire, ACH, or Same Day ACH as a 1st party or from 3rd party businesses, offramp to any recipient.
* [Liquidation Addresses](https://apidocs.bridge.xyz/platform/orchestration/liquidation_address/liquidation_address#multichain-%2B-multicurrency) - Offramp from stablecoin or crypto to USD via Wire or ACH.
* [Supported Countries](https://apidocs.bridge.xyz/platform/customers/compliance/supported-countries-list) - We support USD on/offramps for customers in +100 countries.
## Logistics
* **Virtual accounts are fully permitted to receive the following transactions.**
1. First-party payments where you are sending USD from your bank, fintech app, or brokerage account
2. Payroll payments from businesses
3. Third-party payment where a registered business sends USD from its bank account
4. Third-party payment from a family member’s bank account, where you share a surname
5. Third-party Person-to-Person payment for an amount less than \$4,000
6. Third party payments in most states except for New York and Texas
* Refer [here](/platform/orchestration/more/cutoffs) for cutoffs and processing times.
* Refer [here](/platform/orchestration/more/payment-tracking) for payment tracking identifiers.
***
## **Request / Response Examples**
#### Related APIs
* Create a [USD External Account](https://apidocs.bridge.xyz/platform/orchestration/external-accounts/external-accounts-api#usd) to use as a [Transfer](https://apidocs.bridge.xyz/platform/orchestration/transfers/transfer#create-transfer) or [Liquidation Address](https://apidocs.bridge.xyz/platform/orchestration/liquidation_address/liquidation_address#multichain-%2B-multicurrency) offramp destination.
* Create a [USD Virtual Account](https://apidocs.bridge.xyz/platform/orchestration/virtual_accounts/virtual-account#usd) to onramp funds using a unique account and routing number.
```bash Request expandable theme={null}
curl --request POST \
--url https://api.bridge.xyz/v0/customers/#{request.customer_id}/external_accounts \
--header 'Api-Key: #{api_key}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: #{request.idempotency_key}' \
--data '
{
"currency": "usd",
"account_type": "us",
"bank_name": "Lead Bank",
"account_name": "Ada Checking Account",
"first_name": "Ada",
"last_name": "Lovelace",
"account_owner_type": "individual", // specifies an individual account
"account_owner_name": "Ada Lovelace",
"account": {
"routing_number": "101019644",
"account_number": "215268129123",
"checking_or_savings": "checking"
},
"address": {
"street_line_1": "923 Folsom Street",
"country": "USA",
"state": "CA",
"city": "San Francisco",
"postal_code": "941070000"
}
}'
```
```json Response expandable theme={null}
{
"id": "039c270f-a038-40be-be7b-43f550ce0678", // external account id
"customer_id": "23c2d462-4c69-4c5a-b31a-88d035d7e8ae",
"created_at": "2025-07-05T19:03:50.819Z",
"updated_at": "2025-07-05T19:03:51.251Z",
"bank_name": "Lead Bank",
"account_name": "Ada Checking Account",
"account_owner_name": "Ada Lovelace",
"active": true,
"currency": "usd",
"account_owner_type": "individual",
"account_type": "us",
"first_name": "Ada",
"last_name": "Lovelace",
"business_name": null,
"account": {
"last_4": "9123",
"routing_number": "101019644",
"checking_or_savings": "checking"
},
"beneficiary_address_valid": true,
"last_4": "9123"
}
```
```bash Request expandable theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/customers//virtual_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
# The source object specifies a USD virtual account.
"source": {
"currency": "usd",
},
# The destination object instructs Bridge where to send the USD deposits to.
# Bridge will automatically handle converting and sending USD to the crypto destination.
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"address": "0x3f5CE5FBFe3E9af3971dD833D26BA9b5C936f0bE"
},
# You can specifcy an optional developer fee to monetize on transactions.
"developer_fee_percent": "1.0" // 1%.
}'
```
```json Response expandable theme={null}
{
"id": "1a400dae-f7fc-4f75-8105-212a14d4132d",
"status": "activated",
"developer_fee_percent": "1.0",
"customer_id": "23c2d200-4c00-4c5a-b31a-00d035d7e0ae",
"created_at": "2025-07-04T22:10:34.564Z",
"source_deposit_instructions": {
"currency": "usd",
"bank_name": "Lead Bank",
"bank_address": "1801 Main St., Kansas City, MO 64108",
"bank_routing_number": "101019644",
"bank_account_number": "215268120000",
"bank_beneficiary_name": "Ada Lovelace",
"bank_beneficiary_address": "923 Folsom Street, 302, San Francisco, California 941070000, US",
"payment_rail": "ach_push",
"payment_rails": [
"ach_push",
"wire"
]
},
"destination": {
"currency": "usdc",
"payment_rail": "ethereum",
"address": "0x3f5ce5fbfe3e9af3971dd833d26ba9b5c936f0be"
}
}
```
```bash Request expandable theme={null}
curl --request POST \
--url https://api.bridge.xyz/v0/transfers \
--header 'Api-Key: #{api_key}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: #{request.idempotency_key}' \
--data '
{
"amount": "10.0",
"on_behalf_of": "cust_alice",
"developer_fee": "0.5",
# source object tells Bridge where to expect deposits from.
# can be fiat or crypto
"source": {
"payment_rail": "ach_push",
"currency": "usd",
},
# deposit object tells Bridge where to send funds to.
# can also be fiat or crypto
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"to_address": "0xdeadbeef",
},
}'
```
```json Response expandable theme={null}
{
"id": "transfer_123",
"state": "awaiting_funds",
"on_behalf_of": "cust_alice",
"amount": "10.0",
"developer_fee": "0.5",
"source": {
"payment_rail": "ach_push",
"currency": "usd"
},
"destination": {
"payment_rail": "polygon",
"currency": "usdc",
"to_address": "0xdeadbeef"
},
# Very important that your customer follows the source deposit instructions
"source_deposit_instructions": {
"bank_account_number": "123456789", # Bridge's bank account number to send deposits to
"bank_routing_number": "101019644", # Bridge's bank account routing number
# if the transfer requires a specific amount, it's important your customer includes
# the exact amount expected.
"amount": "10.0",
"currency": "usd",
"deposit_message": "BVI7depositmessage", # important that the deposit message is included
},
"receipt": {
"initial_amount": "10.0",
"developer_fee": "0.5",
"exchange_fee": "0.0",
"final_amount": "9.5",
"destination_tx_hash": "0xc0ffee", // A destination tx hash will appear after the transfer is complete
},
"created_at": "2023-05-05T19:39:14.316Z",
"updated_at": "2023-05-05T19:39:15.231Z"
}
```
```bash Request expandable theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
"amount": "10.0",
"on_behalf_of": "cust_alice",
"developer_fee": "0.5",
# source object tells Bridge where to expect deposits from.
# can be fiat or crypto
"source": {
# Note that we will not validate or reject payments when the payment_rail
# is specificed as ach_same_day, but the deposit arrives via ACH or Wire.
"payment_rail": "ach_same_day",
"currency": "usd",
},
# deposit object tells Bridge where to send funds to.
# can also be fiat or crypto
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"to_address": "0xdeadbeef",
},
}'
```
```bash Request expandable theme={null}
curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: ' \
--header 'Idempotency-Key: ' \
--data-raw '{
"amount": "10.0",
"on_behalf_of": "cust_alice",
"developer_fee": "0.5",
# source object tells Bridge where to expect deposits from.
# can be fiat or crypto
"source": {
# Note that we will not validate or reject payments when the payment_rail
# is specificed as wire, but the deposit arrives via ACH.
"payment_rail": "wire",
"currency": "usd",
},
# deposit object tells Bridge where to send funds to.
# can also be fiat or crypto
"destination": {
"payment_rail": "ethereum",
"currency": "usdc",
"to_address": "0xdeadbeef",
},
}'
```
```bash Request expandable theme={null}
curl --request POST \
--url https://api.bridge.xyz/v0/transfers \
--header 'Api-Key: #{api_key}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 01123' \
--data '
{
"developer_fee_percent": "0.0",
"on_behalf_of": "cust_1234",
"source": {
"currency": "usdc",
"payment_rail": "bridge_wallet",
"bridge_wallet_id": "bw_1234"
},
"destination": {
"amount": "3.00",
"currency": "usd",
"payment_rail": "wire",
"external_account_id": "ea_1234",
"wire_message": "Payment for Invoice #143509"
}
}'
```
```bash Request expandable theme={null}
curl --request POST \
--url https://api.bridge.xyz/v0/transfers \
--header 'Api-Key: #{api_key}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 01123' \
--data '
{
"developer_fee_percent": "0.0",
"on_behalf_of": "cust_1234",
"source": {
"currency": "usdc",
"payment_rail": "bridge_wallet",
"bridge_wallet_id": "bw_1234"
},
"destination": {
"amount": "3.00",
"currency": "usd",
"payment_rail": "ach",
"external_account_id": "ea_1234", // the US bank account to pay out to
"ach_reference": "INV143509" // optional; appears on recipient statement, max 10 chars (A-Z, a-z, 0-9, spaces)
}
}'
```
```bash Request expandable theme={null}
curl --request POST \
--url https://api.bridge.xyz/v0/transfers \
--header 'Api-Key: #{api_key}' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: 01123' \
--data '
{
"developer_fee_percent": "0.0",
"on_behalf_of": "cust_1234",
"source": {
"currency": "usdc",
"payment_rail": "bridge_wallet",
"bridge_wallet_id": "bw_1234"
},
"destination": {
"amount": "3.00",
"currency": "usd",
"payment_rail": "ach_same_day", // must be submitted before cutoff
"external_account_id": "ea_1234", // the US bank account to pay out to
"ach_reference": "INV143509" // optional; appears on recipient statement, max 10 chars (A-Z, a-z, 0-9, spaces)
}
}'
```
***
**To identify which rail a payment was actually received on,** use the `payment_received_rail` field on the Transfer source, or the `payment_rail` field on the Virtual Account source.
Note that for **Transfers**, the `payment_rail` you specify at creation **reflects your intent** — not a guarantee. **The sending institution determines the actual rail used.** For example, a Transfer created with `payment_rail: wire` may ultimately arrive via ACH, in which case `payment_received_rail` will reflect `ach`.
## **ACH**
* `payment_rail`: Use `ach` for outbound (offramp) transfers. Inbound (onramp) ACH pushed by the customer's bank uses the `ach_push` rail, which is also what appears in Virtual Account deposit instructions.
* **`ach_reference`**: Optional reference included with an ACH offramp. Maximum 10 characters; allowed characters are `A–Z`, `a–z`, `0–9`, and spaces. Set this on the `destination` object.
* `trace_number`: A unique 15-digit number assigned to each ACH transaction. Use this to uniquely identify ACH payments.
* `description`: The ACH description set by the sender, configurable via API for offramps. For onramps, this is a read only field returned when available.
* **`sender_name`** / **`sender_bank_routing_number`**: Sender identity fields returned read-only in onramp responses when available.
***
## **Same Day ACH**
* `payment_rail`: `ach_same_day`
* Same response fields as standard ACH (`trace_number`, `description`, `sender_name`, `ach_reference`).
***
## **Wire**
* `payment_rail`: `wire`
* **`wire_message`**: Optional memo included with the transfer. Up to 140 characters, validated as 4 lines of 35 characters each per the Fedwire standard. Set this on the `destination` object of an offramp transfer.
* **`imad`**: The Input Message Accountability Data — a unique identifier assigned to each incoming Fedwire transaction. Returned read-only in onramp transfer responses and useful for reconciliation and tracing with your bank.
* **`originator_name`** / **`originator_address`**: Name and address of the sender, returned read-only in onramp responses when available.
* **`bank_beneficiary_name`** / **`bank_beneficiary_address`**: Beneficiary details returned read-only in onramp responses when available.
***
## **FedNow ⚡️**
* **Maximum \$10,000,000 per onramp** (this is the FedNow network limit)
* 1st and 3rd party payins and payouts supported
* FedNow operates **24/7/365 and settles in seconds**
* **Payment tracking identifiers**: FedNow onramps will include the following identifiers:
* `end_to_end_id`: The end-to-end identifier assigned by the originator that travels with the payment across the FedNow network. Available across both the Transfers and Virtual Accounts APIs.
* `transaction_id`: The unique transaction identifier assigned to the FedNow payment. Available across both the Transfers and Virtual Accounts APIs.
* We may add more identifiers where helpful, as we roll out the program.
* **Originator details**: FedNow onramps will include, if supplied:
* `sender_name`: The name of the business or individual who initiated the transaction
* `sender_bank_routing_number`: The routing number of the entity that initiated this transaction
* **How to identify whether a deposit arrived via FedNow?** To identify which rail a payment was actually received on, use the `payment_received_rail` field on the Transfer source, or the `payment_rail` field on the Virtual Account source. For FedNow onramps, the `payment_received_rail` will be `fednow`.
Please note you must clearly disclose fee details applicable to FedNow transfers (e.g., FedNow send/receive fees) in a way that is clear, concise, and accessible to your end users.