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, Codex, CCXT, GoldRush, 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 402 Payment Required instead of 429.
Rate Limit Headers
Every response includes headers showing your current quota state:
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1712534460
| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum requests allowed in the current minute |
X-RateLimit-Remaining | Requests remaining before throttling |
X-RateLimit-Reset | Unix timestamp when the window resets |
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. Retry after 42 seconds.",
"retryAfter": 42
}
}
The Retry-After header contains the same value in seconds:
Retry-After: 42
Wait 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 see a 502 response rather than a 429.
| 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 |
| GoldRush | 5 req/sec | Applies per chain endpoint |
| 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.