Balances and Yield

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",
  "status": "idle",
  "balance": {
    "totalUsd": "100250.000000",
    "earnedUsd": "250.000000",
    "reservedUsd": "0.000000",
    "withdrawableUsd": "100250.000000"
  },
  "createdAt": "2026-02-05T08:15:00.000Z",
  "positions": [
    { "id": "cash:ethereum_sepolia:usdc", "kind": "cash", "label": "Cash (Ethereum Sepolia)", "valueUsd": "0.000000" },
    { "id": "syrup-usdc", "pct": 40, "kind": "yield_source", "label": "Syrup USDC", "valueUsd": "40100.000000", "yieldSourceId": "syrup-usdc", "mode": "active", "apyBps": 491 },
    { "id": "morpho-gauntlet-usdc", "pct": 30, "kind": "yield_source", "label": "Morpho Gauntlet USDC Prime", "valueUsd": "30075.000000", "yieldSourceId": "morpho-gauntlet-usdc", "mode": "active", "apyBps": 500 },
    { "id": "morpho-steakhouse-usdc", "pct": 30, "kind": "yield_source", "label": "Morpho Steakhouse USDC Prime", "valueUsd": "30075.000000", "yieldSourceId": "morpho-steakhouse-usdc", "mode": "active", "apyBps": 500 }
  ],
  "strategyAllocations": {
    "usdc": [
      { "yieldSourceId": "syrup-usdc", "targetWeightBps": 4000 },
      { "yieldSourceId": "morpho-gauntlet-usdc", "targetWeightBps": 3000 },
      { "yieldSourceId": "morpho-steakhouse-usdc", "targetWeightBps": 3000 }
    ],
    "usdt": [
      { "yieldSourceId": "cash", "targetWeightBps": 10000, "token": "usdt", "chain": "ethereum_sepolia" }
    ]
  },
  "failureReason": null,
  "depositAddresses": {
    "solana_devnet": "DmaePN7kL6WjSecMaH4urdS8zN8FwNPTxbdTqFwAw6Fd",
    "ethereum_sepolia": "0xFf71D07826d0aFcEcDF07Be9c499f9DDF3ee5cFa"
  }
}

Key fields in the response:

Field	Description
`status`	`idle`, `withdrawal_active`, `rebalance_active`, `withdrawal_and_rebalance_active`, `creating`, or `failed`
`balance.totalUsd`	Gross customer-owned wallet value, including economically-owned funds that are still in transit
`balance.withdrawableUsd`	Conservative amount that can be withdrawn now
`balance.reservedUsd`	Customer-owned value currently reserved by active withdrawal or rebalance work
`balance.earnedUsd`	Lifetime yield earned
`positions[]`	Per-position balances with USD values and target allocations
`strategyAllocations`	Desired targets grouped by stablecoin, expressed in basis points

The positions array includes cash positions and yield sources in your strategy allocation.

yield_source — a strategy position. These entries include yieldSourceId and pct.
cash — idle USDC or USDT sitting in the wallet’s deposit addresses. Cash positions include token and chain; configured cash targets may include pct.

Configured zero-value cash and yield targets can appear so clients can render the current strategy. 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.

When idle stablecoins move into yield

Idle cash is swept into yield positions through rebalances. USDC follows the USDC strategy and USDT follows the USDT strategy; Ground does not convert between them. Rebalances only run when the available idle balance can produce executable yield-entry legs.

Rebalance minimums are environment-configured and applied per executable leg. Sandbox uses small minimums (e.g. 5 stablecoin units per leg) so you can test with small amounts; production minimums are typically higher. If idle cash cannot produce executable legs above the configured threshold, those funds remain idle and withdrawable instead of being swept into yield — no error is returned.

If idle cash is split across multiple strategy targets, each resulting target leg must meet the active environment’s configured minimum. For example, if the active minimum is 5 units per leg, an 8 USDT idle balance with a 50/50 USDT strategy would split into two 4 USDT target legs, so no rebalance legs are created.

Balance definitions

totalUsd answers: “How much value does the customer own?”
withdrawableUsd answers: “How much can the customer withdraw now?”
reservedUsd answers: “How much customer-owned value is currently reserved by active wallet work?”
earnedUsd answers: “How much lifetime yield has this wallet earned?”

totalUsd, withdrawableUsd, and reservedUsd are intentionally not interchangeable. Value can remain customer-owned while still being unavailable to withdraw immediately, for example when a withdrawal or rebalance is 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.

`reservedUsd` timing

reservedUsd reflects the amount reserved by active withdrawal and rebalance work. It is set when the system reserves liquidity for a wallet workflow. The reservation is not always cleared immediately when a transaction broadcasts. It stays active until Ground’s ledger and holdings refresh confirm the next representation of the funds. In practice:

Workflow initiated: reservedUsd increases, withdrawableUsd decreases by the same amount, totalUsd stays the same.
Workflow completed: reservedUsd may remain briefly while the next ledger or holdings refresh catches up.
Refresh catches up: reservedUsd decreases back toward zero, and totalUsd reflects the settled holdings.
Workflow cancelled: reservedUsd decreases, withdrawableUsd increases back to its pre-workflow level.

The invariant 0 <= withdrawableUsd <= totalUsd always holds. 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 stablecoin 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, id, label, search, status, or createdAtGte using the list endpoint’s filters. Filters can be combined when you want to narrow the result set:

curl -X GET "$BASE_URL/v2/wallets?requestId=$REQUEST_ID" \
  -H "Authorization: Bearer $API_TOKEN"

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

The response is the standard cursor-paginated list shape ({ "data": [...], "nextCursor": ... }); a matching wallet appears in data.

Balance and workflow webhooks

Subscribe to workflow lifecycle events and fetch the wallet when you need a fresh balance snapshot:

portfolio_wallet.deposit.status_changed — fires when an external deposit posts to the wallet
portfolio_wallet.rebalance.status_changed — fires as Ground deploys cash or adjusts strategy positions
portfolio_wallet.withdrawal.status_changed — fires when withdrawals change the wallet’s available balance

See Webhooks for registration and payload details.

Getting Started

Wallet Lifecycle

Approvals

Monitoring & Webhooks

Security

Resources

Balances and Yield

Fetch a wallet

When idle stablecoins move into yield

Balance definitions

`reservedUsd` timing

Customer-facing valuation notes

Yield metrics

List wallets

Look up a wallet

Balance and workflow webhooks

​Fetch a wallet

​When idle stablecoins move into yield

​Balance definitions

​reservedUsd timing

​Customer-facing valuation notes

​Yield metrics

​List wallets

​Look up a wallet

​Balance and workflow webhooks

Fetch a wallet

When idle stablecoins move into yield

Balance definitions

`reservedUsd` timing

Customer-facing valuation notes

Yield metrics

List wallets

Look up a wallet

Balance and workflow webhooks