USD integration guide

On and offramp with USD using Wire, ACH, and Same Day ACH

🇺🇸 What we support

• Virtual Accounts - Deposit USD via ACH or Wire and receive payments from 3rd party businesses.
• Transfers - Onramp USD via Wire, ACH, or Same Day ACH as a 1st party or from 3rd party businesses, offramp to any recipient.
• Liquidation Addresses - Offramp from stablecoin or crypto to USD via Wire or ACH.
• Supported Countries - 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 for cutoffs and processing times.
• Refer here for payment tracking identifiers.

---

Request / Response Examples

Related APIs

• 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.

External Account

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

Virtual Account

Request

curl --location --request POST '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-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%.
}'

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

Transfer Onramp

ACH

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",
  },
  # deposit 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"
  },
  # 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"
}

Same Day ACH

Request

curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <Unique 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",
  },
}'

Wire

Request

curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <Unique 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",
  },
}'

Transfer Offramp

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

ACH

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

Same Day ACH

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

---

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.