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

# 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

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

## Shared parameters

All historical endpoints take the same path and query parameters.

**Path Parameters**

<ParamField path="chainId" type="integer" required>
  EVM chain ID (e.g. `1` for Ethereum, `8453` for Base).
</ParamField>

<ParamField path="vaultAddress" type="string" required>
  0x-prefixed, 40-hex vault contract address.
</ParamField>

**Query Parameters**

<ParamField query="startDate" type="string" required>
  Inclusive lower bound of the range, RFC3339 / ISO-8601 (e.g. `2025-06-11T00:00:00Z`).
</ParamField>

<ParamField query="endDate" type="string" required>
  Inclusive upper bound of the range, RFC3339 / ISO-8601.
</ParamField>

<ParamField query="step" type="integer" default="86400">
  Point spacing (granularity) in **seconds**. Defaults to `86400` (1 day).
</ParamField>

<ParamField query="apyInterval" type="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.
</ParamField>

## APR over time

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

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

**Response**

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

<ResponseField name="data" type="array">
  Ordered list of APR buckets.
</ResponseField>

<ResponseField name="data[].timestamp" type="string">
  Bucket representative time, RFC3339 / ISO-8601.
</ResponseField>

<ResponseField name="data[].blockNumber" type="integer">
  On-chain block number of the snapshot chosen as the bucket representative.
</ResponseField>

<ResponseField name="data[].apr" type="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.
</ResponseField>

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

```json theme={null}
{
  "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
```

<CodeGroup>
  ```bash curl theme={null}
  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"
  ```

  ```typescript TypeScript theme={null}
  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();
  ```
</CodeGroup>

**Response**

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

<ResponseField name="baseAsset" type="object | null">
  The vault's underlying token. `null` when the vault has not been indexed yet, or its token is not registered.
</ResponseField>

<ResponseField name="data[].sharePrice" type="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.
</ResponseField>

## TVL over time

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

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

**Response** (shape once data is available)

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

<ResponseField name="data[].tvl" type="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.
</ResponseField>