> ## Documentation Index
> Fetch the complete documentation index at: https://yieldxyz.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/documentation/earn/core-concepts/yield-metadata) |
| Current position holdings and pending actions | [Balances and positions](/documentation/earn/core-concepts/balances-positions) |
| Historical reward rate and historical TVL, as time series | [Rewards and history](/documentation/earn/core-concepts/rewards-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](/documentation/advanced-setup/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](/documentation/earn/core-concepts/rewards-history) for parameters and responses, or the reference pages for [reward rate history](/api-reference/YieldsController_getYieldRewardRateHistory) and [TVL history](/api-reference/YieldsController_getYieldTvlHistory); this page is about why the data behind them takes protocol-specific indexing to produce.

<Note>
  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.
</Note>

## Next steps

<Columns cols={2}>
  <Card title="Rewards and history" icon="clock-rotate-left" href="/documentation/earn/core-concepts/rewards-history">
    Current rate, held rewards, and the historical APY and TVL endpoints in full.
  </Card>

  <Card title="Yield metadata" icon="tags" href="/documentation/earn/core-concepts/yield-metadata">
    The full current-state model behind every yield.
  </Card>

  <Card title="Balances and positions" icon="wallet" href="/documentation/earn/core-concepts/balances-positions">
    Read what an address currently holds and what it can do next.
  </Card>

  <Card title="Reporting" icon="chart-line" href="/documentation/advanced-setup/reporting">
    Account and business-level reporting across your projects.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.