All Hive responses are JSON. The exact shape depends on the transport: REST wraps tool results in a small execution envelope, while MCP returns the standard MCP content array and may include structured output when the tool declares an output schema.

REST API Response

REST execution returns ok, data, and meta. The data field contains the provider-shaped tool result. For example, get_price returns:

json

{
  "ok": true,
  "data": {
    "bitcoin": {
      "usd": 67234.0
    },
    "ethereum": {
      "usd": 3521.5
    }
  },
  "meta": {
    "tool": "get_price",
    "duration_ms": 124
  }
}

Validate data against the specific tool schema rather than assuming a universal provider shape. Use the discovery endpoint to inspect schemas:

bash

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:

json

{
  "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.

When a tool declares an output schema, MCP clients that support structured output can also receive structuredContent with the parsed object. Treat structuredContent as an optimization, not the only source, because older clients still read the text content.

Output Format Parameter

All MCP tools include an optional response_format argument:

Value	Use
`json`	Structured data for code and agents. This is the default.
`markdown`	Human-readable summaries when supported by the tool.

Error Responses

REST errors return a consistent envelope regardless of which tool was called:

json

{
  "ok": false,
  "error": {
    "type": "rate_limit_error",
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 42 seconds.",
    "request_id": "req_abc123",
    "doc_url": "https://docs.hiveintelligence.xyz/errors#rate-limited"
  }
}

Field	Description
`ok`	Always `false` on errors
`error.type`	Stable error family such as `auth_error`, `validation_error`, or `rate_limit_error`
`error.code`	Machine-readable error code for programmatic handling
`error.message`	Human-readable explanation
`error.param`	Invalid parameter name when validation can identify one
`error.request_id`	Request identifier when available
`error.doc_url`	Documentation link for remediation

Rate-limit responses may also include standard HTTP headers such as Retry-After.

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:

json

{
  "data": [...],
  "pagination": {
    "page": 1,
    "perPage": 25,
    "total": 312,
    "hasMore": true
  }
}

To fetch the next page, pass the page argument:

json

{
  "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 response-size guardrail to keep agent calls usable. If a result is too large, the server returns a compact JSON object with truncation metadata:

json

{
  "data": [...],
  "_truncated": true,
  "_pagination": {
    "suggested_page_size": 100,
    "next_action": "Use page and per_page arguments to retrieve smaller chunks."
  },
  "_dropped_fields": []
}

When you see _truncated: true, use pagination arguments or narrower filters to retrieve the full dataset in smaller batches.