Ctrlk
x-twitteryoutube
For the complete documentation index, see llms.txt. This page is also available as Markdown.

🆕Price OHLCV

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it except where noted below.

  • Latency: the most recent candle is the current, still-open interval and keeps updating until it closes. Prices come from a median price feed that refreshes roughly every 5 minutes, so 5m and larger candles are at most ~5 minutes behind; the 1m timeframe is built directly from on-chain swaps and is trade-fresh over a short recent window. Hyperliquid tokens are served live from Hyperliquid's own feed.

  • History: each token's history goes back to the first price Nansen recorded for it, so the start date varies by token.

  • Batch tokens with no data: in batch requests, tokens that have no candles for the requested chain, timeframe, and date range are omitted from tokens. They are not returned as empty data: [] placeholders and do not cause an error. To identify omitted tokens, compare your submitted addresses with the tokens[].token_address values in the response. This omission is distinct from truncation; a token can be omitted with no data while truncated remains false.

  • Truncation: single-token requests return at most 50,000 candles per token, ordered oldest first; if the requested range exceeds that cap, the most recent candles are dropped first. Batch requests return at most 50,000 candles shared across all requested tokens, ordered oldest first across the batch. Check the truncated boolean; when it is true, inspect truncation_note for details. To retrieve complete data, narrow or split the date range. For batch requests, reduce the token count or query tokens individually when complete per-token coverage is required.

  • Truncation on Hyperliquid: Hyperliquid tokens come from Hyperliquid's own feed, which caps each token's response at roughly 5,000 candles — well below the 50,000 above — and drops the oldest candles rather than the most recent, so a range wider than the cap comes back starting later than requested. The same truncated / truncation_note fields flag it; in a batch request truncated is true when at least one token was cut short. Split the request into shorter ranges to walk the full history.

Retrieve token OHLCV candle data

post

Get unified OHLCV (Open, High, Low, Close, Volume) data for tokens across supported chains.

Low timeframes (sub-hourly + 4h): 1m, 5m, 15m, 30m, 1h, 4h High timeframes (multi-day): 1d, 1w, 1M

Returns OHLCV candle data including:

  • Price data: open, high, low, close prices

  • Volume data: trading volume in token units and USD

  • Market cap data: market capitalization at each time point

Date range defaults to the last 30 days if not specified.

Sub-daily resolution notes (1m, 5m, 15m, 30m, 1h, 4h)

  • Open price: Derived from the previous completed candle's close (carry-forward). It can therefore fall outside the current candle's low–high range when price moves sharply at an interval boundary. The very first candle has open: null.

  • Gaps (1m only): Only intervals that contain at least one qualifying on-chain trade emit a candle. Minutes with no activity produce no row — the candle array may be sparse. This is expected behavior and is independent of the truncated flag, which reports only the 50,000-candle server cap.

  • Token-unit volume (1m only): The volume field is null at 1m resolution. Use volume_usd for volume data at this timeframe.

  • Time range boundary (1m only): The to parameter is exclusive — the candle starting at exactly to is not included ([from, to) semantics). All other timeframes (5m and above) use an inclusive upper bound ([from, to]).

Authorizations
apikeystringRequired

API key for authentication

Body

Request model for Token OHLCV endpoint.

This endpoint provides unified OHLCV (Open, High, Low, Close, Volume) data for tokens across supported chains with different time resolutions.

chainstring · enumRequired

Blockchain chain

Example: ethereumPossible values:
token_addressany ofOptional

Token contract address

Example: 0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9
stringOptional
token_addressesany ofOptional

Array of token contract addresses for batch queries (max 10, or max 5 for Hyperliquid, mutually exclusive with token_address)

Example: ["0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9","0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"]
string[]Optional
date_rangeany ofOptionalDeprecated

DEPRECATED: Use 'date' instead. Date range with start/end fields.

dateany ofOptional

Date range for the data (defaults to last 30 days if not specified)

timeframestring · enumRequired

Time resolution for OHLCV data

Example: 1hPossible values:
Responses
200

Token OHLCV data

application/json
Responseany of
or
post/api/v1/tgm/token-ohlcv
POST /api/v1/tgm/token-ohlcv HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 275

{
  "chain": "ethereum",
  "token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
  "token_addresses": [
    "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
    "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984"
  ],
  "date": {
    "from": "2025-01-01T00:00:00Z",
    "to": "2025-01-31T23:59:59Z"
  },
  "timeframe": "1h"
}
{
  "chain": "ethereum",
  "token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
  "timeframe": "1h",
  "data": [
    {
      "interval_start": "2025-01-15T12:00:00Z",
      "open": 100.5,
      "high": 105.25,
      "low": 98.75,
      "close": 103,
      "volume": 1000000,
      "volume_usd": 100000000,
      "market_cap": {
        "open": 1500000000,
        "high": 1600000000,
        "low": 1400000000,
        "close": 1550000000
      }
    }
  ],
  "truncated": false,
  "truncation_note": "text"
}
PreviousNansen Indicators
NextToken Screener

Last updated

Was this helpful?