docs: document the historical add-ons per chain, and what realtime actually holds

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 <Cube> ... 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.

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:
 

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