Polkadot RPC API Documentation

Overview#

Polkadot is a next-generation blockchain protocol that connects multiple specialized blockchains into one unified network. Built on the Substrate framework, Polkadot enables cross-chain transfers of any type of data or asset, not just tokens.

This documentation provides comprehensive coverage of Polkadot's JSON-RPC API methods, enabling developers to interact with Polkadot nodes for building applications, wallets, explorers, and other blockchain tools.

Network Information#

Mainnet (Polkadot)#

Chain ID: Polkadot
Native Token: DOT
Consensus: Nominated Proof-of-Stake (NPoS)

Connection Endpoints#

🔗 RPC Endpoints

PolkadotChain ID: N/A

Mainnet

WSS

wss://api-polkadot.n.dwellir.com/YOUR_API_KEY

✓ Archive Node✓ Trace API✓ Debug API✓ WebSocket

Quick Connect:

curl -X POST https://api-polkadot.n.dwellir.com/YOUR_API_KEY \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"chain_getBlock","params":[],"id":1}'

Authentication#

Authentication is done via the URL path. Replace {YOUR_API_KEY} with your actual API key obtained from dwellir.com.

Substrate JSON‑RPC API Reference#

Browse the core Substrate method groups supported by Polkadot, including system_*, chain_*, state_*, author_*, payment_*, and rpc_methods. Polkadot also exposes grandpa_* and beefy_* where applicable.

Available JSON-RPC Methods

System & Runtime

Identify the chain, runtime versions, and node health.

Chain Data & Finality

Inspect blocks, headers, and finality streams.

State Access & Storage

Query storage, metadata, and runtime entry points.

Authoring & Sessions

Submit extrinsics and manage session keys.

RPC Introspection

Discover supported RPC namespaces and versions.

Get your API key

Get your API key →

Quick Start Examples#

Get Latest Block#

const response = await fetch('https://api-polkadot.n.dwellir.com/YOUR_API_KEY', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'chain_getBlock',
    params: [],
    id: 1
  })
});

const data = await response.json();
console.log('Latest block:', data.result);

Submit Transaction#

import requests
import json

url = "https://api-polkadot.n.dwellir.com/YOUR_API_KEY"
headers = {
    "Content-Type": "application/json"
}

# Properly formatted and signed extrinsic
extrinsic = "0x..." 

payload = {
    "jsonrpc": "2.0",
    "method": "author_submitExtrinsic",
    "params": [extrinsic],
    "id": 1
}

response = requests.post(url, headers=headers, data=json.dumps(payload))
tx_hash = response.json()["result"]
print(f"Transaction hash: {tx_hash}")

const WebSocket = require('ws');

const ws = new WebSocket('wss://api-polkadot.n.dwellir.com/YOUR_API_KEY');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    method: 'chain_subscribeNewHeads',
    params: [],
    id: 1
  }));
});

ws.on('message', (data) => {
  const response = JSON.parse(data);
  if (response.params?.result) {
    console.log('New block:', response.params.result);
  }
});

Error Handling#

Polkadot RPC errors follow the JSON-RPC 2.0 error format:

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": "Expected hex-encoded hash"
  },
  "id": 1
}

Common Error Codes#

Code	Message	Description
-32700	Parse error	Invalid JSON
-32600	Invalid request	Missing required fields
-32601	Method not found	Unknown RPC method
-32602	Invalid params	Invalid method parameters
-32603	Internal error	Node processing error
-32000	Server error	Custom server errors

Best Practices#

1. Connection Management#

Use WebSocket connections for subscriptions and real-time updates
Implement reconnection logic for WebSocket disconnections
Use HTTPS for single queries and transactions

2. Error Handling#

Always check for error responses before processing results
Implement retry logic with exponential backoff
Log errors for debugging and monitoring

3. Performance Optimization#

Batch multiple queries when possible
Cache frequently accessed data like metadata
Use specific block hashes for deterministic queries

4. Security#

Never expose API keys in client-side code
Validate all input data before submission
Use secure storage for private keys

SDK Support#

Official Libraries#

@polkadot/api - JavaScript/TypeScript SDK
py-substrate-interface - Python SDK
subxt - Rust SDK
go-substrate-rpc-client - Go SDK

Integration Example#

// Using @polkadot/api
const { ApiPromise, WsProvider } = require('@polkadot/api');

async function connect() {
  const provider = new WsProvider('wss://api-polkadot.n.dwellir.com/YOUR_API_KEY');
  
  const api = await ApiPromise.create({ provider });
  
  // Query chain data
  const chain = await api.rpc.system.chain();
  console.log(`Connected to ${chain}`);
  
  return api;
}

Additional Resources#

Support#

For additional support or questions:

Email: support@dwellir.com
Documentation: dwellir.com/docs

Method Categories#

Select a category below to explore detailed method documentation: