Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.groundtech.co/llms.txt

Use this file to discover all available pages before exploring further.

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",
  "createdAt": "2026-02-05T08:15:00Z",
  "depositAddresses": {
    "arbitrum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "base": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "ethereum": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "polygon": "0x21246509968c4d24611f414560971AEc2e3A079B",
    "solana": "7nYzKxM3bP4oEFbqkPmA5E2rYJ8HqKz8vFg9abc1"
  },
  "balance": {
    "totalUsd": "100000.000000",
    "withdrawableUsd": "100000.000000",
    "reservedUsd": "0.000000",
    "earnedUsd": "1250.000000"
  },
  "positions": [
    { "id": "syrup-usdc", "kind": "yield_source", "label": "Syrup USDC", "valueUsd": "40000.000000", "pct": 40 },
    { "id": "morpho-gauntlet-usdc", "kind": "yield_source", "label": "Morpho Gauntlet USDC Prime", "valueUsd": "30000.000000", "pct": 30 },
    { "id": "morpho-steakhouse-usdc", "kind": "yield_source", "label": "Morpho Steakhouse USDC Prime", "valueUsd": "30000.000000", "pct": 30 }
  ]
}
Key fields in the response:
FieldDescription
statusidle, withdrawal_active, rebalance_active, withdrawal_and_rebalance_active, creating, or failed
balance.totalUsdGross customer-owned wallet value, including economically-owned funds that are still in transit
balance.withdrawableUsdConservative amount that can be withdrawn now
balance.reservedUsdCustomer-owned value currently reserved by active withdrawal or rebalance work
balance.earnedUsdLifetime yield earned
positions[]Per-position balances with USD values and target allocations
The positions array includes non-zero cash or bridge positions plus yield sources in your strategy allocation.
  • yield_source — a strategy position. These entries include pct.
  • cash — idle USDC sitting in the wallet’s deposit addresses. These entries omit pct.
  • bridge — funds currently being bridged between chains. These entries omit pct.
Cash and bridge entries only appear when their value is greater than zero. 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 USDC moves into yield

Idle USDC is swept into yield positions through rebalances. Rebalances only run when the available idle USDC can produce executable yield-entry legs. Ground currently requires at least 5 USDC per rebalance leg. If a wallet has less than 5 USDC available as idle USDC, those funds remain idle and withdrawable instead of being swept into yield. If idle cash is split across multiple strategy targets, each resulting target leg must meet the 5 USDC minimum. For example, a wallet with an 8 USDC idle balance and a 50/50 strategy would split into two 4 USDC target legs, so no rebalance legs are created. A 50/50 strategy needs about 10 USDC of idle cash for both target legs to clear the minimum.

​
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 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 using the list endpoint’s filters (provide exactly one of id, requestId, or label): 
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 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.