---
title: "Retrieve token OHLCV candle data"
method: POST
path: "/api/v1/tgm/token-ohlcv"
tags: ["Token God Mode"]
---

# Retrieve token OHLCV candle data

`POST /api/v1/tgm/token-ohlcv`

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.

## Request body

- TokenOHLCVRequest — 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.
  - `chain` 'algorand' | 'aptos' | 'arbitrum' | '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', required — Chains supported for TGM OHLCV endpoint (includes Bitcoin).
  - `token_address` string — Token contract address
  - `token_addresses` string[] — Array of token contract addresses for batch queries (max 5, mutually exclusive with token_address)
  - `date_range` TokenOHLCVDateRange — DEPRECATED: Use 'date' field with standard DateRange instead.
    - `start` string, required — Start date and time (ISO format)
    - `end` string, required — End date and time (ISO format)
  - `date` DateRange — Date range model matching the API schema.
    - `from` string — Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string — End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `timeframe` '1m' | '5m' | '15m' | '30m' | '1h' | '4h' | '1d' | '1w' | '1M', required — Supported OHLCV resolution values.

## Response `200`

Token OHLCV data

- union
  - TokenOHLCVResponse — Response model for Token OHLCV endpoint (single token). Contains the requested OHLCV data with metadata about the request parameters.
    - `chain` string, required — Blockchain chain
    - `token_address` string, required — Token contract address
    - `timeframe` string, required — Time resolution used
    - `data` OHLCVCandle[], required — OHLCV candle data points, ordered by interval_start
      - `interval_start` string, required — Start time of the candle interval (ISO datetime string)
      - `open` number — Opening price
      - `high` number — Highest price in the interval
      - `low` number — Lowest price in the interval
      - `close` number — Closing price
      - `volume` number — Trading volume in token units
      - `volume_usd` number — Trading volume in USD
      - `market_cap` MarketCapData, required — Market capitalization data for OHLCV candles.
        - `open` number — Market cap at candle open
        - `high` number — Highest market cap in the candle
        - `low` number — Lowest market cap in the candle
        - `close` number — Market cap at candle close
    - `truncated` boolean — True if the result reached the maximum candle count; the most recent candles may be missing. Narrow the date range for complete coverage.
    - `truncation_note` string — Human-readable detail when 'truncated' is true.
  - TokenOHLCVBatchResponse — Response model for batch Token OHLCV requests (multiple tokens). Contains OHLCV data grouped by token address.
    - `chain` string, required — Blockchain chain
    - `timeframe` string, required — Time resolution used
    - `tokens` TokenOHLCVTokenData[], required — OHLCV data per token, ordered by token address
      - `token_address` string, required — Token contract address
      - `data` OHLCVCandle[], required — OHLCV candle data points, ordered by interval_start
        - `interval_start` string, required — Start time of the candle interval (ISO datetime string)
        - `open` number — Opening price
        - `high` number — Highest price in the interval
        - `low` number — Lowest price in the interval
        - `close` number — Closing price
        - `volume` number — Trading volume in token units
        - `volume_usd` number — Trading volume in USD
        - `market_cap` MarketCapData, required — Market capitalization data for OHLCV candles.
          - `open` number — Market cap at candle open
          - `high` number — Highest market cap in the candle
          - `low` number — Lowest market cap in the candle
          - `close` number — Market cap at candle close
    - `truncated` boolean — True if the result reached the maximum candle count; the most recent candles may be missing. Narrow the date range for complete coverage.
    - `truncation_note` string — Human-readable detail when 'truncated' is true.

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)