Account, keys, and usage overview
This page describes how a Cryptohopper account, its API keys, and its MCP usage relate to one another. It is the conceptual map that ties together subscription tiers, API key security, and rate limits.
Account model
A Cryptohopper account is the root authority for everything described in these docs. The account holds:
- The active subscription tier (Pioneer, Explorer, Adventurer, Hero).
- The set of API keys (with per-tier limits on how many can exist simultaneously).
- The current weekly usage counter and reset time.
- The list of exchanges the account has permission to query.
All MCP requests authenticate against an API key, which in turn resolves to an account. All limits described in these docs are enforced per account.
API keys
An API key is a bearer token issued by the account. It is presented in the Authorization header of every MCP request:
Authorization: Bearer
Key properties
| Property | Description |
|---|---|
| Ownership | Keys are tied to the account that created them. |
| Scope | All keys under an account share identical access — same tier, same exchanges, same quota. |
| Revocation | Keys can be revoked at any time through the Cryptohopper account interface. Revocation takes effect immediately. |
| Rotation | A new key can be created and an old key revoked independently. |
| Quota | Keys share the account's single weekly quota. Creating additional keys does not increase the quota. |
When to use multiple keys
The number of keys an account can hold depends on the tier (see subscription tiers). Multiple keys are useful for:
- Separation by agent. Different AI agents or workflows each receive their own key. When rotating or revoking a key, only the owning agent is affected.
- Separation by environment. A production key and a development key, each revocable independently.
- Attribution. Usage logs (where available) can be inspected per key to identify which consumer is spending quota.
Multiple keys do not affect quota. All keys share the same weekly limit at the account level. See how to run multiple agents with multiple API keys.
Usage
Usage is tracked per account, in call units. The weekly counter increments every time a tool is invoked. See rate limits explained for how calls translate to units.
The MCP exposes an inspection tool that returns the current usage state:
| Field | Type | Description |
|---|---|---|
| tier | string | The active subscription tier. |
| calls_used | integer | Units used in the current weekly cycle. |
| calls_limit | integer | The tier's weekly limit. |
| reset_at | string (ISO-8601) | Timestamp of the next weekly reset. |
See usage and limits for the full response schema and example invocations.
Weekly reset
All accounts share the same reset cadence: the weekly counter resets every Friday. The precise reset time per account is stable across weeks and is returned in the reset_at field.
Usage-related errors (QUOTA_EXCEEDED) clear automatically at the reset.
Tier and exchange coverage
The account's tier determines:
- Which exchanges can be queried through the MCP.
- How much historical candle data can be requested.
- How many API keys can exist simultaneously.
- The weekly call limit and cost factor for historical data.
See subscription tiers for the full matrix and supported exchanges for the exchange list.
Authentication failure
An invalid, revoked, or malformed API key returns a 401 Unauthorized response, mapped to an UNAUTHORIZED error in the MCP error schema. See error reference.
Security considerations
API keys grant read access to market data under the account's tier. They do not grant access to Cryptohopper bots, exchange API credentials, or the account itself. Nonetheless, compromised keys consume quota and may contribute to rate-limit noise.
See API key security best practices for guidance on:
- Storage and secret management.
- Key rotation cadence.
- Revoking compromised keys.
- Separating keys by environment.
Relationship to the Cryptohopper Trading API
The Cryptohopper MCP and the Cryptohopper REST Trading API use separate authentication tokens issued under the same account. An MCP key does not authorise Trading API calls, and vice versa.
For end-to-end agents that use the MCP for research and the Trading API for execution, both credentials are required. See Combine MCP + Cryptohopper Trading API for end-to-end agents.
Checking account state from an MCP client The common queries issued from an MCP-compatible client:
What is my current Cryptohopper MCP tier? How much of my weekly quota have I used? Which exchanges am I allowed to query?
Each of these routes to the corresponding tool and returns a structured response the model summarises.
