Skip to content

docs(request-units): document full vs archive billing for Polkadot #445

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CSFeo wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs(request-units): document full vs archive billing for Polkadot #445

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
151914f
docs(request-units): document full vs archive billing for Polkadot
CSFeo Jun 22, 2026
d8acba7
docs(request-units): clarify Polkadot Sidecar ?at= reads are full, no…
CSFeo Jun 22, 2026
6656031
docs(request-units): revert the Polkadot ?at= clarification
CSFeo Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion docs/request-units.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ For each protocol, here's what counts as a **full request (1 RU)** and what coun
| TON | Most requests are **full**. `getTransactions` and `getTransactionsStd` are always **archive**; block/seqno methods are **archive** when the requested seqno is more than 128 behind the tip. See [TON method scope](#ton-method-scope) below. |
| Aptos | Most requests are **full**. `/v1/accounts/{address}/transactions` is always **archive**; block-height methods are **archive** when the requested height is more than 128 behind the tip, and ledger-version methods when the requested version is more than 256 behind. See [Aptos method scope](#aptos-method-scope) below. |
| Starknet | Most requests are **full**. Trace methods are always **2 RUs**; block-scoped methods are **archive** when the requested block is more than 128 behind the tip. See [Starknet method scope](#starknet-method-scope) below. |
| Bitcoin, Sui, Polkadot, TRON, opBNB, Harmony | No archive split — every request is billed as full |
| Polkadot | Most requests are **full**. Sidecar trace endpoints are always **2 RUs**; `chain_getBlockHash` and block-scoped Sidecar endpoints are **archive** when the requested block is more than 128 behind the tip. See [Polkadot method scope](#polkadot-method-scope) below. |
| Bitcoin, Sui, TRON, opBNB, Harmony | No archive split — every request is billed as full |

## Always 2 RUs

Expand Down Expand Up @@ -205,6 +206,31 @@ Starknet requests are billed as full (1 RU) by default. Three cases are billed a

All other Starknet methods are billed as full (1 RU) regardless of the block they target.

## Polkadot method scope

Polkadot is served over two transports — the Substrate node JSON-RPC and the [Sidecar](https://github.com/paritytech/substrate-api-sidecar) REST API. Both are billed as full (1 RU) by default. Three cases are billed at 2 RUs.

**Always 2 RUs** — these Sidecar trace endpoints are billed at the trace rate (2 RUs) regardless of block age, the same as the EVM `debug_*`/`trace_*` rule:

- `/experimental/blocks/head/traces`
- `/experimental/blocks/{number}/traces`
- `/experimental/blocks/{number}/traces/operations`
- `/experimental/blocks/head/traces/operations`

**Archive when targeting a historical block (JSON-RPC)** — billed as archive (2 RUs) when the requested block is more than 128 behind the chain tip, and full (1 RU) otherwise (recent block, or no block parameter):

- `chain_getBlockHash`

**Archive when targeting a historical block (Sidecar REST)** — these endpoints take a block number in the path and are billed as archive (2 RUs) when that block is more than 128 behind the chain tip, and full (1 RU) otherwise (recent block, or a `head` path):

- `/blocks/{number}`
- `/blocks/{number}/header`
- `/blocks/{blockId}/extrinsics/{extrinsicIndex}`
- `/blocks/{blockId}/extrinsics-raw`
- `/blocks/{blockId}/para-inclusions`

All other Polkadot methods and Sidecar endpoints — including requests that target the chain head or omit a block parameter — are billed as full (1 RU).

## HTTP requests vs WebSocket subscriptions

A "request" is anything the node returns to you over the wire. The transport changes how those individual returns are counted.
Expand Down