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

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

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.

Next steps

Balances and positions

Read a position’s current holdings, including claimable rewards and pending actions.

Platform › Data

Why reward and historical data is hard to get right across protocols.