Skip to main content
Building on a stablecoin app, you can create a yield wallet, sweep funds into it, observe balances, and initiate withdrawals to your own addresses. This guide shows the core flow with concrete requests and example responses. Creating a yield wallet is idempotent using a requestId. The response includes per-chain deposit addresses you can sweep to from your existing wallet infrastructure. Create a yield wallet 
curl -X POST "$BASE_URL/yield-wallets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "label": "My Trading Wallet"
  }'
200 response 
{
  "id": "66f62666-4073-4bea-8a8c-410201477e21",
  "createdAt": "2025-09-14T03:32:40.467+00:00",
  "label": "My first wallet",
  "rateBps": 350,
  "accruedAmount": 0,
  "principalBalance": 0,
  "depositAddresses": {
    "arbitrum": {
      "address": "0xa57671a38142a5636eA88b01F935Eaff425B6688",
      "principalBalance": 0
    },
    "base": {
      "address": "0xa57671a38142a5636eA88b01F935Eaff425B6688",
      "principalBalance": 0
    },
    "bsc": {
      "address": "0xa57671a38142a5636eA88b01F935Eaff425B6688",
      "principalBalance": 0
    },
    "ethereum": {
      "address": "0xa57671a38142a5636eA88b01F935Eaff425B6688",
      "principalBalance": 0
    },
    "optimism": {
      "address": "0xa57671a38142a5636eA88b01F935Eaff425B6688",
      "principalBalance": 0
    },
    "polygon": {
      "address": "0xa57671a38142a5636eA88b01F935Eaff425B6688",
      "principalBalance": 0
    },
    "solana": {
      "address": "BAHHuqpgMt5vbHnTkjo1DzjhRo5a2zN6QX2jw66YeGzn",
      "principalBalance": 0
    }
  }
}
After creation, transfer stablecoins from your existing wallets to the corresponding depositAddresses[chain].address. As deposits settle, balances update on-chain and become visible via the wallet detail endpoint. Get a yield wallet by id 
curl -X GET "$BASE_URL/yield-wallets/$WALLET_ID" \
  -H "Authorization: Bearer $TOKEN"
200 response 
{
  "id": "92ff592c-a5d1-4053-a745-53f140cc2851",
  "createdAt": "2025-09-11T21:50:36.372+00:00",
  "label": "My first wallet",
  "rateBps": 350,
  "totalBalance": 68420.45,
  "depositAddresses": {
    "arbitrum": {
      "address": "0x21246509968c4d24611f414560971AEc2e3A079B",
      "totalWithdrawableBalance": 67500.25
    },
    "base": {
      "address": "0x21246509968c4d24611f414560971AEc2e3A079B",
      "totalWithdrawableBalance": 0
    },
    "bsc": {
      "address": "0x21246509968c4d24611f414560971AEc2e3A079B",
      "totalWithdrawableBalance": 850.75
    },
    "ethereum": {
      "address": "0x21246509968c4d24611f414560971AEc2e3A079B",
      "totalWithdrawableBalance": 0
    },
    "optimism": {
      "address": "0x21246509968c4d24611f414560971AEc2e3A079B",
      "totalWithdrawableBalance": 0
    },
    "polygon": {
      "address": "0x21246509968c4d24611f414560971AEc2e3A079B",
      "totalWithdrawableBalance": 0
    },
    "solana": {
      "address": "BskNLCLegEBsLySuTRmGJJoozyAUmeApSvd73b2hg7QM",
      "totalWithdrawableBalance": 0
    }
  }
}
When your users want to spend or settle externally, initiate a withdrawal from the yield wallet to your chosen destination. The request is idempotent and processed asynchronously. Initiate a withdrawal 
curl -X POST "$BASE_URL/yield-wallets/withdraw" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "yieldWalletId": "92ff592c-a5d1-4053-a745-53f140cc2851",
    "requestId": "67c0cd99-8e1e-4712-97a9-97304cb467ac",
    "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
    "withdrawalAmount": 0.00017,
    "destinationToken": "usdt",
    "destinationChain": "bsc"
  }'
200 response 
{
  "id": "22ae640a-af79-450f-bcb6-111f41a00321",
  "requestId": "67c0cd99-8e1e-4712-97a9-97304cb467ac",
  "createdAt": "2025-09-14T03:33:59.662679+00:00",
  "yieldWalletId": "92ff592c-a5d1-4053-a745-53f140cc2851",
  "status": "created",
  "withdrawalAmount": 0.00017,
  "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
  "destinationChain": "bsc",
  "destinationToken": "usdt"
}
As processing proceeds, you can either list withdrawals for the wallet or fetch a single withdrawal by id to observe status transitions until completion. List withdrawals for a wallet 
curl -X GET "$BASE_URL/yield-wallets/503ceb11-369a-4c5b-8bc9-7406cebec439/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,
      "yieldWalletId": "503ceb11-369a-4c5b-8bc9-7406cebec439",
      "withdrawalAmount": 0.00063,
      "destinationToken": "usdt",
      "destinationChain": "bsc",
      "destinationAddress": "0x76F8fc6667E239f83a547d4e16225d6a34f6FA22",
      "txHashes": [
        "0xc1ab4fd839a5a7104710d52adf7b570282711e655b243dc74b8a31be9f7d90f4"
      ],
      "fromPrincipal": 0.00063,
      "fromYield": 0,
      "createdAt": "2025-09-11T04:47:46.786526+00:00"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 4
}
Get a withdrawal by id 
curl -X GET "$BASE_URL/yield-wallets/withdrawals/c1a2b3c4-d5e6-7890-ab12-cd34ef56ab78" \
  -H "Authorization: Bearer $TOKEN"
200 response 
{
  "id": "c1a2b3c4-d5e6-7890-ab12-cd34ef56ab78",
  "requestId": "456e7890-f12c-34d5-b678-901234567890",
  "status": "completed",
  "failureReason": null,
  "yieldWalletId": "123e4567-e89b-12d3-a456-426614174000",
  "withdrawalAmount": 1000.5,
  "destinationToken": "usdc",
  "destinationChain": "ethereum",
  "destinationAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
  "txHashes": [
    "0xc1ab4fd839a5a7104710d52adf7b570282713e655b243dc74b8a31be9f7d90f4",
    "0x3f3eb97aad7733272eda7a514a2c45884fd84f9377bb91e11a87bd3ab0141a53"
  ],
  "fromPrincipal": 0,
  "fromYield": 0,
  "createdAt": "2025-01-15T14:30:45.123Z"
}
This flow lets you integrate Braid’s yield wallets with existing custody, sweeping deposits into the wallet to accrue yield and withdrawing on demand to your operational addresses.