Polkadot RPC Documentation

Complete JSON-RPC API documentation for Polkadot blockchain integration. Learn how to interact with Polkadot nodes using WebSocket and HTTPS endpoints.

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)

Parameter	Value	Details
Chain ID	Polkadot
Native Token	DOT
Consensus	Nominated Proof-of-Stake (NPoS)

Connection Endpoints

Polkadot RPC Endpoints

HTTPS

WSS

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

import { ApiPromise, WsProvider } from '@polkadot/api';const provider = new WsProvider('wss://api-polkadot.n.dwellir.com/<API_Keys_Are_Not_Made_for_Bots>');const api = await ApiPromise.create({ provider });const hash = await api.rpc.chain.getBlockHash(0);console.log(hash.toHex());

from substrateinterface import SubstrateInterfacesubstrate = SubstrateInterface(url='wss://api-polkadot.n.dwellir.com/<API_Keys_Are_Not_Made_for_Bots>')block_hash = substrate.get_block_hash(block_id=0)print(block_hash)

package mainimport (  "bytes"  "fmt"  "io"  "net/http")func main() {  url := "https://api-polkadot.n.dwellir.com/<API_Keys_Are_Not_Made_for_Bots>"  payload := []byte(`{"jsonrpc":"2.0","id":1,"method":"chain_getBlockHash","params":[0]}`)  resp, err := http.Post(url, "application/json",    bytes.NewBuffer(payload))  if err != nil { panic(err) }  defer resp.Body.Close()  body, _ := io.ReadAll(resp.Body)  fmt.Println(string(body))}

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

Python

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

JavaScript

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:

JSON

{
  "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

JavaScript

// 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: