Bridge's Transfer API allows you to seamlessly convert into, out of, and between all forms of a dollar for your customers. At a high level, Transfers require a source and a destination -- both of which can be fiat sources (bank accounts, debit cards etc.) or crypto sources (wallets on chains). The API is generalized and allows you utmost flexibility in moving funds either from fiat to crypto, crypto to crypto, or crypto to fiat. We support a wide range of digital currencies (list) and fiat payment rails (list) to facilitate these transfers.

Note that in some instances, Bridge is unable to directly pull funds from the source account due to the limitation of the financial rail (wires, crypto transfers etc.). In those instances, we return you a set of source_deposit_instructions along with deposit addresses so you can direct your customer to initiate the transfer flow. Once the deposit is initiated and completed by your user, the rest of the transfer will continue as is (without any additional API calls) and the funds will transfer to the passed in destination object.

Read the Developer Fees section on how to set fees.

Please see the Stablecoins and Blockchains page for what is supported, as well as any asset-specific requirements that may apply.

Transfer States

The transfer status refers to the current state of a transfer. There are several possible states that a transfer can be in, including:

• awaiting_funds - Bridge is waiting to receive funds from the customer before it can start to process the transfer. This state only exists when Bridge is awaiting funds from the customer (ex: crypto deposits, wires, ACH push).
• in_review - This is a temporary state that is rarely triggered. If it does occur, it usually resolves automatically within seconds. However, if we are unable to confirm the transaction information by the end of the 24-hour period, we will reach out to the developer with the next steps.
• funds_received - This is an acknowledgment that Bridge has received your funds and is in the process of moving funds on your customer's behalf.
• payment_submitted - This means Bridge has sent the payment and is currently awaiting verification. Depending on the payment rail, this can take anywhere from minutes (Crypto) to hours (Wires) to days (ACH push)
• payment_processed - The transfer has been completed. The funds have been sent to your specified destination.
• undeliverable - Bridge was unable to send the funds to the specified destination. Some examples of this case are an invalid routing number/account number or attempting to send an asset not supported by the destination.
• returned - Bridge has sent the payment, but received notification that it wasn't successful. The funds have been returned to Bridge, and the refund to the sender is in process.
• refunded - The funds for this transfer have been sent back to the original sender.
• canceled - The transfer has been canceled. (Transfers can only be canceled when in the awaiting_funds state).
• error - There was a problem preventing Bridge from processing this transfer. This may require manual intervention to resolve. Please reach out to Bridge if you haven't already been contacted about this transfer.

Please note that a transfer will always progress from awaiting_funds → funds_received → payment_submitted → payment_processed. It can never go backwards.

canceled can only be progressed to from awaiting_funds, and is done by hitting our DELETE /v0/transfers/{transferID} endpoint.

Returning Funds via ACH, Wire, and SEPA

If a customer successfully onramped via ACH, Wire, or SEPA transfer but you would like to return those funds back to the customer, create a new transfer with the following params:

curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": "50.0",
  "on_behalf_of": "cust_alice",
  "source": {
    "payment_rail": "base",
    "currency": "usdc",  // Must be fungible (1:1) with the original deposit currency
    "from_address": "0xdeadbeef"
  },
  "destination": {  
    "payment_rail": "fiat_deposit_return",  // Initiates a return to the original deposit source
    "currency": "usd",                      // Must match the original deposit currency
    "deposit_id": "deposit_123"             // UUID of the original completed deposit
  }
}'

We will respond back with a transfer object that contains source deposit instructions pointing to a crypto address. After you send the correct amount to that address, we will initiate a return of funds back to the customer.

When processing the transfer creation request, we will enforce the following invariants:

• The source currency must be crypto
• The source currency must be an equivalent currency to the original deposit source currency (ex: USDC <> USD)
• The on_behalf_of must match the original deposit customer
• When the original deposit was via ACH, the transfer amount must match the original deposit amount. For Wire and SEPA returns, the transfer amount must be less than or equal to the original deposit amount.
• The request must be within 60 days of the original deposit.