Skip to main content
Send your API key via the X-API-Key header. See Authentication.

​
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

curl -X GET "https://earn.turtle.xyz/v2/opportunities/1/0xabc...def/historical/tvl?intervalSeconds=86400" \
  -H "X-API-Key: pk_live_xxxxx"
Path Parameters
​
chainId
integer
required
EVM chain ID (e.g. 1 for Ethereum).
​
vaultAddress
string
required
0x-prefixed, 40-hex vault contract address.
Query Parameters
​
intervalSeconds
integer
default:"86400"
Bucket width in seconds. Defaults to 86400 (1 day).
​
fromTimestamp
integer
Start of range, Unix seconds, inclusive. Defaults to now - 30 days.
​
toTimestamp
integer
End of range, Unix seconds, inclusive. Defaults to now.
Response 
{
  "baseAsset": {
    "symbol": "USDC",
    "address": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "decimals": 6
  },
  "data": [
    {
      "timestamp": 1748736000,
      "blockNumber": 20111222,
      "tvl": { "native": 1250000.0, "usd": 1250500.0 }
    }
  ]
}
​
baseAsset
object | null
The vault’s underlying token. null when the vault has not been indexed yet, or its token is not registered.
​
data
array
Ordered list of TVL buckets.
​
data[].timestamp
integer
Bucket representative time, Unix seconds.
​
data[].blockNumber
integer
On-chain block number of the snapshot chosen as the bucket representative.
​
data[].tvl
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.