Candle (OHLCV) tool reference

This page is the tool reference for** retrieving candle (OHLCV) data from the Cryptohopper Market Data MCP**.

Tool name

get_candles

Purpose

Returns a series of OHLCV (Open, High, Low, Close, Volume) candles for a specified pair on a specified exchange at a specified timeframe. Supports current (real-time) candles on all tiers and historical candles on Explorer, Adventurer, and Hero.

Arguments

Argument	Type	Required	Description
exchange	string	Yes	Exchange identifier (lowercase). See supported exchanges.
pair	string	Yes	Pair in BASE/QUOTE format.
timeframe	string	Yes	Bar size. See supported timeframes below.
limit	integer	No	Number of candles to return. Default and maximum are tier-dependent.
since	string (ISO-8601)	No	Start time for historical queries. If omitted, returns the most recent limit bars.

Either limit alone (recent bars) or since + limit (historical range) may be used. limit alone is the common case.

Supported timeframes

Value	Duration
1m	1 minute
5m	5 minutes
15m	15 minutes
1h	1 hour
4h	4 hours
1d	1 day

Weekly, monthly, and other timeframe aliases are not supported and will be rejected. Not every supported timeframe is available on every exchange. Unsupported combinations return TIMEFRAME_NOT_SUPPORTED.

Response schema

{
  "exchange": "binance",
  "pair": "BTC/USDT",
  "timeframe": "1h",
  "candles": [
    [1778540400000, 80214.00, 80820.50, 80120.00, 80651.42, 412.85, 318],
    [1778544000000, 80651.42, 80936.22, 80590.00, 80934.19, 298.12, 274]
  ]
}

Top-level fields

Field	Type	Description
exchange	string	The exchange identifier the data came from.
pair	string	The pair, in BASE/QUOTE format.
timeframe	string	The bar size (e.g. 1h).
candles	array	Array of OHLCV records, ordered chronologically (oldest first). Each record is itself an array of seven positions.

Candle record fields

Each candle is an array with the following positions:

Index	Field	Type	Description
0	timestamp	number	Open time of the bar (Unix timestamp in milliseconds).
1	open	number	First traded price in the bar.
2	high	number	Highest traded price in the bar.
3	low	number	Lowest traded price in the bar.
4	close	number	Last traded price in the bar (or current price, for an open bar).
5	volume	number	Base-asset volume traded in the bar.
6	count	number	Number of trades in the bar.

Prices and volume are returned as JSON numbers. Clients that require exact precision should convert them to a decimal type immediately after parsing. See data model.

Ordering

Candles are returned in chronological order — the oldest bar first, the most recent bar last. This matches what most indicator libraries expect as input.

Open vs. closed bars

The last element of the candles array is typically the current, open bar — the bar whose time window has not yet completed. Its close value reflects the current price, not a finalised close. All earlier bars are closed and immutable.

Applications performing indicator calculations (RSI, MACD, moving averages) should typically operate on closed bars only, ignoring the last element. Using the open bar introduces look-ahead noise that can destabilise signals.

Cost

Scenario	Cost on Pioneer	Cost on Explorer/Adventurer	Cost on Hero
Current bar only (real-time)	1	1	1
Short-history lookback	N/A	5×	1×
Long-history lookback	N/A	20×	1×

The boundary between "short" and "long" lookback is tier-specific. See rate limits explained for the exact cost matrix and guidance on staying efficient.

Tier access for historical data

Tier	Historical lookback
Pioneer	Not available — current bar only
Explorer	Up to 90 days
Adventurer	Up to 365 days
Hero	Up to 3 years

Requests exceeding the tier's maximum history return HISTORY_LIMIT_EXCEEDED.

Lookback guidance

Most analyses require far fewer candles than users intuitively request. Suggested lookbacks:

Indicator	Minimum bars	Comfortable
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Moving average (N-period)	N	N + 50
Bollinger Bands (20, 2?)	20	100
ATR(14)	14	100

Pulling more bars than necessary inflates cost (historical queries on Explorer/Adventurer can cost up to 20× a baseline call) without improving the indicator's quality.

Example invocations

Recent bars

Prompted in an MCP client:

Pull the last 100 1-hour candles for ETH/USDT on Binance.

The agent invokes get_candles(exchange="binance", pair="ETH/USDT", timeframe="1h", limit=100).

Historical range

Pull daily candles for BTC/USDT on Binance from 2026-01-01 onwards.

The agent invokes get_candles(exchange="binance", pair="BTC/USDT", timeframe="1d", since="2026-01-01T00:00:00Z", limit=120).

Multi-timeframe

Pull 1h and 4h candles for SOL/USDT on Binance, last 100 each. Compute RSI on both timeframes.

The agent invokes get_candles twice with different timeframe values. The RSI calculation happens in the model's reasoning, not in a tool call.

Errors

Error code	Cause
UNAUTHORIZED	API key invalid or revoked.
EXCHANGE_NOT_SUPPORTED	Exchange not available on the active tier.
PAIR_NOT_FOUND	Pair does not exist on the specified exchange.
TIMEFRAME_NOT_SUPPORTED	Requested timeframe is not supported for this pair/exchange.
HISTORY_LIMIT_EXCEEDED	Requested lookback exceeds the tier's maximum history.
INVALID_PARAMETER	Argument failed validation (e.g. limit out of range, unrecognised timeframe alias).
EXCHANGE_UNAVAILABLE	Upstream exchange not responding.
DATA_UNAVAILABLE	Requested candles are not available from the upstream exchange for this range.
RATE_LIMIT_EXCEEDED	Short-interval rate limit hit.
QUOTA_EXCEEDED	Weekly quota reached.