USD integration guide

🇺🇸 What we support

Virtual Accounts - Deposit USD via ACH, Wire, or FedNow and receive payments from 3rd party businesses.
Transfers - Onramp USD via Wire, ACH, Same Day ACH, or FedNow as a 1st party or from 3rd party businesses, offramp to any recipient including via FedNow.
Liquidation Addresses - Offramp from stablecoin or crypto to USD via Wire, ACH, or FedNow.
Supported Countries - We support USD on/offramps for customers in +100 countries.

Logistics

Virtual accounts are fully permitted to receive the following transactions:

First-party payments where you are sending USD from your bank, fintech app, or brokerage account
Payroll payments from businesses
Third-party payments where a registered business sends USD from its bank account
Third-party payments from a family member’s bank account, where you share a surname
Third-party Person-to-Person payments for an amount less than $4,000

General restriction: third-party payments are supported in most states, except New York and Texas.

Refer here for cutoffs and processing times.
Refer here for payment tracking identifiers.

Request / Response Examples

Create a USD External Account to use as a Transfer or Liquidation Address offramp destination.
Create a USD Virtual Account to onramp funds using a unique account and routing number.

The examples below include // comments for readability. Strip these (and any trailing commas) before sending — they are not valid JSON and will cause a parse error if sent as-is.

External Account
Virtual Account
Transfer Onramp
Transfer Offramp

Request

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"
  }
}'

Response

{
    "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"
}

Request

curl --request POST \
  --url https://api.bridge.xyz/v0/customers/<customer_id>/virtual_accounts \
  --header 'Content-Type: application/json' \
  --header 'Api-Key: <Api-Key>' \
  --header 'Idempotency-Key: <Unique Idempotency Key>' \
  --data '
{
  // 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"
  },
  // Optional developer fee to monetize on transactions (percent-based; see "Developer fees" above).
  "developer_fee_percent": "1.0"
}'

Response

{
    "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"
    }
}

ACH
Same Day ACH
Wire

Request

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"
  },
  // destination object tells Bridge where to send funds to.
  // can also be fiat or crypto
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  }
}'

Response

{
  "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"
  },
  // Important: your customer must follow the source deposit instructions exactly.
  "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" // appears once the transfer is complete
  },
  "created_at": "2023-05-05T19:39:14.316Z",
  "updated_at": "2023-05-05T19:39:15.231Z"
}

Request

curl --request POST \
  --url https://api.bridge.xyz/v0/transfers \
  --header 'Api-Key: <API Key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <Unique Idempotency Key>' \
  --data '
{
  "amount": "10.0",
  "on_behalf_of": "cust_alice",
  "developer_fee": "0.5",
  // Note: Bridge does not validate or reject payments when payment_rail is
  // specified as ach_same_day but the deposit actually arrives via ACH or Wire.
  "source": {
    "payment_rail": "ach_same_day",
    "currency": "usd"
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  }
}'

Response

{
  "id": "transfer_124",
  "state": "awaiting_funds",
  "on_behalf_of": "cust_alice",
  "amount": "10.0",
  "developer_fee": "0.5",
  "source": {
    "payment_rail": "ach_same_day",
    "currency": "usd"
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  },
  "source_deposit_instructions": {
    "bank_account_number": "123456789",
    "bank_routing_number": "101019644",
    "amount": "10.0",
    "currency": "usd",
    "deposit_message": "BVI8depositmessage"
  },
  "created_at": "2023-05-05T19:39:14.316Z",
  "updated_at": "2023-05-05T19:39:15.231Z"
}

Request

curl --request POST \
  --url https://api.bridge.xyz/v0/transfers \
  --header 'Api-Key: <API Key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <Unique Idempotency Key>' \
  --data '
{
  "amount": "10.0",
  "on_behalf_of": "cust_alice",
  "developer_fee": "0.5",
  // Note: Bridge does not validate or reject payments when payment_rail is
  // specified as wire but the deposit actually arrives via ACH.
  "source": {
    "payment_rail": "wire",
    "currency": "usd"
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  }
}'

Response

{
  "id": "transfer_125",
  "state": "awaiting_funds",
  "on_behalf_of": "cust_alice",
  "amount": "10.0",
  "developer_fee": "0.5",
  "source": {
    "payment_rail": "wire",
    "currency": "usd"
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  },
  "source_deposit_instructions": {
    "bank_account_number": "123456789",
    "bank_routing_number": "101019644",
    "amount": "10.0",
    "currency": "usd",
    "deposit_message": "BVI9depositmessage"
  },
  "created_at": "2023-05-05T19:39:14.316Z",
  "updated_at": "2023-05-05T19:39:15.231Z"
}

Wire
ACH
Same Day ACH
FedNow ⚡️

Request

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" // up to 140 characters; validated as 4 lines of 35 characters per Fedwire standard
  }
}'

Request

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)
  }
}'

Request

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)
  }
}'

FedNow offramps are currently in beta. Access is by invitation. Join the waitlist to be notified when access opens to your account.

Eligibility check: not every bank account can receive FedNow. Before sending, check the destination External Account’s payment_rails.supported array — only send payment_rail: "fednow" if "fednow" appears in that list. See the full example below.

Request

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.5",
  "on_behalf_of": "cust_1234",
  "source": {
    "currency": "usdc",
    "payment_rail": "bridge_wallet",
    "bridge_wallet_id": "bw_1234"
  },
  "destination": {
    "amount": "100.00",
    "currency": "usd",
    "payment_rail": "fednow",
    "external_account_id": "ea_1234"
  }
}'

Response

{
  "id": "transfer_abc123",
  "state": "payment_submitted",
  "on_behalf_of": "cust_1234",
  "source": {
    "currency": "usdc",
    "payment_rail": "bridge_wallet",
    "bridge_wallet_id": "bw_1234"
  },
  "destination": {
    "currency": "usd",
    "payment_rail": "fednow",
    "external_account_id": "ea_1234",
    "end_to_end_id": "E2E20260811001"
  },
  "receipt": {
    "initial_amount": "100.00",
    "developer_fee": "0.50",
    "exchange_fee": "0.00",
    "final_amount": "99.50"
  },
  "created_at": "2026-08-11T14:00:00.000Z",
  "updated_at": "2026-08-11T14:00:05.000Z"
}

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 onramps and offramps are 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.
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? Use the payment_received_rail field on the Transfer source, or the payment_rail field on the Virtual Account source. For FedNow onramps, 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.

Offramps (Beta)

FedNow offramps are currently in beta. Reach out to sales to join the waitlist and we’ll open spots as we can!

Register a USD external account

curl --request POST \
  --url https://api.bridge.xyz/v0/customers/<customer-id>/external_accounts \
  --header 'Api-Key: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --header 'Idempotency-Key: ea-7' \
  --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"
  }
}'

The response includes a payment_rails object indicating which USD payment rails are supported for this account. Check payment_rails.supported before routing a payment on a given rail — see the eligibility note above.

{
    "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",
    "payment_rails": {
        "supported": ["ach", "ach_same_day", "fednow"],
        "unsupported_reasons": {
            "wire": "beneficiary address is not valid for wire"
        }
    }
}

If the external account doesn’t support FedNow, the payment_rails object will look as follows. You can view all FedNow participating institutions here: https://www.frbservices.org/financial-services/fednow/organizations.

  "payment_rails": {
    "supported": ["ach", "ach_same_day"],
    "unsupported_reasons": {
      "wire": "beneficiary address is not valid for wire",
      "fednow": "routing number does not support FedNow",
    },
  },

Create an offramp

To create a FedNow offramp, set destination.payment_rail to fednow.

curl --request POST \
  --url https://api.bridge.xyz/v0/transfers \
  --header 'Api-Key: <API Key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <Unique Key>' \
  --data '
{
  "amount": "100.00",
  "on_behalf_of": "cust_12345", // id of the customer who owns the wallet and the external account
  "source": {
    "payment_rail": "bridge_wallet",
    "currency": "usdc",
    "bridge_wallet_id": "wallet_abc123" // id of the bridge wallet with funds
  },
  "destination": {
    "payment_rail": "fednow",
    "currency": "usd",
    "external_account_id": "ext_account_xyz789" // id of the customer bank account
  }
}'

Set up refunds before going live. FedNow eligibility only reflects whether a bank can receive the payment rail — it doesn’t guarantee the receiving bank will accept every individual transaction. If a recipient bank rejects a FedNow offramp, Bridge needs refund handling configured on your account to route the funds back to your customer. Skipping this step means a rejected payment has no path back to the sender.

Introduction

Guides

USD integration guide

🇺🇸 What we support

Logistics

Request / Response Examples

ACH

Same Day ACH

Wire

FedNow ⚡️

Offramps (Beta)

Register a USD external account

Create an offramp

​🇺🇸 What we support

​Logistics

​Request / Response Examples

​Related APIs

​ACH

​Same Day ACH

​Wire

​FedNow ⚡️

​Offramps (Beta)

​Register a USD external account

​Create an offramp

🇺🇸 What we support

Logistics

Request / Response Examples

Related APIs

ACH

Same Day ACH

Wire

FedNow ⚡️

Offramps (Beta)

Register a USD external account

Create an offramp