[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,
      "apy": {
        "base": 0,
        "rewards": 0,
        "total": 0
      },
      "tvlDetails": {
        "tvlNative": "string",
        "tvlUsd": "string",
        "lockedNative": "string",
        "lockedUsd": "string",
        "liquidNative": "string",
        "liquidUsd": "string"
      },
      "tvl": 0,
      "lockedTvl": 0,
      "liquidTvl": 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 APY data point,

  • blockNumber correlating to the block on the blockchain,

  • apy providing the APY percentage value generated by the vault during that time, broken down into base, rewards and total APY.

  • tvlDetails is an array of data on "Total value locked" in the vault in both native token and USD terms. TVL figures indicate the total value locked in the vault at that time, typically represented in a string format which may be converted to a numerical value for quantitative analysis.

  • liquid and locked offer insights into the liquidity and lock-up status of assets within the vault. (Sometimes it is impossible to estimate liquid/locked values precisely. In conditions where some portion of the TVL is "uncertain", the proportion would always lean towards putting it as locked value.)