Use Historical Price Data (Benchmarks)

This guide explains how to integrate Pyth Benchmarks to access historical price data across applications. The Benchmarks API is available on all Pythnet chains.

Benchmarks Terminology

Throughout this guide, Benchmarks refers to Pyth’s historical price data service.

Overview

Pyth Benchmarks lets you query historical prices at specific timestamps. Typical use cases include:

Contract settlement for derivatives such as options or futures
Backtesting trading strategies with historical data
Audit and compliance workflows that require price verification
Analytics to analyze market behavior over time

Benchmarks supports two complementary flows:

Retrieve data from the Benchmarks API or through the Hermes timestamp API. Two REST endpoints are available:

/v1/updates/price/{timestamp}: returns prices for the requested feeds at a given timestamp.
/v1/updates/price/{timestamp}/{interval}: returns prices for a feed at the given timestamp and interval.

Interval Window

The interval parameter represents the number of seconds added to the provided timestamp. For example, with timestamp 1716400000 and interval 60, the API returns price updates from 1716400000 through 1716400060 (inclusive). The interval must not exceed 60 seconds.

After fetching price updates, pass the result to parsePriceFeedUpdates instead of updatePriceFeeds when interacting with the Pyth contract.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "@pythnetwork/pyth-sdk-solidity/IPyth.sol";
import "@pythnetwork/pyth-sdk-solidity/PythStructs.sol";

contract HistoricalPriceConsumer {
    IPyth public pyth;

    constructor(address _pyth) {
        pyth = IPyth(_pyth);
    }

    function settleWithHistoricalPrice(
        bytes[] calldata priceUpdate,
        uint256 priceId,
        uint256 minPublishTime,
        uint256 maxPublishTime,
    ) external {
        // The parsePriceFeedUpdates function requires a fee to be paid.
        // The fee is the same as the fee for the updatePriceFeeds function.
        uint fee = pyth.getUpdateFee(priceUpdate);
        PythStructs.Price memory price = pyth.parsePriceFeedUpdates{value: fee}(
            priceUpdate,
            priceId,
            minPublishTime,
            maxPublishTime,
        );

        // Use the historical price for settlement
        uint256 settlementPrice = uint256(price.price);
        // ... settlement logic
    }
}

The verification flow differs from real-time price updates in that it:

Calls parsePriceFeedUpdates instead of updatePriceFeeds
Provides the price feed ID to ensure the update matches the feed
Supplies minPublishTime and maxPublishTime to enforce the allowable timestamp window, reverting with PriceFeedNotFoundWithinRange when updates fall outside the range

Consult the API reference for additional implementation details.

Additional Resources

API Reference

TradingView Integration

TradingView integration for visualization

Rate Limits

Benchmarks API inherits the same limits as the Hermes API