Docs navigation

Response envelope

Every successful 2xx response from the Blockchain Academics platform (the REST API, the MCP servers in TypeScript and Python, and the bca CLI) returns the same three-key envelope. Your agent never branches on transport or tool identity to find the payload, the citations, or the request id.

Canonical shape

json
{
  "data": { "...": "domain payload: tool- or endpoint-specific" },
  "attribution": {
    "citations": [
      {
        "cite_url": "https://blockchainacademics.com/news/bitcoin-price-history?src=claude",
        "as_of": "2026-04-22T10:12:00Z",
        "source_hash": "sha256:abc123..."
      }
    ]
  },
  "meta": {
    "status": "complete",
    "request_id": "3f9c2a71b8d04e5a",
    "pageInfo": {
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": null,
      "endCursor": null
    }
  }
}

Three top-level keys. Always the same three. Always in that order.

Reading meta.status

Check meta.status before you use data. It is one of four values, and every value other than complete comes with a meta.diagnostic block that says why:

  • complete: the whole answer, current. Use data as it is.
  • partial: data came back, but part of it is missing or defaulted. meta.diagnostic.missing lists what is missing. When a vendor call failed instead, meta.diagnostic.vendor and meta.diagnostic.upstream_status name it.
  • stale: data came back, but it is older than the tool promises. meta.diagnostic.as_of is when the data was current and meta.diagnostic.age_seconds is how old it is; citations[0].as_of carries the same time.
  • unseeded: there is no real data for this call yet (nothing collected, placeholder rows, a source not connected). meta.diagnostic.reason says why and meta.diagnostic.eta when it is expected, or not scheduled. data holds what little exists, often null. Never read an empty data as zero.

Whatever the status, attribution.citations[0] is the primary source: the page the data came from, and the one to show your reader.

Fields

data

The domain payload. Schema is endpoint- or tool-specific: see the REST reference or Tool reference.

data is pure payload. It never contains an envelope-style status field, never contains citations, never contains a request id. Those belong in meta and attribution respectively. If your client reads response.data.status to learn whether the answer is complete, it is a pre-0.3 client: read meta.status. A record's own status field (an agent job's queued, running, done or failed, a transaction's success or failed) is part of the data and stays in data.

On a paged list endpoint, data carries count, total, limit and offset next to its rows (search_news puts the rows under results). On singleton endpoints, data is the object directly.

Over MCP, the server serialises data as a string inside an <untrusted_content> fence so the host model treats upstream text as data, not instructions; attribution and meta stay structured. See MCP quickstart → Parse the envelope. Over HTTP, data is the JSON object itself.

attribution.citations[]

Always an array. Always present on 2xx responses. Always non-empty on 200: a successful response without at least one citation is a server bug, file an issue.

FieldTypeMeaning
cite_urlstringThe page the data came from: an https or http URL. Our own pages are HTTPS and carry ?src= for your client.
as_ofstringRFC 3339 UTC time the data is from: the record's own time when it has one, else the as_of you asked for when it is not in the future, else the time of the answer.
source_hashstringsha256: and hex digits: the record's own hash when it has one, else the first 16 hex digits of a SHA-256 of data. For caching and audit.

citations[0] is always the primary source. A tool that reads a third-party upstream (a CoinGecko coin page, an Etherscan transaction, an SEC filing) puts that upstream page first; the Blockchain Academics page for the same data follows at citations[1] when the site has one. Data with neither an upstream page nor a page on the site cites its tool's entry in the tool reference. See Citations for the rules.

meta.status

Enum: complete, partial, stale or unseeded. What each value means is under Reading meta.status; the client logic is the Status decision tree. The X-BCA-Integration-Status response header mirrors it (live, degraded, stale, pending).

Errors do not use meta.status. Errors use HTTP 4xx/5xx and an error body: see Errors.

meta.request_id

16 hex characters, or the X-Request-ID you sent when it is 8 to 64 letters, digits, _ or -. Echoed in the X-Request-ID response header (Stripe pattern). Every support ticket, every bug report, every audit log references this id. Persist it with your agent's turn log.

meta.pageInfo

Present on every response, in the Linear / GraphQL pageInfo shape. The API pages by offset: it reads count, total and offset from a paged data, and both flags are false on everything else.

FieldTypeMeaning
hasNextPagebooleantrue when the page is not empty and offset + count < total.
hasPreviousPagebooleantrue when offset is above 0.
startCursornullAlways null: the API pages by offset.
endCursornullAlways null: the API pages by offset.

To fetch the next page, call again with offset raised by limit. See REST API → Pagination.

meta.diagnostic (optional)

Present when meta.status is partial, stale or unseeded. Absent on complete.

When status: "unseeded": no real data yet.

json
"diagnostic": {
  "reason": "not_computed_for_entity",
  "eta": "computed every 4 hours for the 50 most mentioned entities and narrative members"
}

When status: "partial" because data is missing:

json
"diagnostic": {
  "reason": "risk_score_inputs_missing",
  "missing": ["regulatory"]
}

When status: "partial" because a vendor call failed:

json
"diagnostic": {
  "reason": "coingecko returned 502",
  "vendor": "coingecko",
  "upstream_status": 502
}

When status: "stale": the data is older than the tool promises.

json
"diagnostic": {
  "reason": "the latest snapshot is older than 6 hours",
  "as_of": "2026-04-22T03:00:00Z",
  "age_seconds": 25920
}

Rate limits

Rate-limit state is not in the envelope body, and the API sends no rate-limit headers. A call over a limit gets HTTP 429 with a detail sentence that names the limit. See REST API → Rate limits.

Errors

Errors break envelope shape intentionally. They return HTTP 4xx/5xx and FastAPI's error body, a detail field:

json
{
  "detail": "This endpoint requires the 'pro' tier or higher (current: 'free'). Upgrade at https://blockchainacademics.com/crypto-api/pricing"
}
HTTPWhen
401Missing or invalid API key.
402The key's plan is below the tool's tier.
403The shared demo key called a tool outside the demo set (X-BCA-Error-Code: BCA_TIER_LOCKED).
404Entity, article, slug or job not found.
422Validation failure: bad params or body.
429Over a rate limit or the daily cap. Honor Retry-After when it is sent.
5xxBackend or upstream failure. Retry with backoff.

Every error response carries the X-Request-ID header. Reference it in support. Over MCP these arrive as the server's error codes (BCA_AUTH, BCA_TIER_LOCKED, BCA_RATE_LIMIT, BCA_UPSTREAM, BCA_BAD_REQUEST); see REST API → Errors.

Status decision tree

Map meta.status to client behavior:

meta.status = "complete"
  └─ Happy path. Use data. Surface citations[0].cite_url per tier rules.
 
meta.status = "unseeded"
  └─ No real data for this call yet.
     ├─ meta.diagnostic.reason  → why
     ├─ meta.diagnostic.eta     → when it is expected, or "not scheduled"
     └─ Agent response: "That data isn't available yet ({reason})."
        Do NOT pretend an empty data or data.value === 0 means zero.
 
meta.status = "partial"
  └─ Data is usable but incomplete.
     ├─ meta.diagnostic.missing → what is missing or defaulted
     ├─ meta.diagnostic.vendor  → which upstream failed, when one did
     └─ Say what is missing. If your use case is trading/compliance:
        retry in 30s or fall through to a secondary source.
 
meta.status = "stale"
  └─ Data is older than the tool promises.
     ├─ meta.diagnostic.as_of        → when it was current
     ├─ meta.diagnostic.age_seconds  → how old it is
     └─ Show as_of prominently to the user. Decide per use case
        whether staleness is acceptable.

Every non-complete status carries enough metadata for the agent to compose an honest, user-facing explanation. That's the whole point of the enum.

Full examples

complete: the happy path

json
{
  "data": {
    "query": "circle mica",
    "count": 1,
    "total": 1,
    "limit": 10,
    "offset": 0,
    "results": [
      {
        "slug": "circle-mica-license",
        "title": "Circle secures full MiCA license",
        "published_at": "2026-04-18T14:02:17Z",
        "summary": "Circle became the first USD stablecoin issuer…",
        "entities": ["circle", "mica", "european-union"]
      }
    ]
  },
  "attribution": {
    "citations": [
      {
        "cite_url": "https://blockchainacademics.com/news/circle-mica-license?src=claude",
        "as_of": "2026-04-18T14:02:17Z",
        "source_hash": "sha256:a9f1b7de2c4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1"
      }
    ]
  },
  "meta": {
    "status": "complete",
    "request_id": "3f9c2a71b8d04e5a",
    "pageInfo": {
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": null,
      "endCursor": null
    }
  }
}

unseeded: no data yet

json
{
  "data": {
    "entity_slug": "example-token",
    "indicator": "coverage_index",
    "window": "7d",
    "value": null
  },
  "attribution": {
    "citations": [
      {
        "cite_url": "https://blockchainacademics.com/crypto-api/docs/reference/tools?src=claude&utm_medium=mcp#get_coverage_index",
        "as_of": "2026-04-22T10:12:00Z",
        "source_hash": "sha256:9d2e4f6a8b0c1e3f"
      }
    ]
  },
  "meta": {
    "status": "unseeded",
    "request_id": "8b4d2f6e1a3c5e7f",
    "pageInfo": {
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": null,
      "endCursor": null
    },
    "diagnostic": {
      "reason": "not_computed_for_entity",
      "eta": "computed every 4 hours for the 50 most mentioned entities and narrative members"
    }
  }
}

The citation is still filled in: when the site has no page for the data it points at the tool's entry in the tool reference, and as_of is the time of the answer.

partial: part of the data is missing

json
{
  "data": {
    "entity_slug": "arbitrum",
    "indicator": "risk_score",
    "window": "90d",
    "value": 0.42,
    "components": { "...": "each input's value and where it came from" }
  },
  "attribution": {
    "citations": [
      {
        "cite_url": "https://blockchainacademics.com/crypto-api/docs/reference/tools?src=claude&utm_medium=mcp#get_risk_score",
        "as_of": "2026-04-22T08:00:00Z",
        "source_hash": "sha256:5e0c9b1d7a3f2e84"
      }
    ]
  },
  "meta": {
    "status": "partial",
    "request_id": "c41f8e2a6b9d0357",
    "pageInfo": {
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": null,
      "endCursor": null
    },
    "diagnostic": {
      "reason": "risk_score_inputs_missing",
      "missing": ["regulatory"]
    }
  }
}

stale: older than promised

json
{
  "data": { "...": "the snapshot, as it was at as_of" },
  "attribution": {
    "citations": [
      {
        "cite_url": "https://blockchainacademics.com/...?src=claude",
        "as_of": "2026-04-22T03:00:00Z",
        "source_hash": "sha256:c3d4e5f6a7b8c9d0"
      }
    ]
  },
  "meta": {
    "status": "stale",
    "request_id": "e5a7c9b1d3f20486",
    "pageInfo": {
      "hasNextPage": false,
      "hasPreviousPage": false,
      "startCursor": null,
      "endCursor": null
    },
    "diagnostic": {
      "reason": "the latest snapshot is older than 6 hours",
      "as_of": "2026-04-22T03:00:00Z",
      "age_seconds": 25920
    }
  }
}

citations[0].as_of is the data's own time, the same as meta.diagnostic.as_of, never the time of the call.

Parsing the envelope

ts
type Status = "complete" | "unseeded" | "partial" | "stale";
 
interface Citation {
  cite_url: string;
  as_of: string | null;
  source_hash: string | null;
}
 
interface Envelope<T> {
  data: T | null;
  attribution: { citations: Citation[] };
  meta: {
    status: Status;
    request_id: string;
    pageInfo: {
      hasNextPage: boolean;
      hasPreviousPage: boolean;
      startCursor: string | null;
      endCursor: string | null;
    };
    diagnostic?: { reason: string; [k: string]: unknown };
  };
}
 
const res = await fetch(url, { headers: { "X-API-Key": key } });
const env: Envelope<ArticleList> = await res.json();
 
if (env.meta.status !== "complete") {
  console.warn(`[${env.meta.request_id}] ${env.meta.status}`, env.meta.diagnostic);
}
const primary = env.attribution.citations[0].cite_url;

What changed in 0.3

Before (0.2, flat)After (0.3, canonical)
cite_url at rootattribution.citations[0].cite_url
as_of at rootattribution.citations[0].as_of
source_hash at rootattribution.citations[0].source_hash
X-BCA-Integration-Status: pending headermeta.status: "unseeded" + meta.diagnostic (the header stays as a mirror)
{data: null, status: "integration_pending"}{data: null, meta: {status: "unseeded", diagnostic: {...}}}
Implicit request id (log-only)meta.request_id (body) + X-Request-ID (header)
No standard pagination envelopemeta.pageInfo (Linear / GraphQL shape, over offset paging)
Rate limits in {error} body fieldsHTTP 429 with a detail sentence; nothing in the envelope

Why the change. The flat shape worked fine when every response had exactly one citation and one freshness timestamp. That assumption breaks the moment you want multi-oracle prices, cross-outlet news corroboration, or enterprise-grade request tracing. The canonical envelope is JSON:API-inspired, drift-resistant, and matches shapes enterprise buyers already recognize (Stripe's request_id, Linear's pageInfo, JSON:API's data/meta split).

Client migration. Read response.attribution.citations[0].cite_url instead of response.cite_url. That is the one change that covers 95% of callers. The rest (pagination, status enum handling) is additive.

Next