API Reference
Response Formats
All Hive responses are JSON. The exact shape depends on which tool you call - most tools return provider-shaped data directly rather than wrapping it in a shared envelope.
REST API Response
Tool responses return the provider's data directly. For example, get_price returns:
{
"bitcoin": {
"usd": 67234.0
},
"ethereum": {
"usd": 3521.5
}
}
Validate against the specific tool schema rather than assuming a universal wrapper. Use the discovery endpoint to inspect schemas:
curl "https://mcp.hiveintelligence.xyz/api/v1/tools?search=get_price" \
-H "Authorization: Bearer YOUR_HIVE_API_KEY"
MCP Response
When calling tools through the MCP protocol, responses follow the MCP content array format:
{
"jsonrpc": "2.0",
"result": {
"content": [
{
"type": "text",
"text": "{\"bitcoin\":{\"usd\":67234.0},\"ethereum\":{\"usd\":3521.5}}"
}
]
},
"id": 1
}
The content[0].text field contains the tool result as a JSON string. Parse it to get the structured data.
Error Responses
Errors return a consistent envelope regardless of which tool was called:
{
"ok": false,
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after 42 seconds.",
"retryAfter": 42
}
}
| Field | Description |
|---|---|
ok | Always false on errors |
error.code | Machine-readable error code for programmatic handling |
error.message | Human-readable explanation |
error.retryAfter | Seconds to wait before retrying (only on 429 responses) |
See the Error Reference for the full list of error codes and HTTP status mappings.
Pagination
Tools that return lists support pagination via page and per_page arguments. Paginated responses include a pagination object:
{
"data": [...],
"pagination": {
"page": 1,
"perPage": 25,
"total": 312,
"hasMore": true
}
}
To fetch the next page, pass the page argument:
{
"tool": "get_yield_pools",
"args": {
"chain": "ethereum",
"page": 2,
"per_page": 25
}
}
Not all tools support pagination. Check the tool schema via the discovery endpoint to confirm.
Response Truncation
Hive applies a 25,000 token limit to tool responses. If a response exceeds this limit, it is truncated and a truncated field is added:
{
"data": [...],
"truncated": true,
"hint": "Use page and per_page arguments to retrieve results in smaller chunks."
}
When you see truncated: true, use pagination arguments to retrieve the full dataset in smaller batches. The hint field provides guidance specific to the tool that returned the truncated response.