> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Get Token OHLCV History
> Retrieve OHLCV (Open, High, Low, Close, Volume) candlestick data for one or multiple tokens.
**Batch Support Available**: This endpoint supports batch queries via POST method for fetching OHLCV data for up to 10 tokens in a single request. [Jump to Batch Query section](#post-request-batch)
Timestamps are in MS (JavaScript timestamps).
### Overview
This endpoint retrieves OHLCV candlestick data for a **token** by its contract address. It automatically resolves the largest pool for the token and includes pre-bonding curve data when available.
Use **GET** for a single token or **POST** for batch requests (up to 10 tokens).
For direct pool/market queries by pool address, use [Market OHLCV History](/rest-api-reference/endpoint/market-ohlcv-history) instead.
## GET Request (Single Token)
### Query Parameters
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address` | string | Yes | Token contract address |
| `chainId` | string | Yes | Chain identifier (e.g., `"ethereum"`, `"base"`, `"solana"`) |
| `period` | string | No | Candle resolution: `1s`, `5s`, `15s`, `30s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `12h`, `1d`, `1w`. Default: `5m` |
| `from` | number | No | Start timestamp (ms). Default: `0` |
| `to` | number | No | End timestamp (ms). Default: current time |
| `amount` | number | No | Maximum number of candles to return (max: 2000) |
| `usd` | boolean | No | Return USD prices. Default: `true` |
| `fill` | boolean | No | Forward-fill empty candles between trades so the series has no gaps (each filled candle carries the previous close, volume `0`). Makes the candle count a function of span and period, independent of trade activity. Default: `false` |
### Step-by-Step Tutorial and Video Walkthrough
* Check out the guide: [Here](https://docs.mobula.io/guides/how-to-track-token-ohlcv-history)
### Usage Example
```bash theme={null}
curl -X GET "https://api.mobula.io/api/2/token/ohlcv-history?address=0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2&chainId=ethereum&period=1h"
```
## POST Request (Batch)
### Request Body
Send an array of token queries directly (minimum 1, maximum 10 per request). Each item uses the same parameters as the GET request.
### Example
```bash theme={null}
curl -X POST "https://api.mobula.io/api/2/token/ohlcv-history" \
-H "Content-Type: application/json" \
-d '[
{ "address": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "chainId": "ethereum", "period": "1h" },
{ "address": "0x6982508145454ce325ddbe47a25d4ec3d2311933", "chainId": "ethereum", "period": "1h" }
]'
```
## Response Format
Response fields use **abbreviated naming** for optimal payload size:
| Field | Type | Description |
| ----- | ------ | ------------------------------- |
| `t` | number | Candle timestamp (ms) |
| `o` | number | Opening price |
| `h` | number | Highest price during the period |
| `l` | number | Lowest price during the period |
| `c` | number | Closing price |
| `v` | number | Volume during the period |
### GET Response Example
```json theme={null}
{
"data": [
{
"t": 1754337900000,
"o": 3245.67,
"h": 3250.12,
"l": 3240.00,
"c": 3248.50,
"v": 125000.50
},
{
"t": 1754341500000,
"o": 3248.50,
"h": 3255.00,
"l": 3245.00,
"c": 3252.30,
"v": 98500.25
}
]
}
```
### POST Response Example
```json theme={null}
{
"data": [
{
"ohlcv": [
{
"t": 1754337900000,
"o": 3245.67,
"h": 3250.12,
"l": 3240.00,
"c": 3248.50,
"v": 125000.50
}
],
"address": "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",
"chainId": "evm:1"
},
{
"ohlcv": [],
"address": "0x0000000000000000000000000000000000000000",
"chainId": "evm:1",
"error": "No pool found for this token"
}
]
}
```
### Period Options
* `1s` - 1 second
* `5s` - 5 seconds
* `15s` - 15 seconds
* `30s` - 30 seconds
* `1m` - 1 minute
* `5m` - 5 minutes
* `15m` - 15 minutes
* `30m` - 30 minutes
* `1h` - 1 hour
* `4h` - 4 hours
* `6h` - 6 hours
* `1d` - 1 day
* `1w` - 1 week
## FAQ
Mobula’s `period` is **not** the same format as TradingView’s [`ResolutionString`](https://www.tradingview.com/charting-library-docs/latest/api/modules/Charting_Library#resolutionstring). Treat them as different contracts and map values in your [datafeed](https://www.tradingview.com/charting-library-docs/latest/connecting_data/datafeed-api/) before calling Mobula.
**Often maps cleanly (Mobula normalizes case):**
* Seconds: TV `1S`, `5S`, … → Mobula `1s`, `5s`, …
* Minute numerals: `1`, `5`, `15`, `30` → `1m`, `5m`, `15m`, `30m`
* Hour-style minute counts: `60` → `1h`; `240` → `4h`; `360` → `6h`; `720` → `12h`
* Days / weeks: `1D` → `1d`, `1W` → `1w`
**Important mismatch — TV `1M` (one month):**\
TradingView uses `1M` for **one month**. Mobula lowercases the string, so `1M` becomes `1m`, which means **one minute**, not one month. Never forward TV’s monthly resolution unchanged.
**Not a direct match:**
* **Tick** bars (`1T`, `5T`, …) — Mobula serves time-based OHLCV candles, not tick aggregation.
* **Unrecognized strings** — fall back to a default period (commonly `1h` for unknown non-empty values, or `5m` when `period` is omitted on this endpoint).
**Supported candle periods (canonical):**\
`1s`, `5s`, `15s`, `30s`, `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `12h`, `1d`, `1w`.\
Aliases such as `5min` or `60` → `1h` are accepted by the API layer. Do **not** use `1month` / TV-style monthly here: they normalize to `1M`, which this OHLCV history service does not support.
**Recommendation:** Add an explicit `tradingViewResolutionToMobulaPeriod(resolution)` (or equivalent) in your integration instead of passing TV resolutions straight through.
### Features
* **Pre-bonding data**: Automatically includes bonding curve data for tokens that graduated from bonding curves (e.g., pump.fun tokens)
* **Auto pool resolution**: Automatically finds the largest liquidity pool for the token
### Notes
* Maximum **2000 candles** per request. If no `amount` is specified and a date range is provided, the default cap is 2000. Without a date range, the default is 300 candles.
* Maximum 10 tokens per POST request
* Rate limit: 5 credits (GET), 10 credits (POST)
* This endpoint uses `mode: token` internally to include pre-bonding curve history when available
## OpenAPI
````yaml get /2/token/ohlcv-history
openapi: 3.0.0
info:
version: 1.0.0
title: Mobula API
description: >-
Documentation of the Mobula API
**Demo API**: The default server (demo-api.mobula.io) is a demo API with
rate limits.
For production use, please use api.mobula.io with an API key from
https://admin.mobula.io
servers:
- url: https://demo-api.mobula.io/api/
description: Demo API (rate limited, for testing only)
- url: https://api.mobula.io/api/
description: Production API (requires API key)
security: []
tags:
- name: V2 - Token
description: Token details, price, security, ATH, and holder data
- name: V2 - Market Data
description: Market details, OHLCV history, and lighthouse metrics
- name: V2 - Trades
description: Token trades, enriched trades, and trade filters
- name: V2 - Wallet
description: Wallet positions, activity, trades, analysis, and labels
- name: V2 - Assets
description: Cross-chain asset details and price history
- name: V2 - Swap
description: Swap quoting and execution
- name: V2 - Perps
description: Perpetual futures quoting, execution, and positions
- name: V2 - Bridge
description: Cross-chain bridge quoting and intent status (Alpha Preview)
- name: V2 - DeFi
description: Bonding pools and pulse data
- name: V2 - Search
description: Universal fast search
- name: V2 - Blockchains
description: System metadata and chain listings
- name: V1 - Market Data
description: Market prices, history, sparklines, pairs, and multi-data
- name: V1 - Wallet
description: Wallet portfolio, transactions, history, and NFTs
- name: V1 - Token
description: First buyers
- name: V1 - Trades
description: Market trades by pair
- name: V1 - Metadata
description: Token metadata, categories, trendings, and news
- name: V1 - Assets
description: List all assets
- name: V1 - Search
description: Search for assets, tokens, and pairs
- name: V1 - DeFi
description: Bonding pool pulse data
- name: V1 - Blockchains
description: Blockchain listings, pairs, and stats
- name: V1 - Webhooks
description: Webhook management
- name: V1 - Feed
description: Custom feed creation
paths:
/2/token/ohlcv-history:
get:
tags:
- V2 - Token
summary: Get token OHLCV history
description: >-
Retrieve OHLCV (Open, High, Low, Close, Volume) candlestick data for a
specific token by its address.
parameters:
- schema:
type: string
description: Token contract address
required: true
description: Token contract address
name: address
in: query
- schema:
type: string
description: Blockchain chain ID (e.g., "evm:56", "solana:solana")
required: false
description: Blockchain chain ID (e.g., "evm:56", "solana:solana")
name: chainId
in: query
- schema:
anyOf:
- type: integer
nullable: true
- type: string
nullable: true
- nullable: true
description: Start date (timestamp or ISO string)
required: false
description: Start date (timestamp or ISO string)
name: from
in: query
- schema:
anyOf:
- type: integer
nullable: true
- type: string
nullable: true
- nullable: true
description: End date (timestamp or ISO string)
required: false
description: End date (timestamp or ISO string)
name: to
in: query
- schema:
type: string
description: Candle period (e.g., "5m", "1h", "1d")
required: false
description: Candle period (e.g., "5m", "1h", "1d")
name: period
in: query
- schema:
type: number
nullable: true
description: Maximum number of candles (max 2000)
required: false
description: Maximum number of candles (max 2000)
name: amount
in: query
- schema:
anyOf:
- type: boolean
- type: string
description: 'Return USD prices (default: true)'
required: false
description: 'Return USD prices (default: true)'
name: usd
in: query
responses:
'200':
description: Token OHLCV history response
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
v:
type: number
o:
type: number
h:
type: number
l:
type: number
c:
type: number
t:
type: number
required:
- v
- o
- h
- l
- c
- t
required:
- data
````