BNB Smart Chain JSON-RPC 快速入门：端点设置、链 ID 和首次调用

如果您正在将 BNB Smart Chain 接入钱包、后端服务或索引器，最快的方法是确认链设置、发送一个 JSON-RPC 请求，然后决定您的工作负载实际需要多少端点容量。本页面是该流程的实用快速入门和参考。

链设置一览

BNB Smart Chain (BSC) 是一个 EVM 兼容网络，因此如果您使用过以太坊，JSON-RPC 接口会看起来很熟悉。以下是将网络添加到客户端或钱包所需的值。

主网是生产流量和真实价值所在。测试网用于开发、水龙头资助的测试以及发布前的集成检查。在配置中将两者分开，以免意外将暂存密钥指向主网。

在编写代码之前决定如何连接

第一个真正的决定不是调用哪个方法，而是您希望如何连接到链。这个选择会影响您的配置、故障处理和预算。

• 本地开发和一次性脚本： 共享公共端点通常就足够了。您可以立即获得一个可用的 URL，并可以在不配置任何东西的情况下迭代请求形状。
• 钱包或 dApp 前端： 您需要一个稳定的 HTTPS 端点，以及一个 WebSocket 端点（如果您显示实时余额、待处理交易或事件驱动的 UI）。浏览器客户端无法运行完整节点，因此托管 RPC API 是正常选择。
• 后端服务、机器人和索引器： 请求量、日志查询和归档读取开始变得重要。这是您比较共享端点与专用节点的地方，也是速率限制和 eth_getLogs 行为成为决定性因素的地方。
• 高吞吐量或延迟敏感的工作负载： 您通常需要专用节点基础设施，这样您的容量就不会与无关流量共享。

如果您仍在权衡提供商，RPC 提供商选择指南 更深入地介绍了评估标准。如果您已经知道想要托管的 BSC 端点，请从 BNB Smart Chain RPC 页面 开始。

第一个请求：确认端点是否存活

在构建任何东西之前，确认端点响应并报告您期望的链。chainId 调用是最便宜的健全性检查。

curl -s https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "eth_chainId",
    "params": []
  }'

正确的主网响应返回 0x38，即十六进制的 56。如果您得到不同的值，则指向了错误的网络。如果您得到错误对象，请转到下面的调试部分。

在设置期间还值得运行另外两个调用：

# 最新区块号
curl -s https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]}'

# 客户端版本字符串
curl -s https://bnb.api.onfinality.io/public \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"web3_clientVersion","params":[]}'

eth_blockNumber 确认节点已同步并正在推进。web3_clientVersion 告诉您哪个客户端实现正在为您服务，这在您比较不同端点的行为时很有用。

将 BNB Smart Chain 添加到钱包或客户端

大多数钱包接受自定义网络。使用上表中的设置。典型的配置对象如下所示：

const bscMainnet = {
  chainId: "0x38", // 56
  chainName: "BNB Smart Chain Mainnet",
  nativeCurrency: {
    name: "BNB Chain Native Token",
    symbol: "BNB",
    decimals: 18,
  },
  rpcUrls: ["https://bnb.api.onfinality.io/public"],
  blockExplorerUrls: ["https://bscscan.com"],
};

对于测试网，替换为链 ID 0x61 (97)、测试网端点和测试网浏览器。将符号保留为 tBNB，这样您的 UI 就不会暗示真实资金。

从 JavaScript 调用 BSC

如果您更喜欢库而不是原始 curl，viem 和 ethers 都可以在 BSC 上工作，因为它是 EVM 兼容的。一个最小的 viem 读取如下所示：

import { createPublicClient, http, formatEther } from "viem";
import { bsc } from "viem/chains";

const client = createPublicClient({
  chain: bsc,
  transport: http("https://bnb.api.onfinality.io/public"),
});

const blockNumber = await client.getBlockNumber();
const balance = await client.getBalance({
  address: "0x0000000000000000000000000000000000000000",
});

console.log(blockNumber, formatEther(balance));

如果您使用 ethers，模式是相同的思路：创建一个指向端点的提供者，然后调用读取方法。重要的是端点 URL 和链 ID 一致。

您将在 BSC 上实际使用的方法

由于 BSC 是 EVM 兼容的，标准的以太坊 JSON-RPC 方法集适用。下表对最常出现的方法进行了分组，并指出了 BSC 特定行为容易让人惊讶的地方。

其中两个值得额外关注。首先，eth_getLogs 是最有可能触及限制的方法，因为宽区块范围和广泛主题的服务成本很高。如果您的索引器查询大范围，预计需要分页，并且需要一个支持您查询模式的端点。其次，eth_subscribe 需要 WebSocket 连接，因此在围绕实时事件进行设计之前，请确认您的端点支持 ws。

调试您实际会遇到的错误

大多数早期的 BSC 集成问题都属于少数几类。在更改代码之前，将症状与可能的原因匹配。

其中一些值得展开。速率限制响应不是您代码中的错误，而是容量信号。如果您在正常负载下看到它们，您的请求模式已经超出了共享端点的能力。Nonce 错误通常意味着您的本地 nonce 跟踪与链发生了偏差，因此在广播之前重新读取待处理 nonce。而来自 eth_call 的回滚错误是正常的合约行为，不是 RPC 失败，因此请解码它们，而不是盲目重试。

何时共享端点足够，何时不够

共享公共端点是开发、低容量读取和原型的良好默认选择。它可以让您快速实现可工作的集成，并在您承诺基础设施之前验证请求形状。

一旦您有生产流量，情况就会改变。您已经超出共享端点的信号包括：

• 正常操作期间频繁出现速率限制响应。
• eth_getLogs 查询需要宽区块范围或长时间回溯。
• 针对历史状态的归档读取。
• 必须长时间保持连接的 WebSocket 订阅。
• 需要隔离您的流量，以免其他租户的负载影响您的延迟。

此时，实际选项是具有更高限制的托管 RPC API 或您控制的专用节点基础设施。OnFinality 为 BNB Smart Chain 提供两者，因此您可以从共享端点开始，然后转移到专用容量，而无需更改应用程序代码，只需更改配置。有关层级差异，请参阅 RPC 定价，有关链的完整列表，请参阅 支持的 RPC 网络。

生产就绪检查清单

在将真实用户指向您的 BSC 集成之前，请确认以下内容：

1. 主网和测试网端点在您的配置中是分开的，没有共享机密。
2. 您有用于瞬态故障的回退端点或重试策略。
3. eth_getLogs 查询已分页且有界。
4. WebSocket 客户端使用指数退避重新连接。
5. 您监控区块高度和错误率，而不仅仅是 HTTP 状态代码。
6. 您的 nonce 处理在重新发送之前从节点重新读取。
7. 您已经决定是否需要归档访问和专用容量。

一个简单的监控探针可以及早发现大多数问题。定期轮询 eth_blockNumber，如果它停止推进或错误率攀升，则发出警报：

while true; do
  curl -s https://bnb.api.onfinality.io/public \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":1,"method":"eth_blockNumber","params":[]}'
  sleep 30
done

如果区块号停滞或端点开始返回错误，这就是您在用户注意到之前进行调查的信号。

关键要点

• BNB Smart Chain 主网使用链 ID 56 (0x38)，测试网使用 97 (0x61)。
• BSC 是 EVM 兼容的，因此标准的以太坊 JSON-RPC 方法适用。
• 在构建之前，使用 eth_chainId 和 eth_blockNumber 确认端点。
• eth_getLogs 和 eth_subscribe 是最有可能触及端点限制的方法。
• 速率限制响应是容量信号，不是代码错误。
• 共享端点适合开发；生产工作负载通常需要专用容量。
• OnFinality 提供 BNB Smart Chain RPC API 访问和专用节点，如果您想要托管基础设施。

常见问题解答

BNB Smart Chain 的链 ID 是什么？

主网是 56，即十六进制的 0x38。测试网是 97，即 0x61。

BSC JSON-RPC 与以太坊 JSON-RPC 相同吗？

基本上是的，因为 BSC 是 EVM 兼容的。相同的方法名称适用，尽管各个端点可能支持的方法和区块范围有所不同。

为什么我的 eth_getLogs 调用在 BSC 上失败？

宽区块范围和广泛主题过滤器的服务成本很高，因此许多端点限制了范围。缩小范围并分页查询。

我需要为 BSC 使用 WebSocket 端点吗？

仅当您想要基于推送的更新（如新区块或日志）时。标准读取通过 HTTP 工作。在围绕订阅进行设计之前，请确认您的端点支持 ws。

我什么时候应该从公共端点迁移？

当您在正常负载下看到速率限制、需要归档数据、运行宽日志查询或想要流量隔离时。此时，比较托管 RPC API 层级和专用节点。