Skip to main content
POST
Withdraw funds

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

withdrawalId
string
required

Withdrawal id. Poll it on the status endpoint.

status
enum<string>
required

Withdrawal status. pending: accepted, not started (the submit response always returns this). bridging: moving funds across chains. transferring: same-chain transfer in progress. Terminal: completed, partial (some sources delivered; see completedAmountRaw), failed.

Available options:
pending,
bridging,
transferring,
completed,
partial,
failed
requested
object
required

What is being withdrawn.

completedAmountRaw
string | null
required

Estimated total delivered by the completed parts. null until a part delivers, so always null on a failed withdrawal. Integer string in the destination token's atomic units (6 decimals, so 1000000 = 1 USDC; 18 decimals on BNB Chain).

destination
object
required

Where the funds are delivered.

legs
object[]
required

Transfers that make up the withdrawal.

expected
object
required

Quote for the withdrawal. null fields unless pricingStatus is quoted.

pricingStatus
enum<string>
required

Fee quote state. quoted: expected holds a current quote. unquoted / quoting: no quote yet. unviable: at least one source is too small to cover its fees.

Available options:
unquoted,
quoting,
quoted,
unviable
errorMessage
string | null
required

Why the withdrawal failed or only partly completed. null otherwise, and always null on the submit response (errors there are returned as HTTP errors).

sources
object[]
required

Balances the withdrawal is funded from.

pendingSignatures
object[]

Self-custody only: requests the signing wallet must answer before the withdrawal continues. Absent for managed custody. Answer them on POST /execution/withdrawals/{withdrawalId}/signatures.