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

# Yields Overview

> Access rolling pool yield/ROI predictions across fixed horizons for pool allocation and performance analysis.

## Overview

The Yields endpoint provides rolling yield/ROI predictions per pool across fixed time horizons (1D, 3D, 7D, 14D, 30D, 90D, 365D). Each prediction is anchored to a specific block/log position and includes aligned arrays for pool tokens, current reserves, observed/predicted volumes, user fees, and ROI fractions. Predictions are derived from historical swap fees and current reserve states.

### Endpoint Matrix

| Endpoint                                               | Summary                                          | Dataset ID | Typical Latency |
| ------------------------------------------------------ | ------------------------------------------------ | ---------- | --------------- |
| [`POST /evm/yields`](/api-reference/evm/yields/yields) | Pool yield/ROI predictions across fixed horizons | `0411`     | \< 300 ms       |

### Parameter Conventions

<ParamField body="chain_id" type="number" required>
  Chain identifier for the target EVM network. See [Chain enumeration](/api-reference/enumerations/chain) for supported values.
</ParamField>

<ParamField body="target_period_days" type="number">
  Target prediction horizon in days. Supported values: 1, 3, 7, 14, 30, 90, 365.
</ParamField>

<ParamField body="from_block" type="number">
  Starting block height (inclusive) for yield predictions.
</ParamField>

<ParamField body="to_block" type="number">
  Ending block height (inclusive) for yield predictions.
</ParamField>

<ParamField body="from_timestamp" type="string">
  Starting timestamp (ISO-8601). If it falls between blocks, the next block after this timestamp is used.
</ParamField>

<ParamField body="to_timestamp" type="string">
  Ending timestamp (ISO-8601). If it falls between blocks, the last block before this timestamp is used.
</ParamField>

<ParamField body="pool_uids" type="string[]">
  BlockDB pool identifiers for filtering yield predictions by pool.
</ParamField>

<ParamField body="pool_addresses" type="string[]">
  Pool contract addresses to scope yield data.
</ParamField>

<ParamField body="require_full_period" type="boolean">
  Only return predictions where `observed_period_days == target_period_days` (no extrapolation).
</ParamField>

<ParamField body="min_roi" type="number">
  Minimum ROI threshold for filtering predictions.
</ParamField>

### Usage Guidance

* **Pool ranking** — Use yield predictions to rank pools by expected fee yield over a horizon
* **Allocation screens** — Build pool allocation signals using APR/ROI predictions with full provenance
* **Model validation** — Compare yield predictions against actual swap fees and reserves for backtesting
* **Horizon selection** — Choose `target_period_days` based on your investment horizon (short-term vs long-term)
* **Full period filtering** — Use `require_full_period: true` to exclude extrapolated predictions when historical data is insufficient

### Yield Calculation

Yield predictions are computed using:

* **Historical swap fees** (from `/evm/swaps/fees`) — Observed fee amounts over the available window
* **Current reserves** (from `/evm/reserves`) — Current pool state for ROI denominator
* **Extrapolation** — When `observed_period_days < target_period_days`, predictions are scaled by `target_period_days / observed_period_days`

ROI per token: `roi_predicted[i] = user_fees_predicted[i] / current_reserves[i]`

### Prediction Quality Indicators

Each yield record includes quality indicators:

* `observed_period_days`: Actual days of history used
* `is_full_period`: `true` when `observed_period_days == target_period_days`
* `is_extrapolated`: `true` when history is shorter than target
* `extrapolation_factor`: Scaling factor applied (target / observed)

### Common Patterns

**Rank pools by 30-day yield:**

```json theme={null}
{
  "chain_id": 1,
  "target_period_days": 30,
  "require_full_period": true,
  "from_timestamp": "2025-12-01T00:00:00Z",
  "to_timestamp": "2025-12-20T00:00:00Z"
}
```

**Get yield predictions for specific pools:**

```json theme={null}
{
  "chain_id": 1,
  "target_period_days": 7,
  "pool_uids": [
    "88e6a0c2ddd26feeb64f039a2c41296fcb3f5640000000000000000000000000"
  ],
  "from_block": 19000000
}
```

**Filter by minimum ROI:**

```json theme={null}
{
  "chain_id": 1,
  "target_period_days": 30,
  "min_roi": 0.05,
  "require_full_period": true
}
```

### Dataset Relationships

* **Swap Fees → Yields**: Historical swap fees are the primary input for yield predictions
* **Reserves → Yields**: Current reserves provide the denominator for ROI calculations
* **Pools → Yields**: Join pool metadata to yield predictions using `pool_uid`
* **Fee Terms → Yields**: Fee terms determine which fees are attributed to LPs/users
* **Yields → Prices**: Yield predictions can inform pricing models for pool tokens

### See Also

* [`POST /evm/yields`](/api-reference/evm/yields/yields) — Yield/ROI predictions endpoint
* [`POST /evm/swaps/fees`](/api-reference/evm/swaps/swap-fees) — Historical swap fees (input to yield models)
* [`POST /evm/reserves`](/api-reference/evm/reserves/reserves) — Current pool reserves (input to yield models)
* [`POST /evm/entities/pools/fee-terms`](/api-reference/evm/entities/fee-terms) — Pool fee configuration
* [`POST /evm/entities/pools`](/api-reference/evm/entities/pools) — Pool metadata registry
* [Pool Type](/api-reference/enumerations/pool-type) — AMM pool classifications