docs: Address Labels API (Metadata.Labels cube) - #236
Merged
Conversation
The Labels API shipped without docs. This adds a page for the Metadata.Labels
cube covering the two contract rules — Address is a mandatory filter, and
in: accepts up to 100 addresses — plus the behaviours that bite you in
practice.
Every fact and all 8 GraphQL examples were verified live against
streaming.bitquery.io before landing:
- Address accepts only is/in (no negation); omitting it returns
"Labels query requires a Address filter in the where clause"
- matching is case-sensitive, so checksummed EVM addresses return zero rows
- records are append-only, so an address repeats per chain and per recording
pass; the recommended default query folds that with
limitBy: {by: [Address, Chain, Label_Type], count: 1}
- the cube is absent from the subscription root, so labels cannot be
streamed — poll RecordedAt instead
- chain slugs (ethereum, bsc, polygon, arbitrum, base, avalanche-c, fantom,
ethpow, bitcoin, tron, solana) and the label-type taxonomy were each
confirmed against a known address
SEO: URL and H1 target "address labels API"; title renders at exactly 60
chars so the brand suffix survives the title trimmer; description is unique
at 158 chars; sections are question-shaped for AEO, and an 8-item FAQ adds
FAQPage JSON-LD, which the July audit flagged as under-used. Balances cube
gains an inbound link.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
buddies2705
pushed a commit
that referenced
this pull request
Aug 7, 2026
It landed in #236 as one item under "Understanding Cubes", next to the EVM and Solana cube pages. Labels are a distinct product surface, not a cube variant, and the section needs room to grow. Moves the page into docs/labels/ and adds a top-level sidebar category following the Stablecoin APIs pattern (generated-index over its own folder), positioned with the other API product sections between Stablecoin APIs and MCP. The page carries sidebar_label "Overview" so the nav reads "Address Labels API > Overview" rather than repeating the full page title. The URL becomes /docs/labels/address-labels-api, still carrying the target keyword. #236 already shipped and deployed the cubes URL, which is live and serving, so this adds a client redirect from /docs/cubes/address-labels-api/ rather than leaving it to 404. Title, description, canonical, and the FAQPage/TechArticle/BreadcrumbList JSON-LD were re-verified in the production build at the new URL, the generated redirect page was confirmed to point at it, and the inbound link from the Balances cube was repointed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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.
Documents the newly released Labels API, which shipped without docs.
New page:
docs/cubes/address-labels-api.md→/docs/cubes/address-labels-apiWhat it covers
The two contract rules —
Addressis a mandatory filter andin:takes up to 100 addresses — plus the behaviours that actually bite users:Addressaccepts onlyis/in; there is no negation, and omitting it returns"Labels query requires a Address filter in the where clause"limitBy: {by: [Address, Chain, Label_Type], count: 1}RecordedAtinsteadVerification
Every fact and all 8 GraphQL examples were executed live against
streaming.bitquery.iobefore landing — all 8 return non-empty data. Site builds clean.SEO
| Bitquery Docssuffix survives the title trimmerThe 100-address batch size is stated as a firm limit throughout (6 places, no hedging) so readers size their batches correctly.
Data quirks worth a look (labels team)
The ETH USDT contract carries a
cex-hot-wallet: bitfinexlabel, and the Tron USDT contract carriescex-deposit-address: coinex-deposit. Both were kept out of examples that claim clean output.The only
token-cloneexample I could verify was Polygon's canonical WMATIC contract, which looks like a mislabel — so the page documents the type in the reference table but deliberately builds no "detect fake tokens" walkthrough around it.🤖 Generated with Claude Code