NEW

Introducing Transporter, a new bridging app powered by CCIP. Go cross-chain.

Back

Historical Price Feeds API

Deploy your own Historical Price Feeds API for retrieving data.

Overview

This API endpoint allows you to fetch historical prices from Chainlink price feeds for a specified period. The API endpoint returns the price data in JSON format. You can use this API endpoint to fetch historical prices for a single round or multiple rounds.

Objective

This example shows you how to set up and run a pre-built API that reads historical price data from Chainlink Price Feeds. The API runs offchain, but reads the data from onchain Chainlink Data Feeds. You can use this API to build your own applications.

Before you begin

Steps to implement

1 Set up the project
  1. Clone the Historical Prices API repo and change directories:

    git clone https://github.com/smartcontractkit/quickstarts-historical-prices-api.git && cd quickstarts-historical-prices-api
    
  2. Install the dependencies:

    yarn install
    
  3. Build the project:

    yarn build
    
  4. Start the server:

    yarn start
    
2 Write, compile, and deploy your first smart contract

After you complete the setup steps, you can access the UI at http://localhost:3000. The API is available at http://localhost:3000/api/price.

In order to fetch the price for a single round, you need to specify the same start and end timestamps. Make sure that the time frame exists. The API endpoint will return the price for the round that is within the specified time frame.

Request a single-round

Make a simple curl request to test the API:

curl http://localhost:3000/api/price?contractAddress=0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419&startTimestamp=1614556800&endTimestamp=1614556800&chain=mainnet&rpcUrl=https://eth-mainnet.alchemyapi.io/v2/your-api-key

Response:

{
  "description": "ETH/USD",
  "decimals": 8,
  "rounds": [
    {
      "phaseId": "1",
      "roundId": "1",
      "answer": "2000",
      "timestamp": "2021-03-01T00:00:00Z"
    },
    {
      "phaseId": "1",
      "roundId": "2",
      "answer": "2100",
      "timestamp": "2021-03-01T01:00:00Z"
    }
  ]
}
3 Request multiple rounds

In order to fetch the prices for multiple rounds, you need to specify different start and end timestamps. Make sure that the start timestamp is less than the end timestamp and that the time frames exist. The API endpoint will return the prices for the rounds that are within the specified time frame.

Make a simple curl request to test the API with multiple rounds returned:

GET /api/price?contractAddress=0x5f4eC3Df9cbd43714FE2740f5E3616155c5b8419&startTimestamp=1614556800&endTimestamp=1614643200&chain=mainnet&rpcUrl=https://eth-mainnet.alchemyapi.io/v2/your-api-key

Example response:

{
  "description": "ETH/USD",
  "decimals": 8,
  "rounds": [
    {
      "phaseId": "1",
      "roundId": "1",
      "answer": "2000",
      "timestamp": "2021-03-01T00:00:00Z"
    },
    ⋮
    ⋮
  ]
}

Reference

The endpoint for this API is GET /api/price.

Query Parameters

RequiredParameterDescriptionTypeOptions
contractAddressThe address of the Chainlink price feed contract.stringPrice Feeds
startTimestampThe start timestamp of the period for fetching prices.numberUnix timestamp in seconds. Example: 1681187628
endTimestampThe end timestamp of the period for fetching prices.numberUnix timestamp in seconds. Example: 1681187628
chainThe blockchain network where the contract is deployed.stringmainnet, arbitrum, bsc, polygon , avalanche, fantom, moonbeam, moonriver, optimism, metis, gnosis
rpcUrlThe RPC URL for the blockchain network.stringRPC URLs

Response

The response is a JSON object with the following properties:

  • description: The price pair name.
  • decimals: The number of decimals for the answer.
  • rounds: An array of round data objects. Each round data object has the following properties:
    • phaseId: The phase ID of the round.
    • roundId: The round ID.
    • answer: The price at the round.
    • timestamp: The timestamp of the round in UTC.

Errors

The API endpoint may return one of the following errors:

  • Input validation error: This error is returned when the input parameters are not valid.
  • Failed to get client for chain: This error is returned when the API fails to get a client for the specified blockchain network.
  • Failed to get phase data from contract: This error is returned when the API fails to get phase data from the contract.

Stay updated on the latest Chainlink news