Kusama API: Endpoints, Methods, and How to Connect

Kusama API Decision Checklist

Before integrating the Kusama API, consider these factors:

What Is the Kusama API?

The Kusama API refers to the JSON-RPC and WebSocket interfaces that allow developers to interact with the Kusama blockchain. Kusama is Polkadot's canary network — a multi-chain environment built with Substrate that serves as a proving ground for runtime upgrades and parachain deployments before they go live on Polkadot.

Through the Kusama API, you can query on-chain data (blocks, transactions, accounts, events), submit extrinsics (transactions), and subscribe to real-time updates. The API follows the Substrate JSON-RPC specification, with additional methods for specific pallets.

Kusama API Endpoints

Public Endpoint (Rate-Limited)

For testing and low-volume use, a public endpoint is available:

HTTPS: https://kusama.api.onfinality.io/public
WSS:    wss://kusama.api.onfinality.io/public-ws

This endpoint is rate-limited and should not be used in production applications.

Shared API Key Endpoint

After signing up for an API key, you can use a dedicated endpoint with higher rate limits and access to archive data:

HTTPS: https://kusama.api.onfinality.io/rpc?apikey=YOUR_API_KEY
WSS:    wss://kusama.api.onfinality.io/ws?apikey=YOUR_API_KEY

Dedicated Node

For maximum performance and control, deploy a dedicated Kusama node. You can choose between full, archive, and validator node types, with options for geographic placement.

Common Kusama API Methods

Here are some frequently used JSON-RPC methods on Kusama:

Chain Methods

• chain_getBlock — Get the latest block or a block by hash
• chain_getBlockHash — Get block hash by number
• chain_getHeader — Get block header
• chain_subscribeNewHeads — Subscribe to new block headers

State Methods

• state_getStorage — Query storage by key
• state_getMetadata — Get runtime metadata
• state_getRuntimeVersion — Get current runtime version

System Methods

• system_chain — Get chain name
• system_health — Get node health status
• system_peers — List connected peers

Author Methods

• author_submitExtrinsic — Submit a signed extrinsic
• author_pendingExtrinsics — List pending extrinsics

Connecting to the Kusama API

Using cURL

curl -H "Content-Type: application/json" \
  -d '{"id":1, "jsonrpc":"2.0", "method": "chain_getBlock"}' \
  https://kusama.api.onfinality.io/public

Using JavaScript (Polkadot.js)

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

async function main() {
  const provider = new WsProvider('wss://kusama.api.onfinality.io/public-ws');
  const api = await ApiPromise.create({ provider });

  // Get chain info
  const chain = await api.rpc.system.chain();
  const lastHeader = await api.rpc.chain.getHeader();

  console.log(`Chain: ${chain}`);
  console.log(`Latest block: ${lastHeader.number}`);

  // Subscribe to new blocks
  api.rpc.chain.subscribeNewHeads((header) => {
    console.log(`New block #${header.number}`);
  });
}

main().catch(console.error);

Using Python

import requests
import json

url = "https://kusama.api.onfinality.io/public"
payload = {
    "jsonrpc": "2.0",
    "method": "chain_getBlock",
    "params": [],
    "id": 1
}
response = requests.post(url, json=payload)
print(response.json())

Kusama API vs. Subscan API

While the Kusama JSON-RPC API provides direct blockchain access, the Subscan API offers a RESTful interface with aggregated data such as account history, token transfers, and price information. The Subscan API is useful for analytics and frontend applications, but it does not allow submitting transactions or subscribing to real-time events. For full control and real-time interaction, use the native JSON-RPC API.

Infrastructure Considerations

Public vs. Private Endpoints

Public endpoints are convenient for development but unsuitable for production due to rate limits and potential instability. For production applications, consider:

• Shared API service: Provides higher rate limits, archive data, and multiple geographic regions. Suitable for most dApps and wallets.
• Dedicated node: A full or archive node dedicated to your application. Offers the best performance, clear rate limits, and full control over node configuration.

Archive vs. Full Node

• Full node: Stores only recent state (usually 256 blocks). Suitable for submitting transactions and querying current state.
• Archive node: Stores all historical state. Required for applications that need to query past account balances, historical events, or run analytics.

Geographic Placement

Choose a provider with nodes in regions close to your users to minimize latency. OnFinality offers Kusama endpoints in multiple regions including Hong Kong and N. Virginia.

Troubleshooting Common Issues

Connection Timeouts

• Check that your firewall allows outbound connections on ports 443 (HTTPS) and 443 (WSS).
• If using a public endpoint, ensure you are not being rate-limited. Switch to an API key endpoint.

"Method not found" Errors

• Verify that the method name matches the Substrate JSON-RPC specification. Some methods may be available only on certain node types.
• Ensure you are using the correct endpoint (e.g., archive node for state_getStorage with historical keys).

Slow Responses

• Public endpoints may experience congestion during high network activity.
• Consider upgrading to a dedicated node or a shared API service with guaranteed resources.

Key Takeaways

• The Kusama API provides JSON-RPC and WebSocket access to the Kusama blockchain, enabling querying, transaction submission, and real-time subscriptions.
• Public endpoints are suitable for testing; production applications should use API key-based or dedicated node infrastructure.
• Archive nodes are necessary for historical data queries.
• Choose a provider with geographic diversity and reliable uptime for production workloads.
• For detailed endpoint information and pricing, visit the Kusama network page and RPC pricing page.

Frequently Asked Questions

What is the difference between Kusama and Polkadot APIs? Both use the same Substrate JSON-RPC specification. The main difference is the network — Kusama is a canary network with faster governance and lower value at stake, while Polkadot is the mainnet with higher security and stability.

Can I use the Kusama API to interact with parachains? Yes, but you need to connect to the specific parachain's RPC endpoint. Kusama's relay chain API does not expose parachain state directly.

How do I get an API key for Kusama? Sign up at OnFinality and create an API key from the dashboard. You can then use it with the shared endpoint.

What is the rate limit for the public endpoint? The public endpoint is rate-limited to prevent abuse. Exact limits are not published; for production use, obtain an API key or dedicated node.

Does the Kusama API support WebSocket subscriptions? Yes, the WebSocket endpoint supports subscriptions such as chain_subscribeNewHeads and state_subscribeStorage.

For a full list of supported networks and their endpoints, see the supported networks page.