> ## 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.

# Rewards and history

> Read what a position is currently earning and holding, then query historical reward rate and TVL as time series.

Knowing what a position is earning right now is one field on the yield. Knowing what it has actually earned over time is harder: every protocol distributes and reports rewards differently, so answering that question at scale means indexing many protocols consistently. That data complexity, not a separate product, is what [Platform › Data](/documentation/platform/data/index) covers in depth.

This page is the Earn-side surface: current rate, current holdings, and the two history endpoints available today.

## Current rate: `rewardRate` on the yield

`rewardRate` on the `YieldDto` is the yield's current estimated return: a `total`, a `rateType` (`APR` or `APY`), and a `components[]` breakdown by `yieldSource` (`staking`, `lending`, `campaign_incentive`, and others). It is a snapshot, not a series. See [Yield metadata](/documentation/earn/core-concepts/yield-metadata#reward-rate) for the full field list.

## Rewards held by a position

A position's outstanding rewards show up as a `claimable` balance, and, when a claim step is required, as a `CLAIM_REWARDS` pending action on that balance. See [Balances and positions](/documentation/earn/core-concepts/balances-positions) for the full balance shape and how to read `pendingActions`.

`mechanics.rewardClaiming` (`auto` or `manual`) and `mechanics.rewardSchedule` tell you what to expect before a position exists; see [Yield metadata](/documentation/earn/core-concepts/yield-metadata#mechanics).

## Historical APY

`GET /v1/yields/{yieldId}/reward-rate/history` returns a time series of the yield's `rewardRate` over time, for charts and rate comparisons. Each data point is one snapshot: a `timestamp` and the `rewardRate` at that time, as a decimal string.

Query it with a `period` (`1d`, `7d`, `30d`, `90d`, `1y`, `all`, default `30d`) or an explicit `from` / `to` range, an `interval` (`day`, `week`, `month`, default `day`), and `limit` / `offset` for pagination.

## Historical TVL

`GET /v1/yields/{yieldId}/tvl/history` returns the same kind of series for Total Value Locked. Each data point carries a `timestamp`, `tvl` (human-readable token units), and `tvlRaw` (smallest unit). It takes the same `period` / `from` / `to`, `interval`, and pagination parameters, plus an optional `feeConfigurationId` to resolve TVL for a partner allocator vault instead of the underlying yield.

## Current, historical, and held are not the same thing

<Note>
  `rewardRate` is the yield's current rate, not a history. Reward rate and TVL history are independent time series for that same yield, not a position's balance. A position's actual holdings, including anything claimable, live in balances. Query the one that answers your question instead of deriving one from another.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="Balances and positions" icon="wallet" href="/documentation/earn/core-concepts/balances-positions">
    Read a position's current holdings, including claimable rewards and pending actions.
  </Card>

  <Card title="Platform › Data" icon="database" href="/documentation/platform/data/index">
    Why reward and historical data is hard to get right across protocols.
  </Card>
</CardGroup>


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