BNB API：BSC JSON-RPC 方法与端点设置

链设置一览

在编写任何代码之前，请先正确设置网络参数。BSC 与 EVM 等效，因此只要链 ID 和端点正确，您现有的以太坊工具即可使用。

如果您只需要本页的一件事，那就是这张表。将其添加到您的钱包配置、Hardhat/Foundry 网络文件或后端环境变量中，大多数“错误网络”错误就会消失。

快速建议：共享端点还是专用节点？

大多数团队应从共享 RPC API 端点开始，并在出现特定信号时迁移到专用节点。使用以下内容来决定您目前所处的位置。

这个决定很少是永久的。从共享开始，测量，然后升级那些真正受影响的工作负载。OnFinality 同时提供 RPC API 访问 和 专用节点，因此您可以在不更改应用程序逻辑的情况下在两者之间切换。

您实际会调用的 BSC 方法

BSC 实现了标准的以太坊 JSON-RPC 接口。在实践中，一小部分方法覆盖了几乎所有生产流量。

读取状态

• eth_blockNumber — 当前区块高度，用于健康检查和延迟检测。
• eth_getBalance — 地址的原生 BNB 余额。
• eth_getTransactionCount — nonce，签名前需要。
• eth_call — 执行只读合约调用，无需交易。
• eth_getCode 和 eth_getStorageAt — 合约字节码和原始存储槽。
• eth_getBlockByNumber — 区块头，可选包含完整交易。

读取日志和收据

• eth_getLogs — 索引器的主力，但也是超时和范围错误的最常见来源。
• eth_getTransactionReceipt — 确认包含并读取发出的事件。

写入

• eth_sendRawTransaction — 提交已签名的交易。请注意，BSC 在大多数托管端点上不支持 eth_sendTransaction，因此请在客户端签名。
• eth_gasPrice 和 eth_estimateGas — 签名前的费用和 gas 估算。

链元数据

• eth_chainId — 确认您位于 56 或 97。
• net_version — 遗留网络标识符，仍被某些工具使用。

值得了解的 BSC 特定行为：出块时间短，gas 便宜，内存池交易量高。这种组合意味着 nonce 管理和 gas 定价比在较安静的链上更重要。

使用 curl 设置端点

在集成任何内容之前测试连接性。一次 eth_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。如果得到不同的值，则指向了错误的网络。如果出现连接错误，请先检查出口规则和 DNS。

现在读取余额和最新区块：

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

对于批量调用，在一个 HTTP 请求中发送请求对象的 JSON 数组。批处理减少了往返次数，但请保持批量适中——非常大的批量是超时的常见原因，并且通常会被共享端点限流。

接入 JavaScript

使用 ethers，提供者只需一行代码。将端点保留在配置中而不是硬编码，以便以后可以交换提供商或添加故障转移。

import { JsonRpcProvider } from "ethers";

const provider = new JsonRpcProvider(process.env.BSC_RPC_URL);

const network = await provider.getNetwork();
console.log("chainId", network.chainId.toString()); // expect 56

const block = await provider.getBlockNumber();
const balance = await provider.getBalance("0xYourAddress");
console.log({ block, balance: balance.toString() });

对于 viem，等效方法使用 createPublicClient 配合 http() 或 web3() 传输。如果您需要推送更新——新区块、待处理交易或合约事件——请使用针对 wss:// 端点的 WebSocket 传输。BSC 主网在 OnFinality 上同时支持 HTTP 和 WebSocket；测试网仅支持 HTTP，因此请相应地规划您的测试网工具。

钱包和 dApp 网络配置

如果您要将 BSC 添加到钱包或 dApp，请使用 wallet_addEthereumChain 参数。这些是用户切换网络时将看到的值。

await window.ethereum.request({
  method: "wallet_addEthereumChain",
  params: [{
    chainId: "0x38",
    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 和测试网浏览器。在尝试发送交易之前，从 BSC 水龙头获取测试网资金——零余额是测试网写入静默失败的最常见原因。

故障模式及如何调试

大多数 BSC RPC 问题属于少数几类。匹配症状，然后进行修复。

两个习惯可以防止大多数这些问题。首先，始终在启动时确认链 ID，如果错误则快速失败。其次，将每个 RPC 调用视为可能失败：用超时包装它，使用退避重试，并在配置中保留第二个端点用于故障转移。

生产就绪检查清单

在将真实流量指向端点之前，请确认以下事项。

• 启动时验证链 ID，而非假设。
• 端点存储在配置中，至少有一个备用 URL。
• 为每个调用路径配置超时和重试。
• eth_getLogs 范围有界并分页。
• Nonce 处理集中化，避免并发写入者冲突。
• 监控区块高度延迟、错误率和 p95 延迟。
• 如果共享吞吐量成为瓶颈，有文档化的迁移到专用节点的路径。

如果其中几项已经导致事件，那就是评估专用基础设施的信号。OnFinality 的 BNB Chain 网络页面 列出了端点和传输详细信息，RPC 定价 涵盖了计划形态。如需更广泛的框架，请参阅 如何选择 RPC 提供商。

关键要点

• BSC 主网是链 ID 56，原生代币为 BNB；测试网是链 ID 97，代币为 tBNB。
• OnFinality 公共端点为 https://bnb.api.onfinality.io/public（主网）和 https://bnb-testnet.api.onfinality.io/public（测试网）。
• 一小部分方法——eth_chainId、eth_getBalance、eth_call、eth_getLogs、eth_sendRawTransaction——覆盖了大多数生产流量。
• 在客户端签名交易；不要依赖托管端点上的 eth_sendTransaction。
• eth_getLogs 范围限制和 nonce 处理是生产事件的两个最常见来源。
• 从共享 RPC API 端点开始，然后将繁重或延迟敏感的工作负载迁移到 专用节点。
• 始终配置备用端点并监控区块高度延迟。

常见问题

BSC 链 ID 是什么？ BNB Smart Chain 主网使用链 ID 56 (0x38)。测试网使用链 ID 97 (0x61)。

BSC 支持 WebSocket 吗？ 是的。BSC 主网同时支持 HTTP 和 WebSocket 传输。测试网访问仅支持 HTTP，因此请相应地规划订阅。

为什么我的 eth_getLogs 调用失败？ 通常是因为区块范围太宽，端点无法在一个请求中提供。缩小范围、分页或使用适合索引工作负载的端点。

我可以在 BSC 上使用我的以太坊工具吗？ 可以。BSC 与 EVM 等效，因此一旦设置正确的链 ID 和端点，ethers、viem、Hardhat 和 Foundry 即可使用。

如何获取测试网 BNB？ 在发送交易之前，使用 BSC 测试网水龙头为您的地址充值 tBNB。

何时应该迁移到专用节点？ 当共享吞吐量、日志查询或延迟成为反复出现的问题时——例如持续的 eth_getLogs 回填或延迟敏感的交易写入。

在哪里可以看到 OnFinality 支持哪些网络？ 支持的 RPC 网络 页面列出了当前网络覆盖范围和端点。