SEO remediation (Ahrefs 2026-07-30): site-wide Open Graph + ranking recovery

[buddies2705]

Remediation of the 2026-07-30 Ahrefs Site Audit of docs.bitquery.io.

Two phases in one branch — reviewable as two independent commits:

Commit	Scope
4985eac4	Phase 1 — config + mechanical. Clears both Errors and ~578 Warnings.
e1039686	Phase 2 — ranking recovery on the 9 pages that lost positions.

Correcting the export's headline numbers first

The CSVs are UTF-16/TSV with newlines inside multi-value cells, so wc -l overstates record counts ~9×. "5,157 Open Graph issues" is 573; "3,604 IndexNow" is 572. Real totals collapse to three root causes, only one of which is in this repo.

Phase 1 — config + mechanical

• og:type + og:site_name in headTags. Docusaurus emits og:title/description/image/url/locale and neither of these, so all 573 indexable pages failed Open Graph validation. One config change. Verified: 1019 built pages carry both; the 245 without are client-redirect stubs, which correctly have no OG block.
• Sitemap contained a redirect. createSitemapItems hardcoded /crypto-reward-tax-calculator/ with a trailing slash; that path is a separate Next.js app whose normalization 308s to the unslashed form.
• Two http:// internal links → https. The v1 link on Pump-Fun-API alone tripped 4 separate reports. Both support.bitquery.io links on how-to-filter-anomaly-prices (two occurrences, not one).
• alt text on 4 images, written from the actual screenshots.
• Polymarket generated-index retitled. This index — not its child page — is what ranks (position 2 for polymarket api, 863 organic). Google was discarding "Polymarket Implementation Guide" and substituting the child page's title verbatim. Description was 95 chars.

Phase 2 — ranking recovery

All 9 pages verified technically clean first (200, self-canonical, no noindex), so these are content and internal-linking problems, not indexation. Every documented query was run against the live API before being written.

Defects found by reading the pages, absent from the Ahrefs export

• solana_dexscreener shipped unparseable JSON — ""So111… (doubled quote) and an unterminated "pair_address key. Copy-paste failed outright.
• matic-dextrades promised what it never delivered — the callout routed readers there for history "with dataset: combined or archive" while dataset appeared nowhere else in the file.
• The TRC20 flagship query fails server-side — upstream: tron: backend … context deadline exceeded after 3 minutes, under a heading claiming to answer the most-asked USDT question on Tron.
• Six dead example tokens across two pages — AVAX ($10k/30d), IXT ($427/30d), BILLY (12 trades/30d), AUTISM (9), Pnut (1).
• Stale hardcoded query variables (2024-08-15, 2024-11-06, 2024-11-13) — copy-pasting requested a ~20-month window. Now since_relative.
• Pumpfun cannibalization — Pump-Fun-API had no keywords at all while the hub claimed "Best PumpFun API", and pump-fun-to-pump-swap, the page hoarding four terms it shouldn't own, was the only page in the cluster that ranked.

Two items where my own analysis was wrong

• four-meme-api has no payload problem. It ships 42 KB gzipped; the 728 KB I flagged was uncompressed DOM, and peers are larger (solana-dextrades 892 KB). Ahrefs' "Size (bytes) 42372" was already the compressed figure.
• pancake-swap-api inlinks were understated — 6 in-repo references, not 3. No action taken rather than adding decorative links.

Also documented

• MATIC→POL rebrand: wrapped native now reports WPOL, Tether as USDT0 — filter by contract, not symbol.
• Fungible: true on Polygon rankings, or Polymarket ERC-1155 outcome tokens dominate with empty symbols.
• UpdateCount as a wallet classifier: 1.2M updates in ~10 days (exchange hot wallet) vs 5 on a wallet holding 87.5M USDT (cold storage).
• Memecoin pools decay within hours — one candidate went 34,325 trades/2h → 28 trades/1h while being tested — and aggregators (Jupiter, dflow, Aquifer) expose no MarketAddress.
• Balances preferred over BalanceUpdates throughout.

Verification

• yarn build passes; build output confirmed to reflect the changes (not a cache hit)
• scripts/check-links.mjs: no link errors (532 pages, 1294 routes, strict)
• 151/151 internal /docs links in changed files resolve
• 17 JSON blocks parse (one deliberate reader placeholder excepted)

Deliberately not in this PR

• V1 docs site (409 pages). Every /v1/** page emits canonical → /v1/, plus one shared 108-char title and one shared description across all 409, and double-fired GA4. Separate deployment — needs a handoff to that repo. Our robots.txt should not declare /v1/sitemap.xml until that canonical is fixed.
• crypto-reward-tax-calculator — no OG, no X card, zero outlinks. Separate Next.js app.
• 5 "Slow page" warnings (crawl artifact — Ahrefs logged 13–19 s TTFB; live is 0.58–0.61 s), 572 IndexNow rows (upsell), 91 "changed" notices (prior audit work landing), 6 AI-content flags (Ahrefs' classifier; 5 of 6 have zero traffic).
• twitter:site — omitted rather than guess a live social handle.

Open items

• Holders aggregate stats (sum/median/gini/nakamoto) returned total: 0 and median: 0 on a token whose top holder has 18M. Left out of the docs; worth an API-team look.
• Templated descriptions down 145 → 138. The rest is Phase 3.
• BalanceUpdates still appears in ~70 docs files.

🤖 Generated with Claude Code