Historical Data

Many endpoints allow the retrieval of a series of data across time. Everything below will apply to all historical endpoints unless explicitly stated in the reference documentation.

The four elements to consider are:

• start

• end

• interval

• result set

For additional information about how time is treated in the Token API, see the Time section.

Start

The start of a time series is always inclusive, i.e., the first element in the result set will be associated with the start block.

If the requested data is associate with either a token or a contract, the start of a time series is optional. If block number and timestamp are omitted, the start is the block at which the token or contract was deployed.

End

The end of a time series is always inclusive, i.e., the last element in the result set will be associate with the end block. ⚠️ This is non-standard but required because there is no way to express the concept of "latest block + 1".

The end of a time series is optional. If block number and timestamp are omitted, the end is the latest block.

Interval

Interval is the periodicity of the data. Supported values are blocks and seconds.

The interval is optional. If this value is omitted, the default is 86,400 seconds, i.e., a day.

Internally, our data is stored by block number. Ethereum blocks take an average of approximately 12 seconds to produce, so asking for data at a higher resolution is meaningless. Other chains produce blocks faster (e.g., Polygon) and others more slowly (e.g., Bitcoin).

⚠️ If the interval is not a multiple of the range expressed by start and end, the partial element will be eliminated from the head of the result set. E.g.,

• given

  • start block = 1

  • end block = 9

  • interval = 3

• result array will be

  • [block 3] [block 6] [block 9]

Result Set

Result sets (the array of results) are limited to 4,000 elements. Given an interval of 1 day, 4,000 elements span almost 11 years, which is more than enough to retrieve daily values for any token or contract in existence.

As the interval is shortened, developers must be aware of the number of intervals between start and end.

If a request potentially returns more than 4,000 elements, the call will return a 400 response code with message "Number of data points in result cannot exceed 4000. Either increase interval or reduce range."