Merge branch 'main' of https://github.com/bitquery/streaming-data-platform-docs

Author: Kshitij0O7

docs/trading/crypto-price-api/crypto-ohlc-candle-k-line-api.md

@@ -20,11 +20,12 @@ Get real-time and historical OHLC (Open, High, Low, Close) candle data, K-line c
 | How do I get OHLCV data for a token using Bitquery? | **Last 7 Days** [Crypto Price API](/docs/trading/crypto-price-api/introduction/) ; **historical:** [DEXTradeByTokens OHLC](/docs/cubes/dextradesbyTokens/#how-do-i-get-ohlc-in-a-dextradebytokens-query) |
 | How do I get OHLC in a DEXTradeByTokens query? | [DEXTradeByTokens OHLC](/docs/cubes/dextradesbyTokens/#how-do-i-get-ohlc-in-a-dextradebytokens-query) (for **historical** OHLC or DEX-level control) |
 | How do I get historical OHLCV for a Solana token? | **Main OHLC:** [Crypto Price API — Quick start](/docs/trading/crypto-price-api/introduction/#quick-start) · [Tokens cube](/docs/trading/crypto-price-api/tokens/) · **Historical / DEX:** [Historical OHLCV on Solana](/docs/blockchain/Solana/solana-dextrades/#how-do-i-get-historical-ohlcv-for-a-solana-token) · [Solana OHLC API](/docs/blockchain/Solana/solana-dextrades/#solana-ohlc-api) |
-| How do I get the current price of a token using Bitquery API? | [Quick start](/docs/trading/crypto-price-api/introduction/#quick-start) · [Tokens cube](/docs/trading/crypto-price-api/tokens/) · [Examples](/docs/trading/crypto-price-api/examples/) |
+| How do I get the current price of a token using Bitquery API? | **Recommended:** [Pairs + rank 1 (top market)](/docs/trading/crypto-price-api/pairs#most-accurate-token-price) · [Quick start](/docs/trading/crypto-price-api/introduction/#quick-start) · [Examples](/docs/trading/crypto-price-api/examples/) |
+| Which cube gives the most accurate price for one token? | [Pairs with `Ranking: { Position: { eq: 1 } }`](/docs/trading/crypto-price-api/pairs#most-accurate-token-price) — prices from the token's top market rather than a blend across all its pools |
 | How do I get price change percentage for a token? | [Price change](/docs/start/starter-queries/#volume-of-multiple-tokens-across-different-chains) |
 | How do I get 1-minute OHLC candles for a DEX pair? | **Main:** [Your first OHLC query](#your-first-ohlc-query) (`Duration: { eq: 60 }`) · [Pairs cube](/docs/trading/crypto-price-api/pairs/) · **Historical:** [DEX OHLC pattern](/docs/cubes/dextradesbyTokens/#how-do-i-get-ohlc-in-a-dextradebytokens-query) |
 | How do I get the all-time high (ATH) price of a token? | [Solana ATH example](/docs/blockchain/Solana/solana-dextrades/#get-ath-market-cap-of-tokens)|
-| Is there an API to get token price in USD on Solana? | [Crypto Price API — Quick start](/docs/trading/crypto-price-api/introduction/#quick-start) · [Tokens cube](/docs/trading/crypto-price-api/tokens/) · [Latest USD (Solana DEX trades)](/docs/blockchain/Solana/solana-dextrades/#latest-usd-price-of-a-token) |
+| Is there an API to get token price in USD on Solana? | [Pairs + rank 1 (top market)](/docs/trading/crypto-price-api/pairs#most-accurate-token-price) · [Crypto Price API — Quick start](/docs/trading/crypto-price-api/introduction/#quick-start) · [Latest USD (Solana DEX trades)](/docs/blockchain/Solana/solana-dextrades/#latest-usd-price-of-a-token) |
 | How do I use DEXTradeByTokens vs DEXTrades for OHLCV? | [OHLCV: which cube?](/docs/cubes/dextradesbyTokens/#how-do-i-use-dextradebytokens-vs-dextrades-for-ohlcv) · [DEXTrades cube](/docs/cubes/dextrades/) |
 
 ## What is OHLC Data?
@@ -202,23 +203,26 @@ Use the **Currency** cube when you want a unified price view of an asset across
 
 [Learn more about Currency Cube ➤](/docs/trading/crypto-price-api/currency/)
 
-### **Tokens Cube** - Chain-Specific Token Data
+### **Tokens Cube** - Chain-Wide Blended Candles
 
-Use the **Tokens** cube when you need OHLC data for a specific token on a specific blockchain.
+Use the **Tokens** cube when you want one candle per token per chain, or a stream of candles for every token on a chain.
 
 **Key Features:**
 - Aggregates across all pairs for that token
 - Can provide both chain specific and chain agnostic prices
 - Can provide only USD-quoted prices
 - Can combine volume and price data from all chains
 
+> Because the candle blends every pool where the token is base, thin pools contribute to it as well. For candles on **one specific token**, prefer the Pairs cube with rank 1 (below).
+
 [Learn more about Tokens Cube ➤](/docs/trading/crypto-price-api/tokens/)
 
-### **Pairs Cube** - Trading Pair Specific Data
+### **Pairs Cube** - Top Market and Pair-Specific Candles
 
-Use the **Pairs** cube when you need OHLC data for specific trading pairs on specific DEXs.
+Use the **Pairs** cube for OHLC on a specific market — and, with the rank filter, for the most accurate candles on a specific **token**.
 
 **Key Features:**
+- **Recommended for a single token:** add `Ranking: { Position: { eq: 1 } }` to get candles from the token's top market instead of a blend across all pools ([how and why](/docs/trading/crypto-price-api/pairs#most-accurate-token-price))
 - Pair-specific OHLC data (e.g., ETH/USDC on Uniswap)
 - Can be quoted in USD or quote token
 - Market/DEX-specific data

docs/trading/crypto-price-api/currency.md

@@ -6,6 +6,10 @@ description: "Query currency-level crypto prices and conversions with Bitquery T
 
 The Currency Cube provides a unified, chain-agnostic price for an asset in USD, such as Bitcoin by aggregating prices and volumes from all its representations (e.g., WBTC, cbBTC, and other bridged or wrapped forms) across all supported chains. This multi-chain cryptocurrency price data approach ensures consistent pricing across different blockchain implementations.
 
+:::note Use this for cross-chain assets, not for a single token
+Currency prices aggregate **across chains and token representations**, so use this cube when you want one global number for an asset like BTC or ETH. For the price of a **specific token on a specific market**, use the [Pairs cube with `Ranking: { Position: { eq: 1 } }`](/docs/trading/crypto-price-api/pairs#most-accurate-token-price). Note that `Ranking` is **not** available on `Currencies` — it exists on `Trades`, `Pairs`, and `Tokens` only.
+:::
+
 ### How OHLC is Calculated
 
 The OHLC values (Open, High, Low, Close) are determined across all chains and token representations of an asset for the selected interval (e.g., 60 seconds):

docs/trading/crypto-price-api/examples.md

@@ -4,6 +4,72 @@ description: "Quick Start Examples via Bitquery Trading APIs for multi-chain pri
 ---
 # Quick Start Examples
 
+## Most Accurate Price for a Token (Top Market, Rank 1) {#most-accurate-price-for-a-token}
+
+The recommended way to price a **specific token**: query the `Pairs` cube with `Ranking: { Position: { eq: 1 } }` to get the price from the token's **top market** — the pool currently carrying the most volume for it — instead of a value blended across every pool it trades in. Thin, fragmented pools therefore cannot pull the number away from the market where the token actually trades.
+
+Full explanation, streaming variant, and caveats: [Getting the Most Accurate Token Price](/docs/trading/crypto-price-api/pairs#most-accurate-token-price).
+
+[Run query ➤](https://ide.bitquery.io/Token-price-from-top-market--rank-1_2)
+
+```graphql
+{
+  Trading {
+    Pairs(
+      where: {
+        Token: {
+          Address: { is: "DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263" }
+          Network: { is: "Solana" }
+        }
+        Ranking: { Position: { eq: 1 } }
+        Interval: { Time: { Duration: { eq: 60 } } }
+        Price: { IsQuotedInUsd: true }
+      }
+      limit: { count: 1 }
+      orderBy: { descending: Block_Time }
+    ) {
+      Token {
+        Symbol
+        Address
+      }
+      QuoteToken {
+        Symbol
+      }
+      Market {
+        Protocol
+        Address
+        Network
+      }
+      Price {
+        IsQuotedInUsd
+        Ohlc {
+          Open
+          High
+          Low
+          Close
+        }
+      }
+      Ranking {
+        Position
+        Weight
+      }
+      Volume {
+        Usd
+      }
+      Block {
+        Time
+      }
+    }
+  }
+}
+```
+
+`Price.Ohlc.Close` is the latest price on the top market. Keep `Price: { IsQuotedInUsd: true }` in the filter — every market also publishes rows priced in **quote token units**, so without it a WBTC/WSOL market would return the price of WBTC in SOL rather than in dollars.
+
+`Ranking.Weight` tells you how concentrated the token's liquidity is: near 1 means a single pool drives the price; a low value means it is fragmented across many pools — the case where this query differs most from the blended `Tokens` price.
+
+Change `query` to `subscription` and drop `limit`/`orderBy` to stream it live.
+
 ## Real-Time Token Prices in USD on Solana
 
 Stream live OHLC (Open, High, Low, Close) price and volume data for all tokens on Solana, quoted directly in USD. Useful for dashboards, analytics, or bots that need stable fiat-based prices.
@@ -216,6 +282,8 @@ subscription {
 
 Get a snapshot of tokens with aggregated USD volume and average price over the last 24 hours. The query uses `limitBy: { count: 1, by: Token_Id }` to return one row per token, and conditional metrics (`Volume.Usd(if: ...)`, `Price.Average.Mean(..., if: ...)`) to show volume and price for the last 1h, 4h, and 24h. Useful for dashboards, top-movers lists, or comparing short-term vs daily metrics.
 
+> The `Tokens` cube is the right choice here: volume is summed across all of a token's pools. Note that its prices are blended across those pools too — to price one specific token from its top market instead, use [Pairs with rank 1](/docs/trading/crypto-price-api/pairs#most-accurate-token-price).
+
 [Run query ➤](https://ide.bitquery.io/aggregated-data-for-tokens)
 
 ```graphql
@@ -559,6 +627,8 @@ query {
 
 Fetch the top 10 tokens by 5-minute percentage price change (USD-based), only including tokens with at least $100k trading volume. Ideal for building a "top movers" list.
 
+> Scanning every token on a chain is exactly what the `Tokens` cube is for. Once you have picked a token out of the list, price it from its top market with [Pairs + rank 1](/docs/trading/crypto-price-api/pairs#most-accurate-token-price).
+
 Here we have selected the filter `Price: {IsQuotedInUsd: true}`, this means that any price values such as OHLC or Average indicators will be in USD. If you want them in quote currency, change the filter to `Price: {IsQuotedInUsd: false}`.
 
 This stream uses [expressions](/docs/graphql/capabilities/expression/)
@@ -641,6 +711,8 @@ This stream uses [expressions](/docs/graphql/capabilities/expression/)
 
 Stream the top 10 tokens on Solana by 5-minute price change (in USD), filtered by $100k+ volume. Updates continuously.
 
+> As above, this is a chain-wide scan. For a watchlist of specific tokens, stream their top markets instead — see [Watchlist: top-market price for several tokens](/docs/trading/crypto-price-api/pairs#most-accurate-token-price).
+
 Here we have selected the filter `Price: {IsQuotedInUsd: true}`, this means that any price values such as OHLC or Average indicators will be in USD. If you want them in quote currency, change the filter to `Price: {IsQuotedInUsd: false}`.
 
 This stream uses [expressions](/docs/graphql/capabilities/expression/)
@@ -723,6 +795,8 @@ Calculate the percentage drawdown (price decline) for tokens of a specific curre
 
 This query uses [expressions](/docs/graphql/capabilities/expression/) to calculate drawdown as: `((Close - Open) / Open) * 100`.
 
+> This compares a currency's token representations against each other, so `Tokens` fits. To measure one token's drawdown on the market where it actually trades, run the same expression against [Pairs with rank 1](/docs/trading/crypto-price-api/pairs#most-accurate-token-price).
+
 > **Note:** You can use `Token: {Address: {is: "token_address"}}` filter instead of `Currency: {Id: {is: "bid:bitcoin"}}` to filter by token address. We include `Volume: { Usd: { gt: 10 } }` to filter out tokens with very low trading volume.
 
 [Run query](https://ide.bitquery.io/Drawdown-of-a-token-last-hour)

docs/trading/crypto-price-api/introduction.mdx

@@ -97,6 +97,10 @@ Use the same **`bid:<chain>`** convention as **`Token.Id`**.
 
 ## Quick Start {#quick-start}
 
+:::tip Pricing one specific token? Start with Pairs + rank 1
+The stream below is a **firehose** of every token on every chain, and the `Tokens` cube is the right choice for it. If instead you want the price of **one token**, query the [**Pairs** cube with `Ranking: { Position: { eq: 1 } }`](/docs/trading/crypto-price-api/pairs#most-accurate-token-price) — it returns the price from the token's **top market** rather than a blend across all of its pools, which matters for tokens with fragmented liquidity.
+:::
+
 [Run Stream >](https://ide.bitquery.io/1-second-crypto-price-stream)
 
 > Note: A `Volume: {Usd: {gt: 5}}` filter is applied to remove extreme outliers; the price stream already pre-filters outliers—this is an additional check.
@@ -247,9 +251,9 @@ Each message contains:
 
 The Price APIs have three core data cubes:
 
-- **Tokens**: Price data for a specific token on a specific chain. Use this when you care about chain-specific prices like USDT on Solana.
+- **Tokens**: One blended price per token per chain, aggregated across every pool the token trades in. Use it for chain-wide streams and per-chain aggregates.
 - **Currencies**: An aggregated view of tokens that represent the same underlying asset. For example, tokens like cbBTC, WBTC, and other Bitcoin-wrapped tokens are all grouped under the Bitcoin currency.
-- **Pairs**: Price and volume data for token pairs on specific markets/protocols. E.g., SOL/USDC on Raydium (Solana) or ETH/USDT on Uniswap (Ethereum).
+- **Pairs**: Price and volume data for token pairs on specific markets/protocols. E.g., SOL/USDC on Raydium (Solana) or ETH/USDT on Uniswap (Ethereum). **This is also the recommended cube for a specific token's price** — filter to its top market with [`Ranking: { Position: { eq: 1 } }`](/docs/trading/crypto-price-api/pairs#most-accurate-token-price).
 
 > Note: Expressions are supported in this API.
 
@@ -326,6 +330,8 @@ It takes amounts and prices from all chains that use BTC and wrapped versions (i
 
 Let's say you don't want a chain agnostic view, but want to focus on a particular chain. How to stream or query prices for it? This is where tokens come in.
 
+> **Note:** the price below is blended across **all pools** where the token is base. For a single token, the [rank-1 Pairs query](/docs/trading/crypto-price-api/pairs#most-accurate-token-price) prices it from its top market instead — recommended whenever you care about one specific token.
+
 > Note: We include `Volume: {Usd: {gt: 5}}` to further remove extreme outliers; the stream already pre-filters outliers—this is an additional check.
 
 ```graphql
@@ -469,6 +475,8 @@ subscription {
 This is the 3rd cube in these set of APIs. The Pairs cube gives you price, volume, and market-level trading data between two tokens — a base token and a quote token.
 We will breakdown in detail how base token and Quote are chosen in the next section.
 
+> **Recommended for single-token prices:** add `Ranking: { Position: { eq: 1 } }` to a Pairs query to get a token's price from its **top market** — the pool carrying the most volume for it. See [Getting the Most Accurate Token Price](/docs/trading/crypto-price-api/pairs#most-accurate-token-price).
+
 > **Tip**: Use `TokenId` instead of `Token.Address` to fetch all variants of the same token (e.g., ETH, WETH, bridged ETH) across multiple chains.
 
 > Note: We include `Volume: {Usd: {gt: 5}}` to further remove extreme outliers; the stream already pre-filters outliers—this is an additional check.
@@ -565,25 +573,32 @@ Use `TargetVolume` to get price intervals aggregated over a volume threshold:
 
 ## When to Choose Which Cube (Token, Currency, Pair)?
 
+:::tip The short answer
+For the price of a **specific token**, use **`Pairs` with `Ranking: { Position: { eq: 1 } }`** — see [Getting the Most Accurate Token Price](/docs/trading/crypto-price-api/pairs#most-accurate-token-price). Use `Tokens` for chain-wide streams and per-chain aggregates, and `Currencies` for one cross-chain number per asset.
+:::
+
+### Use the **`Pairs`** cube when:
+
+- You want the **price of a specific token** — filter to its top market with `Ranking: { Position: { eq: 1 } }` so thin pools do not affect the number ([how and why](/docs/trading/crypto-price-api/pairs#most-accurate-token-price)).
+- You want **pair-level trading data** (e.g., SOL/USDC, ETH/DAI).
+- You’re analyzing trading activity **on a specific market or DEX** (e.g., Uniswap, PancakeSwap, Raydium).
+- You need **OHLC, volume, liquidity**, and market-specific pricing between two tokens.
+- You're exploring **price arbitrage** or spreads across chains or platforms.
+
 ### Use the **`Tokens`** cube when:
 
-- You want token price data **on a specific blockchain**.
-- You're interested in metrics like OHLC, volume, and moving averages **for one network** (e.g., USDC on Solana or ETH on Arbitrum).
-- You want to stream or query **chain-specific** price movements.
+- You want a **firehose** of price updates for every token on a chain.
+- You want **one chain-wide number per token**, blended across all of its pools, rather than the price on a single market.
+- You're interested in **aggregate volume across all of a token's pools**, or the currency-level `Supply` and `MarketCap` fields.
+
+  > For a **single token's price**, prefer `Pairs` with rank 1: the `Tokens` price is a volume-weighted blend of every pool, so thin pools can pull it away from the primary market. See [Tokens cube](/docs/trading/crypto-price-api/tokens).
 
 ### Use the **`Currencies`** cube when:
 
 - You want a **chain-agnostic view** of a token (e.g., BTC across Bitcoin, Ethereum (WBTC), Solana, etc.).
 - You need a **global price** for a currency, combining its various representations.
 - You're looking for **aggregated OHLC and average prices** for a token across chains.
 
-### Use the **`Pairs`** cube when:
-
-- You want **pair-level trading data** (e.g., SOL/USDC, ETH/DAI).
-- You’re analyzing trading activity **on a specific market or DEX** (e.g., Uniswap, PancakeSwap, Raydium).
-- You need **OHLC, volume, liquidity**, and market-specific pricing between two tokens.
-- You're exploring **price arbitrage** or spreads across chains or platforms.
-
 ## Crypto Price API for TradingView
 
 With the new Price API, you can simply feed the stream to your custom datafeed object in the TradingView code and have it update charts in real-time.
@@ -603,6 +618,10 @@ import VideoPlayer from "../../../src/components/videoplayer.js";
       q: "How do I get real-time crypto prices and OHLC candles?",
       a: "Use Trading.Tokens, Trading.Pairs, or Trading.Currencies for aggregated USD prices and OHLC over the last ~30 days. For older history, build candles from DEXTradeByTokens on the chain you need.",
     },
+    {
+      q: "Which cube gives the most accurate price for a specific token?",
+      a: "Trading.Pairs filtered with Ranking: { Position: { eq: 1 } }. That returns the price on the token's top market — the pool contributing the most volume — instead of the Tokens cube's blend across every pool, which thin pools can pull off the primary market's price. See Getting the Most Accurate Token Price on the Pairs cube page.",
+    },
     {
       q: "What is the difference between Crypto Price API and Crypto Trades API?",
       a: "Crypto Price API gives aggregated price feeds and OHLC by token or pair. Crypto Trades API returns individual swap rows with USD price, market cap, and supply on every trade.",