Token Ohlcv
token_ohlcvOHLC PRICE HISTORY of a token: OHLC / OHLCV candles (open, high, low, close, volume) over time for ONE token or up to 50 — the data behind a price chart or candlestick chart. Use for "price of over time", "OHLC", "candles", "price chart", "historical price between two dates", "price at ", volatility. NOT a single latest price (use token_price); for a well-known coin with no chain pinned use currency_ohlcv; for trade counts and traders per bucket built from individual swaps use token_trade_bars.
Covers Ethereum, Arbitrum, Base, Matic, Optimism, Binance Smart Chain, Tron,
Solana, Robinhood and Arc, including rare and newly-launched tokens; resolve a
symbol with find_tokens first.
Candles of interval_seconds: 1, 3, 5, 10, 30, 60, 300, 900, 1800 or 3600
(for 4h / 1d candles request 3600 and aggregate). Period: after_time /
before_time (UTC), or window_hours back from before_time or now —
after_time wins; about 30 days of history. Newest candle first (order =
oldest flips it), at most limit candles per token; to page back pass the oldest
Time as before_time. Every row carries Token_Address and Network. Batch:
up to 50 addresses, separated by |, , or spaces; every row carries
Addresses_Requested, Addresses_Invalid and Addresses_Used — the rule is in
the address parameter — and Addresses_Not_Found, the addresses looked up
that have no candle in the window (when nothing is found the result is empty, so no row carries the list). An empty address is the chain's
native coin (on Solana wrapped SOL; Arc has none — use currency_ohlcv with
usdc). Latest tick: interval_seconds=1, window_hours=1,
first row (larger candles lag by up to their size).
One row per candle (re-written copies of an open candle are collapsed).
A candle's High and Low cover EVERY swap in it, however small and in
whichever pool, and a swap's price is worked out from its own two amounts,
so one tiny or unusual swap can stretch them far past anything that could
actually be traded at — the closes are the robust series.
Market_Cap_Usd needs a known circulating supply — null is normal for
long-tail tokens; Fdv_Usd is the total-supply valuation — call it FDV, never
market cap. Both are null when the supply is unknown or not credible (e.g.
parked on a burn address), and they are this token's OWN valuation: null
for a token that stands for a multi-chain or bridged asset (WETH, WBTC,
USDC, LINK on each of its chains). Asset_Market_Cap_Usd / Asset_Fdv_Usd
carry the whole asset's figures on every candle. token_price says which
case applies. For a well-known coin
(USDC, USDT, WETH, WBTC, BTC, ETH, SOL, DAI, …) with no chain or contract
pinned prefer currency_ohlcv — it aggregates the asset across chains.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"address": "<address>"
},
"name": "token_ohlcv"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max candles per token (at most 10000). A batch returns at most 10000 candles in total, split evenly across the tokens used. | |
| order | No | "newest" (default) = newest candle first; "oldest" = oldest first (with after_time: the first candles after that moment). | newest |
| address | Yes | Token contract / mint address, or several (one call instead of one per token); rows are grouped per token in the order given and carry Token_Address and Network. Up to 50 addresses, separated by `|`, `,` or spaces. An empty entry (a leading, trailing or doubled separator) is ignored - it counts neither as requested nor as invalid. EVM addresses (0x + 40 hex characters) are matched case-insensitively; Solana (32-44 base58 characters) and Tron (base58 starting with T) addresses are case-sensitive. Every row carries Addresses_Requested (distinct entries; duplicates and differently-cased EVM addresses count once), Addresses_Invalid (entries that are not an address of the requested chain, or of any chain when none is requested — skipped, never looked up) and Addresses_Used (addresses looked up, at most 50); valid addresses after the 50th are ignored, so when Addresses_Used + Addresses_Invalid is below Addresses_Requested, call again with the rest. A value without any well-formed address is refused; one whose well-formed addresses all belong to another chain than the requested one is answered with an error. Empty (or only separators) = the chain's native coin (ETH, BNB, MATIC, TRX) — pass blockchain with it; on Solana that is wrapped SOL (So11111111111111111111111111111111111111112); Arc has no native-coin row and is answered with an error. | |
| after_time | No | Window start, UTC — "2026-09-15 08:00:00", a date, or unix seconds; candles starting at or after it. Takes precedence over window_hours. History reaches back about 30 days — an older start is moved up to it. Empty (default) = window_hours before the end. A value that is not a date-time is rejected. Format: YYYY-MM-DD, YYYY-MM-DD HH:MM[:SS], ISO-8601 like 2026-09-20T00:00:00Z (fraction or +02:00 offset allowed) or 10-digit unix seconds; an impossible date (2026-02-30, month 00) is rejected. | |
| blockchain | No | Token_Network — Ethereum (eth), Arbitrum (arb, arbitrum one), Base, Matic (polygon, polygon pos), Optimism (op, op mainnet), Binance Smart Chain (bsc, bnb, bnb chain, bnb smart chain), Tron (trx), Solana (sol), Robinhood (rh) or Arc (arc network, circle arc); case-insensitive, any other value is rejected. Applies to every address. Pass it whenever known. Empty (default) = every chain the address trades on, each returned separately. | |
| before_time | No | Window end, UTC, exclusive — same formats as after_time; candles starting before it. Empty (default) = now. To page further back, pass the oldest Time of the previous page. Format: YYYY-MM-DD, YYYY-MM-DD HH:MM[:SS], ISO-8601 like 2026-09-20T00:00:00Z (fraction or +02:00 offset allowed) or 10-digit unix seconds; an impossible date (2026-02-30, month 00) is rejected. | |
| window_hours | No | Look-back in hours before before_time (or before now); ignored when after_time is set. Values above 720 (the 30 days of history) read as 720. Keep it proportionate to the candle size (e.g. 24 for 1m candles, 720 for 1h candles). | |
| interval_seconds | No | Candle size in seconds — one of 1, 3, 5, 10, 30, 60, 300, 900, 1800, 3600 (anything else is rejected). |