Transfers

Overview

The Transfer API enables seamless conversion to and from fiat and crypto across various supported currencies and rails. At its core, the API is designed to abstract away the complexity of cross-rail and cross-currency money movement, supporting:

Fiat → Crypto
Crypto → Crypto
Crypto → Fiat

Transfers include both a source and a destination, each of which can represent fiat sources or blockchain-based wallets. The API is generalized, composable, and rails-agnostic, allowing for a variety of transfer flows that suit modern financial applications. Refer to supported currencies and rails here: Payment routes.

How transfers work

Depending on the source, Bridge either pulls funds (e.g. Bridge wallet, prefunded account) or generates deposit instructions when a third-party source (e.g. bank, external wallet) is specified. If the funds reside outside of Bridge, you will receive a source_deposit_instructions object in the response payload containing deposit bank details or blockchain addresses. Once your customer completes the deposit, Bridge will automatically detect and process the payment to the destination.

Key Concepts

source: Where the funds come from. This can be a Bridge-controlled wallet, a customer’s crypto wallet, or a fiat source like a bank account.
destination: Where the funds go. This can be any supported rail or chain.
on_behalf_of: Customer identifier. Required when sending/receiving on behalf of a user.
developer_fee or developer_fee_percent: Monetize transfers via fixed or percentage fees. Refer the Developer Fees section on how to set fees.
features: Optional settings to add flexibility (e.g. allow_any_from_address, flexible_amount).
initiation: Payment initiation context for some transfers sourced from Bridge Wallets. Send it in the Create Transfer request only when the source wallet response includes initiation_required: true. Bridge does not include initiation in Create Transfer, Get Transfer, or List Transfers responses.

High Level Flow

For one time transfers, the high level flow is:

You, the developer, will create a transfer specifying the source and destination
1. If the source is a pre-funded account or a bridge wallet, Bridge will pull funds directly from it and skip the above steps — there is no deposit required.
2. If the source is a Bridge Wallet and the wallet response includes initiation_required: true, include an initiation object in the create request.
Bridge will create a transfer object which will include source_deposit_instructions.
You will instruct your customer to follow the source_deposit_instructions.
Your customer will send a deposit following the source_deposit_instructions.
Bridge will match your customer’s deposit to the transfer you created.
Bridge sends money to the destination.

Create Transfer

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

Deposit Instructions

Fiat Deposits

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

Unique Deposit MessageDue to the limitations of fiat rails, we will create a unique identifier for your customer to attach to the deposit they send to Bridge. We rely on that identifier to match customer deposits to your transfer.

Direct your customer to send funds to Bridge’s bank account, with the required amount and currency, and to include the deposit message (starting with BRG). Your customer can include the unique deposit message as the wire memo/message, ACH push description, SEPA reference, or SPEI memo. The deposit message is unique per transfer and including it with your transaction is required for Bridge to process. Crypto Deposits If you receive crypto deposits, remember to configure a crypto return policy! Refer Crypto Return Policies

{
  ...
  "source_deposit_instructions": {
    "payment_rail": "ethereum", # expected blockchain
    "amount": "10.0", # expected amount
    "currency": "usdc", # expected currency
    "from_address": "0xdeadbeef", # expected address for funds to originate from
    "to_address": "0xc0ffee" # Bridge's deposit address to send funds to
  },
   ...
}

In this instance, we need to request your customer to deposit funds to Bridge from their wallet. The source_deposit_instructions object in the response will contain Bridge’s deposit address. You can guide your user to use Metamask or an equivalent wallet to create a blockchain transfer to move funds from their wallet to our deposit address. Memo Based Blockchains

{
  ...
  "source_deposit_instructions": {
    "payment_rail": "stellar",
    "amount": "10.0",
    "currency": "usdc",
    "from_address": "GDUY7JALICESTELLARADDRESS",
    "to_address": "GDUY7JSBRIDGESTELLARDEPOSITADDRESS",
    "blockchain_memo": "123456",
  },
  ...
}

For memo-based blockchains, such as Stellar and Tron, a blockchain_memo will be provided as part of the source_deposit_instructions in the response.

This must be included in the crypto deposit memo. When you forget to include the memo, your off-ramp will experience signficant delays

Transfer Delivery

Once we receive the deposit for your transfer, we will move the funds to the destination. You can use the Transfers API to check the state of the transfer or listen to webhooks.

Orchestration

Wallets

Issuance

Cards

Customers

Logistics

Additional information

Overview

How transfers work

Key Concepts

High Level Flow

Create Transfer

Deposit Instructions

Transfer Delivery

​Overview

​How transfers work

​Key Concepts

​High Level Flow

​Create Transfer

​Deposit Instructions

​Transfer Delivery

Overview

How transfers work

Key Concepts

High Level Flow

Create Transfer

Deposit Instructions

Transfer Delivery