Orderbook tool reference

This page is the tool reference for retrieving orderbook snapshots from the Cryptohopper Market Data MCP. For the conceptual guide, see a practical guide to crypto orderbook data.

Tool name

get_orderbook

Purpose

Returns a point-in-time snapshot of the orderbook for a specified pair on a specified exchange. Contains the current resting bids and asks with price and size per level.

Arguments

Argument	Type	Required	Description
exchange	string	Yes	Exchange identifier (lowercase).
pair	string	Yes	Pair in BASE/QUOTE format (e.g. BTC/USDT).
depth	integer	No	Maximum number of levels to return per side. Default is exchange-dependent. Upper bound is upstream-dependent.

Response schema

{
  "exchange": "binance",
  "pair": "BTC/USDT",
  "timestamp": "2026-04-24T14:03:00Z",
  "bids": [
    [80934.18, 5.32816],
    [80930.05, 1.10000],
    [80925.40, 3.40000]
  ],
  "asks": [
    [80936.22, 1.20000],
    [80940.00, 2.50000],
    [80945.75, 0.80000]
  ]
}

Fields

Field	Type	Description
exchange	string	The exchange identifier the data came from.
pair	string	The pair, in BASE/QUOTE format.
timestamp	string (ISO-8601)	Capture time of the snapshot.
bids	array	Array of [price, size] tuples, sorted by price descending (highest bid first).
asks	array	Array of [price, size] tuples, sorted by price ascending (lowest ask first).

Prices and sizes are returned as JSON numbers. Clients that require exact precision for execution-related calculations should convert them to a decimal type immediately after parsing. See data model for conventions.

Ordering

• bids are sorted descending by price. The first entry is the best bid (highest price a buyer is offering).
• asks are sorted ascending by price. The first entry is the best ask (lowest price a seller is offering).

The spread is the difference between asks[0] and bids[0]. The midpoint is their average.

Depth

Orderbook depth varies by exchange. The MCP returns what the upstream exchange exposes via its public API.

Typical depth (levels per side)	Exchanges
100	Most major exchanges at default
Up to 500 or more	Some exchanges, when depth is requested

Requests for more depth than the upstream supports are clamped to the upstream maximum. The depth argument is best-effort, not guaranteed.

Freshness

Orderbooks are captured at request time. The timestamp field reflects when the snapshot was read from the upstream exchange.

Orderbooks become stale very quickly — typically within seconds on liquid pairs. Clients should not cache orderbook responses for use in execution decisions.

Cost

Aspect	Cost
Per invocation	1 call unit on all tiers
Historical variant	Not supported — orderbook history is not available through the MCP

Example invocations

Basic snapshot

Prompted in an MCP client:

Show me the current orderbook for BTC/USDT on Binance.

The agent invokes get_orderbook(exchange="binance", pair="BTC/USDT") and returns a snapshot.

Custom depth

Pull the top 50 levels of the ETH/USDT orderbook on Kraken.

The agent invokes get_orderbook(exchange="kraken", pair="ETH/USDT", depth=50).

Derived metrics

The MCP returns raw levels; derived metrics (spread, depth within X%, slippage for a given order size) are computed by the model or by the calling code.

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.
INVALID_PARAMETER	Argument failed validation (e.g. malformed pair symbol, negative depth).
EXCHANGE_UNAVAILABLE	Upstream exchange not responding.
RATE_LIMIT_EXCEEDED	Short-interval rate limit hit.
QUOTA_EXCEEDED	Weekly quota reached.

Tier access

Orderbook queries are available on all tiers (Pioneer, Explorer, Adventurer, Hero).

The exchange-coverage restriction applies: on Pioneer, orderbook queries are limited to Binance, Coinbase, and Kraken. On Explorer and above, more exchanges are available.