Historical Token OHLCV

Note: This is a beta endpoint (/api/v1beta1/). Request shapes, response fields, and pricing may change as we iterate.

Get historical "Token God Mode" (TGM) token OHLCV (Beta)

post

Beta — subject to breaking changes.

Historical counterpart of /tgm/token-ohlcv. Returns OHLCV candles over a window anchored to exactly one of as_of_date or as_of_ts.

Differences from /tgm/token-ohlcv:

• Flat date contract: date_from + as_of_date (no date / date_range wrapper). as_of_date is the data-window upper bound.

• Hyperliquid requests may instead provide a timezone-aware as_of_ts; only candles completed by that exact instant are returned. A candle whose interval ends exactly at as_of_ts is included.

• High-tf (1d, 1w) supports apply_blacklist_filter to exclude blacklisted token prices from volume_usd.

• Low-tf (5m, 15m, 30m, 1h, 4h) does not support apply_blacklist_filter; passing it returns 400.

• 4h always excludes its trailing partial bucket, for spot and Hyperliquid alike, with either as_of_date or as_of_ts. Other low-tf timeframes may still include a partial trailing bucket with as_of_date.

• For 4h, a date-only as_of_date (e.g. 2026-04-15) means through the end of that day, so the day's final completed bucket (20:00-24:00) is included. A datetime-valued as_of_date is an exact instant instead: e.g. 2026-04-15T23:59:59Z excludes that same bucket, because it has not closed yet at 23:59:59.

Accepted timeframes: 5m, 15m, 30m, 1h, 4h, 1d, 1w. 1m and 1M are not supported.

Hyperliquid: chain="hyperliquid" is supported; pass the coin symbol (e.g. "BTC", "HYPE", "@1", "XYZ/USDC") in token_address. The apply_blacklist_filter flag is not accepted for Hyperliquid; market-cap fields are returned as null (HL perps have no market-cap concept). Candles from 2025-05-29 are built from fills and match the exchange's own candles; volume is base units and volume_usd is volume × close, as on /tgm/token-ohlcv. Both are null before 2025-05-29 (mark-price candles, no volume) and on the trailing partial bucket when as_of_date lands mid-bucket on a day or week timeframe. Weekly candles start Thursday 00:00 UTC, as on the exchange.

Authorizations

apikeystringRequired

API key for authentication

Body

Request model for the historical TGM token OHLCV endpoint.

chainstring · enumRequired

Blockchain chain (ethereum, solana, base, bnb, hyperliquid).

Example: ethereumPossible values:

token_addressstringRequired

Token contract address. For chain='hyperliquid', pass the coin symbol instead (e.g. "BTC", "HYPE", "@1", "XYZ/USDC").

Example: 0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9

date_fromstringRequired

Start of the data window, ISO 8601 (date or datetime).

Example: 2025-06-01T00:00:00Z

as_of_dateany ofOptional

Snapshot anchor; semantically equivalent to date_to. The data window is [date_from, as_of_date]. Date-only values are treated as end-of-day. Asymmetry: the blacklist anchor uses the date part only, while the data-window upper bound preserves the time component if supplied. So as_of_date='2025-06-07T15:30:00Z' clamps the data to 15:30 but evaluates the blacklist as of the full day 2025-06-07 (daily granularity).

Example: 2025-06-07T23:59:59Z

stringOptional

as_of_tsany ofOptional

Exact UTC-normalized cutoff for Hyperliquid requests. Only candles that are complete at this timestamp are returned. Provide exactly one of as_of_date or as_of_ts.

Example: 2026-03-30T12:02:17.123456Z

string · date-timeOptional

timeframestring · enumRequired

OHLCV interval. Accepted: 5m, 15m, 30m, 1h, 4h, 1d, 1w. 1m and 1M are not supported.

Example: 1dPossible values:

apply_blacklist_filterany ofOptional

High-tf-only (1d/1w). When True, prices for currently-flagged blacklisted tokens resolve to NULL in volume_usd (prod-equivalent). When False, historical prices are returned regardless of current blacklist status. Passing this with a low-tf timeframe returns 400 — low-tf has no blacklist plumbing (sources the unfiltered 5m feed).

Example: true

booleanOptional

Responses

200

Historical TGM Token OHLCV data

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

402

Payment Required

application/json

403

Forbidden

application/json

404

Not Found

application/json

422

Unprocessable Content

application/json

429

Too Many Requests

application/json

500

Internal Server Error

application/json

502

Bad Gateway

application/json

503

Service Unavailable

application/json

504

Gateway Timeout

application/json

post/api/v1beta1/tgm/historical-token-ohlcv

POST /api/v1beta1/tgm/historical-token-ohlcv HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 240

{
  "chain": "ethereum",
  "token_address": "0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9",
  "date_from": "2025-06-01T00:00:00Z",
  "as_of_date": "2025-06-07T23:59:59Z",
  "as_of_ts": "2026-03-30T12:02:17.123456Z",
  "timeframe": "1d",
  "apply_blacklist_filter": true
}

{
  "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"
}