REST API reference
Every MCP tool is a thin wrapper around a REST endpoint on api.blockchainacademics.com. If you would rather call HTTP directly (a non-MCP integration, a server-side pipeline, an internal job runner), the same API key and the same canonical envelope apply.
Base URL
https://api.blockchainacademics.comThe MCP servers and the CLI read BCA_API_BASE to point at another host (an allowlist: production, https://staging-api.blockchainacademics.com, and localhost); a custom HTTP client sets its own base URL. See Environment variables.
Authentication
Every request carries the API key in the X-API-Key header:
X-API-Key: bca_xxxxxxxxxxxxxxxxA key is bca_ followed by 48 hex characters. The API reads the key from this header only: it does not read an Authorization: Bearer header, so a call that sends only that is treated as a call with no key. Get a key at blockchainacademics.com/crypto-api/signup.
Response envelope
Every 2xx JSON response under /v1 (except /v1/health, /v1/status and the billing and key-issuing account routes) returns the canonical three-key envelope:
{
"data": { "...": "endpoint-specific payload" },
"attribution": {
"citations": [
{
"cite_url": "https://blockchainacademics.com/...",
"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
}
}
}Full field-by-field breakdown, including what each meta.status value means: Response envelope. Citation semantics: Citations.
Response headers
Every response carries X-Request-ID, and every enveloped response also carries X-BCA-Integration-Status:
X-Request-ID: 3f9c2a71b8d04e5a
X-BCA-Integration-Status: liveX-Request-ID mirrors meta.request_id: 16 hex characters, or the X-Request-ID you sent when it is 8 to 64 letters, digits, _ or -. Log it with every call. X-BCA-Integration-Status mirrors meta.status: live for complete, pending for unseeded, degraded for partial and stale for stale. The API sends no X-RateLimit-* headers; see Rate limits.
Core endpoint map
| Endpoint group | Path | Who uses it |
|---|---|---|
| Articles / corpus | /v1/articles/... | search_news, get_article, get_as_of_snapshot |
| Entities | /v1/entities/... | get_entity, list_entity_mentions, list_entities |
| Topics | /v1/topics/... | list_topics, get_topic |
| Academy | /v1/academy/... | get_explainer, search_academy |
| Market | /v1/market/... | get_price, get_ohlc, get_market_overview, get_pair_data |
| On-chain | /v1/onchain/... | get_wallet_profile, get_tx, get_token_holders, get_defi_protocol |
| Sentiment | /v1/sentiment/... | get_sentiment, get_social_pulse, get_fear_greed |
| Proprietary indicators | /v1/indicators/... | get_coverage_index, get_narrative_strength, … |
| Agent jobs | /v1/agent-jobs/... | generate_due_diligence, summarize_whitepaper, get_agent_job, … (see Agent jobs) |
| Directories | /v1/directories/... | list_stablecoins, list_yields, list_vcs, list_jobs, get_job, … |
| Fundamentals | /v1/fundamentals/... | get_tokenomics, get_audit_reports, compare_protocols |
| Chain-specific | /v1/chains/... | get_solana_ecosystem, get_l2_comparison |
| Regulatory | /v1/regulatory/... | get_regulatory_status, track_sec_filings, get_mica_status |
| Security | /v1/security/... | scan_contract, check_phishing_domain, get_bug_bounty_programs |
| History time-series | /v1/history/... | get_history_prices, get_history_sentiment, … |
| Services (revenue, POST) | /v1/services/... | book_kol_campaign, request_custom_research, submit_listing |
| Grants | /v1/grants/... | search_grants, get_grant |
| Studio (leads) | /v1/studio/... | Internal: powers the studio's contact form |
For exact parameters, request bodies, and response shapes of every endpoint, see the live Swagger. This page intentionally does not duplicate it: the OpenAPI JSON is the source of truth, and a mirror drifts.
Example: search_news over HTTP
curl -s "https://api.blockchainacademics.com/v1/articles/search?q=circle+mica&limit=5" \
-H "X-API-Key: $BCA_API_KEY"Response:
{
"data": {
"query": "circle mica",
"count": 1,
"total": 1,
"limit": 5,
"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=other",
"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
}
}
}Example: list with pagination
List endpoints page by offset. A paged answer carries count, total, limit and offset in data, and meta.pageInfo.hasNextPage says whether another page exists.
curl -s "https://api.blockchainacademics.com/v1/articles/search?q=ethereum&limit=2" \
-H "X-API-Key: $BCA_API_KEY"{
"data": {
"query": "ethereum",
"count": 2,
"total": 147,
"limit": 2,
"offset": 0,
"results": [
{ "slug": "eth-pectra-mainnet", "title": "Pectra goes live on Ethereum mainnet", "published_at": "2026-04-20T12:00:00Z" },
{ "slug": "eth-staking-rate", "title": "ETH staking yield falls below 3%", "published_at": "2026-04-19T08:31:00Z" }
]
},
"attribution": {
"citations": [
{
"cite_url": "https://blockchainacademics.com/news/eth-pectra-mainnet?src=other",
"as_of": "2026-04-20T12:00:00Z",
"source_hash": "sha256:b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3"
}
]
},
"meta": {
"status": "complete",
"request_id": "7d1e0b5c9a2f4e83",
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": null,
"endCursor": null
}
}
}To fetch the next page, add limit to offset:
curl -s "https://api.blockchainacademics.com/v1/articles/search?q=ethereum&limit=2&offset=2" \
-H "X-API-Key: $BCA_API_KEY"hasPreviousPage is true once offset is above 0. startCursor and endCursor are always null: the API pages by offset, and the cursor fields stay so the envelope shape never changes.
Example: degraded response (partial)
Data came back, but an input is missing. meta.diagnostic.missing names it:
{
"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=other&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"]
}
}
}When a vendor call failed instead, meta.diagnostic names the vendor: {reason, vendor, upstream_status}. See Reading meta.status for every status.
Errors
Errors return HTTP 4xx/5xx and do not reuse the envelope shape. The body is FastAPI's: a detail field, a sentence for most errors and a list of field problems when the request fails validation.
{
"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 X-API-Key. |
| 402 | The key's plan is below the tool's tier. detail names the tier needed. |
| 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. detail says which field failed. |
| 429 | Over a rate limit or the daily cap, too many agent jobs at once, or an upstream data provider's rate limit. |
| 5xx | Backend failure. Retry with backoff. |
Some 429s carry Retry-After and X-BCA-Error-Code: BCA_RATE_LIMIT: the demo key's caps, keyless article reads, the agent-job cap and the daily budget for live crypto Twitter reads. A 429 that passes on an upstream data provider's rate limit carries Retry-After only. A key's per-second limit and daily cap carry neither. Every error response carries the X-Request-ID header: include it in any support ticket.
Over MCP the servers map these to their own codes: BCA_AUTH (401), BCA_TIER_LOCKED (the demo key's 403), BCA_RATE_LIMIT (429) and BCA_UPSTREAM (5xx, without the API's detail). A 402, 404 or 422 carries the API's detail, as BCA_UPSTREAM from the TypeScript server and as BCA_BAD_REQUEST from the Python server. Both servers also answer BCA_BAD_REQUEST when the arguments fail their own check before any call is made.
Integration-state responses are not errors. When there is no real data for a call yet, the response is HTTP 200 with meta.status: "unseeded" and a meta.diagnostic block: see Envelope → Status decision tree.
Pagination
List endpoints accept:
| Param | Default | Max | Notes |
|---|---|---|---|
limit | varies | varies | Per-endpoint default and max are in Swagger (/v1/articles/search: 20, max 100). |
offset | 0 | none | Rows to skip. Add limit to it for the next page. |
Inspect meta.pageInfo.hasNextPage on every response to decide whether to keep walking. Do not assume data.results.length < limit means you are done.
Rate limits
Limits are counted per account on Free, Starter, Pro and Team (a rotated key keeps its counters) and per key on Enterprise. Each plan has a per-second rate limit and a daily cap. On Free, Starter, Pro and Team the daily cap is a thirtieth of the monthly quota plus 30% headroom, so a month's calls cannot all land on one day. The monthly quota itself is not enforced: the daily cap is what stops a key. The per-second limits and the quotas are on Pricing.
Over either limit you get HTTP 429 with a detail sentence that names the limit, for example Rate limit exceeded: 2 requests/second for free tier. There are no rate-limit headers: back off and retry after a second, or after midnight UTC for the daily cap. Agent loops with retries should cache. See Tiers & quotas for what changes between tiers.
Agent jobs
The agent-backed tools are POST routes that start a job, plus one GET that polls it. Each tool's tier is on the tool reference.
| Tool | Route |
|---|---|
generate_due_diligence | POST /v1/agent-jobs/due-diligence |
generate_tokenomics_model | POST /v1/agent-jobs/tokenomics-model |
summarize_whitepaper | POST /v1/agent-jobs/summarize-whitepaper |
translate_contract | POST /v1/agent-jobs/translate-contract |
monitor_keyword | POST /v1/agent-jobs/monitor-keyword |
get_agent_job | GET /v1/agent-jobs/{job_id} |
A POST answers HTTP 202 with job_id and status_url (/v1/agent-jobs/{job_id}). Poll that URL until data.status is done (the output is in data.result) or failed (the reason is in data.error). A key sees only the jobs it started, and can have 3 jobs queued or running at a time; a fourth gets HTTP 429.
Webhooks
The API sends no webhooks yet. monitor_keyword saves a keyword subscription with its webhook_url (the MCP servers accept only an HTTPS URL on a public host), but the watcher that would read those subscriptions and send webhooks is not built. The answer says so: meta.status is unseeded, meta.diagnostic.reason explains why, and data.webhook_delivery is not_active. Polling the job with get_agent_job gives the same answer. Agent jobs do not call back either: poll status_url for the result.
Next
- Live Swagger: interactive, click to try.
- OpenAPI JSON: for codegen.
- Response envelope: field-by-field breakdown.
- Citations: why
citations[]is an array. - Tool reference: the MCP view of the same surface.