TON JSON-RPC：端点、方法及使用方法

快速决策指南：哪种 TON RPC 设置适合您的应用？

在连接客户端之前，请决定哪种 TON RPC 访问模式符合您的工作负载。选择会影响延迟、速率限制以及您需要管理的基础设施量。

如果您需要具有可预测性能的托管端点，OnFinality 提供 TON RPC 端点 和 TON 测试网 RPC，支持 HTTPS JSON-RPC。对于生产工作负载，托管服务可消除运行自己节点的运维负担。有关详细信息，请参阅 RPC 定价。

什么是 TON JSON-RPC？

TON JSON-RPC 是通往开放网络（TON）的 JSON-RPC 2.0 接口，TON 是一个非 EVM 的第一层区块链。与以太坊的 JSON-RPC 不同，TON 的接口不兼容 EVM，并使用自己的一套方法。它提供了一个单一的 HTTPS 端点，您可以在其中调用方法读取区块链数据、运行智能合约 get 方法以及发送交易。

TON 节点内部使用二进制 ADNL 协议进行通信，该协议无法从 Web 应用程序直接访问。TON JSON-RPC 充当桥梁，将标准 HTTP JSON-RPC 请求转换为节点调用，并以熟悉的格式返回结果。

TON JSON-RPC 端点和身份验证

主要的 TON JSON-RPC 端点由 TON Center 提供：

• 主网：https://toncenter.com/api/v2/jsonRPC
• 测试网：https://testnet.toncenter.com/api/v2/jsonRPC

所有 API 方法都可通过此单一端点使用。您通过在 X-API-Key 标头中发送 API 密钥进行身份验证。没有密钥时，请求限制为每秒 1 次。有密钥时，限制更高，但仍适用。

示例请求：

curl -X POST "https://toncenter.com/api/v2/jsonRPC" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getMasterchainInfo",
    "params": {}
  }'

响应：

{
  "ok": true,
  "result": {
    "last": {
      "workchain": -1,
      "shard": "-9223372036854775808",
      "seqno": 123456,
      "root_hash": "...",
      "file_hash": "..."
    },
    "state_root_hash": "...",
    "init": {
      "workchain": -1,
      "shard": "-9223372036854775808",
      "seqno": 0,
      "root_hash": "...",
      "file_hash": "..."
    }
  },
  "@extra": "...",
  "jsonrpc": "2.0",
  "id": "1"
}

常用 TON JSON-RPC 方法

TON JSON-RPC 公开了一组映射到 TON Center API v2 的方法。以下是最常用的方法：

有关完整列表，请参阅官方 TON 文档。

使用 JavaScript 调用 TON JSON-RPC

您可以使用任何语言调用 TON JSON-RPC。以下是使用 fetch 的 JavaScript 示例：

const endpoint = "https://toncenter.com/api/v2/jsonRPC";
const apiKey = "YOUR_API_KEY";

async function callTonRpc(method, params = {}) {
  const response = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": apiKey
    },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method,
      params
    })
  });
  return response.json();
}

// 获取地址余额
const balance = await callTonRpc("getAddressBalance", {
  address: "EQD..."
});
console.log(balance.result);

TON JSON-RPC 与 REST API 对比

TON Center 同时提供 REST 和 JSON-RPC 端点。REST API 为每个方法使用单独的 URL（例如 /getAddressBalance），而 JSON-RPC 使用带有 method 字段的单一端点。当您想要批量调用多个请求或更喜欢一致的接口时，JSON-RPC 非常有用。

公共、托管与专用 TON RPC 对比

使用 TON JSON-RPC 时，您有三个主要选项：

1. 公共端点 – 免费但有速率限制（无密钥时 1 RPS）。适合测试和低流量应用。
2. 托管 RPC 服务 – 提供具有更高速率限制、监控和支持的可靠端点。OnFinality 提供 TON RPC 作为托管服务。
3. 专用节点 – 您拥有自己的 TON 节点，完全控制配置，无共享速率限制。这非常适合高吞吐量或自定义用例。

常见 TON JSON-RPC 问题排查

• 401 Unauthorized：检查您的 API 密钥并确保其有效。
• 403 Forbidden：您的 API 密钥可能没有请求方法的权限。
• 429 Too Many Requests：您已超出速率限制。请等待或升级您的计划。
• 422 Unprocessable Entity：您的请求参数无效。请检查方法签名。
• 500 Internal Server Error：节点可能遇到问题。请稍后重试。
• 504 Gateway Timeout：请求耗时过长。对于繁重查询，请考虑使用专用节点。

关键要点

• TON JSON-RPC 是通往开放网络的 JSON-RPC 2.0 接口，使用单一 HTTPS 端点。
• 通过 X-API-Key 标头进行身份验证；没有密钥时，限制为 1 RPS。
• 常用方法包括 getMasterchainInfo、getAddressBalance 和 runGetMethod。
• 根据您的工作负载和可靠性需求选择公共、托管或专用 RPC。
• 对于生产环境，请考虑使用托管服务（如 OnFinality 的 TON RPC）以避免速率限制和运维开销。

常见问题解答

TON JSON-RPC 是否与以太坊 JSON-RPC 兼容？ 不。TON 是非 EVM 区块链，因此其 JSON-RPC 方法不同。您不能使用 eth_getBalance 或其他 EVM 方法。

如何获取 TON API 密钥？ 您可以通过在 TON Center 注册您的应用程序来获取密钥。像 OnFinality 这样的托管提供商也提供带有其端点的 API 密钥。

我可以将 WebSocket 与 TON JSON-RPC 一起使用吗？ TON JSON-RPC 基于 HTTP。对于实时更新，TON 提供了单独的流式 API，支持 WebSocket。

TON JSON-RPC 的速率限制是多少？ 没有 API 密钥时，限制为每秒 1 个请求。有密钥时，限制更高，但因提供商而异。

如何使用 TON JSON-RPC 发送交易？ 您需要将交易序列化为 cell 包，并使用 sendBoc 方法。这比 EVM 交易更复杂。

有关更多详细信息，请探索 支持的 RPC 网络 和 RPC 定价。