---
url: /docs/transfer-quotes.md
description: >-
  Create a transfer quote to lock in the source wallet, destination address,
  token, network, and amount before executing a transfer.
---

A transfer quote locks in the details of a stablecoin move before you execute it: the source managed wallet, the destination address, the token, the network, and the amount. Executing the [transfer](/docs/transfers) simply consumes this quote, it does not take any new parameters of its own.

`customer_token` must match `sender_token`, except for a [USDC and USDT swap](#usdc-and-usdt-swap) and for `USDC` and `EURC` on Base, which [convert into each other](#usdc-and-eurc-conversion-on-base). `customer_network` must match the source wallet's own network, except when both tokens are `USDC` (a USDC transfer can cross chains using [Circle CCTP v2](#cross-chain-usdc-transfers-circle-cctp-v2)) and for a [USDC and USDT swap](#usdc-and-usdt-swap) between the supported networks.

## How it works

* **Source**: a managed wallet (`wallet_id`, `bl_...`) that holds the stablecoin balance. This is the only supported source, unlike payouts, which can also draw from an external blockchain wallet.
* **Destination**: any blockchain address, `customer_wallet_address`, normally on the same network as the source wallet; a USDC transfer can target a different [CCTP v2 network](#cross-chain-usdc-transfers-circle-cctp-v2) instead. It does not need to belong to a BlindPay customer or wallet, it can be any address the recipient controls.
* **Expiry is 5 minutes**, fixed and not configurable. A transfer quote is meant to be executed immediately after creation, not held for later use: call [create a transfer](/docs/transfers) right after creating the quote, and request a new one if `expires_at` passes.

`expires_at` is returned in epoch milliseconds.

## Cross-chain USDC transfers (Circle CCTP v2)

When both `sender_token` and `customer_token` are `USDC`, `customer_network` can be a different network than the source wallet's. BlindPay bridges the move using [Circle's Cross-Chain Transfer Protocol v2](https://developers.circle.com/cctp): USDC is burned on the source chain and an equivalent amount is minted on the destination chain once Circle attests the burn.

Supported networks are Ethereum, Polygon, Base, Arbitrum, and Arc on a production instance; on a development instance, the matching testnets (Ethereum Sepolia, Polygon Amoy, Base Sepolia, Arbitrum Sepolia, Arc Testnet), using real testnet USDC rather than USDB, since CCTP can only move native USDC. Both the source and destination network must be on the same side of that mainnet/testnet boundary. Requesting a token other than USDC across networks returns `cross_chain_transfers_only_support_usdc`; requesting a network pair CCTP v2 does not support returns `cctp_route_not_supported`.

The quote itself is unaffected by the bridge: amounts stay 1:1 and BlindPay adds no fee on top, exactly like a same-network transfer. Any [partner fee](#partner-fees) you set applies the same way on both. Circle's protocol deducts its own small fee (typically a fraction of a cent up to a few cents, a few basis points of the amount) from the amount minted on the destination chain; this is not reflected in `receiver_amount` or any other quote field. Cross-chain transfers typically settle in 8 to 20 seconds; transfers sourced from Polygon settle in around 8 seconds either way.

Solana, Stellar, Tron, and Tempo are not part of cross-chain transfers yet; same-network moves on those chains are unaffected.

## USDC and USDT swap

On a production instance, a transfer can swap `USDC` into `USDT` or `USDT` into `USDC`: set `sender_token` to one and `customer_token` to the other. The swap can also change network on the way, so the source wallet's network and `customer_network` don't have to match. Supported routes:

| `sender_token` | Source wallet network | `customer_token` | `customer_network` |
| --- | --- | --- | --- |
| `USDC` | `polygon`, `base`, or `arbitrum` | `USDT` | `polygon`, `ethereum`, or `tron` |
| `USDT` | `polygon` | `USDC` | `polygon`, `base`, `arbitrum`, or `ethereum` |
| `USDT` | `polygon` | `USDT` | `tron` |

USDT from Polygon to Tron keeps the token and only changes network: it is priced 1:1 before the swap fee. On `tron`, `customer_wallet_address` can be any Tron address; there are no managed wallets on Tron, so a swap can deliver USDT there but not start from it. Any other pair of tokens and networks is not a swap and follows the usual rules: a different network fails with `cross_chain_transfers_only_support_usdc`, the same network with `sender_and_customer_tokens_must_be_the_same`. Swaps are not available on development instances.

The quote is priced live by BlindPay's liquidity provider. `commercial_quotation` is the provider's rate and `blindpay_quotation` the rate applied to the transfer, after BlindPay's swap fee: both are units of `customer_token` per `sender_token`, times 100, so `99.97` means 1 USDC = 0.9997 USDT. The swap fee is 3 basis points (0.03%) by default and can be set per instance by BlindPay. Amounts are rounded down to the cent, so on small amounts `blindpay_quotation` can sit a few basis points further from `commercial_quotation` than the fee alone. `sender_amount` is in `sender_token` and `receiver_amount` in `customer_token`; any [partner fee](#partner-fees) is charged in `sender_token` before swapping.

The smallest swap is 100 USDC, measured on the USDC side whichever direction you swap. A smaller request fails with `400` `fx_amount_below_minimum`. If the route is temporarily unavailable at the provider, the quote fails with `400` `swap_route_not_supported`.

A swap settles in a few minutes, usually 3 to 5, and can take up to about 20. The destination receives exactly `receiver_amount`. If the swap can't be executed at a rate that covers `receiver_amount`, nothing is swapped: the funds go back to the source wallet and the transfer ends `failed`. See [swap execution](/docs/transfers#usdc-and-usdt-swap) for the legs and webhooks.

## USDC and EURC conversion on Base

A transfer can convert between `USDC` and `EURC` when the source wallet and `customer_network` are both `base`: set `sender_token` to one and `customer_token` to the other. On a development instance the same conversion runs between `USDB` and `EURB`, BlindPay's test tokens, on `base_sepolia`. No other network or token pair converts.

The quote is priced live by BlindPay's liquidity provider. `commercial_quotation` and `blindpay_quotation` carry the rate as units of `customer_token` per `sender_token`, times 100: `89.1` means 1 USDC = 0.891 EURC. `sender_amount` is in `sender_token` and `receiver_amount` in `customer_token`; any [partner fee](#partner-fees) is charged in `sender_token` before converting.

The smallest conversion is 100 USDC, measured on the USDC side whichever direction you convert, so selling about 90 EURC is enough. A smaller request fails with `400` `fx_amount_below_minimum`.

Prices move fast, so [executing the transfer](/docs/transfers#usdc-and-eurc-conversion) re-prices it: if the rate moved more than 0.5% against the customer since the quote, the transfer is refused with `409` `fx_rate_moved` and nothing moves. Create a new quote and try again. Otherwise the destination receives exactly `receiver_amount`.

## Prerequisites

You also need a [customer](/docs/kb/kyc) whose `kyc_status` is `approved`, `approved_rfi`, or `compliance_request`, and a [managed wallet](/docs/wallets) holding the stablecoin balance you want to move. This is wider than payins and payouts, which require `approved` or `approved_rfi` only: a customer paused by an open RFI (`compliance_request`) can still move funds already sitting in their managed wallet through a transfer, even though creating a new payin or payout for them stays blocked until the RFI is resolved. Any other `kyc_status` fails with `400` `kyc_not_approved`.

Creating a transfer quote also requires the caller to hold the transaction-create permission on the instance. Dashboard roles that have it: `owner`, `admin`, `finance`, `checker`, and `operations`. A caller without it gets a `403` `user_not_allowed` before `wallet_id` or any other field is checked.

## Request fields

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `wallet_id` | string (`bl_...`) | yes | The managed wallet the funds move out of. Must belong to your instance and not be deleted. |
| `amount_reference` | enum | yes | `sender` or `receiver`. Which side `request_amount` refers to. Only changes the result when a [partner fee](#partner-fees) is set; without one, `sender_amount` and `receiver_amount` both equal `request_amount`. |
| `request_amount` | integer | yes | Amount in minor units, no floats. `$100.00` sends as `10000`. Minimum is `1`. |
| `sender_token` | enum | yes | `USDC`, `USDT`, `USDB`, `EURC`, or `EURB`. Must be a token allowed on the source wallet's network. `EURC` and `EURB` are only available on `base` and `base_sepolia`. |
| `customer_token` | enum | yes | Must equal `sender_token`, except for a [USDC and USDT swap](#usdc-and-usdt-swap) or a [USDC and EURC conversion on Base](#usdc-and-eurc-conversion-on-base). |
| `customer_network` | enum | yes | Must equal the source wallet's own network, unless `sender_token` and `customer_token` are both `USDC` and the pair is a [supported CCTP v2 route](#cross-chain-usdc-transfers-circle-cctp-v2), or the quote is a [USDC and USDT swap](#usdc-and-usdt-swap) on a supported route. |
| `customer_wallet_address` | string | yes | The destination blockchain address, 32 to 64 characters, validated for the target network (see table below). Can be another wallet you created or any external address. |
| `cover_fees` | boolean | yes | Who pays the [partner fee](#partner-fees). `true`: the fee is added on top and the destination receives the full amount. `false`: the fee is deducted from the amount the destination receives. Has no effect without a partner fee. |
| `partner_percentage_fee` | integer | no | Partner percentage fee for this transfer, in hundredths of a percent: `150` is 1.50%, `1000` is 10.00%. `0` to `9900`. Defaults to `0`. |
| `partner_flat_fee` | integer | no | Partner flat fee for this transfer, in minor units of `sender_token`: `50` is 0.50, `1000` is 10.00. `0` to `100000`. Defaults to `0`. |
| `partner_fee_id` | string (`pf_...`) | no | Stored on the quote but not used for the fee amount. Transfers take the fee per request through `partner_percentage_fee` and `partner_flat_fee` instead. |

Address format by network family:

| Network family | Format | Example |
| --- | --- | --- |
| EVM (`ethereum`, `polygon`, `base`, `arbitrum`, `tempo`, and their testnets) | `0x` + 40 hex characters (42 total) | `0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372` |
| `stellar`, `stellar_testnet` | `G` + 55 base32 characters (56 total) | `GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` |
| `solana`, `solana_devnet` | base58, 32 to 44 characters | `11111111111111111111111111111111111111111` |
| `tron` | `T` + 33 base58 characters (34 total) | `TAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA` |

An address that doesn't match the format for `customer_network` fails with `VALIDATION_FAILED` and a message naming the field: `Invalid wallet address for network {network}`.

USDT transfers are currently restricted to Polygon and Solana, a tighter limit than payins and payouts allow for USDT. A [USDC and USDT swap](#usdc-and-usdt-swap) can also deliver USDT on Ethereum and Tron.

## Partner fees

Set `partner_percentage_fee` and `partner_flat_fee` on the quote to charge your customer a fee on this transfer. The fee is set per request: transfers do not read the payin or payout rates of a [partner fee configuration](/docs/learn/partner-fees).

The total partner fee is the percentage fee plus the flat fee. The percentage is applied to the amount it is based on and rounded to the nearest minor unit. Amounts always add up: `sender_amount = receiver_amount + partner_fee_amount`.

| `amount_reference` | `cover_fees` | `sender_amount` (leaves the wallet) | `receiver_amount` (reaches the destination) |
| --- | --- | --- | --- |
| `sender` | `false` | `request_amount` | `request_amount` minus the fee |
| `sender` | `true` | `request_amount` plus the fee | `request_amount` |
| `receiver` | `false` | `request_amount` | `request_amount` minus the fee |
| `receiver` | `true` | Grossed up so that, after the percentage fee on `sender_amount` and the flat fee, exactly `request_amount` is left | `request_amount` |

Examples with `partner_percentage_fee: 1000` (10%) and `partner_flat_fee: 1000` (10.00) on a `request_amount` of `5000` (50.00):

| `amount_reference` | `cover_fees` | `sender_amount` | `receiver_amount` | `partner_fee_amount` |
| --- | --- | --- | --- | --- |
| `sender` | `false` | `5000` | `3500` | `1500` (5.00 + 10.00) |
| `sender` | `true` | `6500` | `5000` | `1500` |
| `receiver` | `true` | `6667` | `5000` | `1667` (10% of 66.67, plus 10.00) |

## Create a transfer quote

```bash [cURL]
curl https://api.blindpay.com/v1/instances/in_000000000000/transfer-quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "wallet_id": "bl_000000000000",
  "amount_reference": "sender",
  "cover_fees": true,
  "request_amount": 1000,
  "sender_token": "USDC",
  "customer_wallet_address": "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372",
  "customer_token": "USDC",
  "customer_network": "polygon",
  "partner_percentage_fee": 150,
  "partner_flat_fee": 50
}'
```

```js [index.js]
const response = await fetch(
  'https://api.blindpay.com/v1/instances/in_000000000000/transfer-quotes',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: 'Bearer YOUR_API_KEY',
    },
    body: JSON.stringify({
      wallet_id: 'bl_000000000000',
      amount_reference: 'sender',
      cover_fees: true,
      request_amount: 1000,
      sender_token: 'USDC',
      customer_wallet_address: '0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372',
      customer_token: 'USDC',
      customer_network: 'polygon',
      partner_percentage_fee: 150,
      partner_flat_fee: 50,
    }),
  },
)

const quote = await response.json()
```

### Examples by transfer type

The quote body is what decides the kind of transfer; [executing it](/docs/transfers#execute-a-transfer) is the same call for all of them.

**Same network, same stablecoin.** USDC from a Base wallet to another Base address:

```bash [cURL]
curl https://api.blindpay.com/v1/instances/in_000000000000/transfer-quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "wallet_id": "bl_000000000000",
  "amount_reference": "sender",
  "cover_fees": false,
  "request_amount": 10000,
  "sender_token": "USDC",
  "customer_token": "USDC",
  "customer_network": "base",
  "customer_wallet_address": "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C"
}'
```

**Different networks, same stablecoin.** USDC from a Base wallet to a Polygon address, bridged with [Circle CCTP v2](#cross-chain-usdc-transfers-circle-cctp-v2):

```bash [cURL]
curl https://api.blindpay.com/v1/instances/in_000000000000/transfer-quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "wallet_id": "bl_000000000000",
  "amount_reference": "sender",
  "cover_fees": false,
  "request_amount": 10000,
  "sender_token": "USDC",
  "customer_token": "USDC",
  "customer_network": "polygon",
  "customer_wallet_address": "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C"
}'
```

**Same network, different stablecoins.** USDC from a Base wallet, delivered as EURC to a Base address. See [USDC and EURC conversion on Base](#usdc-and-eurc-conversion-on-base):

```bash [cURL]
curl https://api.blindpay.com/v1/instances/in_000000000000/transfer-quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "wallet_id": "bl_000000000000",
  "amount_reference": "sender",
  "cover_fees": false,
  "request_amount": 10000,
  "sender_token": "USDC",
  "customer_token": "EURC",
  "customer_network": "base",
  "customer_wallet_address": "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C"
}'
```

```json
{
  "id": "qu_000000000000",
  "expires_at": 1712958191000,
  "commercial_quotation": 86.5,
  "blindpay_quotation": 86.5,
  "receiver_amount": 8650,
  "sender_amount": 10000,
  "partner_fee_amount": 0,
  "partner_percentage_fee": 0,
  "partner_flat_fee": 0,
  "flat_fee": 0
}
```

100.00 USDC leaves the wallet and 86.50 EURC reaches the destination. Swap the two tokens to convert EURC into USDC.

**USDC to USDT swap.** USDC from a Polygon wallet, delivered as USDT to a Polygon address. See [USDC and USDT swap](#usdc-and-usdt-swap):

```bash [cURL]
curl https://api.blindpay.com/v1/instances/in_000000000000/transfer-quotes \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{
  "wallet_id": "bl_000000000000",
  "amount_reference": "sender",
  "cover_fees": false,
  "request_amount": 10000,
  "sender_token": "USDC",
  "customer_token": "USDT",
  "customer_network": "polygon",
  "customer_wallet_address": "0xDD6a3aD0949396e57C7738ba8FC1A46A5a1C372C"
}'
```

```json
{
  "id": "qu_000000000000",
  "expires_at": 1712958191000,
  "commercial_quotation": 100.01,
  "blindpay_quotation": 99.98,
  "receiver_amount": 9998,
  "sender_amount": 10000,
  "partner_fee_amount": 0,
  "partner_percentage_fee": 0,
  "partner_flat_fee": 0,
  "flat_fee": 0
}
```

100.00 USDC leaves the wallet and 99.98 USDT reaches the destination. To swap and change network at once, set `customer_network` to another [supported route](#usdc-and-usdt-swap), for example `ethereum`.

## Response

```json
{
  "id": "qu_000000000000",
  "expires_at": 1712958191000,
  "commercial_quotation": 100,
  "blindpay_quotation": 100,
  "receiver_amount": 1000,
  "sender_amount": 1065,
  "partner_fee_amount": 65,
  "partner_percentage_fee": 150,
  "partner_flat_fee": 50,
  "flat_fee": 50
}
```

| Field | Type | Notes |
| --- | --- | --- |
| `id` | string (`qu_...`) | Pass this as `transfer_quote_id` when you create the transfer. |
| `expires_at` | number | Epoch milliseconds. Execute the transfer before this passes. |
| `commercial_quotation` | number | Rate as units of `customer_token` per `sender_token`, times 100. `100` for every transfer that keeps the same token, including a cross-chain USDC move; the live provider rate for a [USDC and USDT swap](#usdc-and-usdt-swap) or a [USDC and EURC conversion](#usdc-and-eurc-conversion-on-base). |
| `blindpay_quotation` | number | The rate applied to the transfer. Same as `commercial_quotation`, except for a [USDC and USDT swap](#usdc-and-usdt-swap), where BlindPay's swap fee is taken out. |
| `receiver_amount` | number | Amount the destination receives, in minor units. See [partner fees](#partner-fees). |
| `sender_amount` | number | Amount that leaves the source wallet, in minor units: `receiver_amount` plus `partner_fee_amount`. |
| `partner_fee_amount` | number | Total partner fee for this transfer, percentage plus flat. `0` without a partner fee. |
| `partner_percentage_fee` | number | The percentage fee you requested, echoed back. |
| `partner_flat_fee` | number | The flat fee you requested, echoed back. |
| `flat_fee` | number | The flat part of the fee, same as `partner_flat_fee`. |

The `qu_` prefix is shared across payin quotes, payout quotes, and transfer quotes, you can't tell which kind of quote an ID refers to just by looking at it.

## Validation order

The API checks, in this order: the caller has permission to create transactions, the wallet exists and belongs to your instance. A quote on a supported [USDC and USDT swap](#usdc-and-usdt-swap) route goes through the same-network checks below, even when the networks differ, and is exempt from the matching-token rule. Otherwise, if `customer_network` differs from the source wallet's network, the API requires both `sender_token` and `customer_token` to be `USDC` (`cross_chain_transfers_only_support_usdc` otherwise) and the network pair to be a [supported CCTP v2 route](#cross-chain-usdc-transfers-circle-cctp-v2) (`cctp_route_not_supported` otherwise). If `customer_network` matches the source wallet's network, the API instead checks that the token and network are allowed for your instance type, that USDT is only used on Polygon or Solana, and that `sender_token` matches `customer_token` unless the pair is a [USDC and EURC conversion on Base](#usdc-and-eurc-conversion-on-base) (`sender_and_customer_tokens_must_be_the_same` otherwise). Either path then checks that the receiving customer's `kyc_status` is one of `approved`, `approved_rfi`, or `compliance_request`, and finally computes the [partner fee](#partner-fees) (`partner_fee_exceeds_transfer_amount` or `partner_fee_not_supported_on_network`) and, for a swap or conversion, the live rate (`fx_amount_below_minimum` under the 100 USDC minimum, `fx_quote_unavailable` if no price can be obtained, `swap_route_not_supported` if the provider can't settle the swap route). The first failing check is the one returned.

## Testing

There is no dedicated test-amount sentinel for transfer quotes or transfers (unlike payins and payouts, which force outcomes at `$666.00` and `$777.00`). On development instances, transfer quotes go through the same token and network rules as production, restricted to the development tokens and testnets described in [supported chains](/docs/kb/supported-chains). Cross-chain USDC quotes are the exception: on a development instance they use real testnet USDC, not USDB, on the CCTP v2 testnets (Ethereum Sepolia, Polygon Amoy, Base Sepolia, Arbitrum Sepolia), since Circle's protocol can only move native USDC. A USDC and EURC conversion runs between `USDB` and `EURB` on `base_sepolia`, priced by the liquidity provider's sandbox.

## Related

* [Send](/docs/send): the concept overview and scope for transfers
* [Transfers](/docs/transfers): execute a transfer against this quote
* [Managed wallets](/docs/wallets): create and fund the source wallet
* [Payout quotes](/docs/payout-quotes): compare against the quote used for off-ramp payouts
* [Supported chains](/docs/kb/supported-chains): token and network support matrix
