Data

Understand how yield, reward, and TVL data is indexed across protocols, and where to query current and historical values.

Every number the Yield API returns, current or historical, comes from indexing on-chain state. Reading what a position holds right now is comparatively simple. Reconstructing what it actually earned over time is not: every protocol reports rewards, prices, and balances differently, so answering that question consistently across networks means running a dedicated indexing pipeline per protocol family, not a single generic reader.

What you can query

Capability	Where it lives
Current yield metadata: rate, TVL, mechanics, provider and network context	Yield metadata
Current position holdings and pending actions	Balances and positions
Historical reward rate and historical TVL, as time series	Rewards and history

This page explains why historical, indexed data is hard to build consistently; it is not the field-level API contract. For account or business reporting (revenue, actions, KPI summaries), see Reporting.

Why current data is not the same problem as historical data

A yield’s current rewardRate and TVL are live reads: one snapshot, fetched or computed on demand. Some of that snapshot already depends on indexing having run at least once. statistics.tvl and related fields on a YieldDto are null when the yield isn’t ERC-4626-based or its indexer hasn’t produced a value yet, which is one visible edge of the same underlying problem: current data quality is bounded by indexing coverage.

Building a reward-rate/history or tvl/history series means normalizing years of protocol-specific state, not reading one number:

• Some protocols rebase balances directly; others require checkpointing a share price (ERC-4626 vaults) or reading discrete transfer and claim events.
• Reward accounting differs by chain family: EVM liquid staking, Cosmos and Polkadot staking rewards, Solana validator commission, and TON pool flows each expose rewards through a different on-chain shape.
• A protocol’s own state doesn’t carry a ready-made time series; one has to be built and kept current as new blocks arrive.

How the history gets built

yield.xyz runs protocol-specific indexers to turn that raw state into the normalized series the history endpoints serve, for example: ERC-4626 price-per-share and TVL indexing, Lido reward indexing, Morpho borrow position and snapshot indexing, TON pool flow, position, and reward indexing, and native historical balance indexing for chains without an equivalent standard. Each pipeline absorbs one protocol’s accounting model so the output is the same shape regardless of source.

Indexed rows are aggregated into daily snapshots per yield. The finest interval the history endpoints expose is day; week and month aggregate further. This is a data-modeling property of the underlying tables, not a delivery guarantee about how quickly a given block’s activity appears.

Querying the history

The two public history endpoints are:

• GET /v1/yields/{yieldId}/reward-rate/history
• GET /v1/yields/{yieldId}/tvl/history

See Rewards and history for parameters and responses, or the reference pages for reward rate history and TVL history; this page is about why the data behind them takes protocol-specific indexing to produce.

Rewards indexing, balance indexing, and TVL indexing are separate pipelines that can be at different points in their own backfill or catch-up cycle. Treat history as good for charts and trend comparisons, not as a real-time feed of the current block.

Next steps

Rewards and history

Current rate, held rewards, and the historical APY and TVL endpoints in full.

Yield metadata

The full current-state model behind every yield.

Balances and positions

Read what an address currently holds and what it can do next.

Reporting

Account and business-level reporting across your projects.