Response format

Where Hive attaches provenance, and how the shape differs between hero tools and category tools.

Responses are typed and bounded, and material ones carry provenance. Where that provenance sits depends on which surface answered.

MCP tools

Tools reached through discovery attach a top-level _hive object alongside the payload:

{
  "_hive": {
    "receipt_id": "9f2c…",
    "provider": "coingecko",
    "tool": "get_coin_price",
    "runtime_status": "ok",
    "fetched_at": "2026-08-19T14:22:07Z",
    "cache_status": "miss",
    "duration_ms": 184
  }
}

_hive also carries receipt_version, server_version, input_digest, and result_digest. The digests are SHA-256 self-checks over the canonical arguments and the normalized payload. They let you detect accidental mutation; they are not server signatures.

Hero tools

The three hero tools return a source_receipt instead:

{
  "source_receipt": {
    "provider": "coingecko",
    "tool": "get_coin_price",
    "runtime_status": "ok",
    "fetched_at": "2026-08-19T14:22:07Z",
    "cache_status": "hit",
    "source": "…",
    "receipt_id": "9f2c…"
  }
}

Same three fields you care about, different container. See receipts.

runtime_status values

runtime_status is an enum, not free text:

Value	Meaning
ok	The call succeeded against a healthy provider
invalid_input	Your arguments failed validation, or the venue and method combination is unsupported. Fixable by correcting the call
missing_key	The provider is not configured
plan_required	Your plan does not include this
rate_limited	Throttled
degraded	The provider answered but is unhealthy. Treat the result as low confidence
failing	The provider is down

invalid_input is worth handling separately: it is not an outage, so retrying unchanged will fail the same way.

Cache fields

cache_status tells you whether the response came from Hive’s cache. On a hit, observed_at is when Hive first saw the data and cache_age_ms is how long ago that was.

A cache_age_ms of zero means Hive fetched from the provider just now. It does not promise that the provider’s own underlying datum is current.

Normalization fields

Where Hive knows something is off about a datapoint, it says so in a field rather than dropping the row:

Field	Meaning
is_delisted	No longer actively traded on the venue
is_price_suspect	Diverges enough from other sources to warrant a check
funding_mechanism	How this venue calculates funding, since venues differ

Your agent decides what to do with a flagged row. Hive does not filter it out for you.

Bounded output

Every list-returning tool respects limit, page, per_page, and offset, and Hive caps total response size regardless of what you ask for. An unbounded response would burn the context your agent needs for the actual task.

Errors

Failures return an error object naming the cause and the next action. See errors.