Balances and Yield

Monitor wallet balances, positions, and yield metrics.

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 includes the wallet balance and its positions:

{
  "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": "USDC (Ethereum Sepolia)",
      "valueUsd": "0.000000",
      "chain": "ethereum_sepolia",
      "token": "usdc",
      "allocationGroup": "usdc"
    },
    {
      "id": "syrup-usdc",
      "pct": 40,
      "kind": "yield_source",
      "label": "Syrup USDC",
      "valueUsd": "40100.000000",
      "mode": "active",
      "apyBps": 491,
      "chain": "ethereum_sepolia",
      "token": "usdc",
      "allocationGroup": "usdc",
      "withdrawableUsd": "40100.000000",
      "navUpdateMode": "continuous",
      "priceAsOf": "2026-10-19T12:00:00.000Z"
    },
    {
      "id": "morpho-gauntlet-usdc",
      "pct": 30,
      "kind": "yield_source",
      "label": "Morpho Gauntlet USDC Prime",
      "valueUsd": "30075.000000",
      "mode": "active",
      "apyBps": 500,
      "chain": "ethereum_sepolia",
      "token": "usdc",
      "allocationGroup": "usdc",
      "withdrawableUsd": "30075.000000",
      "navUpdateMode": "continuous",
      "priceAsOf": "2026-10-19T12:00:00.000Z"
    },
    {
      "id": "morpho-steakhouse-usdc",
      "pct": 30,
      "kind": "yield_source",
      "label": "Morpho Steakhouse USDC Prime",
      "valueUsd": "30075.000000",
      "mode": "active",
      "apyBps": 500,
      "chain": "ethereum_sepolia",
      "token": "usdc",
      "allocationGroup": "usdc",
      "withdrawableUsd": "30075.000000",
      "navUpdateMode": "continuous",
      "priceAsOf": "2026-10-19T12:00:00.000Z"
    }
  ],
  "strategyAllocations": {
    "usdc": [
      {
        "yieldSourceId": "syrup-usdc",
        "targetWeightBps": 4000,
        "chain": "ethereum_sepolia",
        "token": "usdc",
        "allocationGroup": "usdc"
      },
      {
        "yieldSourceId": "morpho-gauntlet-usdc",
        "targetWeightBps": 3000,
        "chain": "ethereum_sepolia",
        "token": "usdc",
        "allocationGroup": "usdc"
      },
      {
        "yieldSourceId": "morpho-steakhouse-usdc",
        "targetWeightBps": 3000,
        "chain": "ethereum_sepolia",
        "token": "usdc",
        "allocationGroup": "usdc"
      }
    ],
    "usdt": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "ethereum_sepolia",
        "allocationGroup": "usdt"
      }
    ],
    "usdt:tron": [
      {
        "yieldSourceId": "cash",
        "targetWeightBps": 10000,
        "token": "usdt",
        "chain": "tron_shasta",
        "allocationGroup": "usdt:tron"
      }
    ]
  },
  "failureReason": null,
  "depositAddresses": {
    "solana_devnet": "DmaePN7kL6WjSecMaH4urdS8zN8FwNPTxbdTqFwAw6Fd",
    "ethereum_sepolia": "0xFf71D07826d0aFcEcDF07Be9c499f9DDF3ee5cFa",
    "tron_shasta": "TBXSw8fM4jpQkGc6zZjsVABFpVN7UvXPdV",
    "stellar_testnet": "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"
  },
  "autoRebalance": true
}

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 gross amount that can be withdrawn now, before plan-specific fees
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
autoRebalance	Whether Ground maintains percentage targets automatically
strategyAllocations	Desired targets keyed by usdc, usdt, and usdt:tron, expressed in basis points; null for manually allocated wallets

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

• yield_source — a held or configured yield position. id is its public yield-source ID. allocationGroup, token, and chain identify its funding group; pct, when present, is its target weight within that group. A resolved source also includes mode, apyBps, navUpdateMode, and priceAsOf.
• cash — idle USDC or USDT sitting in the wallet’s deposit addresses. Cash positions include token and chain; configured cash targets may include pct. Cash position IDs follow cash:<chain>:<token>, using the network key for the wallet’s environment.

Configured zero-value cash and yield targets can appear for every strategy group, including Ethereum USDT and TRON USDT, so clients can render the current strategy. The sum of all positions[].valueUsd equals balance.totalUsd.

Use strategyAllocations for desired targets and positions[].allocationGroup to group actual holdings. usdt is Ethereum USDT, while usdt:tron is native TRON USDT. Each group is weighted independently; the wallet’s balance totals span all groups. A manually allocated wallet still identifies each holding’s group even though its strategyAllocations is null.

Balances are calculated from refreshed onchain holdings and price feeds, then cached for faster reads. They may briefly lag deposits or withdrawals.

​

When idle stablecoins move into yield

Idle cash is swept into yield positions through rebalances. Each allocation group is evaluated independently, using its compatible funds and strategy. Rebalances only run when the available idle balance can produce executable yield-entry legs.

If the cash cannot meet the minimum for each planned movement, it stays in cash and remains withdrawable; no error is returned. Splitting a deposit across several targets can leave each movement below the minimum. See rebalance examples for how the thresholds apply.

​

Balance definitions

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

Funds awaiting settlement, such as an in-progress withdrawal or rebalance, remain included in totalUsd but may be unavailable for withdrawal. Use withdrawableUsd to show the amount currently available before withdrawal fees.

A pending claim whose workflow has been cancelled is unavailable for withdrawal until settlement is reconciled; it does not prevent withdrawing other available cash or positions.

​

reservedUsd timing

reservedUsd reflects the amount reserved by active withdrawal and rebalance work.

Broadcasting a transaction does not immediately release reserved funds. Ground keeps them reserved until it confirms the resulting balance. A completed operation can therefore remain reserved briefly while the balance updates:

• 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.

​

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).

​

Earned and APY over time

GET /v2/accounting/yield/earned-series returns a time series for charting wallet performance, scoped to one wallet (walletId) or the whole organization (scope=organization). Each point carries two distinct metrics:

• cumulativeEarnedUsd — lifetime cumulative earned value, mark-to-market. This includes realized and unrealized gains: it moves both ways and can dip to show losses, unlike the monotonic balance.earnedUsd.
• blendedApyBps — the wallet’s blended APY at that point, in basis points. Each held yield source contributes its trailing ~30-day NAV growth (annualized), weighted by marked position value, with idle cash weighted at 0%. It describes the rate the allocation is positioned at, independent of wallet size — not what was earned, which the cumulative fields carry.

curl -X GET "$BASE_URL/v2/accounting/yield/earned-series?walletId=$WALLET_ID" \
  -H "Authorization: Bearer $API_TOKEN"

{
  "scope": "wallet",
  "interval": "day",
  "status": "exact",
  "series": [
    {
      "asOf": "2026-08-23T00:00:00.000Z",
      "cumulativeEarnedUsd": "0.383780",
      "blendedApyBps": 424,
      "status": "ok"
    }
  ]
}

Wallet APY is unavailable while the wallet holds non-USD investments. Earnings remain available, and each investment’s APY is shown in its own currency.

​

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.

​

Stock holdings

positions remains a flat list of actual holdings. A stock position uses kind: "stock" and includes assetSymbol, exact integer nativeUnits, and indicative price fields. Interpret nativeUnits using tokenDecimals (also returned by the catalog). Stocks are held in manual wallets and have no automatic strategy target.

Stock appreciation, depreciation and realized trading gains affect wallet value but are excluded from earnedUsd and yield reporting. A last observed stock mark may be stale: inspect priceFreshness and priceAsOf before presenting it as current. A missing mark is unavailable rather than a zero price.

​

Preview a stock allocation

For a manual wallet, use the position ID from the catalog as the destination:

curl -X POST "https://production.groundtech.co/v2/wallets/$WALLET_ID/allocate-preview" \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allocations":[{"from":"cash:ethereum:usdc","to":"qqqon","amountUsd":"728"}]}'

An illustrative preview includes the requested dollar allocation and a separate stock quote:

{
  "positions": [
    {
      "id": "cash:ethereum:usdc",
      "label": "USDC Cash",
      "beforeUsd": "1000.000000",
      "afterUsd": "272.000000",
      "deltaUsd": "-728.000000"
    },
    {
      "id": "qqqon",
      "label": "QQQon",
      "beforeUsd": "0.000000",
      "afterUsd": "728.000000",
      "deltaUsd": "728.000000"
    }
  ],
  "assetQuotes": [
    {
      "from": "cash:ethereum:usdc",
      "to": "qqqon",
      "assetId": "qqqon",
      "side": "buy",
      "indicative": true,
      "quotedAt": "2026-10-21T04:00:00.000Z",
      "stockNativeUnits": "1000000000000000000",
      "stockTokenDecimals": 18,
      "cashAsset": {
        "kind": "cash",
        "chain": "ethereum",
        "token": "usdc"
      },
      "cashNativeUnits": "727557767",
      "cashBudgetNativeUnits": "728000000",
      "unspentCashNativeUnits": "442233"
    }
  ]
}

afterUsd describes the requested allocation. The quote estimates actual token quantities and cash spend; it does not guarantee the eventual value or execution price. Cash quantities use the cash token’s decimals (six for Ethereum USDC). Stock quantities use stockTokenDecimals.

Submit the same allocations to POST /v2/wallets/{id}/allocate with a new requestId to create the instruction. Ground requests a fresh quote before execution and keeps the buy within its available cash budget. Read wallet activity until the instruction completes, then read the wallet’s settled positions. Unspent cash remains in the wallet. For paths with earlier redemption or bridge operations, their fees can reduce the cash available for the stock purchase.

A sell quote includes minimumCashNativeUnits in addition to the estimated receive amount. Stock previews return HTTP 503 when a current quote within the permitted price bounds is unavailable; retry later. A pair with no supported conversion path returns HTTP 400.