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
  }
}

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.