[PRO] Vault Range Historical Data

This endpoint is available to vaults.api premium subscribers. See Plans for details.

The Vault Range Historical DATA (GET /v1/vaults/{network}/{vaultAddress}/historical-data) endpoint provides a chronological series of data for a specified vault, covering a user-defined range of time. This endpoint is useful for getting detailed historical data of a vault over the specified time range.

The maximum time range that can be queried is 30 days.

Only requests made with valid API keys are handled.

Parameters

• interval (required): A query parameter that defines the resolution of the APY data (1 day, 7 days, 30 days).

• from_timestamp (required): The starting point of the requested time range, defined as seconds since the epoch.

• to_timestamp (required): The endpoint of the requested time range, also specified as seconds since the epoch.

• page: An optional query parameter indicating the page number of the results for paginated output.

• per_page: An optional query parameter setting the number of items per page for pagination, with a default of 10 and a max of 50.

• granularity (required): A query parameter that specifies the time interval between each data point in the response, allowing for granular control over the dataset density.

• vaultAddress (required): The address of the vault for which historical APY data is being queried is included as a path parameter.

• network (required): The network on which the vault is located, also a path parameter. Acceptable values include mainnet, arbitrum, optimism, polygon, base, and gnosis.

Responses

• 200 OK: The successful response consists of a JSON object that includes pagination details and an array of data points; each point contains the total TVL, locked TVL, liquid TVL denominated in USD and APY, base pay, and rewards APY in BIPS.

An example response is structured as follows:

{
  "next_page": 0,
  "data": [
    {
      "timestamp": 0,
      "blockNumber": 0,
      "baseApy": 0,
      "rewardsApy": 0,
      "apy": 0,
      "tvl": 0,
      "liquidTvl": 0,
      "lockedTvl": 0,
    },
    ...
  ]
}

In this response format:

• next_page indicates the next page number to query if pagination is used.

• data is an array where each element contains:

  • timestamp reflecting the time for the data point,

  • blockNumber correlating to the block on the blockchain,

  • baseApy showing the APY value generated by the vault at that point in time.

  • rewardsApy showing the APY value generated by the vault's rewards at that point in time.

  • apy showing the total APY value generated by the vault at that point in time

  • tvl showing the total TVL in USD of the vault at that point in time

  • liquidTvl showing liquid TVL in USD of the vault at that point in time

  • lockedTvl showing locked TVL in USD of the vault at that point in time

(Sometimes, it is impossible to estimate liquid/locked values precisely. In conditions where some portion of the TVL is "uncertain", the proportion will always lean towards putting it as locked value.)