Calculating Yield Accrual

Portfolio Wallets earn yield from multiple sources with different accrual mechanics. This guide explains how yield is computed and how to use the yield endpoint for detailed reporting.

How yield accrues

All yield sources are variable-rate. Rates change over time based on market conditions and protocol performance.

Tokens and shares valued by an exchange rate

These positions appreciate in value over time. When Ground deploys USDC or USDT, the stablecoin is converted into a compatible yield token or vault shares at the current exchange rate. As the protocol earns yield, the NAV (net asset value) per share increases, making those shares worth more of the source’s deposit token. The wallet’s balance.totalUsd reflects the current market value of all positions, so NAV appreciation is automatically captured in the balance.

Wallet-level earnings

Yield is reported at the wallet level, not per position. This is because rebalances move funds between positions over time, making per-position attribution misleading. The earnedUsd field represents lifetime yield earned across all positions since the wallet was created. It is computed internally using per-position yield accrual tracking rather than a simple deposit/withdrawal accounting formula, so it accurately reflects actual yield even through rebalances and partial withdrawals. Yield does not move on the same cadence for every source:

syrup-usdc updates continuously from live onchain share-to-assets conversion.
Morpho ERC-4626 vaults exposed by the live catalog update continuously from live onchain ERC-4626 conversion reads.

For the simple case of one completed deposit and no returned principal, balance.totalUsd = depositUsd + balance.earnedUsd to the supported accounting precision.

The yield endpoint

Use GET /v2/wallets/:id/yield for a detailed yield breakdown:

curl -X GET "$BASE_URL/v2/wallets/$WALLET_ID/yield" \
  -H "Authorization: Bearer $API_TOKEN"

{
  "walletId": "9d1a1c83-3a1c-4c14-9c5a-0c9a57a4a7db",
  "earnedUsd": "250.000000",
  "annualizedUsd": "3821.400000",
  "currentBalanceUsd": "82500.000000",
  "positions": [
    {
      "yieldSourceId": "syrup-usdc",
      "name": "Syrup USDC",
      "denominationCurrency": "USD",
      "apyBps": 453,
      "pct": 40,
      "deployedValueUsd": "33000.000000",
      "navUpdateMode": "continuous",
      "priceAsOf": "2026-10-19T12:00:00.000Z"
    },
    {
      "yieldSourceId": "morpho-gauntlet-usdc",
      "name": "Morpho Gauntlet USDC Prime",
      "denominationCurrency": "USD",
      "apyBps": 472,
      "pct": 30,
      "deployedValueUsd": "24750.000000",
      "navUpdateMode": "continuous",
      "priceAsOf": "2026-10-19T12:00:00.000Z"
    },
    {
      "yieldSourceId": "morpho-steakhouse-usdc",
      "name": "Morpho Steakhouse USDC Prime",
      "denominationCurrency": "USD",
      "apyBps": 468,
      "pct": 30,
      "deployedValueUsd": "24750.000000",
      "navUpdateMode": "continuous",
      "priceAsOf": "2026-10-19T12:00:00.000Z"
    }
  ]
}

Response fields

Field	Description
`earnedUsd`	Cumulative yield earned (same as `balance.earnedUsd` on the wallet)
`annualizedUsd`	Estimated annualized yield in USD; `null` while any non-USD-denominated investment is held
`currentBalanceUsd`	Current total wallet balance
`positions`	Per-source APY and allocation breakdown

Yield source fields

Field	Description
`yieldSourceId`	Identifier for the yield source
`name`	Display name
`denominationCurrency`	Currency of the source APY, such as USD or MXN; position values remain USD
`apyBps`	Historical annualized 30-day return in `denominationCurrency` (100 bps = 1%). `null` when history is unavailable.
`pct`	Actual deployed value as a percentage of the total wallet balance, including cash
`deployedValueUsd`	Current USD value deployed to this yield source
`navUpdateMode`	`continuous` or `discrete` when known; controls whether client-side accrual between snapshots is appropriate
`priceAsOf`	Timestamp of the reference price used for the position’s value; `null` when unavailable

Displaying yield to users

Recommended approach

Total earned — use balance.earnedUsd from the wallet response or earnedUsd from the yield endpoint
Portfolio APY (30-day) — when all held sources have denominationCurrency: "USD", compute a blended APY from the yield endpoint’s positions array:
blendedApyBps = sum(source.apyBps * source.pct / 100) for each source
USD sources use the same historical 30-day APY as the yield-source catalog. Cash earns 0% and is included in the total balance used for the weights. This works for manual and auto-rebalancing wallets. If a held source is non-USD or has unavailable APY, show the blend as unavailable.
Yield breakdown — show each yield source’s name, apyBps, and pct from the yield endpoint
Performance over time — for charts, use GET /v2/accounting/yield/earned-series: cumulativeEarnedUsd per point for an earned-dollars line, and the precomputed blendedApyBps per point for an APY line (same weighted-blend idea as above, computed server-side from trailing NAV growth at each historical point). See Balances and Yield.

Non-USD investments

When a wallet holds CETES or another non-USD investment, this endpoint returns the source’s APY in denominationCurrency and annualizedUsd: null. The earned-series endpoint also returns blendedApyBps: null for dates when non-USD investments were held. Display these rates as unavailable, not 0%. USD balances and earned amounts remain available. Display CETES’s MXN APY separately, using the position’s denominationCurrency label.

{
  "walletId": "b1c2d3e4-0000-4000-8000-000000000001",
  "earnedUsd": "0.040000",
  "annualizedUsd": null,
  "currentBalanceUsd": "18.950000",
  "positions": [
    {
      "yieldSourceId": "etherfuse-cetes-stellar",
      "name": "Etherfuse Mexican Treasuries (CETES)",
      "denominationCurrency": "MXN",
      "apyBps": 570,
      "pct": 80,
      "deployedValueUsd": "15.160000",
      "navUpdateMode": "discrete",
      "priceAsOf": "2026-10-23T12:00:00.000Z"
    }
  ]
}

Current rate previews

A catalog row may include an optional currentApy with apyBps, asOf, and validUntil. Display this separately as Current APY and stop displaying it at validUntil. It is a source’s current rate preview; wallet earnings use actual position valuation, and portfolio APY uses historical apyBps. A current preview can be available while historical APY is still null. See the yield-source details for each source’s valuation and rate methodology.

Important notes

apyBps uses the historical 30-day basis. Source-specific valuation and annualization methods are described in the yield-source catalog.
Balances may briefly lag deposits or withdrawals due to caching. See Balances and Yield for valuation notes.
earnedUsd is lifetime. It remains monotonic even when individual source valuations update on different cadences.

Getting Started

Wallet Lifecycle

Fees

Approvals

Monitoring & Webhooks

Security

Resources

API Reference

Calculating Yield Accrual

How yield accrues

Tokens and shares valued by an exchange rate

Wallet-level earnings

The yield endpoint

Response fields

Yield source fields

Displaying yield to users

Recommended approach

Non-USD investments

Current rate previews

Important notes

​How yield accrues

​Tokens and shares valued by an exchange rate

​Wallet-level earnings

​The yield endpoint

​Response fields

​Yield source fields

​Displaying yield to users

​Recommended approach

​Non-USD investments

​Current rate previews

​Important notes

How yield accrues

Tokens and shares valued by an exchange rate

Wallet-level earnings

The yield endpoint

Response fields

Yield source fields

Displaying yield to users

Recommended approach

Non-USD investments

Current rate previews

Important notes