Historical Data

Time-series APR, APY, share price, and TVL for an opportunity vault.

Overview

Return a vault’s historical metrics over time, bucketed at a configurable interval. Every endpoint is keyed by chain ID plus vault address and backed by Turtle’s on-chain vault-metrics indexer.

There are four series, plus a combined endpoint:

• GET /v2/opportunities/{chainId}/{vaultAddress}/historical/apr for APR over time
• GET /v2/opportunities/{chainId}/{vaultAddress}/historical/apy for APY over time
• GET /v2/opportunities/{chainId}/{vaultAddress}/historical/share-price for share price over time
• GET /v2/opportunities/{chainId}/{vaultAddress}/historical/tvl for TVL over time
• GET /v2/opportunities/{chainId}/{vaultAddress}/historical for the combined series

Availability: the APR, APY, and share price series are live and returning data. Historical TVL (and the combined /historical endpoint, which includes it) is still coming online. These currently return an empty data array for most vaults while the TVL backfill completes.

Shared parameters

All historical endpoints take the same path and query parameters.

Path Parameters

chainId · integer · required

EVM chain ID (e.g. 1 for Ethereum, 8453 for Base).

vaultAddress · string · required

0x-prefixed, 40-hex vault contract address.

Query Parameters

startDate · string · required

Inclusive lower bound of the range, RFC3339 / ISO-8601 (e.g. 2025-06-11T00:00:00Z).

endDate · string · required

Inclusive upper bound of the range, RFC3339 / ISO-8601.

step · integer · default: "86400"

Point spacing (granularity) in seconds. Defaults to 86400 (1 day).

apyInterval · integer · default: "604800"

APY/APR trailing window (lookback) in seconds, independent of step. Defaults to 604800 (7 days). Applies to the apr and apy series.

APR over time

GET /v2/opportunities/{chainId}/{vaultAddress}/historical/apr

curl

curl -X GET "https://earn.turtle.xyz/v2/opportunities/8453/0x25d9...832d/historical/apr?step=86400&startDate=2025-06-11T00:00:00Z&endDate=2026-06-11T00:00:00Z"

const res = await fetch(
  'https://earn.turtle.xyz/v2/opportunities/8453/0x25d9...832d/historical/apr?step=86400&startDate=2025-06-11T00:00:00Z&endDate=2026-06-11T00:00:00Z'
);
const { data } = await res.json();

Response

{
  "data": [
    {
      "timestamp": "2026-06-10T23:49:35Z",
      "blockNumber": 47173014,
      "apr": { "base": 0.0824, "reward": 0, "total": 0.0824 }
    }
  ]
}

data · array

Ordered list of APR buckets.

data[].timestamp · string

Bucket representative time, RFC3339 / ISO-8601.

data[].blockNumber · integer

On-chain block number of the snapshot chosen as the bucket representative.

data[].apr · object

APR for the bucket, expressed as a decimal (e.g. 0.0824 = 8.24%). base is the underlying yield, reward is incentive APR, and total is their sum.

APY over time

GET /v2/opportunities/{chainId}/{vaultAddress}/historical/apy

Identical shape to APR, with an apy object (base / reward / total) in place of apr.

{
  "data": [
    {
      "timestamp": "2026-06-10T23:49:35Z",
      "blockNumber": 47173014,
      "apy": { "base": 0.0858, "reward": 0, "total": 0.0858 }
    }
  ]
}

Share price over time

GET /v2/opportunities/{chainId}/{vaultAddress}/historical/share-price

curl

curl -X GET "https://earn.turtle.xyz/v2/opportunities/8453/0x25d9...832d/historical/share-price?step=86400&startDate=2025-06-11T00:00:00Z&endDate=2026-06-11T00:00:00Z"

const res = await fetch(
  'https://earn.turtle.xyz/v2/opportunities/8453/0x25d9...832d/historical/share-price?step=86400&startDate=2025-06-11T00:00:00Z&endDate=2026-06-11T00:00:00Z'
);
const { baseAsset, data } = await res.json();

Response

{
  "baseAsset": {
    "symbol": "USDT",
    "address": "0xfde4c96c8593536e31f229ea8f37b2ada2699bb2",
    "decimals": 6
  },
  "data": [
    {
      "timestamp": "2026-06-10T23:49:35Z",
      "blockNumber": 47173014,
      "sharePrice": { "native": 1.02403, "usd": 1.0231 }
    }
  ]
}

baseAsset · object | null

The vault’s underlying token. null when the vault has not been indexed yet, or its token is not registered.

data[].sharePrice · object

Share price for the bucket. native is denominated in the base asset; usd is the USD value, or null when no USD price was available for that bucket.

TVL over time

Historical TVL is coming online. The endpoint is live and accepts the shared parameters, but currently returns an empty data array ({ "baseAsset": null, "data": [] }) for most vaults while the TVL backfill completes.

GET /v2/opportunities/{chainId}/{vaultAddress}/historical/tvl

Response (shape once data is available)

{
  "baseAsset": {
    "symbol": "USDC",
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "decimals": 6
  },
  "data": [
    {
      "timestamp": "2026-06-10T23:49:35Z",
      "blockNumber": 47173014,
      "tvl": { "native": 1250000.0, "usd": 1250500.0 }
    }
  ]
}

data[].tvl · object

TVL for the bucket. native is denominated in the base asset; usd is the USD value, or null when no USD price was available for that bucket.