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

​
Fetch a wallet

curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID" \
  -H "Authorization: Bearer $API_TOKEN"
The response is a clean neobank-style shape: 
{
  "id": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "label": "Treasury Portfolio",
  "createdAt": "2026-02-05T08:15:00Z",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "base": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "polygon": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "solana": "7nYzKxM3bP4oEFbqkPmA5E2rYJ8HqKz8vFg9abc1"
  },
  "balance": {
    "totalUsd": "82500.000000",
    "withdrawableUsd": "82500.000000",
    "pendingWithdrawalUsd": "0.000000",
    "inTransitUsd": "0.000000",
    "earnedUsd": "250.000000"
  },
  "positions": [
    { "yieldSourceId": "resolv-lp", "name": "Resolv LP", "valueUsd": "33000.000000", "pct": 40 },
    { "yieldSourceId": "usdz", "name": "T-Bills (M0)", "valueUsd": "49500.000000", "pct": 60 }
  ]
}
Key fields in the response:
FieldDescription
balance.totalUsdTotal wallet value (principal + yield) across all positions
balance.withdrawableUsdAmount available for immediate withdrawal
balance.pendingWithdrawalUsdValue currently encumbered by active withdrawal(s) (see timing note below)
balance.inTransitUsdValue currently in transit (e.g. funds being bridged or deployed into a yield position)
balance.earnedUsdCumulative yield earned
positions[]Per-position balances with USD values and target allocations
The positions array always includes one entry per yield source in your strategy allocation. It may also include two additional system-managed entries:
  • cash — idle USDC sitting in the wallet’s deposit addresses that has not yet been deployed into a yield position. This typically appears briefly after a deposit or withdrawal, before the next rebalance cycle invests the funds.
  • in-transit — funds currently being bridged between chains as part of a rebalance or deposit flow.
These entries only appear when their value is greater than zero (they are omitted from the response when the balance is zero). They do not have a pct field (since they are not part of the strategy allocation). The sum of all positions[].valueUsd equals balance.totalUsd. Balances are computed from refreshed onchain holdings + price feeds and cached for fast reads. They may briefly lag deposits or withdrawals.

​
pendingWithdrawalUsd timing

pendingWithdrawalUsd reflects the total amount encumbered by active (non-terminal) withdrawals. It is set when a withdrawal is initiated and the system reserves liquidity. Once a withdrawal’s funds have been physically broadcast onchain, the reserved amount is deducted from totalUsd (since the funds have left the wallet) rather than continuing to be held in pendingWithdrawalUsd. In practice:
  • Withdrawal initiated: pendingWithdrawalUsd increases, withdrawableUsd decreases by the same amount, totalUsd stays the same.
  • Withdrawal broadcast/completed: pendingWithdrawalUsd decreases back toward zero, totalUsd decreases by the delivered amount.
  • Withdrawal cancelled: pendingWithdrawalUsd decreases, withdrawableUsd increases back to its pre-withdrawal level.
The invariant withdrawableUsd = totalUsd - pendingWithdrawalUsd always holds.

​
Customer-facing valuation notes

  • resolv-lp is valued from Resolv’s oracle feed and can be up to ~24 hours stale per Resolv’s documented cadence.
  • syrup-usdc is valued from an onchain ERC-4626 conversion read at request time (typically block-level fresh).
  • Treat both as NAV-based valuations, not guaranteed 1:1 USDC marks at every instant.
For destination-specific withdrawability (including in-flight reservations) and a sourcing plan, use POST /v2/wallets/:id/withdrawal-preview (see Withdraw Funds).

​
Yield metrics

You can monitor yield through the wallet response:
  • balance.earnedUsd — cumulative yield earned since wallet creation
  • balance.totalUsd — total value including accumulated yield
For a detailed breakdown including per-source APY, use GET /v2/wallets/:id/yield (see Calculating Yield Accrual).

​
List wallets

curl -X GET "$BASE_URL/v2/wallets?limit=25" \
  -H "Authorization: Bearer $API_TOKEN"
Supports cursor-based pagination. The response includes a nextCursor field for fetching subsequent pages. See API Conventions for details.

​
Look up a wallet

Look up a wallet by requestId or label: 
curl -X GET "$BASE_URL/v2/wallets/lookup?requestId=$REQUEST_ID" \
  -H "Authorization: Bearer $API_TOKEN"

curl -X GET "$BASE_URL/v2/wallets/lookup?label=My%20Portfolio" \
  -H "Authorization: Bearer $API_TOKEN"

​
Balance and position webhooks

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