Withdraw Funds

Withdrawals are asynchronous. A withdrawal may involve unwinding yield positions, bridging across chains, and waiting for customer approval — all orchestrated automatically.

Withdrawal lifecycle

Preview — check available balance and get a sourcing estimate.
Initiate — create the withdrawal. The system reserves liquidity and begins sourcing.
Track — poll or subscribe to webhooks as the withdrawal progresses.
Complete — the withdrawal reaches completed when all payout legs are terminal.

Preview a withdrawal

curl -X POST "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/withdrawal-preview" \
  -H "Authorization: Bearer $BRAID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationChain": "polygon",
    "destinationToken": "usdc",
    "withdrawalAmount": "65000"
  }'

{
  "amountUsd": "65000.00",
  "feeUsd": "0.00",
  "availableUsd": "82500.00",
  "estimatedCompletionTime": "PT2H"
}

Field	Description
`amountUsd`	Requested withdrawal amount
`feeUsd`	Fee charged (currently `"0.00"`)
`availableUsd`	Unreserved balance in the relevant bridge domain(s)
`estimatedCompletionTime`	Best-effort ISO 8601 duration for end-to-end completion

Initiate a withdrawal

curl -X POST "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/withdraw" \
  -H "Authorization: Bearer $BRAID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
    "chain": "ethereum",
    "token": "usdc",
    "withdrawalAmount": "65000",
    "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'

Field	Required	Description
`requestId`	Yes	UUID v4 idempotency key
`chain`	Yes	Destination chain
`token`	Yes	Destination token
`withdrawalAmount`	Yes	Amount as a string (e.g. `"65000"`, `"100.50"`)
`destinationAddress`	Yes	Recipient address on the destination chain

Field naming

The preview endpoint uses destinationChain / destinationToken (read-only query describing where you’d send). The initiate endpoint uses chain / token (action parameters). This is intentional — the preview scopes availability; the initiate commits the withdrawal.

Amount limits

Must be a positive number.
Max 6 decimal places for USDC (e.g. "100.123456" is valid, "100.1234567" returns precision_overflow).
Cannot exceed the wallet’s unreserved balance. Use the preview endpoint to check availability.
There is no minimum withdrawal amount, but very small withdrawals may not be economically efficient due to gas and bridging costs.

Sandbox notes

chain: "ethereum" refers to Ethereum Sepolia in sandbox.
Solana is part of the CCTP unified bridge domain for sourcing liquidity, but direct Solana withdrawal destinations are not yet supported. The endpoint currently expects an EVM destination address.

Withdrawal response

{
  "id": "11b17950-1f5c-4d36-8f0d-0f3d1d0c6a45",
  "requestId": "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "amountUsd": "65000.00",
  "feeUsd": "0.00",
  "destinationChain": "ethereum",
  "destinationToken": "usdc",
  "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "status": "processing",
  "txHash": null,
  "failureReason": null,
  "payouts": [
    {
      "id": "0c7c6fcb-3c49-4f6d-9a8d-1d2b8d1ef7b0",
      "legKey": "pos_usdz_001",
      "status": "processing",
      "amount": "65000.00",
      "token": "usdc",
      "chain": "ethereum",
      "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
      "txHash": null
    }
  ],
  "sourceLegs": [
    {
      "id": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
      "positionKey": "usdz",
      "sourceChain": "arbitrum",
      "requestedUsdcUnits": "35000000000",
      "status": "processing"
    },
    {
      "id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "positionKey": "cash_usdc:cctp",
      "sourceChain": "arbitrum",
      "requestedUsdcUnits": "30000000000",
      "status": "completed"
    }
  ],
  "createdAt": "2026-02-05T11:00:00.000Z",
  "updatedAt": "2026-02-05T11:05:00.000Z",
  "completedAt": null
}

Top-level fields

Field	Description
`id`	Unique withdrawal identifier
`requestId`	Your idempotency key
`walletId`	Parent wallet ID
`amountUsd`	Withdrawal amount as a USD string
`feeUsd`	Fee charged (currently `"0.00"`)
`destinationChain`	Target chain
`destinationToken`	Target token
`status`	Current status (see Withdrawal statuses)
`txHash`	Primary delivery tx hash (populated when payout is broadcast)
`failureReason`	Machine-readable reason when `status` is `failed` (see Failure reasons)
`createdAt` / `updatedAt`	Timestamps
`completedAt`	When the withdrawal reached terminal state (`null` if in progress)

`payouts[]` — delivery legs

Each withdrawal has one or more payout legs tracking chain-level delivery.

Field	Description
`id`	Payout leg identifier
`legKey`	Unique key in the format `pos_{positionKey}_{attempt}` (e.g. `pos_usdz_001`). The attempt suffix is zero-padded and increments on retry.
`status`	Payout leg status (see Payout leg statuses)
`amount`	Amount as a USD string
`token`	Token being delivered
`chain`	Chain for delivery
`destinationAddress`	Recipient address
`txHash`	Onchain tx hash (populated after broadcast)

`sourceLegs[]` — liquidity sourcing

Source legs show where funds are being unwound from to fulfill the withdrawal.

Field	Description
`id`	Source leg identifier
`positionKey`	Which position is being sourced (e.g. `usdz`, `cash_usdc:cctp`)
`sourceChain`	Chain where the position is held
`requestedUsdcUnits`	Amount in USDC base units (6 decimals). `"35000000000"` = 35,000 USDC. Divide by `1,000,000` to get USDC.
`status`	Source leg status

Withdrawal statuses

Status	Terminal	Meaning
`pending`	No	Accepted and reserved; sourcing hasn’t started
`processing`	No	Unwinding, bridging, or delivering in progress
`completed`	Yes	All payout legs finished successfully
`partially_completed`	Yes	Some payout legs completed, others failed or were cancelled
`failed`	Yes	Withdrawal failed
`cancelled`	Yes	Withdrawal was cancelled before any payouts completed

Payout leg statuses

Status	Terminal	Meaning
`planning`	No	Leg is being planned
`waiting_for_prior_approval`	No	Blocked behind a prior approval on the same wallet+chain
`pending_customer_approval`	No	Turnkey approval required
`pending_broadcast`	No	Signed, waiting to broadcast
`broadcasted`	No	Broadcast submitted, waiting for finality
`processing`	No	In progress
`completed`	Yes	Delivered successfully
`failed`	Yes	Failed
`cancelled`	Yes	Cancelled
`skipped`	Yes	Leg not needed (e.g. no unwind required)

Failure reasons

When a withdrawal or payout leg fails, failureReason contains a machine-readable code:

Reason	Meaning
`cancelled`	Cancelled by system
`cancelled_by_customer`	Cancelled by customer request
`usdc_authorization_expired`	USDC transfer authorization expired before broadcast
`onchain_reverted`	EVM transaction reverted onchain
`onchain_failed`	Solana transaction failed onchain
`turnkey_activity_failed`	Turnkey signing activity failed
`cash_leg_unfulfillable_stale_ledger`	Cash source insufficient (stale balance data)

Customer approvals (head-of-line gating)

Only one customer approval can be outstanding per walletId + chain. If you submit multiple withdrawals quickly, later ones queue behind the earlier approval. Withdrawal responses include:

customerApprovalState: "required" | "queued" | "not_required"
blockedBy: describes the blocking payout leg when queued

For the full Turnkey approval lifecycle, see Transaction Approvals.

List withdrawals

curl "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/withdrawals?limit=25" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"

Param	Default	Description
`limit`	25	Items per page (1–100)
`cursor`	—	Opaque cursor from `nextCursor`
`sort`	`createdAt`	Sort field
`order`	`desc`	`asc` or `desc`
`status`	—	Repeatable filter (e.g. `status=processing&status=completed`)

{
  "data": [
    {
      "id": "11b17950-1f5c-4d36-8f0d-0f3d1d0c6a45",
      "requestId": "df8b7be6-e110-4f6d-9b2d-7c44a5b1f0b0",
      "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
      "amountUsd": "65000.00",
      "feeUsd": "0.00",
      "destinationChain": "ethereum",
      "destinationToken": "usdc",
      "status": "completed",
      "createdAt": "2026-02-05T11:00:00.000Z",
      "completedAt": "2026-02-05T12:30:00.000Z"
    }
  ],
  "nextCursor": null
}

Fetch a withdrawal

curl "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/withdrawals/$WITHDRAWAL_ID" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"

Cancel a withdrawal

curl -X POST "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/withdrawals/$WITHDRAWAL_ID/cancel" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"

Cancellation is best-effort. If some payout legs have already completed, the withdrawal transitions to partially_completed rather than cancelled. You can also cancel or retry individual payout legs:

# Cancel a specific payout leg
curl -X POST "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/withdrawals/$WITHDRAWAL_ID/payouts/$PAYOUT_ID/cancel" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"

# Retry a failed payout leg
curl -X POST "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/withdrawals/$WITHDRAWAL_ID/payouts/$PAYOUT_ID/retry" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"

Timing expectations

Position	Unwind time	Notes
Cash (USDC)	Instant	No unwind needed
`usdz`	Instant (`PT0H`)	Convert to USDC on Arbitrum
`syrupUsdc`	Instant (`PT0H`)	ERC-4626 redemption on Ethereum
`rlp`	Up to 24h (`PT24H`)	Async Resolv exit window
`ustb`	Up to 48h (`P2D`)	Superstate redemption window

Cross-chain delivery via CCTP adds time on top of the unwind. Typical CCTP bridging is ~1h (p50), up to ~3h (max). For per-position estimates to a specific destination, use POST /v2/portfolio-wallets/withdrawal-time-estimates — see Estimate withdrawal times.

Estimate withdrawal times

Estimate end-to-end withdrawal times for a set of positions and destination:

curl -X POST "$BASE_URL/v2/portfolio-wallets/withdrawal-time-estimates" \
  -H "Authorization: Bearer $BRAID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "destinationToken": "usdc",
    "destinationChain": "ethereum",
    "positions": [
      { "positionKey": "usdz", "targetWeightBps": 6000 },
      { "positionKey": "rlp", "targetWeightBps": 4000 }
    ]
  }'

Field	Required	Description
`destinationToken`	Yes	Destination token (only `usdc` today)
`destinationChain`	Yes	`ethereum`, `arbitrum`, `base`, `polygon`, or `optimism`
`positions`	Yes	Positions array (same shape as wallet creation)

Each estimate breaks the withdrawal into steps (unwind_liquidity, convert_to_usdc, bridge_cctp, payout_transfer_and_finality) with p50, p90, and max durations. fullSettlementTime aggregates across steps. "p90": "PT1H30M" means “90th percentile is about 1 hour 30 minutes”. These are best-effort estimates, not an SLA.

Withdrawal webhooks

Subscribe to these events for real-time tracking:

portfolio_wallet.withdrawal.status_changed
portfolio_wallet.withdrawal.payout.status_changed

See Webhooks for registration and payload details.

Bridge domains reference

A bridge domain is a hard boundary for where liquidity can come from. The withdrawal engine never crosses bridge domain boundaries.

USDC unified (CCTP)

USDC on CCTP-supported chains forms a single usdc:unified domain: Ethereum, Arbitrum, Base, Polygon, Optimism, Solana. A withdrawal to any of these chains can source USDC from any other chain in the domain (via CCTP bridging).

BSC (always isolated)

BSC USDC is isolated: usdc:bsc. Cannot be bridged to or from CCTP chains.

How cash fits in

Within a bridge domain, cash is always the first source of liquidity. Only if cash is insufficient will the system unwind yield positions. The sourceLegs[] array shows the sourcing order.

Next steps

Transaction Approvals — approve withdrawals via Turnkey
Webhooks — subscribe to withdrawal and payout events
Balances and Yield — monitor balance changes after withdrawal

Getting Started

Portfolio Wallets

Platform

Withdraw Funds

Withdrawal lifecycle

Preview a withdrawal

Initiate a withdrawal

Field naming

Amount limits

Sandbox notes

Withdrawal response

Top-level fields

`payouts[]` — delivery legs

`sourceLegs[]` — liquidity sourcing

Withdrawal statuses

Payout leg statuses

Failure reasons

Customer approvals (head-of-line gating)

List withdrawals

Fetch a withdrawal

Cancel a withdrawal

Timing expectations

Estimate withdrawal times

Withdrawal webhooks

Bridge domains reference

USDC unified (CCTP)

BSC (always isolated)

How cash fits in

Next steps

Getting Started

Portfolio Wallets

Platform

​Withdrawal lifecycle

​Preview a withdrawal

​Initiate a withdrawal

​Field naming

​Amount limits

​Sandbox notes

​Withdrawal response

​Top-level fields

​payouts[] — delivery legs

​sourceLegs[] — liquidity sourcing

​Withdrawal statuses

​Payout leg statuses

​Failure reasons

​Customer approvals (head-of-line gating)

​List withdrawals

​Fetch a withdrawal

​Cancel a withdrawal

​Timing expectations

​Estimate withdrawal times

​Withdrawal webhooks

​Bridge domains reference

​USDC unified (CCTP)

​BSC (always isolated)

​How cash fits in

​Next steps

Withdrawal lifecycle

Preview a withdrawal

Initiate a withdrawal

Field naming

Amount limits

Sandbox notes

Withdrawal response

Top-level fields

`payouts[]` — delivery legs

`sourceLegs[]` — liquidity sourcing

Withdrawal statuses

Payout leg statuses

Failure reasons

Customer approvals (head-of-line gating)

List withdrawals

Fetch a withdrawal

Cancel a withdrawal

Timing expectations

Estimate withdrawal times

Withdrawal webhooks

Bridge domains reference

USDC unified (CCTP)

BSC (always isolated)

How cash fits in

Next steps