# Nansen Token OHLCV

> Nansen Token OHLCV is a paid API for AI agents from Nansen at api.nansen.ai, paid per call via MPP, $0.01/call, status unknown (last checked 2026-10-09).

Returns unified OHLCV candlestick data (open, high, low, close, volume, market cap) for any token across 35+ supported blockchains at multiple timeframes.

## Facts

- Endpoint: POST https://api.nansen.ai/api/v1/tgm/token-ohlcv?utm_source=zero.xyz
- Price: $0.01/call
- Payment: MPP
- Status: unknown
- Last checked: 2026-10-09
- Activations on Zero: 0
- Provider: Nansen
- Docs: https://docs.nansen.ai
- Website: https://nansen.ai
- Tags: blockchain, smart-money, wallet, tokens, defi, analytics, profiler, dex, pnl, onchain, prediction-market, data
- Canonical page: https://www.zero.xyz/c/nansen-token-ohlcv-26f49142
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_7EDW-q-mwrqfycGDP12ar

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability nansen-token-ohlcv-26f49142 -d '<json body>'
```

Example prompt: Pull me the daily OHLCV candles for the AAVE token (0x7fc66500c84a76ad7e9c93437bfc5ac33e2ddae9) on Ethereum from January 1 2025 to January 31 2025 — I want the open, high, low, close, volume, and market cap for each day.

## When to prefer this

Use this endpoint when you need historical price candlestick data for a specific token on a supported blockchain. It is the unified replacement for legacy TGM price endpoints and supports both sub-hourly (1m–1h) and multi-hour (4h–1M) timeframes. Prefer this over generic market data APIs when you need on-chain analytics context (market cap history, volume in token units) alongside price data, or when working with DeFi tokens on chains like Solana, Base, Arbitrum, or Avalanche that may not be covered by centralized exchange APIs.

## Known failure modes

- Missing required fields (chain, token_address, timeframe) returns 422 validation error
- Unsupported chain value returns 422 with enum validation error
- Invalid token address format may return empty data or 404
- Date range too large for low timeframes may return timeout or truncated results
- Token not found on specified chain returns empty data array
- Invalid timeframe string returns 422 enum validation error

## How this service works

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]`).

## Output

An array of OHLCV candle objects, each containing: interval_start timestamp, open/high/low/close prices, trading volume in token units and USD, and market cap OHLC values. Results are ordered by interval_start and cover the requested date range at the specified timeframe resolution.

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "title": "TokenOHLCVRequest",
 "required": [
  "chain",
  "timeframe"
 ],
 "properties": {
  "date": {
   "anyOf": [
    {
     "type": "object",
     "title": "DateRange",
     "properties": {
      "to": {
       "anyOf": [
        {
         "type": "string"
        }
       ],
       "title": "To",
       "examples": [
        "2025-01-31T23:59:59Z"
       ],
       "description": "End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)"
      },
      "from": {
       "anyOf": [
        {
         "type": "string"
        }
       ],
       "title": "From",
       "examples": [
        "2025-01-01T00:00:00Z"
       ],
       "description": "Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)"
      }
     },
     "description": "Date range model matching the API schema."
    }
   ],
   "description": "Date range for the data (defaults to last 30 days if not specified)"
  },
  "chain": {
   "enum": [
    "algorand",
    "aptos",
    "arbitrum",
    "arc",
    "avalanche",
    "base",
    "bitcoin",
    "bitlayer",
    "bnb",
    "chiliz",
    "ethereum",
    "gravity",
    "hyperevm",
    "hyperliquid",
    "injective",
    "iotaevm",
    "linea",
    "mantle",
    "mantra",
    "monad",
    "near",
    "optimism",
    "plasma",
    "polygon",
    "robinhood",
    "sei",
    "solana",
    "sonic",
    "stacks",
    "starknet",
    "stellar",
    "sui",
    "ton",
    "tron",
    "viction"
   ],
   "type": "string",
   "title": "TGMOHLCVChain",
   "description": "Chains supported for TGM OHLCV endpoint (includes Bitcoin)."
  },
  "timeframe": {
   "enum": [
    "1m",
    "5m",
    "15m",
    "30m",
    "1h",
    "4h",
    "1d",
    "1w",
    "1M"
   ],
   "type": "string",
   "title": "ResolutionEnum",
   "description": "Supported OHLCV resolution values."
  },
  "date_range": {
   "anyOf": [
    {
     "type": "object",
     "title": "TokenOHLCVDateRange",
     "required": [
      "start",
      "end"
     ],
     "properties": {
      "end": {
       "type": "string",
       "title": "End",
       "examples": [
        "2025-02-01T00:00:00Z"
       ],
       "description": "End date and time (ISO format)"
      },
      "start": {
       "type": "string",
       "title": "Start",
       "examples": [
        "2025-01-01T00:00:00Z"
       ],
       "description": "Start date and time (ISO format)"
      }
     },
     "description": "DEPRECATED: Use 'date' field with standard DateRange instead."
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "anyOf": [
  {
   "type": "object",
   "title": "TokenOHLCVResponse",
   "required": [
    "chain",
    "token_address",
    "timeframe",
    "data"
   ],
   "properties": {
    "data": {
     "type": "array",
     "items": {
      "type": "object",
      "title": "OHLCVCandle",
      "required": [
       "interval_start",
       "market_cap"
      ],
      "properties": {
       "low": {
        "anyOf": [
         {
          "type": "number"
         }
        ],
        "title": "Low",
        "examples": [
         98.75
        ],
        "description": "Lowest price in the interval"
       },
       "high": {
        "anyOf": [
         {
          "type": "number"
         }
        ],
        "title": "High",
        "examples": [
         105.25
        ],
        "description": "Highest price in the interval"
       },
       "open": {
        "anyOf": [
         {
          "type": "number"
         }
        ],
        "title": "Open",
        "examples": [
         100.5
        ],
        "description": "Opening price. For sub-daily timeframes (`1m`, `5m`, `15m`, `30m`, `1h`, `4h`) this is the previous completed candle's close (carry-forward), so it can fall outside the current candle's `low`–`high` range when price gaps at the interval boundary. Null on the very first (inception) candle, when no prior close exists."
       },
       "close": {
        "anyOf": [
         {
          "type": "number"
         }
        ],
        "title": "Close",
        "examples": [
         103
        ],
        "description": "Closing price"
       },
       "volume": {
        "anyOf": [
         {
          "type": "number"
         }
        ],
        "title": "Volume",
        "examples": [
         1000000
        ],
        "description": "Trading volume in token units. Null for `1m` resolution — token-unit volume is not available at that resolution; use `volume_usd` instead."
       },
       "market_cap": {
        "type": "object",
        "title": "MarketCapData",
        "properties": {
         "low": {
          "anyOf": [
           {
            "type": "number"
           }
          ],
          "title": "Low",
          "examples": [
           1400000000
          ],
          "description": "Lowest market cap in the candle"
         },
         "high": {
          "anyOf": [
           {
            "type": "number"
           }
          ],
          "title": "High",
          "examples": [
           1600000000
          ],
  
… (truncated)
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/nansen-token-ohlcv-26f49142/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.nansen.ai](https://www.zero.xyz/host/api.nansen.ai/llms.txt)