Skip to main content

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​

HTTPS Endpoint​

https://api-polkadot.n.dwellir.com/{YOUR_API_KEY}

WebSocket Endpoint​

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

Authentication​

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

API Categories​

Polkadot's RPC API is organized into the following method categories:

Core APIs​

Author Methods​

Submit and manage extrinsics (transactions) on the network.

Chain Methods​

Query blockchain data including blocks, headers, and finalized state.

State Methods​

Access runtime storage, metadata, and proof generation.

System Methods​

Node information, health checks, and network properties.

Specialized APIs​

BEEFY Methods​

Bridge Efficiency Enabling Finality Yielder protocol operations.

Grandpa Methods​

GRANDPA finality gadget operations and proofs.

Child State Methods​

Manage child storage tries for contracts and parachains.

Sync State Methods​

Monitor and manage node synchronization state.

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}")

Subscribe to New Blocks (WebSocket)​

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​

CodeMessageDescription
-32700Parse errorInvalid JSON
-32600Invalid requestMissing required fields
-32601Method not foundUnknown RPC method
-32602Invalid paramsInvalid method parameters
-32603Internal errorNode processing error
-32000Server errorCustom 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:

Method Categories​

Select a category below to explore detailed method documentation: