Skip to content

Commit 581cb4f

Browse files
brunopgalvaobrunopgalvao
committed
add query with rest api
1 parent ff2c42b commit 581cb4f

File tree

6 files changed

+367
-1
lines changed

6 files changed

+367
-1
lines changed

‎.chain-interactions/query-data/query-rest.md‎

Lines changed: 255 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,255 @@
1-
TODO
1+
---
2+
title: Query On-Chain State with Sidecar REST API
3+
description: Learn how to query on-chain storage data using the Substrate API Sidecar REST API service.
4+
categories: Chain Interactions
5+
---
6+
7+
# Query On-Chain State with Sidecar REST API
8+
9+
## Introduction
10+
11+
[Substrate API Sidecar](https://github.com/paritytech/substrate-api-sidecar){target=\_blank} is a REST service that makes it easy to interact with Polkadot SDK-based blockchains. It provides a simple HTTP interface to query account balances, asset information, block data, and other on-chain state without requiring WebSocket connections or SDK integrations.
12+
13+
This guide demonstrates how to query on-chain storage using the Sidecar REST API with `curl` commands. You'll learn to retrieve account balances, asset metadata, and block information from Polkadot Hub.
14+
15+
## Prerequisites
16+
17+
- [curl](https://curl.se/){target=\_blank} or any HTTP client
18+
- Access to a Sidecar instance (public or self-hosted)
19+
20+
## Public Sidecar Endpoints
21+
22+
Parity provides public Sidecar instances for Polkadot ecosystem chains:
23+
24+
| Chain | Endpoint |
25+
|-------|----------|
26+
| Polkadot | `https://polkadot-public-sidecar.parity-chains.parity.io` |
27+
| Kusama | `https://kusama-public-sidecar.parity-chains.parity.io` |
28+
| Polkadot Hub | `https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io` |
29+
| Kusama Asset Hub | `https://kusama-asset-hub-public-sidecar.parity-chains.parity.io` |
30+
31+
For production applications, consider running your own Sidecar instance. See [Running Sidecar Locally](#running-sidecar-locally) for instructions.
32+
33+
## Query Account Balance
34+
35+
The `/accounts/{accountId}/balance-info` endpoint returns an account's native token balance, including free, reserved, and frozen amounts.
36+
37+
### Request
38+
39+
```bash
40+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/accounts/14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3/balance-info"
41+
```
42+
43+
### Response
44+
45+
```json
46+
--8<-- "code/chain-interactions/query-data/query-rest/balance-info-response.json"
47+
```
48+
49+
### Response Fields
50+
51+
| Field | Description |
52+
|-------|-------------|
53+
| `at.hash` | Block hash at which the query was executed |
54+
| `at.height` | Block number at which the query was executed |
55+
| `nonce` | Number of transactions sent from this account |
56+
| `tokenSymbol` | Native token symbol of the chain |
57+
| `free` | Balance available for transfers (in planck) |
58+
| `reserved` | Balance locked for on-chain activities |
59+
| `frozen` | Balance frozen and unavailable for transfers |
60+
| `transferable` | Actual balance available to transfer |
61+
| `locks` | Array of balance locks with their reasons |
62+
63+
### Query at a Specific Block
64+
65+
You can query the balance at a specific block height or hash using the `at` query parameter:
66+
67+
```bash
68+
# Query at block height
69+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/accounts/14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3/balance-info?at=10000000"
70+
71+
# Query at block hash
72+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/accounts/14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3/balance-info?at=0x..."
73+
```
74+
75+
## Query Asset Balances
76+
77+
The `/accounts/{accountId}/asset-balances` endpoint returns an account's balances for assets managed by the Assets pallet.
78+
79+
### Request All Asset Balances
80+
81+
```bash
82+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/accounts/14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3/asset-balances"
83+
```
84+
85+
### Request Specific Asset Balance
86+
87+
To query a specific asset (e.g., USDT with asset ID 1984):
88+
89+
```bash
90+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/accounts/14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3/asset-balances?assets[]=1984"
91+
```
92+
93+
### Response
94+
95+
```json
96+
--8<-- "code/chain-interactions/query-data/query-rest/asset-balances-response.json"
97+
```
98+
99+
### Response Fields
100+
101+
| Field | Description |
102+
|-------|-------------|
103+
| `assetId` | Unique identifier for the asset |
104+
| `balance` | Account's balance of this asset (in smallest unit) |
105+
| `isFrozen` | Whether the account's asset balance is frozen |
106+
| `isSufficient` | Whether this account's existence is being paid for by this asset balance (per-account flag, not the asset's global sufficiency setting) |
107+
108+
!!! note
109+
The `isSufficient` field in the asset balance response is a per-account flag. To check if an asset is configured as a sufficient asset (can pay for account existence), query the [Asset Details](#query-asset-details) endpoint and check the `isSufficient` field there.
110+
111+
### Query Multiple Assets
112+
113+
You can query multiple assets in a single request:
114+
115+
```bash
116+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/accounts/14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3/asset-balances?assets[]=1984&assets[]=1337"
117+
```
118+
119+
## Query Asset Metadata
120+
121+
Use the pallet storage endpoint to query asset metadata like name, symbol, and decimals.
122+
123+
### Request
124+
125+
```bash
126+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/pallets/assets/storage/Metadata?keys[]=1984"
127+
```
128+
129+
### Response
130+
131+
```json
132+
--8<-- "code/chain-interactions/query-data/query-rest/asset-metadata-response.json"
133+
```
134+
135+
The `name` and `symbol` fields are returned as hex-encoded strings. To decode them:
136+
137+
- `0x54657468657220555344` decodes to "Tether USD"
138+
- `0x55534474` decodes to "USDt"
139+
140+
## Query Asset Details
141+
142+
Query the asset configuration including owner, supply, and account count:
143+
144+
### Request
145+
146+
```bash
147+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/pallets/assets/storage/Asset?keys[]=1984"
148+
```
149+
150+
### Response
151+
152+
```json
153+
--8<-- "code/chain-interactions/query-data/query-rest/asset-details-response.json"
154+
```
155+
156+
### Response Fields
157+
158+
| Field | Description |
159+
|-------|-------------|
160+
| `owner` | Account that owns the asset |
161+
| `issuer` | Account authorized to mint new tokens |
162+
| `admin` | Account with administrative privileges |
163+
| `freezer` | Account that can freeze balances |
164+
| `supply` | Total supply of the asset (in smallest unit) |
165+
| `minBalance` | Minimum balance required to hold this asset |
166+
| `isSufficient` | Whether this asset can pay for account existence (accounts holding only this asset don't need native tokens) |
167+
| `accounts` | Number of accounts holding this asset |
168+
| `sufficients` | Number of accounts whose existence is paid for by this asset |
169+
| `status` | Asset status (Live, Frozen, or Destroying) |
170+
171+
## Query Block Information
172+
173+
The `/blocks/{blockId}` endpoint returns detailed block information including extrinsics and events.
174+
175+
### Request Latest Block
176+
177+
```bash
178+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/blocks/head"
179+
```
180+
181+
### Request Specific Block
182+
183+
```bash
184+
# By block number
185+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/blocks/10000000"
186+
187+
# By block hash
188+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/blocks/0x..."
189+
```
190+
191+
### Response
192+
193+
```json
194+
--8<-- "code/chain-interactions/query-data/query-rest/block-response.json"
195+
```
196+
197+
## Query Foreign Asset Balances
198+
199+
For cross-chain assets (foreign assets), use the `/accounts/{accountId}/foreign-asset-balances` endpoint:
200+
201+
```bash
202+
curl -s "https://polkadot-asset-hub-public-sidecar.parity-chains.parity.io/accounts/14E5nqKAp3oAJcmzgZhUD2RcptBeUBScxKHgJKU4HPNcKVf3/foreign-asset-balances"
203+
```
204+
205+
## Running Sidecar Locally
206+
207+
For production applications or high-frequency queries, run your own Sidecar instance.
208+
209+
### Using npm
210+
211+
```bash
212+
# Install globally
213+
npm install -g @substrate/api-sidecar
214+
215+
# Run with default settings (connects to ws://127.0.0.1:9944)
216+
substrate-api-sidecar
217+
218+
# Run with custom node URL
219+
SAS_SUBSTRATE_URL=wss://polkadot-asset-hub-rpc.polkadot.io substrate-api-sidecar
220+
```
221+
222+
### Using Docker
223+
224+
```bash
225+
docker run --rm -p 8080:8080 \
226+
-e SAS_SUBSTRATE_URL=wss://polkadot-asset-hub-rpc.polkadot.io \
227+
parity/substrate-api-sidecar
228+
```
229+
230+
Once running, access your local instance at `http://localhost:8080`.
231+
232+
## API Reference
233+
234+
For a complete list of endpoints and parameters, see the [Sidecar API Documentation](https://paritytech.github.io/substrate-api-sidecar/docsv2/){target=\_blank}.
235+
236+
Common endpoints include:
237+
238+
| Endpoint | Description |
239+
|----------|-------------|
240+
| `/accounts/{accountId}/balance-info` | Native token balance |
241+
| `/accounts/{accountId}/asset-balances` | Assets pallet balances |
242+
| `/accounts/{accountId}/foreign-asset-balances` | Foreign assets balances |
243+
| `/accounts/{accountId}/pool-asset-balances` | Pool asset balances |
244+
| `/blocks/{blockId}` | Block information |
245+
| `/blocks/head` | Latest block |
246+
| `/pallets/{palletId}/storage/{storageItemId}` | Pallet storage queries |
247+
| `/transaction/material` | Transaction construction material |
248+
249+
## Where to Go Next
250+
251+
Now that you understand how to query on-chain state with the REST API, explore these related topics:
252+
253+
- **[Query with SDKs](/chain-interactions/query-data/query-sdks/)** - Use TypeScript, Python, or Rust SDKs for programmatic access
254+
- **[Runtime API Calls](/chain-interactions/query-data/runtime-api-calls/)** - Execute runtime APIs for specialized queries
255+
- **[Send Transactions](/chain-interactions/send-transactions/with-sdks/)** - Learn to construct and submit transactions

‎.snippets/code/chain-interactions/query-data/query-rest/asset-balances-response.json‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
{
2+
"at": {
3+
"hash": "0x826f74ae5f6fea33383075156231de5ca8e0ddb308b3f799c9bd64463ed8cb5b",
4+
"height": "10646570"
5+
},
6+
"assets": [
7+
{
8+
"assetId": "1984",
9+
"balance": "1000000",
10+
"isFrozen": false,
11+
"isSufficient": false
12+
}
13+
]
14+
}

‎.snippets/code/chain-interactions/query-data/query-rest/asset-details-response.json‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
{
2+
"at": {
3+
"hash": "0xaf0628855a206da5e95e564b58b9a0bfc490cc8de047a0521252b631be77fac7",
4+
"height": "10646571"
5+
},
6+
"pallet": "assets",
7+
"palletIndex": "50",
8+
"storageItem": "asset",
9+
"keys": ["1984"],
10+
"value": {
11+
"owner": "15uPcYeUE2XaMiMJuR6W7QGW2LsLdKXX7F3PxKG8gcizPh3X",
12+
"issuer": "15uPcYeUE2XaMiMJuR6W7QGW2LsLdKXX7F3PxKG8gcizPh3X",
13+
"admin": "15uPcYeUE2XaMiMJuR6W7QGW2LsLdKXX7F3PxKG8gcizPh3X",
14+
"freezer": "15uPcYeUE2XaMiMJuR6W7QGW2LsLdKXX7F3PxKG8gcizPh3X",
15+
"supply": "77998622834557",
16+
"deposit": "1000000000000",
17+
"minBalance": "10000",
18+
"isSufficient": true,
19+
"accounts": "13572",
20+
"sufficients": "13465",
21+
"approvals": "18",
22+
"status": "Live"
23+
}
24+
}

‎.snippets/code/chain-interactions/query-data/query-rest/asset-metadata-response.json‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
{
2+
"at": {
3+
"hash": "0xaf0628855a206da5e95e564b58b9a0bfc490cc8de047a0521252b631be77fac7",
4+
"height": "10646571"
5+
},
6+
"pallet": "assets",
7+
"palletIndex": "50",
8+
"storageItem": "metadata",
9+
"keys": ["1984"],
10+
"value": {
11+
"deposit": "2008200000",
12+
"name": "0x54657468657220555344",
13+
"symbol": "0x55534474",
14+
"decimals": "6",
15+
"isFrozen": false
16+
}
17+
}

‎.snippets/code/chain-interactions/query-data/query-rest/balance-info-response.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"at": {
3+
"hash": "0xb909e50be96fc0f939588c4a7730670f9ee53c67d95d516198530e5cfe189d6c",
4+
"height": "10646569"
5+
},
6+
"nonce": "0",
7+
"tokenSymbol": "DOT",
8+
"free": "10000000000",
9+
"reserved": "0",
10+
"frozen": "0",
11+
"transferable": "10000000000",
12+
"locks": []
13+
}

‎.snippets/code/chain-interactions/query-data/query-rest/block-response.json‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
{
2+
"number": "10646572",
3+
"hash": "0x5abb54c72ffe3c342536f6e34a8558445ef23a460ae8a6fb366af6d9105c3950",
4+
"parentHash": "0xaf0628855a206da5e95e564b58b9a0bfc490cc8de047a0521252b631be77fac7",
5+
"stateRoot": "0x0be63683f15de9dff2d1553d4904ec3f446b244cfbf7aa69afa1b2faee824688",
6+
"extrinsicsRoot": "0xb4f58daf2791928cebcd1cdee3c51487127824dc0ba4e9b4b9b4be6af6c09b79",
7+
"authorId": "12owmS8Sobqxfx6KK9vk9e67FqnGpZdmxCFCRFptzZdsoujC",
8+
"logs": [
9+
{
10+
"type": "PreRuntime",
11+
"index": "6",
12+
"value": ["0x61757261", "0x35fdc30800000000"]
13+
}
14+
],
15+
"onInitialize": {
16+
"events": []
17+
},
18+
"extrinsics": [
19+
{
20+
"method": {
21+
"pallet": "timestamp",
22+
"method": "set"
23+
},
24+
"signature": null,
25+
"nonce": null,
26+
"args": {
27+
"now": "1733237652000"
28+
},
29+
"tip": null,
30+
"hash": "0x...",
31+
"info": {},
32+
"era": {
33+
"immortalEra": "0x00"
34+
},
35+
"events": [],
36+
"success": true,
37+
"paysFee": false
38+
}
39+
],
40+
"onFinalize": {
41+
"events": []
42+
},
43+
"finalized": true
44+
}

0 commit comments

Comments
 (0)