Kusama API：端点、方法和如何连接

Kusama API 决策清单

在集成 Kusama API 之前，请考虑以下因素：

什么是 Kusama API？

Kusama API 指的是允许开发者与 Kusama 区块链交互的 JSON-RPC 和 WebSocket 接口。Kusama 是 Polkadot 的金丝雀网络——一个基于 Substrate 构建的多链环境，作为运行时升级和平行链部署在 Polkadot 上线前的试验场。

通过 Kusama API，您可以查询链上数据（区块、交易、账户、事件）、提交外部函数（交易）以及订阅实时更新。该 API 遵循 Substrate JSON-RPC 规范，并包含特定 pallet 的额外方法。

Kusama API 端点

公共端点（有速率限制）

用于测试和低流量使用，提供公共端点：

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

此端点有速率限制，不应用于生产应用。

共享 API 密钥端点

注册获取 API 密钥后，您可以使用具有更高速率限制和归档数据访问权限的专用端点：

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

专用节点

为获得最佳性能和控制，部署专用 Kusama 节点。您可以选择全节点、归档节点和验证人节点类型，并可选择地理位置。

常用 Kusama API 方法

以下是 Kusama 上一些常用的 JSON-RPC 方法：

链方法

• chain_getBlock — 获取最新区块或按哈希获取区块
• chain_getBlockHash — 按区块号获取区块哈希
• chain_getHeader — 获取区块头
• chain_subscribeNewHeads — 订阅新区块头

状态方法

• state_getStorage — 按键查询存储
• state_getMetadata — 获取运行时元数据
• state_getRuntimeVersion — 获取当前运行时版本

系统方法

• system_chain — 获取链名称
• system_health — 获取节点健康状态
• system_peers — 列出已连接的对等节点

作者方法

• author_submitExtrinsic — 提交已签名的外部函数
• author_pendingExtrinsics — 列出待处理的外部函数

连接到 Kusama API

使用 cURL

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

使用 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 });

  // 获取链信息
  const chain = await api.rpc.system.chain();
  const lastHeader = await api.rpc.chain.getHeader();

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

  // 订阅新区块
  api.rpc.chain.subscribeNewHeads((header) => {
    console.log(`New block #${header.number}`);
  });
}

main().catch(console.error);

使用 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 与 Subscan API 对比

虽然 Kusama JSON-RPC API 提供直接的区块链访问，但 Subscan API 提供 RESTful 接口，包含账户历史、代币转账和价格信息等聚合数据。Subscan API 适用于分析和前端应用，但不允许提交交易或订阅实时事件。如需完全控制和实时交互，请使用原生 JSON-RPC API。

基础设施考虑因素

公共端点 vs. 私有端点

公共端点便于开发，但由于速率限制和潜在的不稳定性，不适合生产环境。对于生产应用，请考虑：

• 共享 API 服务：提供更高的速率限制、归档数据和多个地理区域。适用于大多数 dApp 和钱包。
• 专用节点：专用于您的应用的全节点或归档节点。提供最佳性能、明确的速率限制和对节点配置的完全控制。

归档节点 vs. 全节点

• 全节点：仅存储近期状态（通常 256 个区块）。适用于提交交易和查询当前状态。
• 归档节点：存储所有历史状态。对于需要查询过去账户余额、历史事件或运行分析的应用是必需的。

地理位置

选择在靠近用户区域有节点的提供商，以最小化延迟。OnFinality 在多个区域提供 Kusama 端点，包括香港和弗吉尼亚北部。

常见问题排查

连接超时

• 检查您的防火墙是否允许出站连接到端口 443 (HTTPS) 和 443 (WSS)。
• 如果使用公共端点，请确保您没有被速率限制。切换到 API 密钥端点。

“方法未找到”错误

• 验证方法名称是否与 Substrate JSON-RPC 规范匹配。某些方法可能仅在特定节点类型上可用。
• 确保您使用了正确的端点（例如，对于使用历史键的 state_getStorage，使用归档节点）。

响应缓慢

• 在网络活动高峰期，公共端点可能会遇到拥塞。
• 考虑升级到专用节点或具有保证资源的共享 API 服务。

关键要点

• Kusama API 提供对 Kusama 区块链的 JSON-RPC 和 WebSocket 访问，支持查询、交易提交和实时订阅。
• 公共端点适用于测试；生产应用应使用基于 API 密钥或专用节点的基础设施。
• 归档节点对于历史数据查询是必需的。
• 为生产工作负载选择具有地理多样性和可靠正常运行时间的提供商。
• 有关详细的端点信息和定价，请访问 Kusama 网络页面 和 RPC 定价页面。

常见问题

Kusama 和 Polkadot API 有什么区别？ 两者都使用相同的 Substrate JSON-RPC 规范。主要区别在于网络——Kusama 是一个金丝雀网络，具有更快的治理和较低的价值风险，而 Polkadot 是主网，具有更高的安全性和稳定性。

我可以使用 Kusama API 与平行链交互吗？ 可以，但您需要连接到特定平行链的 RPC 端点。Kusama 中继链 API 不直接暴露平行链状态。

如何获取 Kusama 的 API 密钥？ 在 OnFinality 注册，并从仪表板创建 API 密钥。然后您可以将其用于共享端点。

公共端点的速率限制是多少？ 公共端点有速率限制以防止滥用。确切的限制未公布；对于生产使用，请获取 API 密钥或专用节点。

Kusama API 是否支持 WebSocket 订阅？ 是的，WebSocket 端点支持订阅，例如 chain_subscribeNewHeads 和 state_subscribeStorage。

有关支持的网络及其端点的完整列表，请参阅 支持的网络页面。