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": "Core Yield Portfolio",
  "createdAt": "2026-02-05T08:15:00Z",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "base": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "polygon": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "solana": "7nYzKxM3bP4oEFbqkPmA5E2rYJ8HqKz8vFg9abc1"
  },
  "balance": {
    "totalUsd": "100000.000000",
    "withdrawableUsd": "100000.000000",
    "availableToInitiateUsd": "100000.000000",
    "pendingWithdrawalUsd": "0.000000",
    "inTransitUsd": "0.000000",
    "earnedUsd": "1250.000000"
  },
  "positions": [
    { "yieldSourceId": "syrup-usdc", "name": "Syrup USDC", "valueUsd": "40000.000000", "pct": 40 },
    { "yieldSourceId": "morpho-gauntlet-usdc", "name": "Morpho Gauntlet USDC Prime", "valueUsd": "30000.000000", "pct": 30 },
    { "yieldSourceId": "morpho-steakhouse-usdc", "name": "Morpho Steakhouse USDC Prime", "valueUsd": "30000.000000", "pct": 30 }
  ]
}
Key fields in the response:
FieldDescription
balance.totalUsdGross customer-owned wallet value, including economically-owned funds that are still in transit
balance.withdrawableUsdConservative amount that can be withdrawn now
balance.availableToInitiateUsdBackwards-compatible alias of withdrawableUsd on wallet responses
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.earnedUsdLifetime 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.

​
Balance definitions

  • totalUsd answers: “How much value does the customer own?”
  • withdrawableUsd answers: “How much can the customer withdraw now?”
  • availableToInitiateUsd answers: “Same as withdrawableUsd on the wallet response.”
  • pendingWithdrawalUsd answers: “How much value is already committed to active withdrawals?”
  • earnedUsd answers: “How much lifetime yield has this wallet earned?”
totalUsd, withdrawableUsd, and pendingWithdrawalUsd are intentionally not interchangeable. Value can remain customer-owned while still being unavailable to withdraw immediately, for example when a prior unwind, bridge, or payout boundary is still settling. Internally, Ground keeps that value represented through explicit transfer boundaries. When funds move from one representation to another, the transfer row stays active until the destination representation is durably written or observed. That is what keeps totalUsd from dipping during internal protocol steps.

​
pendingWithdrawalUsd timing

pendingWithdrawalUsd reflects the total amount encumbered by active withdrawal reservations. It is set when a withdrawal is initiated and the system reserves liquidity. The reservation is not cleared immediately when the withdrawal broadcasts or even when the withdrawal reaches a terminal status. It stays active until Ground’s holdings refresh confirms the observed balances have caught up to the payout. In practice:
  • Withdrawal initiated: pendingWithdrawalUsd increases, withdrawableUsd decreases by the same amount, totalUsd stays the same.
  • Withdrawal completed: the withdrawal can already be terminal, but pendingWithdrawalUsd may remain temporarily while the next holdings refresh catches up.
  • Holdings refresh catches up: pendingWithdrawalUsd decreases back toward zero, and totalUsd reflects the delivered amount.
  • Withdrawal cancelled: pendingWithdrawalUsd decreases, withdrawableUsd increases back to its pre-withdrawal level.
The invariant 0 <= withdrawableUsd <= totalUsd always holds. The invariant withdrawableUsd <= totalUsd - pendingWithdrawalUsd also always holds. On wallet responses, availableToInitiateUsd = withdrawableUsd. The invariant “customer-owned value is always represented somewhere” also always holds.

​
Customer-facing valuation notes

  • syrup-usdc is valued from live onchain share-to-assets conversion and can move continuously.
  • Morpho ERC-4626 vaults exposed by the live catalog are valued from live onchain ERC-4626 conversion reads.
  • Treat NAV-based positions as protocol valuations, not guaranteed 1:1 USDC marks at every instant.
For destination-specific initiation readiness 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 — lifetime 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.