Vault Historical TVL

The Vault Historical TVL (GET /v1/vaults/{network}/{vaultAddress}/historical-tvl/{timestamp}) endpoint is a data retrieval service designed to obtain historical Total Value Locked (TVL) figures for a particular vault at a specific timestamp. It caters to the need for historical data analysis, allowing users to track the TVL changes over time and assess vault growth or decline.

Parameters

• vaultAddress (required): The address of the vault in question. This information is included as a path parameter and is essential to targeting the correct data set within the system.

• network (required): The network identifier supports a variety of blockchain networks, such as mainnet, arbitrum, optimism, polygon, base, and gnosis. It is also a path parameter that needs to match the vault's network.

• timestamp (required): A Unix epoch time or equivalent numeric timestamp indicating the specific moment for which the historical TVL data is requested. The system will fetch the closest available data point to this timestamp.

Responses

• 200 OK: On success, this endpoint returns a JSON object that includes the timestamp, block number, and the corresponding TVL for the vault at that particular historical moment.

The response will generally look like the following:

{
  "timestamp": 0,
  "blockNumber": 0,
  "tvlDetails": {
    "tvlNative": "string",
    "tvlUsd": "string",
    "lockedNative": "string",
    "lockedUsd": "string",
    "liquidNative": "string",
    "liquidUsd": "string"
  },
  "tvl": "string"
}

In this structure:

• timestamp is the actual timestamp for which the data was retrieved, which may be the closest available match to the requested timestamp.

• blockNumber refers to the specific block on the blockchain that corresponds to the retrieved timestamp.

• 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.)

This endpoint is indispensable for conducting temporal analysis and understanding a vault's financial history. This can provide insights into trends and help forecast future performance.