API Reference
Rate Limits
Hive enforces two limits per account: a per-minute request rate (so a single misbehaving agent does not starve other clients) and a monthly credit budget (so each plan tier is bounded by usage). One credit equals one tool call, regardless of upstream provider or payload size.
Plan limits
| Plan | Requests/min | Monthly credits | API keys |
|---|---|---|---|
| Demo | 30 | 10,000 | 5 |
| Analyst | 500 | 500,000 | 10 |
| Pro | 1,000 | 2,000,000 | 25 |
| Enterprise | 3,000 | Unlimited (custom) | 100 |
Rate limits apply per API key. Credit budgets apply at the account level — creating multiple keys under one account does not multiply the credit pool. See Pricing for full plan comparison and Dashboard → Plans to upgrade.
What counts as a credit
One credit equals one tool call — one MCP tools/call or one REST POST /api/v1/execute. The credit cost is the same whether the upstream provider is CoinGecko, DefiLlama, GoPlus, Alchemy, Codex, CCXT, Helius, Tenderly, or Moralis, and whether the response is small or large. Discovery calls (tools/list, GET /api/v1/tools) are free and do not deduct credits.
Credits reset at the start of each calendar month. If a request exceeds your monthly credit budget, the response is 429 with error.code: "QUOTA_EXCEEDED" and X-Quota-Remaining: 0.
Rate Limit Headers
Responses include headers showing your current quota state. IP-level throttles use standard RateLimit-* headers, while authenticated key-level limits include X-RateLimit-* and X-Quota-Remaining.
RateLimit-Limit: 500
RateLimit-Policy: 500;w=60
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-Quota-Remaining: 9992| Header | Description |
|---|---|
RateLimit-Limit | Maximum IP-level requests allowed in the current window |
RateLimit-Policy | Window policy, for example 500;w=60 |
RateLimit-Remaining / RateLimit-Reset | Remaining requests and reset timing when provided by the limiter |
X-RateLimit-Limit | Maximum authenticated API-key requests allowed in the current minute |
X-RateLimit-Remaining | Authenticated API-key requests remaining before throttling |
X-Quota-Remaining | Monthly credits remaining for the account, or unlimited |
When You Hit the Limit
When you exceed your rate limit, Hive returns a 429 Too Many Requests response:
{
"ok": false,
"error": {
"type": "rate_limit_error",
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Maximum 500 requests per minute.",
"doc_url": "https://docs.hiveintelligence.xyz/errors#rate-limited"
}
}On hard throttles, the Retry-After header contains the wait time in seconds:
Retry-After: 42Wait for the indicated period before retrying. Retrying immediately will continue to return 429 until the window resets.
Provider-Specific Limits
Hive aggregates data from multiple upstream providers. Each provider has its own rate limits that Hive enforces internally. If a provider limit is hit, you will generally see a 502 provider error rather than a Hive 429.
Examples:
| Provider | Limit | Notes |
|---|---|---|
| CoinGecko | 30 req/min | Free tier; Pro keys have higher limits |
| DeFiLlama | No hard limit | Best-effort, may slow under heavy load |
| GoPlus | 20 req/min | Security endpoint specific |
| Helius | 10 req/sec | Solana RPC and DAS endpoints |
Hive retries provider failures with exponential backoff before surfacing an error to you. See Error Reference for provider error handling details.
Best Practices
Cache responses where possible. Token prices and protocol TVL don't change every second. A short TTL cache reduces your request count significantly.
Use category endpoints for focused queries. Category-scoped endpoints (/hive_market_data/mcp, /hive_security_risk/mcp) expose a smaller tool surface and reduce the chance of hitting provider limits unrelated to your task.
Batch with multi-asset tools. Tools like get_price accept comma-separated IDs ("ids": "bitcoin,ethereum,solana"). One request returns data for multiple assets instead of one request per asset.