Data Model

This page describes the common data model shared across the Cryptohopper MCP's market-data tools. The three primary data types — ticker, orderbook, and candle — each have their own reference page with the exact response schema:

• Ticker tool reference
• Orderbook tool reference
• Candle tool reference

This page documents the conventions common to all three.

Conventions

Symbol format

All pair symbols use the BASE/QUOTE format:

Example	Base	Quote
BTC/USDT	BTC	USDT
ETH/USD	ETH	USD
SOL/USDC	SOL	USDC

The format is normalised server-side. Upstream exchanges use a variety of notations (e.g. BTCUSDT, BTC-USDT, tBTCUSDT); the MCP presents a uniform BASE/QUOTE regardless of the upstream convention.

See supported exchanges for the list of exchanges the MCP can query.

Exchange identifiers

Exchange names in requests and responses use lowercase identifiers:

Identifier	Exchange
binance	Binance
coinbase	Coinbase
kraken	Kraken
bybit	Bybit
okx	OKX

The full list is returned by the list-exchanges tool and documented in supported exchanges.

Timestamps

All timestamps in responses are UTC and ISO-8601 formatted: 2026-04-24T14:03:00Z

Numeric timestamps, where exposed (for example, inside candle records), are Unix timestamps in milliseconds.

Decimal encoding

Price and size values are returned as JSON numbers (floats). Examples from each tool:

// Ticker
{
  "last": 80934.19,
  "baseVolume": 11744.6152
}

// Orderbook level
[80934.18, 5.32816]

// Candle record
[1778540400000, 81833.92, 81833.92, 81720.40, 81812.55, 142.8731, 318]

Because JSON numbers are parsed as IEEE-754 floating-point in most languages, clients that require exact precision (for example, when computing order sizes) should convert these values to a decimal type immediately after parsing — for instance, Python's Decimal, JavaScript's BigNumber.js, or an equivalent.

Optional fields

Some fields are optional and may be absent from responses when the upstream exchange does not provide them. Clients should treat missing fields as null rather than an error.

Common fields

Three fields appear in most responses:

Field	Type	Description
exchange	string	The exchange identifier the data came from.
pair	string	The pair in BASE/QUOTE format.
timestamp	string (ISO-8601)	The time at which the data was captured.

The remaining fields depend on the tool. Full schemas follow.

Ticker schema (summary)

A ticker response is a single object describing the current state of a market. Field names follow CCXT conventions.

Fields include:

• last — last traded price
• bid — best bid price
• ask — best ask price
• bidVolume — size at the best bid
• askVolume — size at the best ask
• high — 24-hour high
• low — 24-hour low
• open — opening price for the 24-hour window
• close — closing price for the 24-hour window (typically equal to last)
• previousClose — closing price of the prior 24-hour window
• average — average of open and close
• vwap — 24-hour volume-weighted average price
• baseVolume — 24-hour volume in the base asset
• quoteVolume — 24-hour volume in the quote asset
• change — 24-hour absolute price change
• percentage — 24-hour percentage change

See ticker tool reference for the full schema and field types.

Orderbook schema (summary)

An orderbook response contains two arrays — bids and asks — each element being a [price, size] tuple:

• bids — array of [price, size] pairs, sorted by price descending (highest bid first)
• asks — array of [price, size] pairs, sorted by price ascending (lowest ask first)

The depth of each side depends on the upstream exchange. See orderbook tool reference for details.

Candle schema (summary)

A candle response is an array of OHLCV records, ordered chronologically (oldest first by default). Each record is itself an array with seven positions:

Index	Field	Description
0	timestamp	Open time of the bar (Unix timestamp in milliseconds)
1	open	Opening price
2	high	Highest price in the bar
3	low	Lowest price in the bar
4	close	Closing price
5	volume	Base-asset volume traded in the bar
6	count	Number of trades in the bar

Example:

[1778540400000, 81833.92, 81833.92, 81720.40, 81812.55, 142.8731, 318]

See candle tool reference for the full schema, supported timeframes, and lookback semantics.

Error responses

When a tool invocation fails, the response follows the MCP error envelope:

{
  "code": "QUOTA_EXCEEDED",
  "message": "Weekly call limit reached",
  "details": {
    "reset_at": "2026-04-25T00:00:00Z"
  }
}