> ## 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 TVL

> Time-series TVL for an opportunity vault.

<Note>
  Send your API key via the `X-API-Key` header. See [Authentication](/sdk/authentication/api-keys).
</Note>

## Overview

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

## TVL over time

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

<CodeGroup>
  ```bash curl theme={null}
  curl -X GET "https://earn.turtle.xyz/v2/opportunities/1/0xabc...def/historical/tvl?intervalSeconds=86400" \
    -H "X-API-Key: pk_live_xxxxx"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    'https://earn.turtle.xyz/v2/opportunities/1/0xabc...def/historical/tvl?intervalSeconds=86400',
    { headers: { 'X-API-Key': 'pk_live_xxxxx' } }
  );
  const { baseAsset, data } = await res.json();
  ```
</CodeGroup>

**Path Parameters**

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

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

**Query Parameters**

<ParamField query="intervalSeconds" type="integer" default="86400">
  Bucket width in seconds. Defaults to `86400` (1 day).
</ParamField>

<ParamField query="fromTimestamp" type="integer">
  Start of range, Unix seconds, inclusive. Defaults to `now - 30 days`.
</ParamField>

<ParamField query="toTimestamp" type="integer">
  End of range, Unix seconds, inclusive. Defaults to `now`.
</ParamField>

**Response**

```json theme={null}
{
  "baseAsset": {
    "symbol": "USDC",
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "decimals": 6
  },
  "data": [
    {
      "timestamp": 1748736000,
      "blockNumber": 20111222,
      "tvl": { "native": 1250000.0, "usd": 1250500.0 }
    }
  ]
}
```

<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" type="array">
  Ordered list of TVL buckets.
</ResponseField>

<ResponseField name="data[].timestamp" type="integer">
  Bucket representative time, Unix seconds.
</ResponseField>

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

<ResponseField name="data[].tvl" type="object">
  TVL for the bucket. `tvl.native` is denominated in the base asset; `tvl.usd` is the USD value, or `null` when no USD price was available for that bucket.
</ResponseField>