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
{
"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. Usedataas it is.partial: data came back, but part of it is missing or defaulted.meta.diagnostic.missinglists what is missing. When a vendor call failed instead,meta.diagnostic.vendorandmeta.diagnostic.upstream_statusname it.stale: data came back, but it is older than the tool promises.meta.diagnostic.as_ofis when the data was current andmeta.diagnostic.age_secondsis how old it is;citations[0].as_ofcarries the same time.unseeded: there is no real data for this call yet (nothing collected, placeholder rows, a source not connected).meta.diagnostic.reasonsays why andmeta.diagnostic.etawhen it is expected, ornot scheduled.dataholds what little exists, oftennull. Never read an emptydataas 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.
| Field | Type | Meaning |
|---|---|---|
cite_url | string | The page the data came from: an https or http URL. Our own pages are HTTPS and carry ?src= for your client. |
as_of | string | RFC 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_hash | string | sha256: 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.
| Field | Type | Meaning |
|---|---|---|
hasNextPage | boolean | true when the page is not empty and offset + count < total. |
hasPreviousPage | boolean | true when offset is above 0. |
startCursor | null | Always null: the API pages by offset. |
endCursor | null | Always 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.
"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:
"diagnostic": {
"reason": "risk_score_inputs_missing",
"missing": ["regulatory"]
}When status: "partial" because a vendor call failed:
"diagnostic": {
"reason": "coingecko returned 502",
"vendor": "coingecko",
"upstream_status": 502
}When status: "stale": the data is older than the tool promises.
"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:
{
"detail": "This endpoint requires the 'pro' tier or higher (current: 'free'). Upgrade at https://blockchainacademics.com/crypto-api/pricing"
}| HTTP | When |
|---|---|
| 401 | Missing or invalid API key. |
| 402 | The key's plan is below the tool's tier. |
| 403 | The shared demo key called a tool outside the demo set (X-BCA-Error-Code: BCA_TIER_LOCKED). |
| 404 | Entity, article, slug or job not found. |
| 422 | Validation failure: bad params or body. |
| 429 | Over a rate limit or the daily cap. Honor Retry-After when it is sent. |
| 5xx | Backend 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
{
"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
{
"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
{
"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
{
"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
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;from typing import Any, Literal, TypedDict
Status = Literal["complete", "unseeded", "partial", "stale"]
class Citation(TypedDict):
cite_url: str
as_of: str | None
source_hash: str | None
resp = httpx.get(url, headers={"X-API-Key": key})
env = resp.json()
if env["meta"]["status"] != "complete":
print(f"[{env['meta']['request_id']}] {env['meta']['status']}",
env["meta"].get("diagnostic"))
primary = env["attribution"]["citations"][0]["cite_url"]What changed in 0.3
| Before (0.2, flat) | After (0.3, canonical) |
|---|---|
cite_url at root | attribution.citations[0].cite_url |
as_of at root | attribution.citations[0].as_of |
source_hash at root | attribution.citations[0].source_hash |
X-BCA-Integration-Status: pending header | meta.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 envelope | meta.pageInfo (Linear / GraphQL shape, over offset paging) |
Rate limits in {error} body fields | HTTP 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
- Citations: why
citations[]is an array, and what multi-source looks like. - Attribution & licensing: your obligation when surfacing citations downstream.
- Tiers & quotas: what changes between plans.
- REST API reference: endpoint map, pagination, errors.
- Tool reference: every tool's arguments and tier.