Yield API and staking APY analytics reference for reward statements, APR, APY, fees, penalties, benchmarks, and forecasts.

Yield API and APY analytics

Design staking reward and yield APIs with explicit rate definitions, time-weighted capital, gross-to-net components, protocol evidence, methodology versions, and forecast uncertainty.

Measurement rule: a staking rate is meaningful only with a defined numerator, denominator, period, compounding assumption, fee treatment, asset unit, methodology version, and data-quality state.

Metric dictionary

Separate realized rewards from projections

Historical statements are built from observed position balances, cash flows, protocol rewards, fees, and penalties. Forecasts are scenario outputs with assumptions and uncertainty.

APR

Annualized simple rate under a stated period and methodology. No compounding implied.

APR contract

APY

Annualized rate with an explicit compounding assumption—not a protocol guarantee.

APY contract

Forecast

Forward scenario with assumptions, range, source, timestamp, and confidence context.

Forecast contract

Illustrative reward statement

Preserve gross components and external flows before deriving a net return.

{
  "period": {"start":"2026-09-01","end":"2026-09-30"},
  "asset": "native-token",
  "average_earning_balance_raw": "...",
  "components": [
    {"type":"protocol_reward","amount_raw":"..."},
    {"type":"provider_fee","amount_raw":"-..."},
    {"type":"penalty","amount_raw":"-..."}
  ],
  "net_reward_raw": "...",
  "methodology": "time-weighted-v2",
  "completeness": "complete"
}

Use time-aware capital

Deposits, activation delays, partial exits, withdrawals, rebasing balances, share-rate changes, and external transfers change the capital actually exposed to staking. A simple beginning- or ending-balance denominator can misstate return.

Build calculations from event-sourced flows and periodic snapshots. Preserve the exact observations referenced by a result. A superseding calculation can correct late data without erasing the previously published value.

Required calculation context

Native asset and raw integer units
Measurement window and protocol cutoffs
Earning-state duration
Gross rewards and reward components
Validator, provider, or protocol fees
Penalties, slashing, and transaction costs
External inflows and outflows
Methodology and adapter version

Benchmark context

State the validator cohort, fees, network, period, sample coverage, data freshness, and exclusions. A benchmark without a defined comparison set is not reproducible.

Forecast context

Return assumptions, scenarios, ranges, and timestamps. Avoid wording that turns a changing estimate into a promised return.

Build reproducible APY analytics

See the full methodology guide for rate definitions, time weighting, reward components, protocol adapters, benchmarks, and corrections.

Read analytics guide