# Polkadot RPC Documentation

## Polkadot RPC plans and rate limits

- **Free plan:** 20 responses per second, up to 100,000 responses a day.
- **Plans:** $49/mo, $299/mo, $999/mo with 25M, 150M, and 500M included responses. Overages billed at $5/$3/$2 per million responses respectively.
- **Paid rate limits:** 100 to 5,000 responses per second (bursts from 500 to 10,000), no daily limit.
- **Billing:** 1 response = 1 API credit on every shared plan, over HTTPS or WebSocket (WSS) where Polkadot supports it.

Details: [Pricing](https://www.dwellir.com/docs/getting-started/pricing) · [Rate limits](https://www.dwellir.com/docs/getting-started/rate-limits) · [Authentication](https://www.dwellir.com/docs/getting-started/authentication) · [Archive nodes](https://www.dwellir.com/docs/getting-started/archive-nodes)

## 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

## Authentication

Authentication is done via the URL path. Replace `{YOUR_API_KEY}` with your actual API key obtained from [dwellir.com](https://www.dwellir.com).

## 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.

## Quick Start Examples

### Get Latest Block

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

### Subscribe to New Blocks (WebSocket)

```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

- [Polkadot Wiki](https://wiki.polkadot.network/)
- [Substrate Documentation](https://docs.substrate.io/)
- [Polkadot JS Apps](https://polkadot.js.org/apps/)
- [Network Explorer](https://polkadot.subscan.io/)
- [Run your own Polkadot node with the Dwellir-maintained snap](https://www.dwellir.com/blog/polkadot-snap-package)

## Support

For additional support or questions:

- Email: <support@dwellir.com>
- Documentation: [dwellir.com/docs](https://www.dwellir.com/docs)

***

## Method Categories

Select a category below to explore detailed method documentation:
