Skip to content

Commit 19bcea7

Browse files
brunopgalvaobrunopgalvao
committed
Add runtime API calls guide with SDK examples
Add comprehensive guide for calling runtime APIs using PAPI, Polkadot.js, Dedot, Python Substrate Interface, and Subxt. Examples demonstrate AccountNonceApi and Metadata runtime API calls with complete, tested code snippets for each SDK.
1 parent b91301c commit 19bcea7

File tree

12 files changed

+596
-1
lines changed

12 files changed

+596
-1
lines changed

‎.chain-interactions/query-data/runtime-api-calls.md‎

Lines changed: 337 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,337 @@
1-
TODO
1+
---
2+
title: Runtime API Calls
3+
description: Learn how to call runtime APIs on Polkadot Hub using PAPI, Polkadot.js, Dedot, Python Substrate Interface, and Subxt.
4+
categories: Chain Interactions
5+
---
6+
7+
# Runtime API Calls
8+
9+
## Introduction
10+
11+
Polkadot SDK runtime APIs provide direct access to the blockchain's WebAssembly (Wasm) runtime, enabling specialized queries and computations that go beyond simple storage reads. Unlike storage queries that fetch static data, runtime APIs execute logic within the runtime to compute results dynamically.
12+
13+
Common runtime APIs include:
14+
15+
- **AccountNonceApi** - retrieves the current transaction nonce for an account
16+
- **Metadata** - queries available metadata versions and runtime information
17+
- **TransactionPaymentApi** - estimates transaction fees before submission
18+
- **NominationPoolsApi** - retrieves staking pool information and pending rewards
19+
- **StakingApi** - accesses staking-related computations
20+
21+
This guide demonstrates how to call runtime APIs using five popular SDKs:
22+
23+
- **[Polkadot API (PAPI)](/reference/tools/papi/){target=\_blank}** - modern TypeScript library with type-safe APIs
24+
- **[Polkadot.js API](/reference/tools/polkadot-js-api/){target=\_blank}** - comprehensive JavaScript library (maintenance mode)
25+
- **[Dedot](/reference/tools/dedot/){target=\_blank}** - lightweight TypeScript library optimized for performance
26+
- **[Python Substrate Interface](/reference/tools/py-substrate-interface/){target=\_blank}** - Python library for Substrate chains
27+
- **[Subxt](/reference/tools/subxt/){target=\_blank}** - Rust library with compile-time type safety
28+
29+
Select your preferred SDK below to see complete, runnable examples that query Polkadot Hub for account nonces and metadata information.
30+
31+
## Call Runtime APIs
32+
33+
=== "PAPI"
34+
35+
**Prerequisites**
36+
37+
- [Node.js](https://nodejs.org/){target=\_blank} v18 or higher
38+
- npm, pnpm, or yarn package manager
39+
40+
**Environment Setup**
41+
42+
1. Create and initialize a new project:
43+
44+
```bash
45+
mkdir papi-runtime-api-example && cd papi-runtime-api-example && \
46+
npm init -y && npm pkg set type=module
47+
```
48+
49+
2. Install dependencies:
50+
51+
```bash
52+
npm install polkadot-api && \
53+
npm install --save-dev @types/node tsx typescript
54+
```
55+
56+
3. Generate types for Polkadot Hub:
57+
58+
```bash
59+
npx papi add pah -n polkadot_asset_hub
60+
```
61+
62+
**Call Runtime APIs**
63+
64+
The following example demonstrates calling several runtime APIs:
65+
66+
- `AccountNonceApi.account_nonce` - gets the current nonce for an account
67+
- `Metadata.metadata_versions` - retrieves supported metadata versions
68+
69+
Create a file named `runtime-apis.ts` and add the following code:
70+
71+
```typescript title="runtime-apis.ts"
72+
--8<-- "code/chain-interactions/query-data/runtime-api-calls/papi/runtime-apis.ts"
73+
```
74+
75+
Ensure to replace `INSERT_WS_ENDPOINT` with a valid WebSocket endpoint (e.g., `wss://polkadot-asset-hub-rpc.polkadot.io`) and `INSERT_ADDRESS` with the account address you want to query.
76+
77+
Run the script:
78+
79+
```bash
80+
npx tsx runtime-apis.ts
81+
```
82+
83+
You should see output similar to:
84+
85+
--8<-- 'code/chain-interactions/query-data/runtime-api-calls/papi/runtime-apis-ts.html'
86+
87+
=== "Polkadot.js"
88+
89+
!!! warning "Maintenance Mode Only"
90+
The Polkadot.js API is no longer actively developed. New projects should use [PAPI](/reference/tools/papi/){target=\_blank} or [Dedot](/reference/tools/dedot/){target=\_blank} as actively maintained alternatives.
91+
92+
**Prerequisites**
93+
94+
- [Node.js](https://nodejs.org/){target=\_blank} v18 or higher
95+
- npm, pnpm, or yarn package manager
96+
97+
**Environment Setup**
98+
99+
1. Create and initialize a new project:
100+
101+
```bash
102+
mkdir pjs-runtime-api-example && cd pjs-runtime-api-example && \
103+
npm init -y && npm pkg set type=module
104+
```
105+
106+
2. Install dependencies:
107+
108+
```bash
109+
npm install @polkadot/api
110+
```
111+
112+
**Call Runtime APIs**
113+
114+
The following example demonstrates calling several runtime APIs:
115+
116+
- `accountNonceApi.accountNonce` - gets the current nonce for an account
117+
- `metadata.metadataVersions` - retrieves supported metadata versions
118+
119+
Create a file named `runtime-apis.js` and add the following code:
120+
121+
```javascript title="runtime-apis.js"
122+
--8<-- "code/chain-interactions/query-data/runtime-api-calls/pjs/runtime-apis.js"
123+
```
124+
125+
Ensure to replace `INSERT_WS_ENDPOINT` with a valid WebSocket endpoint (e.g., `wss://polkadot-asset-hub-rpc.polkadot.io`) and `INSERT_ADDRESS` with the account address you want to query.
126+
127+
Run the script:
128+
129+
```bash
130+
node runtime-apis.js
131+
```
132+
133+
You should see output similar to:
134+
135+
--8<-- 'code/chain-interactions/query-data/runtime-api-calls/pjs/runtime-apis-js.html'
136+
137+
=== "Dedot"
138+
139+
**Prerequisites**
140+
141+
- [Node.js](https://nodejs.org/){target=\_blank} v18 or higher
142+
- npm, pnpm, or yarn package manager
143+
144+
**Environment Setup**
145+
146+
1. Create and initialize a new project:
147+
148+
```bash
149+
mkdir dedot-runtime-api-example && cd dedot-runtime-api-example && \
150+
npm init -y && npm pkg set type=module
151+
```
152+
153+
2. Install dependencies:
154+
155+
```bash
156+
npm install dedot && \
157+
npm install --save-dev @dedot/chaintypes @types/node tsx typescript
158+
```
159+
160+
**Call Runtime APIs**
161+
162+
The following example demonstrates calling several runtime APIs:
163+
164+
- `accountNonceApi.accountNonce` - gets the current nonce for an account
165+
- `metadata.metadataVersions` - retrieves supported metadata versions
166+
167+
Create a file named `runtime-apis.ts` and add the following code:
168+
169+
```typescript title="runtime-apis.ts"
170+
--8<-- "code/chain-interactions/query-data/runtime-api-calls/dedot/runtime-apis.ts"
171+
```
172+
173+
Ensure to replace `INSERT_WS_ENDPOINT` with a valid WebSocket endpoint (e.g., `wss://polkadot-asset-hub-rpc.polkadot.io`) and `INSERT_ADDRESS` with the account address you want to query.
174+
175+
Run the script:
176+
177+
```bash
178+
npx tsx runtime-apis.ts
179+
```
180+
181+
You should see output similar to:
182+
183+
--8<-- 'code/chain-interactions/query-data/runtime-api-calls/dedot/runtime-apis-ts.html'
184+
185+
=== "Py Substrate Interface"
186+
187+
**Prerequisites**
188+
189+
- [Python](https://www.python.org/){target=\_blank} 3.8 or higher
190+
- pip package manager
191+
192+
**Environment Setup**
193+
194+
1. Create a new project directory and set up a virtual environment:
195+
196+
```bash
197+
mkdir psi-runtime-api-example && cd psi-runtime-api-example && \
198+
python3 -m venv venv && source venv/bin/activate
199+
```
200+
201+
2. Install the substrate-interface package:
202+
203+
```bash
204+
pip install substrate-interface
205+
```
206+
207+
**Call Runtime APIs**
208+
209+
The following example demonstrates calling several runtime APIs:
210+
211+
- `AccountNonceApi.account_nonce` - gets the current nonce for an account
212+
- `Core.version` - retrieves runtime version information
213+
214+
Create a file named `runtime_apis.py` and add the following code:
215+
216+
```python title="runtime_apis.py"
217+
--8<-- "code/chain-interactions/query-data/runtime-api-calls/psi/runtime_apis.py"
218+
```
219+
220+
Ensure to replace `INSERT_WS_ENDPOINT` with a valid WebSocket endpoint (e.g., `wss://polkadot-asset-hub-rpc.polkadot.io`) and `INSERT_ADDRESS` with the account address you want to query.
221+
222+
Run the script:
223+
224+
```bash
225+
python runtime_apis.py
226+
```
227+
228+
You should see output similar to:
229+
230+
--8<-- 'code/chain-interactions/query-data/runtime-api-calls/psi/runtime-apis-py.html'
231+
232+
=== "Subxt"
233+
234+
[Subxt](/reference/tools/subxt/){target=\_blank} is a Rust library that provides compile-time type safety through code generation from chain metadata.
235+
236+
**Prerequisites**
237+
238+
- [Rust](https://rustup.rs/){target=\_blank} toolchain (latest stable)
239+
- Cargo package manager
240+
241+
**Environment Setup**
242+
243+
1. Create a new Rust project:
244+
245+
```bash
246+
cargo new subxt-runtime-api-example && cd subxt-runtime-api-example
247+
```
248+
249+
2. Install the Subxt CLI:
250+
251+
```bash
252+
cargo install subxt-cli@{{ dependencies.crates.subxt_cli.version }}
253+
```
254+
255+
3. Download the Polkadot Hub metadata:
256+
257+
```bash
258+
subxt metadata --url INSERT_WS_ENDPOINT -o asset_hub_metadata.scale
259+
```
260+
261+
Ensure to replace `INSERT_WS_ENDPOINT` with the proper WebSocket endpoint, such as `wss://polkadot-asset-hub-rpc.polkadot.io` for Polkadot Hub.
262+
263+
4. Update `Cargo.toml` with the required dependencies:
264+
265+
```toml title="Cargo.toml"
266+
--8<-- "code/chain-interactions/query-data/runtime-api-calls/subxt/Cargo.toml"
267+
```
268+
269+
**Call Runtime APIs**
270+
271+
The following example demonstrates calling several runtime APIs:
272+
273+
- `AccountNonceApi.account_nonce` - gets the current nonce using the static interface
274+
- `Metadata.metadata_versions` - retrieves supported metadata versions using the dynamic interface
275+
276+
Create a file at `src/bin/runtime_apis.rs` and add the following code:
277+
278+
```rust title="src/bin/runtime_apis.rs"
279+
--8<-- "code/chain-interactions/query-data/runtime-api-calls/subxt/src/bin/runtime_apis.rs"
280+
```
281+
282+
Ensure to replace `INSERT_WS_ENDPOINT` with a valid WebSocket endpoint (e.g., `wss://polkadot-asset-hub-rpc.polkadot.io`) and `INSERT_ADDRESS` with the account address you want to query.
283+
284+
Run the script:
285+
286+
```bash
287+
cargo run --bin runtime_apis
288+
```
289+
290+
You should see output similar to:
291+
292+
--8<-- 'code/chain-interactions/query-data/runtime-api-calls/subxt/runtime-apis-rs.html'
293+
294+
## Available Runtime APIs
295+
296+
The following runtime APIs are commonly available on Polkadot SDK-based chains:
297+
298+
| API | Description |
299+
|-----|-------------|
300+
| `AccountNonceApi` | Get current transaction nonce for an account |
301+
| `TransactionPaymentApi` | Query transaction fees and weight information |
302+
| `TransactionPaymentCallApi` | Estimate fees for a call without creating an extrinsic |
303+
| `Metadata` | Query metadata versions and runtime metadata |
304+
| `BlockBuilder` | Access block building functionality |
305+
| `Core` | Core runtime version and execution |
306+
| `TaggedTransactionQueue` | Validate transactions in the pool |
307+
| `OffchainWorkerApi` | Offchain worker functionality |
308+
| `SessionKeys` | Session key management |
309+
| `GrandpaApi` | GRANDPA finality information |
310+
| `BabeApi` | BABE consensus information |
311+
| `NominationPoolsApi` | Nomination pools data and pending rewards |
312+
| `StakingApi` | Staking-related computations |
313+
314+
!!! note
315+
Available runtime APIs vary by chain. Check your target chain's metadata to see which APIs are exposed.
316+
317+
## Where to Go Next
318+
319+
<div class="grid cards" markdown>
320+
321+
- <span class="badge guide">Guide</span> **Query On-Chain State**
322+
323+
---
324+
325+
Learn how to query storage data from the blockchain.
326+
327+
[:octicons-arrow-right-24: Get Started](/chain-interactions/query-data/query-sdks/)
328+
329+
- <span class="badge guide">Guide</span> **Send Transactions**
330+
331+
---
332+
333+
Learn how to construct and submit transactions.
334+
335+
[:octicons-arrow-right-24: Get Started](/chain-interactions/send-transactions/with-sdks/)
336+
337+
</div>

‎.snippets/code/chain-interactions/query-data/runtime-api-calls/dedot/runtime-apis-ts.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<div class="termynal" data-termynal>
2+
<span data-ty="input"><span class="file-path"></span>npx tsx runtime-apis.ts</span>
3+
<span data-ty="progress"></span>
4+
<span data-ty>Connected to Polkadot Hub</span>
5+
<span data-ty>Querying runtime APIs for: 15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5</span>
6+
<span data-ty></span>
7+
<span data-ty>AccountNonceApi Results:</span>
8+
<span data-ty> Account Nonce: 11</span>
9+
<span data-ty></span>
10+
<span data-ty>Metadata API Results:</span>
11+
<span data-ty> Supported Metadata Versions: [14, 15, 16]</span>
12+
</div>

‎.snippets/code/chain-interactions/query-data/runtime-api-calls/dedot/runtime-apis.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { DedotClient, WsProvider } from 'dedot';
2+
import type { PolkadotAssetHubApi } from '@dedot/chaintypes';
3+
4+
const ASSET_HUB_RPC = 'INSERT_WS_ENDPOINT';
5+
6+
// Example address to query (Polkadot Hub address)
7+
const ADDRESS = 'INSERT_ADDRESS';
8+
9+
async function main() {
10+
// Initialize provider and client with Asset Hub types
11+
const provider = new WsProvider(ASSET_HUB_RPC);
12+
const client = await DedotClient.new<PolkadotAssetHubApi>(provider);
13+
14+
console.log('Connected to Polkadot Hub');
15+
console.log(`Querying runtime APIs for: ${ADDRESS}\n`);
16+
17+
// Call AccountNonceApi to get the account nonce
18+
const nonce = await client.call.accountNonceApi.accountNonce(ADDRESS);
19+
console.log('AccountNonceApi Results:');
20+
console.log(` Account Nonce: ${nonce}`);
21+
22+
// Query metadata versions using Metadata runtime API
23+
const metadataVersions = await client.call.metadata.metadataVersions();
24+
console.log('\nMetadata API Results:');
25+
console.log(` Supported Metadata Versions: [${metadataVersions.join(', ')}]`);
26+
27+
// Disconnect the client
28+
await client.disconnect();
29+
}
30+
31+
main().catch(console.error);

‎.snippets/code/chain-interactions/query-data/runtime-api-calls/papi/runtime-apis-ts.html‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<div class="termynal" data-termynal>
2+
<span data-ty="input"><span class="file-path"></span>npx tsx runtime-apis.ts</span>
3+
<span data-ty="progress"></span>
4+
<span data-ty>Connected to Polkadot Hub</span>
5+
<span data-ty>Querying runtime APIs for: 15oF4uVJwmo4TdGW7VfQxNLavjCXviqxT9S1MgbjMNHr6Sp5</span>
6+
<span data-ty></span>
7+
<span data-ty>AccountNonceApi Results:</span>
8+
<span data-ty> Account Nonce: 11</span>
9+
<span data-ty></span>
10+
<span data-ty>Metadata API Results:</span>
11+
<span data-ty> Supported Metadata Versions: [14, 15, 16]</span>
12+
</div>

0 commit comments

Comments
 (0)