Skip to main content
High-yield wallet withdrawals let you return funds to your own custody while respecting the recognized vs estimated yield split. This guide shows how to initiate a withdrawal, understand the response, and poll for completion. Withdrawals are:
  • Idempotent: keyed by requestId.
  • Constrained: you can only withdraw up to principal + recognizedYield (the withdrawable balance).
  • Delayed: cash payout is expected ~4.5 days after initiation (estimatedPayoutAt), even though the withdrawable balance is reduced immediately.

​
1. Check withdrawable balance

Before initiating a withdrawal, fetch the wallet and inspect withdrawableBalance. 
curl -X GET "$BASE_URL/high-yield-wallets/$WALLET_ID" \
  -H "Authorization: Bearer $TOKEN"
Excerpt of 200 response 
{
  "id": "92ff592c-a5d1-4053-a745-53f140cc2851",
  "withdrawableBalance": 95000.0,
  "recognizedYield": 5000.0,
  "estimatedAccruedYield": 120.5
}
You may withdraw any amount 0 < withdrawalAmount <= withdrawableBalance. If you attempt to exceed this, the API returns a 400 with Insufficient withdrawable balance.

​
2. Initiate a withdrawal

curl -X POST "$BASE_URL/high-yield-wallets/withdraw" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "highYieldWalletId": "92ff592c-a5d1-4053-a745-53f140cc2851",
    "requestId": "67c0cd99-8e1e-4712-97a9-97304cb467ac",
    "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
    "withdrawalAmount": 1000.5,
    "destinationToken": "usdc",
    "destinationChain": "ethereum"
  }'
200 response 
{
  "id": "22ae640a-af79-450f-bcb6-111f41a00321",
  "requestId": "67c0cd99-8e1e-4712-97a9-97304cb467ac",
  "createdAt": "2025-09-14T03:33:59.662679+00:00",
  "highYieldWalletId": "92ff592c-a5d1-4053-a745-53f140cc2851",
  "status": "processing",
  "withdrawalAmount": 1000.5,
  "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
  "destinationChain": "ethereum",
  "destinationToken": "usdc",
  "estimatedPayoutAt": "2025-09-18T17:45:12.000Z"
}
On initiation:
  • Braid immediately reduces principal and/or recognized yield at the accounting layer.
  • A high_yield_wallet_withdrawals record is created with status="processing".
  • estimatedPayoutAt is set to ~4.5 days in the future, when you should expect on-chain settlement.

​
3. List withdrawals for a wallet

curl -X GET "$BASE_URL/high-yield-wallets/$WALLET_ID/withdrawals?page=1&pageSize=20" \
  -H "Authorization: Bearer $TOKEN"
200 response 
{
  "withdrawals": [
    {
      "id": "af8fc553-a16c-4bff-a3e4-0091173f0eb6",
      "requestId": "47c0cd99-8e1e-4712-97a9-97304cb467ac",
      "status": "completed",
      "failureReason": null,
      "highYieldWalletId": "92ff592c-a5d1-4053-a745-53f140cc2851",
      "withdrawalAmount": 540.25,
      "destinationToken": "usdt",
      "destinationChain": "bsc",
      "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
      "payoutTxHash": "0xc1ab4fd839a5a7104710d52adf7b570282711e655b243dc74b8a31be9f7d90f4",
      "estimatedPayoutAt": "2025-09-18T17:45:12.000Z",
      "completedAt": "2025-09-18T18:02:30.000Z",
      "createdAt": "2025-09-11T04:47:46.786526+00:00"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}
Statuses you will see:
  • processing: withdrawal created and pending payout (principal and recognized yield already reduced).
  • completed: on-chain payout finalized; payoutTxHash and completedAt populated.
  • failed: no payout; failureReason may be present.

​
4. Fetch a single withdrawal by id

curl -X GET "$BASE_URL/high-yield-wallets/withdrawals/$WITHDRAWAL_ID" \
  -H "Authorization: Bearer $TOKEN"
Use this to drive a detail view or link a webhook/event payload back to your own records.

​
5. Lookup by requestId

If you only have the original idempotency key: 
curl -X GET "$BASE_URL/high-yield-wallets/withdrawals/lookup?requestId=$REQUEST_ID" \
  -H "Authorization: Bearer $TOKEN"
This returns the same shape as GET /high-yield-wallets/withdrawals/{withdrawalId}, scoped to the authenticated organization.