From 85438c5476a486cd3e6b683978a376601c6b63f4 Mon Sep 17 00:00:00 2001 From: Gaurav Agarwal Date: Thu, 27 Aug 2026 15:30:21 +0530 Subject: [PATCH] docs: document the historical add-ons per chain, and what realtime holds The pages a blocked user lands on did not answer the question they were blocked by. archive.md never mentioned that querying it needs anything, and realtime.md claimed a flat "past 8 hours approximately", which contradicts the per-cube retention matrix. The add-on list is taken from the products table rather than written from memory, so it is the real catalogue: - Ethereum, BSC, Base, Arbitrum, Optimism, Polygon, Tron and Robinhood each have Historical Trading Data and Historical Transfers + Balances + Holders. - Solana has Historical OHLCV & Token Price, and Historical Token Transfers & Balances. - Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Dash and Zcash each ship as Chain Data with history included. - Polymarket has Historical Data. Bundles cover all EVM chains, and all six UTXO chains. Cardano, Ripple, Stellar, Algorand, Filecoin, Avalanche, Celo, Cronos and Klaytn have no self-serve add-on at all -- historical access there is Enterprise. That distinction was not written down anywhere. archive.md now also quotes the exact rejection message, since it names the entitlement you are missing and therefore tells you which add-on to buy, and warns that archive is not deployed for every cube on every chain. realtime.md replaces the flat 8 hours with the real shape -- about 12 hours on Solana DEXTrades, 7 days on DEXTradeByTokens, a few days on the EVM cubes, 30 days on Trading -- and states the behaviour that generates most "the data is wrong" reports: realtime does not error past its window, it silently returns fewer rows. paid.md gains the same table, which closes the gap left when its add-on section listed only points, stream-minutes and stream data. Co-Authored-By: Claude Opus 5 --- docs/graphql/dataset/archive.md | 42 ++++++++++++++++++++++++++++++++ docs/graphql/dataset/realtime.md | 21 +++++++++++++++- docs/ide/paid.md | 20 +++++++++++++++ 3 files changed, 82 insertions(+), 1 deletion(-) diff --git a/docs/graphql/dataset/archive.md b/docs/graphql/dataset/archive.md index 12ccfa6f..cd086ce1 100644 --- a/docs/graphql/dataset/archive.md +++ b/docs/graphql/dataset/archive.md @@ -27,6 +27,48 @@ Archive Database features: Also Check [Combined](/docs/graphql/dataset/combined) and [RealTime](/docs/graphql/dataset/realtime) dataset. +## Do I need anything to query the archive dataset? {#access} + +Yes. Self-serve plans query `realtime` by default. To run a query with +`dataset: archive` or `dataset: combined` you add a **historical data add-on** +for the chain you want, from **Account → Billing**. Without it the query is +rejected with: + +``` +access restricted: your plan only allows "realtime", +but the request uses "archive:eth:Transactions" +``` + +That message names exactly what you asked for, so it also tells you which +add-on to buy. + +### Chains with a self-serve historical add-on + +| Chain | Add-ons available | +| --- | --- | +| Ethereum, BNB Chain (BSC), Base, Arbitrum, Optimism, Polygon, Tron, Robinhood | Historical Trading Data · Historical Transfers + Balances + Holders | +| Solana | Historical OHLCV & Token Price · Historical Token Transfers & Balances | +| Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Dash, Zcash | Chain Data (historical included) | +| Polymarket | Historical Data | + +Bundles cover all EVM chains at once, and all six UTXO chains at once. Current +prices are on the [pricing page](https://bitquery.io/pricing). + +### Chains that are Enterprise only + +Cardano, Ripple, Stellar, Algorand, Filecoin, Avalanche, Celo, Cronos and +Klaytn have **no self-serve historical add-on**. Historical access to those is +part of an Enterprise plan — [contact sales](https://bitquery.io/forms/api). + +:::caution Archive is not deployed for every cube on every chain +Even with the add-on, some cube and chain combinations have no archive table. +Those return a ClickHouse error such as +`no table can query ... consider use realtime dataset`. That is not a +problem with your query. Check the +[Data Coverage & Retention matrix](/docs/graphql/data-coverage-retention/) +for what exists where. +::: + ## Does Bitquery have data for all historical blocks since genesis? {#does-bitquery-have-data-for-all-historical-blocks-since-genesis} With the exception of Solana, Bitquery provides complete historical data (from genesis onward) for all supported blockchains. For Solana, full historical token transfers are available via the V1 API, while in V2, Bitquery offers price aggregates starting from 2024. diff --git a/docs/graphql/dataset/realtime.md b/docs/graphql/dataset/realtime.md index 92e28b05..ee5fcc92 100644 --- a/docs/graphql/dataset/realtime.md +++ b/docs/graphql/dataset/realtime.md @@ -6,7 +6,26 @@ description: "Realtime Database in Bitquery GraphQL with clear syntax, examples, # Realtime Database Realtime is the default database (if you omit the attribute, then it is used). -The `realtime` database contains data from the past 8 hours approximately, but with a limitation. When querying `realtime` data using the Streaming APIs, you will only receive data that is not in the `archive` dataset. For example, if the latest block in the archive is 2 hours old, you will only receive data that is more recent than this block. + +**How much data `realtime` holds depends on the cube, not on one fixed number.** +It is roughly 12 hours on Solana `DEXTrades`, about 7 days on Solana +`DEXTradeByTokens`, a few days on the EVM transfer and DEX cubes, and about 30 +days on the `Trading` cubes. The +[Data Coverage & Retention matrix](/docs/graphql/data-coverage-retention/) is the +source of truth per chain and per cube. + +There is also a limitation on the streaming side: when querying `realtime` you +only receive data that is not already in the `archive` dataset. If the latest +block in the archive is 2 hours old, you only receive data more recent than that +block. + +:::caution Realtime does not error when you ask for more than it holds +Querying a date range wider than the retention window returns **fewer rows, not +an error** — a chart simply starts late. If a result looks short, check the +retention matrix before assuming the data is missing, and switch to +[`archive`](/docs/graphql/dataset/archive/) or +[`combined`](/docs/graphql/dataset/combined/) for history. +::: The main cases when it is used is for: diff --git a/docs/ide/paid.md b/docs/ide/paid.md index 3aa6e8ce..72c86825 100644 --- a/docs/ide/paid.md +++ b/docs/ide/paid.md @@ -48,6 +48,26 @@ Step 2 of the checkout is **Top Up Credits** — optional. Add-ons are billed to | **100k Stream-minutes** | +100,000 streaming minutes | | **1 GB Stream Data** | +1 GB of stream traffic | +### Historical data add-ons + +Self-serve plans query the `realtime` dataset. To run `dataset: archive` or +`dataset: combined`, add the historical add-on for the chain you need: + +| Chain | Add-ons | +| --- | --- | +| Ethereum, BNB Chain (BSC), Base, Arbitrum, Optimism, Polygon, Tron, Robinhood | **Historical Trading Data** · **Historical Transfers + Balances + Holders** | +| Solana | **Historical OHLCV & Token Price** · **Historical Token Transfers & Balances** | +| Bitcoin, Bitcoin Cash, Litecoin, Dogecoin, Dash, Zcash | **Chain Data (historical included)** | +| Polymarket | **Historical Data** | + +Bundles cover every EVM chain in one purchase, and all six UTXO chains in +another. Prices are shown at checkout and on the +[pricing page](https://bitquery.io/pricing). + +Cardano, Ripple, Stellar, Algorand, Filecoin, Avalanche, Celo, Cronos and +Klaytn have no self-serve historical add-on — historical access to those is +part of Enterprise. + You can add multiple units of each add-on using the quantity selector. Prices per unit are shown in the checkout and on the [pricing page](https://bitquery.io/pricing). ## Additional Points