Rate limits and cost factors

This page documents how the Cryptohopper Market Data MCP counts calls, applies rate limits, and charges cost multipliers for historical data. It is the technical reference; for the tier summary, see subscription tiers.

Two independent limits

The MCP enforces two separate limits on every account:

• Weekly call limit. A rolling weekly quota of calls, tier-specific.
• Rate limit. A short-interval cap on how quickly calls can be made.

Both limits are applied per account. Creating additional API keys does not multiply either limit.

Weekly call limit

Tier	Weekly calls
Pioneer	6,000
Explorer	30,000
Adventurer	150,000
Hero	1,250,000

The counter resets every Friday at a fixed time per account. Exceeding the limit returns a QUOTA_EXCEEDED error until the next reset.

The current usage and time until reset can be queried at any time. See usage and limits.

Rate limit

In addition to the weekly limit, a short-interval rate limit prevents rapid bursts. The exact window and threshold are applied uniformly across tiers and may be adjusted without notice to maintain service stability.

Exceeding the rate limit returns a RATE_LIMIT_EXCEEDED error. Retrying after a brief delay typically succeeds.

Guidance: If your workflow involves many sequential calls (for example, sweeping tickers across all pairs on an exchange), add a small delay between calls — in the order of tens to hundreds of milliseconds — to stay under the rate limit. MCP clients do this automatically in most cases.

Cost unit

A call unit is the baseline charge for a single tool invocation. The weekly call limit is expressed in units.

Most tool invocations count as 1 unit. Historical candle queries may count as more than 1 unit, as described below.

Cost factor: historical data

Historical candle queries carry a cost multiplier on the Explorer and Adventurer tiers. The multiplier depends on lookback depth:

Lookback depth	Cost multiplier
Short history (recent bars within a short window)	5×
Long history (bars reaching towards the tier's maximum history)	20×

The boundary between "short" and "long" is tier-specific and may be adjusted. As a working rule, queries pulling roughly the most recent ~10% of the tier's historical allowance are charged at 5×; deeper queries are charged at 20×.

On the Hero tier, all historical queries are charged at 1× regardless of lookback depth.

Ticker and orderbook queries are always charged at 1× on all tiers.

Examples

Query	Tier	Unit cost
Current BTC/USDT ticker on Binance	Any	1
Full orderbook snapshot for ETH/USDT on Kraken	Any	1
Last 100 × 1h candles for SOL/USDT on Binance (recent)	Explorer	5
Last 500 × 1h candles reaching back ~3 weeks	Explorer	5
Last 1,000 × 1h candles reaching back towards 90-day limit	Explorer	20
Last 1,000 × 4h candles (deep lookback)	Adventurer	20
Last 3,000 × 1h candles (3-year lookback)	Hero	1

The exact cost of a specific query can be previewed by calling the usage endpoint after the query — the delta in calls_used is the unit cost.

Budgeting guidance

A few working rules to stay within quota:

• Prefer tickers for broad scans. A 200-pair ticker sweep costs 200 units. The same sweep via orderbooks costs 200 units (though each call transfers far more data). The same sweep via deep candle history can cost thousands of units.
• Keep candle lookback tight. Most indicators (RSI, MACD, moving averages up to 200-period) do not need more than 150-200 candles of context. Pulling 1,000 candles by default is the most common cause of unnecessary quota spend.
• Cache where it makes sense. Orderbooks go stale within seconds, so caching orderbook snapshots is rarely useful. Candle data older than the current bar is immutable, so caching or persisting historical candles is appropriate.
• Use Hero when historical depth is structurally required. If your workflow routinely pulls long candle histories, the flat 1× cost factor on Hero is typically more economical than pulling the same data on Adventurer at 20×.

Quota for multi-agent deployments

If multiple agents share one account, all agents draw from the same weekly quota. To separate agents:

• Create additional API keys (within the tier's key allowance). Each key consumes from the shared quota but can be revoked or rotated independently.
• Implement application-level throttling per key to prevent one agent from exhausting the quota for others.

See how to run multiple agents with multiple API keys for patterns.

Error handling

Limit-related errors returned by the MCP:

Error code	Meaning
QUOTA_EXCEEDED	Weekly call limit reached. Resets on the next reset time.
RATE_LIMIT_EXCEEDED	Short-interval rate limit hit. Retry after brief delay.
HISTORY_LIMIT_EXCEEDED	Requested lookback exceeds the tier's maximum history.
EXCHANGE_NOT_SUPPORTED	Requested exchange is not in the tier's allow list.

Full error reference: error reference.

Checking current usage

The MCP exposes a usage-inspection tool that returns:

• tier — the active subscription tier.
• calls_used — units used in the current weekly cycle.
• calls_limit — the tier's weekly limit.
• reset_at — ISO-8601 timestamp of the next reset.