docs: steer single-token prices to Pairs cube with rank-1 filter - #247
Merged
Conversation
The Tokens cube reports a volume-weighted blend of every pool where a token is base. For tokens with fragmented liquidity, thin pools contribute to that blend and pull the reported price away from the market where the token actually trades. Add a canonical "Getting the Most Accurate Token Price (Rank 1)" section to the Pairs cube page covering the query, the streaming variant, a multi-token watchlist, how to read Ranking.Weight, and the caveats (top market can flip mid-stream; rank filters still need a token filter or time bound). Point the price-index algorithm page, Tokens/Currencies cube pages, introduction, OHLC guide, examples, limit-order page, and the trading data overview at it. Tokens stays documented as the right cube for chain-wide streams, cross-pool volume, and supply/market-cap fields. All added queries and the subscription verified live against streaming.bitquery.io. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The two TradingView guides chart one specific token and the indicators guide computes SMA/EMA/WSMA, all via the Tokens cube, whose price blends every pool where the token is base. Add a steer to Pairs with Ranking.Position = 1 in each, noting that the same Price.Ohlc and Price.Average fields are available there (verified live) and that the top market can change mid-stream. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Live checking turned up a real trap: every market publishes its rows
twice, once priced in USD and once in quote-token units. The rank
filter selects the market, not the denomination, so the snippets as
first written could return e.g. WBTC priced in SOL rather than USD.
Add Price: { IsQuotedInUsd: true } to all four rank-1 snippets, replace
the incorrect claim that values always come back in USD with a warning
explaining the two row variants, and add the gotcha to the caveat list.
Re-verified: all queries and the subscription return IsQuotedInUsd:true
rows. Docusaurus build passes (onBrokenLinks: throw) and check-links
reports no errors.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Wire the three saved queries into the four insertion points: latest price and watchlist on the Pairs page, the stream on the Pairs page, and the lead example on the Examples page (which reuses the latest-price query). Build passes and check-links reports no errors. Co-Authored-By: Claude Fable 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.
Problem
The docs teach
Trading.Tokensas the default way to get a token's price. That price is a volume-weighted blend of every pool where the token is base. For tokens with fragmented liquidity — one primary pool plus a tail of thin ones — the thin pools contribute to the blend and pull the reported price away from the market where the token actually trades. Users hit this and conclude our prices are wrong.Change
Recommend
Trading.PairswithRanking: { Position: { eq: 1 } }for the price of a specific token — the quote from the pool currently carrying the most volume for it.Stance is steer, not deprecate.
Tokensstays documented as the right cube for chain-wide firehose streams, cross-pool volume totals, and currency-levelSupply/MarketCap. The framing is blend vs. top market, consistent with the Price Index Algorithm page rather than contradicting it.New canonical section: Getting the Most Accurate Token Price (Rank 1) on the Pairs cube page (
#most-accurate-token-price) — query, streaming variant, multi-token watchlist, how to readRanking.Weight, and caveats. Eleven other pages link to it instead of re-explaining.12 files: Pairs (canonical section) · Tokens, Currencies, introduction, price-index-algorithm, examples, OHLC guide, limit-order, trading-data-overview · both TradingView guides + trading-indicators.
Gotcha this uncovered
Live checking caught a trap worth reviewing carefully: every market publishes each row twice, once priced in USD and once in quote-token units. The rank filter selects the market, not the denomination — so a rank-1 query without
Price: { IsQuotedInUsd: true }can return e.g. WBTC priced in SOL. All snippets carry the filter and the page warns about it explicitly (3rd commit).Also documented: the rank-1 market flips as volume moves (observed BONK switching between an amm_v3/USDC pool and a whirlpool/WSOL pool within minutes), so stream consumers must key on
Market.Addressper message.Verification
streaming.bitquery.ioand returned data; the subscription validated verbatim over WebSocket (graphql-transport-ws).Price.Average(SMA/EMA/WSMA) confirmed populated on rank-1 rows, so the indicators guide can honestly point there.onBrokenLinks: "throw");check-linksreports no errors.Deliberately not touched
crypto-marketcap-api.md— supply and market cap are currency-level fields, unaffected by the pool blend.crypto-trades-api/*andmcp/trading/*— these useTrading.Trades, no Tokens-cube price queries.Follow-ups
solana-dextrades,bsc-dextrades,robinhood-trades, per-chain marketcap) still show Tokens-price examples. They now have a stable link target.🤖 Generated with Claude Code