docs: lead with the Trading cube, and add a one-page API reference for AI assistants - #251
Merged
Merged
Conversation
Trading cube first. The docs already say Trading.Pairs / Tokens / Currencies
are the primary source for real-time and the last ~30 days, with DEXTrades and
DEXTradeByTokens for history beyond that -- but the panel did the opposite:
225 of 367 trade and price entries led with a DEX cube, and on Ethereum, Base,
Arbitrum, BSC and TRON a DEX-cube query was the first thing under Price & OHLC.
Trading-cube entries now sort first, 92 DEX-cube entries are relabelled
"historical (beyond 30 days)", and 195 tooltips say which side they are on.
Pairs + rank 1. Zero of the 31 shipped Pairs queries used
`Ranking: {Position: {eq: 1}}`, so we shipped none of the pattern the docs
recommend for pricing one token -- the Tokens price is volume-blended across
every pool. Added the three documented rank-1 queries and authored one per
chain for Ethereum, Base, BSC, Arbitrum, Optimism and Solana, each now the
first entry in its Price & OHLC section.
Two traps found while authoring these, both now in the query comments:
Trading.Token.Address is stored lowercase and the filter is case-sensitive, so
a checksummed address returns zero rows and no error; and picking the example
token by "top volume" surfaced obscure tokens and, on Solana, a homoglyph spoof
of SOL -- the examples are canonical addresses instead.
Balances. Balance is the question every chain gets asked, current and
historical. 16 chains were missing one or both; authored and verified 11 new
queries (current balance on Base, Arbitrum, Optimism, Polygon; balance at a
past date on Bitcoin, Dogecoin, Litecoin, Bitcoin Cash, Dash, Zcash, Celo),
taking the gap from 16 chains to 7.
Group order now leads with Bitcoin, Solana, Robinhood, Polymarket, Perpetuals,
TRON, Cross-Chain, Ethereum, BSC. Perpetuals is split by venue -- Hyperliquid
and Phoenix -- since that is how people browse it.
663 query entries across 28 groups, 383 stream entries across 17. All audit
gates pass and the site builds with no warnings.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
New page: docs/start/bitquery-for-ai.md, "Bitquery in One Page". We already publish llms.txt (a curated index of links) and llms-full.txt (the whole corpus, 5 MB). Neither answers "give an AI one thing and let it write correct queries": the index makes it fetch twenty pages, and the corpus is too big and mostly navigation. This page is self-contained instead -- no links to follow, every query written out in full. Covers the endpoints and auth for V2 HTTP, V2 WebSocket and V1; exactly which chains are on V2 (eth, bsc, base, arbitrum, optimism, matic, robinhood, plus Solana, Tron and Hyperliquid) versus V1-only; the cube list per root, taken from schema introspection; datasets and retention; and nine worked queries. Section 6 is the part that matters most for a model, because these are the mistakes that yield a plausible wrong answer rather than an error: - Trading cube token addresses are stored lowercase and the filter is case-sensitive, so a checksummed address returns zero rows and no error. - Balances are cumulative, so a realtime balance is a few hours of delta. - A bare EVM root means Ethereum. - V1 list queries without a date bound die on ClickHouse Code 241. - realtime does not error past its retention window, it just returns less. - Price one token with Pairs + rank 1, not with Tokens. All nine example queries were executed against the live API before publishing. Placed third in the Start sidebar and linked first in llms.txt, so the raw markdown twin at /docs/start/bitquery-for-ai/index.md is the thing to paste into a model. Also splits Perpetuals cleanly by venue: two "Solana perps" queries were sitting in an "Other venues" bucket, but Phoenix is the only Solana perp DEX we index, so they are Phoenix queries that never say the word. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Auditing the page I had just written turned up a claim I got wrong. It said "V1 has no subscriptions". Introspecting the V1 schema shows a subscription root does exist -- ethereum(network: EthereumNetwork) -- so the blanket statement is false. What is actually true, and now what the page says: there is no documented V1 WebSocket endpoint, so V2 is the answer for anything live, and the chains outside the V1 EVM family (Bitcoin and relatives, Cardano, Ripple, Stellar, Algorand) genuinely have no GraphQL stream. Adds two facts a model needs and cannot infer: - Ethereum, BSC, Tron and Polygon are migrating off V1, so they should always be queried on V2 even though the V1 schema still accepts them. - Root capitalisation carries the version. V1 roots are lowercase -- ethereum(, tron(, solana(, bitcoin( -- and V2 roots are capitalised -- EVM(, Tron(, Solana(, Trading. A lowercase root means a V1 document. That last one is not cosmetic: an audit script of mine matched roots case-insensitively and reported 20 false V1 violations on Tron, all of which were ordinary V2 Tron( queries. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This was referenced Aug 27, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Follow-on to #250. The Trading-cube commit missed that merge by minutes — #250 merged at 06:29:55Z and
6ff5aa87was pushed after, so it is on the old branch but not inmain. It is cherry-picked here as the first commit.1. Lead with the Trading cube (cherry-picked, was not in #250)
The docs already say
Trading.Pairs/Tokens/Currenciesare the primary source for real time and the last ~30 days, withDEXTradesandDEXTradeByTokensfor history beyond that. The panel did the opposite:Pairsqueries usedRanking: {Position: {eq: 1}}— none of the pattern the docs recommend for pricing one token, since theTokensprice is volume-blended across every pool.Now: Trading entries sort first, 92 DEX entries are relabelled
— historical (beyond 30 days), 195 tooltips say which side they are on, and rank-1 price queries lead Price & OHLC on Ethereum, Base, BSC, Arbitrum, Optimism and Solana.Two traps found while authoring those, now written into the query comments:
Tradingtoken addresses are stored lowercase and the filter is case-sensitive. A checksummed EVM address returns zero rows and no error. WETH, WBNB and Arbitrum WETH all silently returned nothing until lowercased.SoJh2C73…, Cyrillic О). The examples use canonical addresses.Balances: 16 chains lacked a current or historical balance query. Authored and verified 11 — gap down to 7.
Ordering: groups now lead with Bitcoin, Solana, Robinhood, Polymarket, Perpetuals, TRON, Cross-Chain, Ethereum, BSC. Perpetuals is split by venue.
2. New page — Bitquery in One Page
docs/start/bitquery-for-ai.md. We publishllms.txt(an index of links) andllms-full.txt(5 MB, the whole corpus). Neither lets you hand an AI one thing and get correct queries out. This page is self-contained: no links to follow, every query written out.Endpoints and auth for V2 HTTP / V2 WebSocket / V1 · exactly which chains are on V2 versus V1-only · the cube list per root from schema introspection · datasets and retention · nine worked queries · an error table.
Section 6 is the important part for a model — the mistakes that produce a plausible wrong answer instead of an error: lowercase address filters, balances being cumulative, bare
EVMmeaning Ethereum, unbounded V1 queries hittingCode: 241,realtimesilently truncating rather than erroring, andPairs+ rank 1 overTokens.All nine example queries were executed against the live API before publishing.
Third in the Start sidebar, first link in
llms.txt. The artefact to paste into a model is the raw twin at/docs/start/bitquery-for-ai/index.md.Verification
BalanceUpdatesAll 65 queries authored across this work were re-executed read back out of the database, not from the pre-insert test: 59 run, 6 retired (Bitcoin SV, index stopped 2026-02-02), 0 failing.
Known gaps
balancesargument, Algorand selections, Cardano 500) or a representative address (Robinhood, Avalanche).🤖 Generated with Claude Code