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

# Yield Index API

> Benchmark DeFi yield instruments against category indexes and derived risk features

## Overview

The Yield Index API exposes daily benchmark series for each asset category, per-instrument compounded growth, alpha versus the benchmark, rolling yield features, and pairwise instrument correlations.

All endpoints are under the global `/api/v1` prefix and use `x-api-key` authentication.

Supported asset categories are `USD`, `EUR`, `ETH`, and `BTC`.

<Note>
  APY values are returned as decimals, not percentages. For example, `0.052` means `5.2%` APY.
</Note>

## Methodology

The category index is a daily, TVL-weighted benchmark over active instruments in the same `assetCategory`.

Key details:

* Instruments with daily TVL at or below `$100,000` are excluded from the category aggregate for that day.
* Each instrument's index weight is capped at `20%` before the aggregate APY is calculated.
* `indexApy` uses total APY, including rewards.
* `indexApyBase` uses base APY only, excluding rewards where the source provides a split.
* Growth curves compound daily with `growth = product(1 + apy / 365)`.
* Instrument `syntheticGrowthTotal` compounds total APY, while `syntheticGrowthBase` compounds base APY.
* `pricePerShare` is returned when the upstream source provides realized vault share-price data.

## Get Yield Index

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/yield-index/:category`

Retrieve the daily category benchmark series, including index APY, compounded growth, TVL, and index-level rolling features.

### Request

```bash theme={null}
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/USD?from=2026-01-01&to=2026-05-01"
```

### Path Parameters

| Parameter  | Type   | Required | Description                                   |
| ---------- | ------ | -------- | --------------------------------------------- |
| `category` | string | Yes      | Asset category: `USD`, `EUR`, `ETH`, or `BTC` |

### Query Parameters

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `from`    | string | No       | Inclusive start date in `YYYY-MM-DD` format |
| `to`      | string | No       | Inclusive end date in `YYYY-MM-DD` format   |

### Response

```json theme={null}
[
  {
    "day": "2026-05-01",
    "indexApy": 0.0412,
    "indexApyBase": 0.0387,
    "indexGrowth": 1.1864,
    "indexGrowthBase": 1.1721,
    "totalTvlUsd": 1200000000,
    "indexApyMean30d": 0.0405,
    "indexApyStdev30d": 0.0031,
    "indexApyCv30d": 0.0765,
    "indexApyObsCount30d": 30,
    "indexApyMean90d": 0.0398,
    "indexApyStdev90d": 0.0042,
    "indexApyCv90d": 0.1055,
    "indexApyObsCount90d": 90,
    "indexApyMean365d": 0.0431,
    "indexApyStdev365d": 0.0069,
    "indexApyCv365d": 0.1601,
    "indexApyObsCount365d": 365
  }
]
```

### Response Fields

| Field                          | Type           | Description                                                 |
| ------------------------------ | -------------- | ----------------------------------------------------------- |
| `day`                          | string         | UTC calendar day in `YYYY-MM-DD` format                     |
| `indexApy`                     | number         | TVL-weighted total category APY for the day                 |
| `indexApyBase`                 | number         | TVL-weighted base category APY for the day                  |
| `indexGrowth`                  | number         | Daily-compounded growth of \$1 using `indexApy`             |
| `indexGrowthBase`              | number         | Daily-compounded growth of \$1 using `indexApyBase`         |
| `totalTvlUsd`                  | number         | Total eligible TVL in USD before weight caps                |
| `indexApyMean{30,90,365}d`     | number \| null | Rolling mean of `indexApy` over the window                  |
| `indexApyStdev{30,90,365}d`    | number \| null | Rolling standard deviation of `indexApy` over the window    |
| `indexApyCv{30,90,365}d`       | number \| null | Rolling coefficient of variation, `stdev / mean`            |
| `indexApyObsCount{30,90,365}d` | number         | Number of non-null daily observations in the rolling window |

***

## Get Index Features

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/yield-index/:category/features`

Retrieve the same index-level feature shape returned by `GET /yield-index/:category`. This alias is useful when consumers want to treat category features separately from instrument features.

### Request

```bash theme={null}
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/USD/features?from=2026-04-01"
```

### Parameters

Same as [Get Yield Index](#get-yield-index).

### Response

Same shape as [Get Yield Index](#get-yield-index).

***

## Get Instrument Yield Series

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/yield-index/instrument/:id`

Retrieve a daily instrument yield series with APY, TVL, optional price-per-share, and compounded synthetic growth curves.

### Request

```bash theme={null}
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/instrument/0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b?from=2026-01-01"
```

### Path Parameters

| Parameter | Type   | Required | Description                                            |
| --------- | ------ | -------- | ------------------------------------------------------ |
| `id`      | string | Yes      | Public instrument ID, or internal UUID when applicable |

### Query Parameters

| Parameter | Type   | Required | Description                                 |
| --------- | ------ | -------- | ------------------------------------------- |
| `from`    | string | No       | Inclusive start date in `YYYY-MM-DD` format |
| `to`      | string | No       | Inclusive end date in `YYYY-MM-DD` format   |

### Response

```json theme={null}
[
  {
    "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
    "assetCategory": "USD",
    "protocolName": "Aave",
    "chainId": 8453,
    "tokenSymbol": "USDC",
    "description": "Aave V3 USDC lending pool on Base",
    "day": "2026-05-01",
    "apy": 0.0452,
    "apyBase": 0.0431,
    "apyReward": 0.0021,
    "tvlUsd": 1250000000,
    "pricePerShare": null,
    "syntheticGrowthTotal": 1.1172,
    "syntheticGrowthBase": 1.1094
  }
]
```

### Response Fields

| Field                  | Type           | Description                                               |
| ---------------------- | -------------- | --------------------------------------------------------- |
| `instrumentId`         | string         | Public instrument identifier                              |
| `assetCategory`        | string         | Instrument asset category                                 |
| `protocolName`         | string \| null | Protocol name                                             |
| `chainId`              | number         | Chain ID                                                  |
| `tokenSymbol`          | string \| null | Underlying token symbol                                   |
| `description`          | string \| null | Human-readable instrument description                     |
| `day`                  | string         | UTC calendar day in `YYYY-MM-DD` format                   |
| `apy`                  | number         | Total APY for the day, including rewards                  |
| `apyBase`              | number \| null | Base APY for the day                                      |
| `apyReward`            | number \| null | Reward APY for the day                                    |
| `tvlUsd`               | number         | Total value locked in USD                                 |
| `pricePerShare`        | number \| null | Realized vault share price when available from the source |
| `syntheticGrowthTotal` | number         | Daily-compounded growth using total APY                   |
| `syntheticGrowthBase`  | number         | Daily-compounded growth using base APY                    |

***

## Get Instrument vs Index

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/yield-index/instrument/:id/vs-index`

Retrieve an instrument series joined to its asset-category index for the same days. This endpoint adds index APY, index growth, and `alpha`.

### Request

```bash theme={null}
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/instrument/0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b/vs-index?from=2026-01-01"
```

### Parameters

Same as [Get Instrument Yield Series](#get-instrument-yield-series).

### Response

```json theme={null}
[
  {
    "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
    "assetCategory": "USD",
    "protocolName": "Aave",
    "chainId": 8453,
    "tokenSymbol": "USDC",
    "description": "Aave V3 USDC lending pool on Base",
    "day": "2026-05-01",
    "apy": 0.0452,
    "apyBase": 0.0431,
    "apyReward": 0.0021,
    "tvlUsd": 1250000000,
    "pricePerShare": null,
    "syntheticGrowthTotal": 1.1172,
    "syntheticGrowthBase": 1.1094,
    "indexApy": 0.0412,
    "indexApyBase": 0.0387,
    "indexGrowth": 1.1864,
    "indexGrowthBase": 1.1721,
    "alpha": -0.0692
  }
]
```

### Additional Response Fields

| Field             | Type   | Description                                               |
| ----------------- | ------ | --------------------------------------------------------- |
| `indexApy`        | number | Category index total APY for the day                      |
| `indexApyBase`    | number | Category index base APY for the day                       |
| `indexGrowth`     | number | Category index compounded growth using total APY          |
| `indexGrowthBase` | number | Category index compounded growth using base APY           |
| `alpha`           | number | Instrument total growth minus category index total growth |

***

## Get Instrument Features

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/yield-index/instrument/:id/features`

Retrieve daily rolling features for an instrument, including APY stability metrics, percentile bands, reward share, TVL growth, alpha versus the index, beta to the index APY, and alpha drawdown.

### Request

```bash theme={null}
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/instrument/0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b/features?from=2026-04-01&to=2026-05-01"
```

### Parameters

Same as [Get Instrument Yield Series](#get-instrument-yield-series).

### Response

```json theme={null}
[
  {
    "day": "2026-05-01",
    "instrumentId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
    "assetCategory": "USD",
    "apyMean30d": 0.0441,
    "apyStdev30d": 0.0043,
    "apyCv30d": 0.0975,
    "apyP1030d": 0.0386,
    "apyP9030d": 0.0512,
    "apyObsCount30d": 30,
    "apyMean90d": 0.0434,
    "apyStdev90d": 0.0051,
    "apyCv90d": 0.1175,
    "apyP1090d": 0.0368,
    "apyP9090d": 0.0524,
    "apyObsCount90d": 90,
    "apyMean365d": 0.0462,
    "apyStdev365d": 0.0087,
    "apyCv365d": 0.1883,
    "apyP10365d": 0.0341,
    "apyP90365d": 0.0603,
    "apyObsCount365d": 365,
    "apyZscore90d": 0.35,
    "rewardShare": 0.0465,
    "tvlGrowth7d": 0.012,
    "tvlGrowth30d": 0.084,
    "alpha30d": 0.0011,
    "alpha90d": -0.0048,
    "beta90d": 0.82,
    "betaR290d": 0.43,
    "alphaCurrentDd": -0.0062,
    "alphaMaxDd365d": -0.0314,
    "alphaDdDurationDays": 42
  }
]
```

### Response Fields

| Field                     | Type           | Description                                                          |
| ------------------------- | -------------- | -------------------------------------------------------------------- |
| `day`                     | string         | UTC calendar day in `YYYY-MM-DD` format                              |
| `instrumentId`            | string         | Public instrument identifier                                         |
| `assetCategory`           | string         | Instrument asset category                                            |
| `apyMean{30,90,365}d`     | number \| null | Rolling mean of instrument APY over the window                       |
| `apyStdev{30,90,365}d`    | number \| null | Rolling standard deviation of instrument APY over the window         |
| `apyCv{30,90,365}d`       | number \| null | Rolling coefficient of variation, `stdev / mean`                     |
| `apyP10{30,90,365}d`      | number \| null | Rolling 10th percentile of instrument APY over the window            |
| `apyP90{30,90,365}d`      | number \| null | Rolling 90th percentile of instrument APY over the window            |
| `apyObsCount{30,90,365}d` | number         | Number of non-null daily APY observations in the rolling window      |
| `apyZscore90d`            | number \| null | Current APY relative to the 90-day distribution                      |
| `rewardShare`             | number \| null | Current `apyReward / apy`                                            |
| `tvlGrowth7d`             | number \| null | TVL growth over 7 days, calculated as `current / lag - 1`            |
| `tvlGrowth30d`            | number \| null | TVL growth over 30 days, calculated as `current / lag - 1`           |
| `alpha30d`                | number \| null | Instrument growth minus index growth over the trailing 30-day window |
| `alpha90d`                | number \| null | Instrument growth minus index growth over the trailing 90-day window |
| `beta90d`                 | number \| null | Rolling slope of instrument APY regressed on category index APY      |
| `betaR290d`               | number \| null | R-squared of the rolling 90-day APY regression                       |
| `alphaCurrentDd`          | number \| null | Current drawdown of the alpha curve from its running high            |
| `alphaMaxDd365d`          | number \| null | Worst alpha-curve drawdown over the trailing year                    |
| `alphaDdDurationDays`     | number \| null | Days since the alpha curve last reached a high                       |

<Warning>
  `beta90d` is sensitivity of quoted APY to the category index APY. It is not CAPM beta on investment returns.
</Warning>

***

## Get Correlations

<span style={{color: '#10B981', fontWeight: 'bold'}}>GET</span> `/yield-index/correlations/:category`

Retrieve pairwise instrument correlations for an asset category. Correlations are computed on daily APY changes, not APY levels, to reduce bias from autocorrelated yield series.

By default, this endpoint returns the latest available day and the `90` day window.

### Request

```bash theme={null}
curl -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/correlations/USD?day=2026-05-01&window=90"
```

### Path Parameters

| Parameter  | Type   | Required | Description                                   |
| ---------- | ------ | -------- | --------------------------------------------- |
| `category` | string | Yes      | Asset category: `USD`, `EUR`, `ETH`, or `BTC` |

### Query Parameters

| Parameter      | Type   | Required | Description                                                                                       |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------- |
| `day`          | string | No       | Correlation matrix day in `YYYY-MM-DD` format. Defaults to the latest available day.              |
| `window`       | number | No       | Rolling window to return: `30`, `90`, or `365`. Defaults to `90`.                                 |
| `instrumentId` | string | No       | Limit results to pairs containing this instrument. Accepts public instrument ID or internal UUID. |

### Response

```json theme={null}
[
  {
    "day": "2026-05-01",
    "instrumentAId": "0x00002105c053a3e1290845e12a3eea14926472ce7f15da324cdf0700056fc04b",
    "instrumentBId": "0x00002105e1d832a44e229e784c3d4afba9a1ca44a288e34f7e5ddcba23155adc",
    "assetCategory": "USD",
    "corr": 0.27,
    "overlapDays": 90,
    "window": 90,
    "instrumentAName": "Aave V3 USDC lending pool on Base",
    "instrumentBName": "Morpho USDC vault on Base",
    "instrumentAProtocol": "Aave",
    "instrumentBProtocol": "Morpho",
    "instrumentAApy": 0.0452,
    "instrumentBApy": 0.0508,
    "instrumentAApyCv90d": 0.1175,
    "instrumentBApyCv90d": 0.1392
  }
]
```

### Response Fields

| Field                 | Type           | Description                                                       |
| --------------------- | -------------- | ----------------------------------------------------------------- |
| `day`                 | string         | UTC calendar day in `YYYY-MM-DD` format                           |
| `instrumentAId`       | string         | First public instrument identifier                                |
| `instrumentBId`       | string         | Second public instrument identifier                               |
| `assetCategory`       | string         | Shared asset category for the pair                                |
| `corr`                | number \| null | Pearson correlation over the requested window                     |
| `overlapDays`         | number         | Number of overlapping daily APY-change observations in the window |
| `window`              | number         | Returned rolling window, one of `30`, `90`, or `365`              |
| `instrumentAName`     | string \| null | First instrument description                                      |
| `instrumentBName`     | string \| null | Second instrument description                                     |
| `instrumentAProtocol` | string \| null | First instrument protocol                                         |
| `instrumentBProtocol` | string \| null | Second instrument protocol                                        |
| `instrumentAApy`      | number \| null | Latest current APY for the first instrument                       |
| `instrumentBApy`      | number \| null | Latest current APY for the second instrument                      |
| `instrumentAApyCv90d` | number \| null | First instrument's 90-day APY coefficient of variation on `day`   |
| `instrumentBApyCv90d` | number \| null | Second instrument's 90-day APY coefficient of variation on `day`  |

<Note>
  Use `overlapDays` to filter sparse pairs. For example, a 365-day correlation with only 40 overlapping observations is usually not robust enough for portfolio construction.
</Note>

***

## Refresh Yield Index Views

<span style={{color: '#10B981', fontWeight: 'bold'}}>POST</span> `/yield-index/refresh`

Refresh the yield-index materialized views without ingesting new upstream metrics. Most users do not need this endpoint; the normal metrics sync pipeline refreshes the views automatically.

### Request

```bash theme={null}
curl -X POST \
  -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/refresh"
```

### Response

```json theme={null}
{
  "success": true,
  "durationMs": 322,
  "timestamp": "2026-05-01T12:00:00.000Z"
}
```

***

## TypeScript Example

```typescript theme={null}
const BASE_URL = 'https://api.1tx.fi/api/v1';
const API_KEY = process.env['1TX_API_KEY'];

async function getUsdIndex(from?: string) {
  const params = new URLSearchParams();
  if (from) params.set('from', from);

  const response = await fetch(`${BASE_URL}/yield-index/USD?${params}`, {
    headers: { 'x-api-key': API_KEY ?? '' },
  });

  if (!response.ok) {
    throw new Error(`Failed to fetch yield index: ${response.status}`);
  }

  return response.json();
}

async function getInstrumentAlpha(instrumentId: string) {
  const response = await fetch(
    `${BASE_URL}/yield-index/instrument/${instrumentId}/vs-index`,
    { headers: { 'x-api-key': API_KEY ?? '' } }
  );

  if (!response.ok) {
    throw new Error(`Failed to fetch instrument alpha: ${response.status}`);
  }

  return response.json();
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Metrics API" icon="chart-line" href="/api-reference/endpoints/metrics">
    Fetch raw historical APY and TVL data
  </Card>

  <Card title="Instruments API" icon="fingerprint" href="/api-reference/endpoints/instruments">
    Discover instrument IDs and metadata
  </Card>
</CardGroup>