Skip to main content
Once your wallet is funded, use these endpoints to track balances, positions, and yield.

​
Fetch a wallet

curl "$BASE_URL/v2/portfolio-wallets/$WALLET_ID" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"
Key fields in the response:
FieldDescription
balance.totalUsdTotal wallet value (principal + yield) across all positions
balance.withdrawableUsdUnreserved balance available for withdrawal
balance.earnedUsdCumulative yield earned
strategy.allocations[]Target allocation per position (positionKey + pct)
strategy.statusaligned or rebalancing
positions[]Per-position holdings with USD values
Balances are computed from refreshed onchain holdings + price feeds and cached for fast reads. They may briefly lag deposits or withdrawals. For destination-specific withdrawability and a sourcing plan, use the withdrawal preview.
  • syrupUsdc is valued from an onchain ERC-4626 conversion at request time (block-level fresh).
  • rlp uses Resolv’s oracle feed and can be up to ~24h stale.
  • Treat both as NAV-based valuations, not guaranteed 1:1 USDC marks.

​
Cash positions

When funds are deposited but not yet deployed into yield positions, they appear as cash. Cash positions use the naming pattern cash_usdc:<domain>:
Position keyMeaning
cash_usdc:cctpUndeployed USDC on any CCTP-bridgeable chain (Ethereum, Arbitrum, Base, Polygon, Optimism, Solana)
cash_usdc:bscUndeployed USDC on BSC (always isolated from CCTP chains)
Cash is excluded from drift calculations and is always sourced first during withdrawals before unwinding yield positions. Small deposits may remain as cash temporarily if deploying them is not economically efficient — see Deposits.

​
Yield metrics

Fetch yield breakdown for a specific wallet. This endpoint uses POST with a JSON body (rather than a path parameter) because it supports optional period filtering. 
curl -X POST "$BASE_URL/v2/portfolio-wallets/yield" \
  -H "Authorization: Bearer $BRAID_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "portfolioWalletId": "'$WALLET_ID'"
  }'
FieldRequiredDescription
portfolioWalletIdYesThe wallet ID to fetch yield for
{
  "portfolioWalletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "totalEarnedUsd": "1250.00",
  "blendedRateBps": 565,
  "positions": [
    { "positionKey": "usdz", "earnedUsd": "750.00", "currentRateBps": 330 },
    { "positionKey": "rlp", "earnedUsd": "500.00", "currentRateBps": 850 }
  ]
}
FieldDescription
totalEarnedUsdTotal yield earned across all positions
blendedRateBpsWeighted average APR across strategy positions (100 bps = 1%)
positions[].earnedUsdYield earned by each position
positions[].currentRateBpsCurrent APR for the yield source

​
Activity feed

Fetch a combined timeline of deposits and withdrawals: 
curl "$BASE_URL/v2/portfolio-wallets/$WALLET_ID/activity?limit=20" \
  -H "Authorization: Bearer $BRAID_API_TOKEN"
ParamDefaultDescription
type—Filter by deposit or withdrawal (omit for both)
limit20Max items per page (1–100)
cursor—Opaque cursor for pagination
{
  "activity": [
    {
      "id": "2a3ad0af-11b3-41d5-96c5-2b9d8799f1e2",
      "type": "deposit",
      "amountUsd": "50000.00",
      "timestamp": "2026-02-05T09:30:00.000Z",
      "detail": {
        "chain": "ethereum",
        "token": "usdc",
        "status": "completed"
      }
    },
    {
      "id": "11b17950-1f5c-4d36-8f0d-0f3d1d0c6a45",
      "type": "withdrawal",
      "amountUsd": "65000.00",
      "timestamp": "2026-02-05T11:00:00.000Z",
      "detail": {
        "destinationChain": "ethereum",
        "status": "processing"
      }
    }
  ],
  "hasMore": false
}
The activity feed uses hasMore (boolean) for pagination instead of nextCursor. Pass the cursor query parameter to paginate when hasMore is true.

​
Balance and position webhooks

Subscribe to these events for real-time updates:
  • portfolio_wallet.balance.updated — fires when wallet balance changes
  • portfolio_wallet.position.updated — fires when a position’s value or rate changes
See Webhooks for registration and payload details.

​
Next steps