Docs navigation

Citations

Every 2xx response from Blockchain Academics carries attribution.citations: an array, always, even when there is only one source.

json
"attribution": {
  "citations": [
    {
      "cite_url": "https://blockchainacademics.com/news/bitcoin-price-history?src=claude",
      "as_of": "2026-04-22T10:12:00Z",
      "source_hash": "sha256:abc123..."
    }
  ]
}

This page explains why the array is a contract, not a convenience, and what it unlocks as the corpus grows.

Why array, not singleton?

The envelope committee debated three shapes. We locked array-only on 2026-04-22 because the other two create drift the day multi-source ships.

Rejected: singleton at root

json
// NOT the shape. Would force a breaking change later.
{ "data": {...}, "cite_url": "...", "as_of": "...", "source_hash": "..." }

Rejected: singleton with a convenience shortcut

json
// NOT the shape. Two sources of truth = eventual drift.
{
  "data": {...},
  "attribution": {
    "cite_url": "...",               // shortcut for citations[0].cite_url
    "citations": [ {...}, {...} ]
  }
}

Locked: array-only

json
{
  "data": {...},
  "attribution": { "citations": [ {...} ] }
}

The winning argument: client code that reads citations[0].cite_url today keeps working unchanged when citations[1], citations[2], … get populated. A cite_url shortcut at the root would have forced every client to re-read the spec on the day multi-source shipped. We paid the small cost of [0] indexing up front in exchange for zero breakage later.

What citations[0] means today

For every response, citations[0] is the primary source: the page the payload was derived from. That is the upstream page when a third party supplied the data, and the Blockchain Academics page otherwise:

  • Tools built on our own corpus cite our page for the record when the site has one. get_article puts the article's original source first and its page under /news second (one entry when they are the same page). get_explainer cites the lesson or course page under /academy, after the external spec the lesson is based on when it names one. get_entity cites the project's own website first (without one, the newest article that mentions it), then its coin page under /prices when the entity is a priced coin.
  • Tools that read a third-party upstream (get_price and get_ohlc from CoinGecko, get_tx from the chain explorers, track_sec_filings from the SEC, get_fear_greed from alternative.me, and so on) put that upstream page first, with its own as_of and source_hash. The Blockchain Academics page for the same data follows at citations[1] only when the site has one (a coin page under /prices, for one); otherwise the upstream page stands alone.
  • On search_news the upstream is the top result's original article and the Blockchain Academics link is that article's page on the site; when the two are the same page there is one citation.
  • Data with no page on the site and no upstream page (the indicators, memos and theses, for example) cites its tool's entry in the tool reference. Every 200 carries at least that one citation.

What multi-source unlocks

The upstream citation shipped first. The same array can carry more entries wherever corroboration matters; three examples, the first partly live today:

1. Market data from multiple oracles

When a price is reconciled across several oracles, every oracle is listed:

json
"attribution": {
  "citations": [
    { "cite_url": "https://blockchainacademics.com/market/btc?src=claude",     "as_of": "2026-04-22T10:12:00Z", "source_hash": "sha256:primary..." },
    { "cite_url": "https://blockchainacademics.com/oracles/chainlink/btc-usd", "as_of": "2026-04-22T10:11:58Z", "source_hash": "sha256:chainlink..." },
    { "cite_url": "https://blockchainacademics.com/oracles/pyth/btc-usd",      "as_of": "2026-04-22T10:11:59Z", "source_hash": "sha256:pyth..." }
  ]
}

citations[0] remains the primary source (what the agent should cite to the end user). citations[1..] are the corroborating entries: auditable, but generally not surfaced in the agent's answer beyond the Blockchain Academics link.

2. News cross-referenced across outlets

Once the same event is covered by multiple publishers that BCA ingests, search_news can annotate articles with their corroborating outlets:

json
"attribution": {
  "citations": [
    { "cite_url": "https://blockchainacademics.com/news/circle-mica-license?src=claude", "as_of": "2026-04-21T09:31:22Z", "source_hash": "sha256:bca..." },
    { "cite_url": "https://blockchainacademics.com/news/circle-mica-license/sources/the-block",      "as_of": "2026-04-21T08:14:00Z", "source_hash": "sha256:tb..." },
    { "cite_url": "https://blockchainacademics.com/news/circle-mica-license/sources/coindesk",       "as_of": "2026-04-21T08:22:11Z", "source_hash": "sha256:cd..." }
  ]
}

Same contract: [0] is the BCA canonical page, [1..] are the outlets that corroborate the facts.

3. On-chain + off-chain reconciliation

For tools like get_wallet_profile, a response may reconcile on-chain activity (Etherscan, Helius, Mempool.space) with BCA-enriched narrative context. Each source that contributed gets its own citation entry.

Client behavior

Free / Starter: surface citations[0].cite_url verbatim

The end-user-facing citation rule (see Attribution & licensing) is about citations[0]. Corroborating sources are for audit / UI disclosure, not the primary cite.

Pro+: leaving the citation out is a license term

On Pro and above you may leave citations[0].cite_url out of the downstream answer. That is a permission in your license, not an API switch: there is no strip_attribution parameter, and every response carries attribution.citations on every tier, so your audit logs keep the full array either way.

Write the array, read [0]

Neither MCP package wraps this in a helper. Over HTTP or MCP, index directly:

ts
const primary = env.attribution.citations[0];
console.log(primary.cite_url, primary.as_of);
 
// For audit logging, persist the full array:
logger.info({
  request_id: env.meta.request_id,
  sources: env.attribution.citations.map(c => c.source_hash),
});

Which endpoints return more than one citation?

Endpoint familyCitations
Articles / news corpusThe original article first, its page on the site second (one entry when they are the same page)
Market prices and candlesCoinGecko or DexScreener page first, the matching page under /prices second
On-chain readsThe chain explorer or DefiLlama page
Regulatory, security, sentimentThe regulator, tracker or index page
Entity cards, explainersThe project's website, then its coin page under /prices when it is a priced coin; a lesson's page under /academy
Indicators, memos, theses, curated directoriesThe tool reference entry for indicators, memos and theses; a directory's source page (a job adds its page on the site)
Agent jobsSingle source (by design)

Indicators, memos and theses are our own work and have no page on the site, so their one citation is the tool's entry in the tool reference. A directory cites where its listing comes from.

FAQ

Is citations[] ever empty? Not on HTTP 200. If you see an empty array, it is a bug: file it with the request_id.

Can a citation's as_of be null? No. When the data has no time of its own, as_of is the as_of you asked for (when it is not in the future) or else the time of the answer, and source_hash is a hash of the data. On a stale answer as_of is the data's own, older time.

Can I pin my agent to citations.length === 1? Don't. You'll break the day we ship multi-source on your endpoint. Read [0], don't assert the length.

Does the order of citations[1..] matter? Only [0] (the primary source) and, when present, the Blockchain Academics editorial link at [1] have fixed meaning. Anything after that is set-valued: treat it as unordered.

Next