How to Query Historical Token Prices: A Comprehensive Guide

Understanding historical token prices is essential for traders, developers, and analysts in the Web3 ecosystem. This guide explains how to retrieve historical price data for native tokens, smart contract-based tokens, and Bitcoin inscription tokens (BRC-20, Runes, etc.) using OKX's Wallet API.

Supported Token Types

The historical price API supports:

Native Tokens: Each blockchain's base currency (e.g., ETH for Ethereum).
Smart Contract Tokens: ERC-20, BEP-20, and other standards.
Bitcoin Inscription Tokens:
- BRC-20 (e.g., ORDI)
- Runes (e.g., Bitcoin Runes)
- ARC-20 and SRC-20
Fractal Bitcoin Chain Tokens: FBRC-20 inscriptions.

API Endpoint and Request Structure

Request Path

GET https://web3.okx.com/api/v5/wallet/token/historical-price

Key Parameters

Parameter	Type	Required	Description
`chainIndex`	String	Yes	Blockchain identifier (e.g., "1" for Ethereum)
`tokenAddress`	String	No	Contract address or inscription ID format (see below)
`limit`	String	No	Results per page (max: 200)
`period`	String	No	Time interval (`1m`, `1h`, `1d`, etc.)

Token Address Formats:

Native Token: "" (empty string)
BRC-20: btc-brc20-ordi
Runes: btc-runesMain-840000:2
FBRC-20: fbtc_fbrc20_babymusk

Practical Examples

Example 1: Querying BRC-20 Token Prices

{
  "chainIndex": "bitcoin",
  "tokenAddress": "btc-brc20-ordi",
  "period": "1d"
}

Example 2: Fetching Ethereum Native Token History

{
  "chainIndex": "1",
  "tokenAddress": "",
  "begin": "1717200000000",
  "end": "1717286400000"
}

Response Format

The API returns:

{
  "prices": [
    {
      "time": "1717257600000",
      "price": "0.000000000000123456"
    }
  ]
}

Prices use 18-decimal precision.

FAQs

How far back can I query historical prices?

Data availability depends on the token and chain. Most major tokens have data from their launch date.

Why is my token address returning no results?

Verify:

Correct chainIndex for the blockchain.
Proper formatting for inscription tokens.
The token exists/has trading history.

Can I get real-time prices with this API?

No, this endpoint retrieves historical data only. For live prices, use the market data API.

Advanced Tips

👉 Maximize your API efficiency with batch requests and caching strategies.

For high-frequency data, use shorter periods like 1m or 5m.
Combine with OHLCV endpoints for candlestick charting.

Conclusion

This API provides granular historical price data for Web3 development, portfolio tracking, and market analysis. Always test queries with small date ranges before large historical pulls.