In order to provide flexibility in the behavior of Transfers, Bridge offers advanced features that can be enabled on a per Transfer basis. Each of the features described below can be enabled using the features field of the create Transfer endpoint. Any features is enabled for a Transfer will also be included in the features section of API responses as well.

These features are intended to make common Transfer patterns easier for developers to implement. The Transfers API defaults to requiring all info to be specified when creating the Transfer, but these features can be used to provide more flexibility if a field like the amount or sending address are not known at creation time.

Flexible Amount

To create a Transfer that will match any funds sent using the source deposit instructions regardless of amount, use the flexible_amount feature.

Because the amount is not known ahead of time, Transfers with the flexible_amount feature only support a percentage based developer_fee_percent. Flexible amount Transfers do not support setting a fixed developer_fee.

Note: Static templates have this feature enabled automatically if no amount is provided when they are created.

Request

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": "wire",
    "currency": "usd",
  },
  "destination": {
    "payment_rail": "ethereum",
    "currency": "usdc",
    "to_address": "0xdeadbeef",
  },
  "developer_fee_percent": "1.0", // A 1% developer fee
  "features": {
    "flexible_amount": true,
  }
}'

Response

{
  "id": "flexible_transfer_789",
  "state": "awaiting_funds",
  "on_behalf_of": "cust_alice",
  "source": {
    "payment_rail": "wire",
    "currency": "usd"
  },
  "destination": {
    "payment_rail": "polygon",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  },
  "source_deposit_instructions": {
    // ...Bridge banking details
    "currency": "usd",
    "deposit_message": "BVI7depositmessage",
  },
 "features": {
    "flexible_amount": true
  },
  "created_at": "2023-05-05T19:39:14.316Z",
  "updated_at": "2023-05-05T19:39:15.231Z"
}

After Bridge receives funds and matches them to the Transfer, the amount will be included in API responses:

{
  "id": "transfer_instance_456",
  "state": "payment_processed",
  "on_behalf_of": "cust_alice",
  "amount": "1337.0",
  "source": {
    "payment_rail": "wire",
    "currency": "usd",
    "bank_beneficiary_name": "Pheobe Bridgers",
    "bank_routing_number": "1234567890",
    "bank_name": "Gringotts",
    "imad": "20240324PPMSXT759764",
  },
  "destination": {
    "payment_rail": "polygon",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  },
  "source_deposit_instructions": {
    // ...Bridge banking details
    "currency": "usd",
    "deposit_message": "BVI7depositmessage",
  },
  "receipt": {
    "initial_amount": "1337.0",
    "developer_fee": "0.0",
    "exchange_fee": "0.0",
    "subtotal_amount": "1337.0",
    "url": "https://dashboard.bridge.xyz/transaction/4181f2d9-7647-4249-b340-068d6ebdf8a2/receipt/c571e913-1f94-457e-a158-4249526b847b",
    gas_fee: "0.0",
    final_amount: "1337.0",
    destination_tx_hash: "0x628ec487573fc503c3cad909bcd271d29a906257dc19a27db8cc82f213cf95e2",
  },
  "features": {
    "flexible_amount": true
  },
  "created_at": "2024-10-06T19:39:14.316Z",
  "updated_at": "2024-10-06T19:39:15.231Z"
},

Static Templates

The static template feature allows the creation of a Transfer template through the API. The response includes standing deposit instructions that can be used multiple times to send funds to the configured destination. The source deposit instructions will remain the same indefinitely including the source memo / wire message / SEPA reference.

Every time that funds match the template, Bridge will create a new Transfer record in the API. The id of the template will never change. Transfer instances created from that template will each have unique ids.

Note: Providing an amount is optional but allowed when creating a Static Template. If no amount is provided, the Transfer will automatically have the flexible_amount feature enabled as well.

Request

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": "sepa",
    "currency": "eur",
  },
  "destination": {
    "payment_rail": "polygon",
    "currency": "usdc",
    "to_address": "0xdeadbeef",
  },
  "features": {
    "static_template": true,
  }
}'

Response

{
  "id": "transfer_template_123",
  "state": "awaiting_funds",
  "on_behalf_of": "cust_alice",
  "source": {
    "payment_rail": "sepa",
    "currency": "eur"
  },
  "destination": {
    "payment_rail": "polygon",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  },
  "source_deposit_instructions": {
    "payment_rail": "sepa",
    "currency": "eur",
    "deposit_message": "BRGEXAMPLEMEMO",
    "iban": "IE57MODR99035505123456",
    "bic": "MODRIE22XXX",
    "account_holder_name": "Bridge Building Sp.z.o.o.",
    "bank_name": "Modulr Finance B.V.",
    "bank_address": "Strawinskylaan 4117, 1077 ZX Amsterdam, The Netherlands"
  },
 "features": {
    "static_template": true,
    "flexible_amount": true
  },
  "created_at": "2023-05-05T19:39:14.316Z",
  "updated_at": "2023-05-05T19:39:15.231Z"
}

This template will remain in the awaiting_funds state unless canceled. Each time Bridge receives funds and matches them to the template, Bridge will expose a new Transfer instance based on the templated configuration.

Fetching Transfers after funds received

{
  "count": 2,
  "data": [
    {
      "id": "transfer_instance_456",
      "state": "payment_processed",
      "on_behalf_of": "cust_alice",
      "amount": "1234.0",
      "source": {
        "payment_rail": "sepa",
        "currency": "eur",
      },
      "destination": {
        "payment_rail": "polygon",
        "currency": "usdc",
        "to_address": "0xdeadbeef"
      },
      "source_deposit_instructions": {
        "payment_rail": "sepa",
        "currency": "eur",
        "deposit_message": "BRGEXAMPLEMEMO",
        "iban": "IE57MODR99035505123456",
        "bic": "MODRIE22XXX",
        "account_holder_name": "Bridge Building Sp.z.o.o.",
        "bank_name": "Modulr Finance B.V.",
        "bank_address": "Strawinskylaan 4117, 1077 ZX Amsterdam, The Netherlands"
      },
      "receipt": {
        "initial_amount": "1234.0",
        "developer_fee": "0.0",
        "exchange_fee": "0.0",
        "subtotal_amount": "1234.0",
        "url": "https://dashboard.bridge.xyz/transaction/4181f2d9-7647-4249-b340-068d6ebdf8a2/receipt/c571e913-1f94-457e-a158-4249526b847b",
        gas_fee: "0.0",
        final_amount: "1234.0",
        destination_tx_hash: "0x628ec487573fc503c3cad909bcd271d29a906257dc19a27db8cc82f213cf95e2",
      },
     "features": {
        "static_template": true,
        "flexible_amount": true
      },
      "created_at": "2024-10-06T19:39:14.316Z",
      "updated_at": "2024-10-06T19:39:15.231Z"
    },
    {
      "id": "transfer_template_123",
      "state": "awaiting_funds",
      "on_behalf_of": "cust_alice",
      "source": {
        "payment_rail": "sepa",
        "currency": "eur",
      },
      "destination": {
        "payment_rail": "polygon",
        "currency": "usdc",
        "to_address": "0xdeadbeef"
      },
      "source_deposit_instructions": {
        "payment_rail": "sepa",
        "currency": "eur",
        "deposit_message": "BRGEXAMPLEMEMO",
        "iban": "IE57MODR99035505123456",
        "bic": "MODRIE22XXX",
        "account_holder_name": "Bridge Building Sp.z.o.o.",
        "bank_name": "Modulr Finance B.V.",
        "bank_address": "Strawinskylaan 4117, 1077 ZX Amsterdam, The Netherlands"
      },
     "features": {
        "static_template": true,
        "flexible_amount": true
      },
      "created_at": "2024-10-05T19:39:14.316Z",
      "updated_at": "2024-10-05T19:39:15.231Z"
    }
  ]
}

{
  "id": "transfer_instance_456",
  "state": "payment_processed",
  "on_behalf_of": "cust_alice",
  "amount": "1234.0",
  "source": {
    "payment_rail": "sepa",
    "currency": "eur",
  },
  "destination": {
    "payment_rail": "polygon",
    "currency": "usdc",
    "to_address": "0xdeadbeef"
  },
  "source_deposit_instructions": {
    "payment_rail": "sepa",
    "currency": "eur",
    "deposit_message": "BRGEXAMPLEMEMO",
    "iban": "IE57MODR99035505123456",
    "bic": "MODRIE22XXX",
    "account_holder_name": "Bridge Building Sp.z.o.o.",
    "bank_name": "Modulr Finance B.V.",
    "bank_address": "Strawinskylaan 4117, 1077 ZX Amsterdam, The Netherlands"
  },
  "receipt": {
    "initial_amount": "1234.0",
    "developer_fee": "0.0",
    "exchange_fee": "0.0",
    "subtotal_amount": "1234.0",
    "url": "https://dashboard.bridge.xyz/transaction/4181f2d9-7647-4249-b340-068d6ebdf8a2/receipt/c571e913-1f94-457e-a158-4249526b847b",
    gas_fee: "0.0",
    final_amount: "1234.0",
    destination_tx_hash: "0x628ec487573fc503c3cad909bcd271d29a906257dc19a27db8cc82f213cf95e2",
  },
  "features": {
    "static_template": true,
    "flexible_amount": true
  },
  "created_at": "2024-10-06T19:39:14.316Z",
  "updated_at": "2024-10-06T19:39:15.231Z"
}

Allow Any From Address

By default, when creating a Transfer sourced from crypto rails (i.e. an offramp or crypto-to-crypto Transfer), Bridge requires the sending address of the wallet sending the funds to be specified upon creation time. For some use cases like consumer sending funds from an exchange, this is difficult or impossible to know ahead of time.

To support these use cases, Bridge has the allow_any_from_address feature. If this feature is enabled, no from_address needs to be specified at Transfer creation time and any funds sent to the source deposit instructions will be matched regardless of the from_address.

"features": {
  "allow_any_from_address": true,
}