Skip to main content
POST
Preview a withdrawal

Integration guide

Authorizations

x-app-id
string
header
required

Your application ID. Required on app-tier and user-tier routes. Omitted on routes that authenticate with x-app-api-key only.

Authorization
string
header
required

JWT access token from POST /auth/verify. Required with x-app-id on user routes. On the smart-route quote it is optional and turns a preview into an executable quote.

Body

application/json
amountRaw
string
required

Amount to deliver, as a positive integer string in the destination token's atomic units (6 decimals, so 1000000 = 1 USDC; 18 decimals on BNB Chain). Minimum is one whole token. Same-chain transfers debit exactly this. A bridge leg debits 2% plus a flat $0.10 more (a swap leg 2% plus $0.04) to cover its fee, and when the live fee is lower the recipient gets more than this amount; the preview's receiveAmountRaw is the estimate. To withdraw everything, send max: true.

Pattern: ^[1-9][0-9]*$
tokenSymbol
enum<string>
required

Stable-coin symbol the withdrawal is denominated in.

Available options:
USDC,
USDC.e,
USDT
destinationAddress
string
required

Recipient address. EVM destinations: 0x-prefixed 20-byte hex. Solana: base58 (32–44 chars).

Pattern: ^(0x[a-fA-F0-9]{40}|[1-9A-HJ-NP-Za-km-z]{32,44})$
destinationChainId
integer
required

Chain ID where the recipient address should receive funds.

Required range: x >= 1
requestId
string<uuid>

Optional idempotency key for an exact-amount transfer. Reuse with the identical body to recover a lost response. Not combined with max.

max
boolean

Withdraw-max intent: cap amountRaw to the deliverable maximum instead of rejecting it. Send the full balance as amountRaw with this flag to empty the balance.

signingAddress
string

Self-custody: the linked EVM wallet that owns and signs this withdrawal. Omit for managed custody.

Required string length: 42
approveMode
enum<string>

Self-custody only (ignored without signingAddress): what the signing wallet can sign. Send the same value to the quote, preview and withdraw. sponsored (default): the wallet can sign an EIP-7702 authorization and Calibur batch, so every source is available. user_broadcast: it cannot (e.g. MetaMask). The withdrawal still never asks it to send a transaction or hold gas; sources that would need a batch (an approve, a same-chain swap, or a same-chain transfer of anything but native Circle USDC; decided by token) are left out of Max, preview and selection. A same-chain native USDC transfer is then two EIP-3009 signatures (amount less the network fee, and the fee).

Available options:
sponsored,
user_broadcast

Response

200

receiveAmountRaw
string | null
required

Estimated amount delivered. null when unviable. Integer string in the destination token's atomic units (6 decimals, so 1000000 = 1 USDC; 18 decimals on BNB Chain).

feeRaw
string | null
required

Estimated fee, deducted from the withdrawn amount (amount in minus amount delivered). Integer string in the destination token's atomic units (6 decimals, so 1000000 = 1 USDC; 18 decimals on BNB Chain).

relayFeeRaw
string | null
required

Bridge provider part of feeRaw; currently equal to it. Integer string in the destination token's atomic units (6 decimals, so 1000000 = 1 USDC; 18 decimals on BNB Chain).

networkFeeRaw
string | null
required

Reserved for a separate network fee; currently always null.

pricingStatus
enum<string>
required

quoted: the withdrawal can be routed. unviable: it cannot; see unviableReason.

Available options:
quoted,
unviable
quoteExpiresAt
string | null
required

ISO-8601 time the quote expires (60 seconds after quoting).

unviableReason
string | null
required

Readable reason when unviable: insufficient balance, too small to cover fees, no liquidity, or no safe route.

maxDeliverableRaw
string | null
required

Set only when the request exceeds the balance: the largest amountRaw that can be routed. It assumes the full fee buffer per leg (2% plus a flat $0.10 per bridge, 2% plus $0.04 per swap), so the amount actually received is usually higher (see receiveAmountRaw on a quoted preview). Integer string in the destination token's atomic units (6 decimals, so 1000000 = 1 USDC; 18 decimals on BNB Chain).