TON API 密钥：如何获取以及何时需要？

如果您搜索了 TON API 密钥，您可能已经有一个钱包、脚本或后端服务需要与 The Open Network 通信，并且遇到了瓶颈：公共端点可用于快速测试，但您需要能够验证、监控和扩展的东西。本页面首先回答实际问题——密钥是什么、如何获取以及如何使用——然后帮助您决定共享的带密钥端点是否足够，或者您的工作负载是否需要专用 TON 节点。

快速回答：TON API 密钥是什么以及不是什么

TON API 密钥是由 RPC 或 API 提供商颁发的凭证。您将其附加到请求中，提供商使用它来识别您的项目、应用与您的计划相关的速率限制和配额，并为您提供使用情况可见性。它不是钱包密钥，不签署交易，也不授予您对 TON 区块链本身的特殊访问权限。它只控制您如何访问为您的请求提供服务的节点基础设施。

这种区别很重要，因为 TON 有两种常见的访问方式：

• 基于 HTTP 的 JSON-RPC，您将方法调用（如 runGetMethod 或 sendBoc）发送到端点，并通过标头或查询参数进行身份验证。
• HTTP API 包装器，提供商在原始节点之上暴露更高级的 REST 风格路由（账户状态、交易历史、jetton 元数据）。

两种方式都可能需要密钥。两种方式都不能让您绕过共识或读取节点没有的数据。

首先决定：共享带密钥端点还是专用节点？

在注册任何东西之前，将您的工作负载与访问模型匹配。大多数团队在开始时过度购买，在启动时购买不足，因此请将此作为快速筛选。

如果您在该表的上半部分，带密钥的共享端点是务实的选择。如果您在下半部分，请在承诺计划之前阅读专用节点部分。

如何获取 TON API 密钥

具体流程取决于提供商，但形式是一致的：

1. 创建账户，使用您想要使用的 RPC 提供商。
2. 在仪表板中创建项目或应用程序。这是拥有密钥和使用计数器的单元。
3. 为该生成 API 密钥。有些提供商立即给您密钥；其他要求您先选择计划。
4. 选择您的网络：TON 主网或 TON 测试网。将它们保留为单独的密钥，以便测试网脚本永远不会触及主网数据。
5. 限制密钥，如果提供商支持——允许的来源、IP 允许列表或按方法范围。
6. 将密钥存储在秘密管理器中，而不是在您的仓库中。像对待任何其他凭证一样对待它。

OnFinality 通过相同的项目模型颁发密钥。您可以查看 TON RPC 网络页面 了解端点详细信息，查看 TON 测试网页面 了解测试网访问，然后查看 RPC 定价 以了解哪个计划符合您预期的请求量。

发送您的第一个经过身份验证的 TON 请求

TON 的 JSON-RPC 接口与 EVM 链不完全相同，因此不要假设 eth_* 方法会起作用。一个典型的经过身份验证的调用如下所示：

curl -s https://ton-mainnet.example-rpc-provider.com/ \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $TON_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "runGetMethod",
    "params": {
      "address": "EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c",
      "method": "seqno",
      "stack": []
    }
  }'

将主机替换为您的提供商给您的端点。重要的部分是 X-API-Key 标头（有些提供商使用 Authorization: Bearer 标头或 ?api_key= 查询参数代替）和 JSON-RPC 信封。如果您使用的是 HTTP API 包装器而不是原始 JSON-RPC，相同的密钥放在相同的标头中，但路径和正文形状会不同。

一个使用 fetch 的最小 JavaScript 客户端如下所示：

const res = await fetch(process.env.TON_RPC_URL, {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": process.env.TON_API_KEY
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "getMasterchainInfo",
    params: {}
  })
});

const data = await res.json();
if (data.error) throw new Error(JSON.stringify(data.error));
console.log(data.result);

将 URL 和密钥保留在环境变量中。轮换泄露的密钥应该是配置更改，而不是代码更改。

TON 端点和网络设置一览

始终根据提供商的文档确认当前的方法列表和传输支持，因为 TON 工具在不断发展，包装器会随时间添加或重命名路由。OnFinality TON 网络页面 是我们这边支持内容的权威参考。

常见故障模式及如何调试

大多数“我的 TON API 密钥不起作用”的报告都归入少数几类。按顺序处理它们。

一个有用的习惯是分别记录 HTTP 状态代码和 JSON-RPC error 对象。提供商通常会返回有效的 JSON-RPC 错误，但 HTTP 状态非 200，将两者混为一谈会减慢调试速度。

当共享带密钥端点不再足够时

带密钥的共享端点是大多数团队的合适默认值。当以下情况之一为真时，它就成为错误的工具：

• 您正在扫描历史记录。 回填交易或构建索引意味着长时间、昂贵的读取，会与其他租户竞争。
• 您需要一致的延迟。 共享池平均而言没问题，但在尾部更嘈杂，这对交易或实时用户体验很重要。
• 您需要隔离。 受监管的工作负载或任何具有严格数据边界的工作负载通常无法共享基础设施。
• 您反复达到限制。 如果您调整退避的时间比发布功能的时间还多，那么计划就是问题所在。

此时，专用 TON 节点 为您提供一个仅服务于您的流量的节点。您保留相同的 API 密钥模型，但其背后的容量是您的。OnFinality 在许多网络上运行专用节点，您可以在承诺之前比较 如何选择 RPC 提供商 中的权衡。

上线前的操作检查清单

• 密钥存储在秘密管理器中，而不是代码或 CI 日志中。
• 主网和测试网密钥是分开的并且命名清晰。
• 您有带指数退避和抖动的重试策略，用于 429 和 5xx。
• 您记录请求 ID，以便将故障与提供商支持相关联。
• 您有备用端点或记录的故障转移计划。
• 您监控错误率和 p95 延迟，而不仅仅是正常运行时间。
• 您知道您的每月请求量以及哪个 RPC 定价 层级覆盖它。
• 如果您计划扩展，您已经查看了 支持的 RPC 网络 的完整列表。

关键要点

• TON API 密钥验证您对提供商的请求；它不签署交易或改变区块链暴露的内容。
• 公共端点适合原型；带密钥的端点是正常的生产默认值。
• TON 使用自己的 JSON-RPC 方法接口，因此不要假设 EVM 方法名称会起作用。
• 将主网和测试网密钥分开，并将它们存储在秘密管理器中。
• 大多数密钥错误是标头错误、网络不匹配或速率限制——首先检查这些。
• 当您需要隔离、可预测的吞吐量或大量历史读取时，迁移到专用 TON 节点。

常见问题解答

TON API 密钥与钱包私钥相同吗？

不。钱包私钥签署交易并控制资金。TON API 密钥仅验证您对 RPC 提供商的请求。永远不要将它们视为可互换的，也永远不要将钱包密钥粘贴到 RPC 配置中。

我可以免费使用 TON API 密钥吗？

许多提供商提供带密钥的免费或试用层级，通常具有较低的速率限制。这是一种合理的原型开发方式。在您对免费层级构建生产依赖之前，请检查提供商当前的计划条款，包括 OnFinality RPC 定价。

我应该为 TON API 密钥使用哪个标头？

这取决于提供商。常见选项是 X-API-Key、Authorization: Bearer <key> 或查询参数。使用提供商文档中说明的任何内容，并避免将密钥放在会被代理记录的 URL 中。

我需要为 TON 测试网使用单独的密钥吗？

是的，在实践中。测试网和主网是具有不同状态的不同网络。单独的密钥可以防止测试脚本意外读取或写入主网数据。

如何知道是否需要专用 TON 节点？

如果您持续达到速率限制、需要隔离或运行大量历史查询，专用节点通常是更好的选择。从 专用节点概述 开始，并将其与您的工作负载进行比较。

在哪里可以找到当前的 TON 端点详细信息？

使用提供商的网络页面作为事实来源。对于 OnFinality，请从 TON 网络页面 和 TON 测试网页面 开始。