The docs cover a real, widely-used open-source explorer with substantial developer material — a PRO API reference, an Etherscan migration guide, RPC/GraphQL docs, and self-hosting setup. But core numbers don't agree across pages (and sometimes within a single page), a flagship migration claim contradicts itself two sentences apart, the one GraphQL example can't be run and demands a credential the docs never define, and several headline pages are placeholder stubs or frozen ~2.5 years behind the product.
1. Free-tier rate limit is stated as 3, 5, and 300/min — on the same page and across pages (critical)
Problem: The requests-and-limits page contradicts itself three ways. The intro says the free plan is "5 rps included in the free plan." A heading right below says "Default API rate limit is 3 requests per second without an API key." The table row "No API key (by IP)" lists the value 3 req/sec, but its own description says "The default rate limit is 300 requests per minute" — and 300/min is 5/sec, not 3/sec. Meanwhile every other page quotes 5: the PRO API page ("Free … 5 RPS"), the migration page ("Free tier RPS: 5"), and the MyAccount page ("5 rps for the free plan").
Consequence: A developer or agent sizing retry/backoff logic has no reliable number — three values (3 rps, 5 rps, 300/min) describe the same default tier on one screen. Pick 5 and you may get throttled at 3; pick 3 and you leave throughput on the table. Agents that parse the table cell (3) silently disagree with the prose shipped beside it.
The fix: Decide the real default no-key limit, express it once in a single unit, and make the table cell, the heading, the intro, and the cross-page tables all cite that one figure. If it's 300/min, write 300/min everywhere and drop the conflicting "3 req/sec."
2. "Same parameters — swap the base URL and key" is contradicted in the adjacent sentence (critical)
Location: /devs/pro-api (self-contained), reinforced by /devs/migrate-from-etherscan
Problem: The PRO API page contradicts itself in two adjacent sentences: "Etherscan uses api.etherscan.io/v2/api?chainid=, Blockscout uses api.blockscout.com/v2/api?chain_id=. Same modules, same parameters — swap the base URL and key." The parameter is renamed (chainid → chain_id) in the same breath that claims "same parameters." The migration page repeats the same self-contradiction: it lists "chainid → chain_id" as a required change and then writes "Same modules, same actions, same parameters."
An AI agent (or a human skimming) that follows "swap the base URL and key" literally sends , leaving the renamed in the query. The scraped docs don't specify how Blockscout handles an unrecognized , so the failure mode is undocumented — it may resolve to a default/wrong chain rather than returning a clean error, which would be worse than a hard failure because nothing signals the mistake.
Code verification
Runtime snippet checks
Run the public examples from this audit in an isolated sandbox and attach the pass, fixed, skipped, and failed counts to the report.
The fix: Stop claiming "same parameters." State plainly, on both pages: "One parameter changes: chainid → chain_id." Better, lead with the path-based alternative the migration page already documents (api.blockscout.com/1/api?module=…), which sidesteps the rename entirely, and mark it as the lowest-friction migration path.
3. Supported-chain count swings from "over 1000" to "100+" to "dozens" (significant)
Problem: The home page claims Blockscout "supports over 1000 L1, L2 and L3 EVM-based chains." The PRO API page says "100+ EVM chains" and, one paragraph later, "dozens of mainnets and testnets." The migration page and the MCP page also say "100+ EVM chains." That's three different orders of magnitude (1000, 100, dozens) for what reads as the same claim.
Consequence: A developer evaluating whether their chain is covered can't tell if the platform supports ~1000 chains or ~100. The PRO API page even undercuts itself within a single section ("100+" then "dozens"). Buyers and agents comparing coverage against Etherscan get a number that depends entirely on which page they landed on.
The fix: Separate the two distinct facts and label them: "Blockscout software powers 1000+ deployed explorers" vs. "the PRO API multichain endpoint currently serves 100+ chains." Replace the vague "dozens" with the same "100+" figure, and point both at the canonical live list (dev.blockscout.com supported chains).
4. API-keys-per-account limit is "Up to 50" on one page and "maximum of 3" on another (significant)
Location: /devs/migrate-from-etherscan vs /using-blockscout/my-account/api-keys
Problem: The migration comparison table advertises "API keys per account: Up to 50." The MyAccount API Keys page says the opposite twice: "A maximum of 3 keys can be created for each account" and "you can add 2 additional keys (up to 3 per account)."
Consequence: A developer architecting key rotation or per-environment keys around the advertised "50" hits a hard wall at 3 and has to redesign. The discrepancy is ~17x, and the two pages give no hint that one supersedes the other (e.g., PRO API account vs. MyAccount).
The fix: Clarify which product each limit belongs to (PRO API account vs. legacy MyAccount) and state both explicitly on both pages. If the "50" is PRO-only, label it "PRO API: up to 50 keys" and keep MyAccount's "3" out of the same comparison row.
5. The only GraphQL curl example is invalid JSON and can't be run; sample schema is unrelated to Blockscout (significant)
Location: /devs/apis/graphql
Problem: The single HTTP-client example is broken in three ways. The JSON body has doubled quotes — '{"query":""{transaction(…)}""}' — which is invalid JSON. The multi-line curl has no line-continuation backslashes and no -X POST, so pasting it into a shell fails. Separately, the "Query types" examples teach a generic blog schema (updatePost, newPost(category:[1])) that has nothing to do with Blockscout's actual GraphQL schema.
Consequence: A developer's first real GraphQL request — the one example provided — fails on copy-paste, and the schema samples send them looking for Post mutations that don't exist. For an agent, this is unrecoverable: the payload won't even parse as JSON.
The fix: Replace with a runnable command: single-quoted, valid JSON ('{"query":"{ transaction(hash:\"0x…\"){ blockNumber value status } }"}'), explicit -X POST, and \ continuations. Swap the blog-tutorial query/mutation/subscription samples for real Blockscout types (transactions, addresses, blocks).
6. The GraphQL example requires a Bearer token the docs never define (significant)
Location: /devs/apis/graphql
Problem: The same GraphQL curl example sends -H 'Authorization: Bearer YOUR_AUTH_TOKEN', but nothing on the page explains what that token is, where to obtain it, or whether the public GraphQL endpoint even requires authentication at all. The placeholder is presented as a required header with zero supporting documentation.
Consequence: A developer hits a wall before their first query: they have a header demanding a credential with no documented way to get one, and no statement of whether it's even needed. An agent assembling a GraphQL call has no way to resolve YOUR_AUTH_TOKEN and will either omit it (and possibly fail) or block. This is exactly the kind of dead-end the "auth documented but never explained end-to-end" anti-pattern produces.
The fix: State explicitly whether the GraphQL endpoint requires auth. If it does, document where the token comes from, how to generate it, and its lifetime; if it doesn't, drop the Authorization header from the example entirely.
7. The consolidated error reference covers only PRO API proxy errors — REST, RPC, and GraphQL have none (significant)
Location: /devs/error-responses
Problem: The docs' only "Error Handling" page documents exclusively the PRO API proxy envelope (error + source) and its 404/500/502/503/504/501 table. The page explicitly carves out everything else: "Successful responses without this JSON envelope — Direct Blockscout responses; 4xx in that case come from upstream … not necessarily the table above." There is no equivalent consolidated error reference for the per-instance REST API, the RPC API, or GraphQL.
Consequence: A developer integrating against a per-instance explorer or the RPC/GraphQL endpoints has no documented error contract — no list of status codes, no error body shapes. They have to reverse-engineer failures by triggering them. Agents can't build error handling against undocumented behavior and will fail on shapes they never saw.
The fix: Add error references for the REST, RPC, and GraphQL APIs (status codes, body shapes, example payloads), or explicitly state on this page which surfaces are out of scope and link to where each one's errors are defined.
8. Beacon-chain withdrawals are still marked "Coming Soon" three years after the hardfork shipped (significant)
Problem: The page header reads "Coming Soon" and the body says validator withdrawals "will soon be activated on the Ethereum mainnet with the Shanghai/Capella hardfork (EIP-4895)." That hardfork went live in April 2023 — over three years before the current date (2026-06-05) — and the page describes the feature entirely in the future tense ("will be displayed on Blockscout").
Consequence: A long-shipped feature is documented as not-yet-available. Users reading this conclude Blockscout can't show withdrawals and look elsewhere; the future-tense framing actively misinforms anyone trying to confirm support.
The fix: Rewrite in present tense, remove the "Coming Soon" banner, and document the live withdrawal views (block page and address page) with current fields. Add a docs freshness check so "Coming Soon" pages get flagged after a shipping date passes.
9. The in-docs release notes are frozen at v5.3.0 (Oct 2023) and quietly defer to GitHub (significant)
Location: /resources/release-notes and /resources/release-notes/v5-3-0-10-23-23
Problem: The newest changelog entry is "V5.3.0: 10/23/23" (October 2023), and that entry itself defers elsewhere: "All backend release notes are now available on github." The release-notes landing page has essentially no content beyond two GitHub links. So the on-site changelog has been dormant for ~2.5 years while still presenting itself as the docs' changelog section. (The docs' own navigation references newer major versions — e.g. an upgrade guide for v7 — but that page body was not in the scraped evidence, so the size of the version gap is asserted by the site nav, not confirmed from the changelog itself.)
Consequence: A self-hoster planning an upgrade can't use the docs changelog to understand what changed since v5.3 — it's frozen and bounces them to raw GitHub release pages with no curated migration narrative. A changelog that looks maintained but stops in 2023 is worse than none, because it implies nothing has shipped since.
The fix: Either keep the on-site release notes current (at minimum a per-major summary up to the current version) or remove the stale changelog section and replace it with a single, clearly-labeled "Release notes live on GitHub" pointer plus the upgrade guides — so it doesn't masquerade as a maintained changelog ending in 2023.
10. Migration page claims free-tier "no restrictions" next to an explicit rate/credit cap (minor)
Location: /devs/migrate-from-etherscan
Problem: The page states "Free-tier access is available on all supported chains with no restrictions" — directly beside its own side-by-side table listing the free tier as "5" RPS, and the PRO API page documenting "100K credits/day · 5 RPS" for the same tier. A 5 RPS, 100K-credits/day ceiling is a restriction.
Consequence: "No restrictions" reads as unlimited to a developer (or agent) doing capacity planning, who then designs against a throughput the platform won't actually serve and gets throttled. It contradicts the very table printed alongside it.
The fix: Replace "no restrictions" with the actual free-tier limits ("all supported chains; 5 RPS and 100K credits/day"). Reserve "no restrictions" for whatever genuinely has none (e.g. chain coverage), and say so precisely.
11. Worked example uses a malformed UUID as the API key (minor)
Location: /using-blockscout/my-account/api-keys
Problem: The "Use API key" walkthrough hard-codes the key fdbfa288-1695-454e-a369-4501253a120 into a full example URL. That string is not a valid UUID: its groups are 8-4-4-4-11, i.e. 31 hex digits / 35 characters, where a real v4 UUID is 32 hex digits / 36 characters — the final group has 11 characters instead of 12.
Consequence: The key isn't flagged as a placeholder (no <your-key> or "example" marker), so a copy-paste reader may pattern their own key validation on a malformed shape, and an agent extracting the example treats it as a literal credential. It won't authenticate regardless, but it teaches the wrong key format.
The fix: Replace it with an obvious, well-formed placeholder (e.g. YOUR_API_KEY) or a clearly-fake but structurally valid UUID, and label placeholder values consistently across all example URLs.
12. Published placeholder pages live in the navigation as real entries (minor)
Location: /devs/dev-portal and /using-blockscout/my-account/verified-addresses/copy-and-sign-message
Problem: Two real nav entries are content-free stubs. The Dev Portal page's entire body is "More info coming soon." (it points readers to dev.blockscout.com). The "Copy and Sign Message" page under Verified Addresses is entirely "Instructions coming soon."
Consequence: A user who navigates to "Copy and Sign Message" expecting to learn how to sign verification messages gets nothing actionable and no link to where the steps actually live. Empty pages in the nav waste clicks and erode trust that other pages are complete.
The fix: Either fill these in or unpublish them from the nav and redirect to the live destination (the Dev Portal stub already points to dev.blockscout.com — make that a redirect rather than a dead-end page).
13. A substantive page is published under the slug "untitled-page" and is part of the machine-readable index (minor)
Location: /devs/untitled-page
Problem: This page has real content — "Onchain Data via Blockscout PRO API & MCP" — but its URL slug is the default placeholder untitled-page. It was retrieved from the docs' llms-full.txt dump, so the placeholder slug is part of the machine-readable index that agents consume.
Consequence: The placeholder slug is an unstable, unhelpful canonical URL — bad for SEO, bad for linking, and it signals to an agent indexing the docs that the page is untitled/unfinished, which can deprioritize genuinely useful AI-agent/MCP content.
The fix: Give the page a real slug (e.g. /devs/ai-agents-mcp), add a redirect from the old one, and regenerate the llms.txt / llms-full.txt index so the slug reflects the content.
14. "Will be deprecated soon" appears with no timeline — on pages still routed to as the canonical destination (minor)
Location: /devs/apis/requests-and-limits and /using-blockscout/my-account/api-keys
Problem: Both pages warn that per-instance / MyAccount API access "will be deprecated soon" with no date or version. Yet the requests-and-limits table still routes "Individual API key" creation to the MyAccount section, and MyAccount remains the documented place to generate keys. So the docs simultaneously tell you to use a flow and that the flow is going away "soon."
Consequence: A developer can't tell whether to invest in MyAccount keys or jump straight to PRO. "Soon" with no date is undated indefinitely, and the still-live key-creation route contradicts the deprecation banner.
The fix: Attach a concrete deprecation target (version or date) and a migration step. If MyAccount keys still work, say "supported until X; new integrations should use PRO" and keep the route; if they're truly sunsetting, point key-creation links at the PRO flow instead.
What they do well
The PRO API error reference (/devs/error-responses) is genuinely structured — an HTTP-code table with the error/source envelope, meanings, and retry guidance — and it honestly flags what it does not cover.
The Etherscan migration page provides concrete side-by-side request URLs and documents a path-based routing alternative (api.blockscout.com/1/api?…), which is exactly the parseable, copy-ready format agents need (once the "same parameters" claim is corrected).
An llms.txt / llms-full.txt index exists, so the docs are already thinking about agent consumption — the gap is content consistency, not machine-readability infrastructure.
Top 3 recommendations
Reconcile the numbers. Run a single pass to make rate limits (3 vs 5 vs 300/min), chain counts (1000 vs 100+ vs dozens), and key limits (50 vs 3) agree across every page — and within each page. These are the contradictions that break agents silently.
Fix the two broken "first requests." Correct the self-contradicting "same parameters" Etherscan claim (state the chainid→chain_id rename up front), and make the GraphQL example runnable: valid JSON, explicit -X POST, Blockscout's real schema, and a clear statement of whether the Bearer token is required and where it comes from.
Retire the stale and stub pages. Update the "Coming Soon" beacon-withdrawals page to present tense, either maintain or clearly redirect the v5.3.0-frozen release notes, and unpublish/redirect the "coming soon" stubs and the untitled-page slug so the nav and machine-readable index reflect what actually ships.