Skip to main content
This quickstart walks through authenticating, creating a portfolio wallet, funding it, and previewing and initiating a withdrawal. The whole flow takes about five minutes.

​
1. Set your base URL

Use sandbox while you build, then switch to production without changing request shapes. 
export BASE_URL="https://sandbox.trybraid.xyz"

​
2. Add your API token

Every request requires a Bearer token in the Authorization header. 
export BRAID_API_TOKEN="your_api_token"

​
3. Create a portfolio wallet

curl -X POST "$BASE_URL/v2/portfolio-wallets" \
  -H "Authorization: Bearer $BRAID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "123e4567-e89b-12d3-a456-426614174000",
    "label": "Treasury Portfolio",
    "positions": [
      { "positionKey": "usdz", "targetWeightBps": 6000 },
      { "positionKey": "rlp", "targetWeightBps": 4000 }
    ]
  }'
The response includes deposit addresses per chain. Sweep stablecoins into the address for the chain you are funding.

​
4. Fetch wallet details

curl -X GET "$BASE_URL/v2/portfolio-wallets/$WALLET_ID" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"
The response includes all the fields you need to display a wallet to your users: 
{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "requestId": "123e4567-e89b-12d3-a456-426614174000",
  "label": "Treasury Portfolio",
  "blendedRateBps": 565,
  "status": "active",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B"
  },
  "globalWalletBalance": 82500,
  "targetPositions": [
    { "positionKey": "usdz", "targetWeightBps": 6000, "maxProcessingTime": "PT0H" },
    { "positionKey": "rlp", "targetWeightBps": 4000, "maxProcessingTime": "PT24H" }
  ],
  "actualPositions": [
    {
      "positionKey": "usdz",
      "asset": "usdz",
      "chain": "arbitrum",
      "balanceUnits": 52500,
      "valueUsd": 52500,
      "actualWeightBps": 6120,
      "targetWeightBps": 6000,
      "driftBps": 120
    },
    {
      "positionKey": "rlp",
      "asset": "rlp",
      "chain": "ethereum",
      "balanceUnits": 25000,
      "valueUsd": 30000,
      "actualWeightBps": 3880,
      "targetWeightBps": 4000,
      "driftBps": -120
    }
  ],
  "liquidityProfile": [
    { "maxProcessingTime": "PT0H", "weightBps": 6000 },
    { "maxProcessingTime": "PT24H", "weightBps": 4000 }
  ]
}
  • globalWalletBalance is the total wallet value (principal + yield) across all positions.
  • targetPositions shows what the wallet is targeting; actualPositions shows what it currently holds.
  • liquidityProfile summarizes how fast each portion of the wallet can be withdrawn.

​
5. 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"
  }'
The preview tells you what balance is available for the requested destination and which positions liquidity will be sourced from.

​
6. 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"
  }'
Withdrawals are asynchronous. Poll the withdrawal endpoint or subscribe to webhooks to track progress.

​
Next steps