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. Developer fees may be specified as a percentage, using the developer_fee_percent field, or for more granular control, fee_config may be used (In Beta, available by request only. See below.) 
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)

​
Developer Fee Configuration [Beta feature]

Developer fees may now additionally be configured with both a flat fee and per-rail options using the new fee_config field. Available by request only. Contact Bridge to enable this feature for your developer account. 
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"
  },
  "fee_config": {
      "source": {
          "wire": {
              "fee_amount": "10.0" // Flat 10 in source currency
            }
        }
    }
}'
Validations
  • developer_fee_percent and fee_config may not both be included in a request body.
  • Updating fee_config performs a full replacement of the existing fee configuration. Include your entire desired configuration in each update.
  • Updating developer_fee_percent clears fee_config, and updating fee_config clears developer_fee_percent.
  • fee_config.source accepts default and payment rail keys such as wire, ach_push, and spei.
  • If the calculated fee exceeds the deposit amount, Bridge will cap the fee at the full deposit amount.
Fee Calculation It is valid to configure both fee_amount and fee_percent. In this case, the flat fee will be deducted from the deposit amount, and percentage fee taken on the remainder. Minimum or maximum fees will look at the resulting combined flat + percentage amount. If the developer fee to be taken exceeds the deposit amount, the entire deposit amount will be taken as developer fee. Let’s examine several examples to illustrate how fees are calculated. All deposits will be made to a virtual account with the following fee_config (note this is an incomplete request body, showing only the fee_config) 
  ...
  "fee_config": {
      "source": {
          "wire": {
              "fee_amount": "10.0",
              "fee_percent": "20.0",
              "minimum_fee": "1.0",
              "maximum_fee": "25.0"
            }
        }
    }
Deposit Amountfee_amountfee_percentLimit AppliedFinal Fee
100.00 USD10.00 USD20% of 90.00 USD = 18.00 USDmaximum_fee caps 28.00 USD to 25.00 USD25.00 USD
20.00 USD10.00 USD20% of 10.00 USD = 2.00 USDNone12.00 USD
5.00 USD10.00 USD requestedNot applied because the flat fee exceeds the depositDeposit amount cap limits the fee to the full deposit5.00 USD

​
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%).