Skip to main content

​
Introduction

Bridge allows developers to collect custom, per-transaction fees from their users. These developer fees are automatically withheld from the customer’s transaction amount and set aside in a ledger reserved for you. Fees are settled and paid out monthly on the 5th of each month to your configured external account. Bridge will collect developer fees in the original transaction currency but will always pay out in USD. You can use the Configure a fee External Account API to configure the external account you want to get paid out in.
Fees are optional. Leaving the developer_fee or developer_fee_percent field blank is treated as a fee of 0.0.

​
Transfers

​
Transfers with fixed amounts

For transfers with a fixed amount, Bridge supports developer fees expressed in USD (as a fixed decimal amount). You can set developer_fee in the API 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": "50.0",
  "on_behalf_of": "cust_alice",
  "developer_fee": "0.5", # developer fee
  "source": {
    "payment_rail": "ach",
    "currency": "usd",
    "external_account_id": "external_account_123",
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef",
  },
}'
In this example:
  • Customer sends: $50.00
  • Developer fee withheld: $0.50
  • Amount delivered to destination: $49.50
Examples
Input amountDeveloper FeeNet to DestinationResult
99.990.9999.00✅ valid
21.205.1916.01✅ valid
5.005.000❌ rejected
5.005.01-❌ rejected
Validations
  • Currency: developer_fee is denominated in USD, not a percentage.
  • Per-Transaction: You specify the fee with each request — allowing full control.
  • Must have sufficient minimum: You cannot deduct more than the total transaction amount. After we deduct the fee, there must be enough for the transaction minimum. Refer Transaction Minimums.
  • Precision: Up to 2 decimal places (e.g., 10.99 is valid, 10.999 is not).
  • Destination amount: Always equal to amount - developer_fee.
  • The fee is only valid on transactions where funds are transferred by Bridge (not to Bridge)

​
Transfers with flexible amounts

When you’re creating Transfers with flexible_amount enabled, only percentage-based fees are supported via the developer_fee_percent field. 
curl --location --request POST 'https://api.bridge.xyz/v0/transfers' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--data-raw '{
  "on_behalf_of": "cust_alice",
  "source": {
    "payment_rail": "ach",
    "currency": "usd",
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef",
  },
  "developer_fee_percent": "2.0", // A 2% developer fee
  "features": {
    "flexible_amount": true,
  }
}'
For example:
  • Customer sends: $100.00
  • Developer fee withheld: $2
  • Amount delivered to destination: $98

​
Virtual Accounts

When using Virtual Accounts, the exact amount of incoming funds is not known ahead of time. As a result, developer fees must be specified as a percentage, using the developer_fee_percent field. 
curl --location --request POST 'https://api.bridge.xyz/v0/customers/cust_alice/virtual_accounts' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <Api-Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--data-raw '{
  "source": {
    "currency": "usd",
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "address": "0xDEADBEEF"
  },
  "developer_fee_percent": "1.0" // 1%.
}'
Validations
  • The fee is always in the source currency.
  • The fee must be less than the customer’s transaction amount.
  • The fee has maximum 5 digits of precision, i.e. 0.00119 is allowed, but 0.0000001 is not
  • The fee is optional. If developer_fee_percent is blank, then it’s equivalent to the fee being set to 0.0
  • The fee is only valid on transactions where funds are transferred by Bridge (not to Bridge)

​
Liquidation Address

​
Global default developer fee percent

To set a global fee that applies to all Liquidation Addresses, use the developer fees API. 
curl --location --request POST 'https://api.bridge.xyz/v0/developer/fees' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--data-raw '{
  "default_liquidation_address_fee_percent": 0.5,
}'
In this example:
  • If a user deposits $50.00, they receive $49.75
  • $0.25 (0.5%) is credited to the developer’s fee ledger

​
Per address developer fee percent

To override the default for a specific address, include custom_developer_fee_percent when creating a Liquidation Address. 
curl --location --request POST 'https://api.bridge.xyz/v0/customers/cust_alice/liquidation_addresses' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <Api-Key>' \
--header 'Idempotency-Key: <Unique Idempotency Key>' \
--data-raw '{
  "chain": "ethereum",
  "currency": "usdc",
  "external_account_id": "ea_alice_bofa"
  "destination_wire_message": "alice_wire_123"
  "destination_payment_rail": "wire",
  "destination_currency": "usd",
  "custom_developer_fee_percent": "10.2",
  "created_at": "2023-11-22T21:31:30.515Z",
  "updated_at": "2023-11-22T21:31:30.515Z"
}'
custom_developer_fee_percent must be a positive decimal (e.g., 10.2 means 10.2%).