Yield Index API - 1tx Documentation

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.

APY values are returned as decimals, not percentages. For example, 0.052 means 5.2% APY.

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

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

Request

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

[
  {
    "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

GET /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

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.

Response

Same shape as Get Yield Index.

Get Instrument Yield Series

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

Request

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

[
  {
    "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

GET /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

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.

Response

[
  {
    "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

GET /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

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.

Response

[
  {
    "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

beta90d is sensitivity of quoted APY to the category index APY. It is not CAPM beta on investment returns.

Get Correlations

GET /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

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

[
  {
    "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`

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.

Refresh Yield Index Views

POST /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

curl -X POST \
  -H "x-api-key: your-api-key" \
  "https://api.1tx.fi/api/v1/yield-index/refresh"

Response

{
  "success": true,
  "durationMs": 322,
  "timestamp": "2026-05-01T12:00:00.000Z"
}

TypeScript Example

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();
}

​Overview

​Methodology

​Get Yield Index

​Request

​Path Parameters

​Query Parameters

​Response

​Response Fields

​Get Index Features

​Request

​Parameters

​Response

​Get Instrument Yield Series

​Request

​Path Parameters

​Query Parameters

​Response

​Response Fields

​Get Instrument vs Index

​Request

​Parameters

​Response

​Additional Response Fields

​Get Instrument Features

​Request

​Parameters

​Response

​Response Fields

​Get Correlations

​Request

​Path Parameters

​Query Parameters

​Response

​Response Fields

​Refresh Yield Index Views

​Request

​Response

​TypeScript Example

​Next Steps

Metrics API

Instruments API

Overview

Methodology

Get Yield Index

Request

Path Parameters

Query Parameters

Response

Response Fields

Get Index Features

Request

Parameters

Response

Get Instrument Yield Series

Request

Path Parameters

Query Parameters

Response

Response Fields

Get Instrument vs Index

Request

Parameters

Response

Additional Response Fields

Get Instrument Features

Request

Parameters

Response

Response Fields

Get Correlations

Request

Path Parameters

Query Parameters

Response

Response Fields

Refresh Yield Index Views

Request

Response

TypeScript Example

Next Steps