# Kusama RPC with Dwellir

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

## Why Build on Kusama?

Kusama is Polkadot’s canary network, offering the same Substrate architecture with faster governance and real economic conditions. It is the proving ground for runtime features before they ship to Polkadot, making it ideal for teams that need production-grade infrastructure with rapid iteration cycles.

### **Fast Iteration with Economic Finality**

- Governance cycles finalize upgrades in **7 days**, letting you ship runtime changes weeks before Polkadot equivalents.
- Real staking economics and on-chain treasury make Kusama suitable for live user pilots and incentivized testing.
- Shared validator set delivers secure finality (\~6s blocks) while preserving flexibility for experimental features.

### **Early Access to Substrate Innovations**

- New runtime pallets, XCM improvements, and networking upgrades land on Kusama first, giving you a head start on upcoming Polkadot capabilities.
- Developers can validate performance at scale without waiting for Polkadot release windows.
- Canary parachains (Statemine, Karura, Hydration, and more) provide a rich ecosystem for cross-chain experimentation.

### **Production Tooling & Ecosystem Depth**

- Fully compatible with the Polkadot JS stack, Subxt, py-substrate-interface, and Dwellir Sidecar REST APIs.
- Rich telemetry, explorers (Subscan, Statescan), and infrastructure partners support monitoring and analytics.
- Seamlessly migrate winning features to Polkadot once product-market fit is proven.

## Quick Start with Kusama

Connect to Kusama’s relay chain endpoints and Sidecar REST surface with Dwellir.

### Installation & Setup

curl (HTTP JSON-RPC)
JavaScript (polkadot.js)
Rust (subxt)
Python (py-substrate-interface)

```bash
curl -s https://api-kusama.n.dwellir.com/YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "method": "chain_getHeader",
    "params": [],
    "id": 1
  }'
```

```typescript
import { ApiPromise, WsProvider } from '@polkadot/api';

async function main() {
  const provider = new WsProvider('wss://api-kusama.n.dwellir.com/YOUR_API_KEY');
  const api = await ApiPromise.create({ provider });

  const [chain, version] = await Promise.all([
    api.rpc.system.chain(),
    api.rpc.system.version(),
  ]);

  console.log(`Connected to ${chain.toString()} v${version.toString()}`);

  // Subscribe to finalized blocks
  const unsub = await api.rpc.chain.subscribeFinalizedHeads((header) => {
    console.log(`Finalized block #${header.number} at ${header.hash}`);
  });

  // Stop subscription after 3 blocks
  setTimeout(async () => {
    await unsub();
    await api.disconnect();
  }, 18000);
}

main().catch(console.error);
```

```rust
use subxt::{OnlineClient, PolkadotConfig};

#[subxt::subxt(runtime_metadata_path = "./metadata/kusama.scale" )]
pub mod kusama {}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = OnlineClient::<PolkadotConfig>::from_url(
        "wss://api-kusama.n.dwellir.com/YOUR_API_KEY"
    ).await?;

    let header = api.rpc().block_header(None).await?.expect("latest header");
    println!("Latest block: #{:?} (hash {:?})", header.number, header.hash());

    let account = api.storage().system().account(
        &"E8MByjWbS49hmzFM1U5rvFJES1Xgz1TSBAZLiYqZQiFTNUY".parse()?
    ).await?;
    println!("Free balance: {} KSM", account.data.free);

    Ok(())
}
```

```python
from substrateinterface import SubstrateInterface

substrate = SubstrateInterface(
    url="wss://api-kusama.n.dwellir.com/YOUR_API_KEY",
    type_registry_preset="kusama"
)

chain = substrate.rpc_request("system_chain", [])
print(f"Connected to {chain['result']}")

head = substrate.rpc_request("chain_getFinalizedHead", [])
print(f"Finalized head: {head['result']}")

account_info = substrate.query(
    module='System',
    storage_function='Account',
    params=['E8MByjWbS49hmzFM1U5rvFJES1Xgz1TSBAZLiYqZQiFTNUY']
)

print(f"Free: {account_info['data']['free']}")
```

## Network Information

| Parameter            | Value            | Details                  |
| -------------------- | ---------------- | ------------------------ |
| Genesis Hash         | 0xb0a8d493…3dafe | Relay chain              |
| Native Token         | KSM              | 12 decimals              |
| SS58 Prefix          | 2                | Address format           |
| Runtime Spec Version | 1007001          | As of 3 Oct 2025         |
| Transaction Version  | 26               | state\_getRuntimeVersion |
| Explorer             | Subscan          | kusama.subscan.io        |

Kusama operates as a relay chain without a parent relay. Parachain IDs are allocated per project; refer to individual parachain docs for cross-chain calls. Runtime and transaction versions above reflect the live values queried via `state_getRuntimeVersion` on 3 October 2025.

## API Reference

Kusama exposes the same Substrate RPC namespaces as Polkadot, covering node telemetry, block production, storage access, and finality tracking.

## Common Integration Patterns

### Track Finality with GRANDPA and BEEFY

```typescript
const finalizedHeads = await api.rpc.chain.subscribeFinalizedHeads((header) => {
  console.log(`GRANDPA finalized #${header.number}`);
});

const beefySub = await api.rpc.beefy.subscribeJustifications((event) => {
  console.log('BEEFY justification', event);
});
```

Combine GRANDPA finalized heads with `beefy_subscribeJustifications` to monitor parachain finality for bridges and XCMP relayers.

### Paginate Large Storage Scans

```typescript
const page = await api.rpc.state.getKeysPaged(
  '0x26aa394eea5630e07c48ae0c9558cef7b99d880ec681799c0cf30e8886371da9',
  100,
  '0x',
  null
);

console.log('Fetched', page.length, 'System.Account keys');
```

Use `state_getKeysPaged` with archive access to traverse large storage maps without overwhelming RPC quotas.

### Decode Fees Before Submission

```typescript
const ext = api.tx.balances.transferAllowDeath(dest, amount);
const info = await api.rpc.payment.queryInfo(ext.toHex());
console.log(`PartialFee: ${info.partialFee.toHuman()}`);
```

Estimate transaction costs using `payment_queryInfo` so you can bound fees before broadcasting to Kusama.

## Performance Best Practices

- Prefer WebSocket connections for subscriptions, finality, and multi-round queries.
- Cache runtime metadata (`api.runtimeVersion`, type bundles) and reuse the ApiPromise instance across requests.
- Shard heavy workloads across archive nodes if you need deep historical access; avoid full-chain scans without pagination.
- Back off exponentially on retries when encountering `isSyncing` or transient `-32010` errors.
- Use Sidecar REST for read-heavy explorers when SCALE decoding is unnecessary.

## Troubleshooting

- **WebSocket handshake fails** – Confirm your API key is appended exactly as provided and outbound TCP/443 is open.
- **Invalid SS58 address** – Ensure addresses use prefix `2`. Convert from Polkadot (prefix 0) with `@polkadot/util-crypto` helpers.
- **Type errors in clients** – Refresh metadata (`api.runtimeMetadata`) after runtime upgrades; Kusama upgrades more frequently than Polkadot.
- **Extrinsic rejected** – Decode the dispatch error via `api.registry.findMetaError` to surface module/error details.
- **rateLimit/TooManyRequests** – Implement per-IP backoff and share a single connection pool across services.

## Smoke Tests

Run these baseline checks against production endpoints (values captured 3 Oct 2025):

```bash
# Node health (peers: 68, isSyncing: false)
curl -s https://api-kusama.n.dwellir.com/YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"system_health","params":[]}'

# Latest block header (#30363294)
curl -s https://api-kusama.n.dwellir.com/YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getHeader","params":[]}'

# Block hash for #30363295 (0x028651…2e0c)
curl -s https://api-kusama.n.dwellir.com/YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"chain_getBlockHash","params":["0x1cf4e9f"]}'

# Runtime version (specVersion 1007001, transactionVersion 26)
curl -s https://api-kusama.n.dwellir.com/YOUR_API_KEY \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"state_getRuntimeVersion","params":[]}'
```

Verify the response fields match the expected peers, block numbers, hashes, and version metadata before onboarding workloads.

## Migration Guide

- **Endpoints** – Replace Polkadot RPC URLs with `https://api-kusama.n.dwellir.com/YOUR_API_KEY` or `wss://api-kusama.n.dwellir.com/YOUR_API_KEY` across services.
- **Addresses** – Re-encode SS58 addresses with prefix `2`; Polkadot addresses (prefix 0) are not valid on Kusama.
- **Runtime Types** – Update your custom type bundles to match the Kusama spec (`specVersion 1007001` as of Oct 2025) and refresh metadata caches after each upgrade.
- **Fee Calibration** – Kusama uses different fee multipliers; re-run `payment_queryInfo` and adjust heuristics for tipping and priority fees.
- **Bridges & XCM** – Confirm target parachain IDs and HRMP channels; Kusama pairs differ from Polkadot equivalents.

## Resources & Tools

- [Kusama Network Portal](https://kusama.network/)
- [Kusama Subscan Explorer](https://kusama.subscan.io)
- [Polkadot Wiki – Kusama Section](https://wiki.polkadot.network/docs/kusama)
- [Parity Telemetry – Kusama](https://telemetry.polkadot.io/#list/Kusama)
- [Substrate Developer Hub](https://docs.substrate.io/)
- [Dwellir Dashboard – Get your API key](https://dashboard.dwellir.com/register)