Base RPC 示例：端点设置、curl 调用和调试

大多数搜索 Base RPC 示例的开发者只想要一样东西：一个可用的端点和一个能立即粘贴到终端中的请求。本页面提供了这些内容，然后解释了当示例进入实际应用时会遇到的设置和故障模式。

Base 是一个结算到以太坊的 OP Stack Layer 2，因此它使用标准的 EVM JSON-RPC。这意味着任何以太坊工具都可以与之配合使用，如果你以前使用过以太坊 RPC，下面的示例应该看起来很熟悉。重要的区别在于链 ID、区块浏览器以及如何处理测试网与主网。

在复制任何内容之前，选择正确的 Base 端点

Base 有两个你在开发过程中会连接的网络，混淆它们是导致“我的余额为零”困惑的最常见原因。使用此表进行选择。

上面的两个端点都是公共 OnFinality RPC URL，并接受 HTTP JSON-RPC。如果你需要一致的吞吐量、WebSocket 订阅、归档数据或 trace 调用，共享的公共端点不是正确的长期选择。当你超出原型阶段时，请比较 RPC 定价 和 专用节点，并查看 Base 网络页面 了解当前支持的传输方式。

一个快速规则：如果一笔交易应该花费真钱或触及用户资金，那么你就在主网（8453）上。如果你正在迭代合约逻辑，那么你几乎肯定在 Sepolia（84532）上。

钱包和框架的 Base 链设置

钱包和大多数框架需要相同的四个值。在 MetaMask、Rabby 或任何 EVM 钱包中手动添加 Base：

• 网络名称：Base
• RPC URL：https://base.api.onfinality.io/public
• 链 ID：8453
• 货币符号：ETH
• 区块浏览器：https://basescan.org

对于 Base Sepolia，将名称改为 Base Sepolia，RPC URL 改为 https://base-sepolia.api.onfinality.io/public，链 ID 改为 84532，浏览器改为 https://sepolia.basescan.org。

如果你将其接入前端，请定义一次链并重复使用。viem 链定义如下所示：

import { defineChain } from "viem";

export const base = defineChain({
  id: 8453,
  name: "Base",
  nativeCurrency: { name: "Ether", symbol: "ETH", decimals: 18 },
  rpcUrls: {
    default: { http: ["https://base.api.onfinality.io/public"] },
  },
  blockExplorers: {
    default: { name: "BaseScan", url: "https://basescan.org" },
  },
});

将链 ID 和 RPC URL 保留在一个配置对象中，而不是将字符串分散在各个组件中。当你以后切换到私有或专用端点时，只需更改一行，而无需在整个代码库中搜索。

一个可以立即运行的最小 curl 示例

最快的健全性检查是通过 HTTP 进行单个 JSON-RPC 调用。这向 Base 请求最新的区块号：

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

响应是一个十六进制字符串，而不是十进制数字：

{ "jsonrpc": "2.0", "id": 1, "result": "0x13a2f1c" }

使用 parseInt(result, 16) 进行转换。如果数字在调用之间不断攀升，则你的端点已上线并同步。如果返回错误对象，请跳至下面的调试部分。

还有两个值得记在笔记中的调用。eth_chainId 确认你正在与你认为的网络通信：

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

它应该返回 0x2105，即十六进制的 8453。而 eth_getBalance 检查地址：

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

将零地址替换为真实地址。结果以 wei 为单位，因此除以 1e18 得到 ETH。

无需猜测地读取响应

JSON-RPC 响应总是两种形状之一。要么有 result 字段，要么有带有 code 和 message 的 error 对象。没有第三种情况，也没有 HTTP 状态码能告诉你全部信息，因为许多 RPC 错误仍然返回 HTTP 200。

这就是为什么“它返回了 200 但我的应用崩溃了”如此常见。你的客户端必须检查 error 字段，而不仅仅是 HTTP 状态。大多数成熟的库（如 viem 和 ethers）会为你做这件事，但手工编写的 fetch 调用通常不会。

当你收到错误时，首先读取 code：

• -32601 表示该方法不存在或未在该端点上启用。
• -32602 表示你的参数格式错误，通常是缺少 0x 前缀或参数数量错误。
• -32000 是通用的服务器端错误，通常指向节点无法服务的请求，例如范围太大。
• 429 或关于速率限制的消息意味着你发送的请求对于你所在的端点层级来说太多。

调试路径：从症状到修复

当出现问题时，请按照此表进行操作，而不是随意更改代码。

eth_getLogs 的情况值得注意。公共端点通常会限制一次调用中可以查询的区块范围。如果你正在索引事件，请以较小的窗口分页浏览历史记录，而不是一次请求数百万个区块。这是一个请求形状问题，而不是网络问题，并且是 Base 索引器似乎“停止工作”的最常见原因之一。

当公共示例不够用时

公共端点非常适合上面的示例和轻量级开发。它不是为具有突发负载、WebSocket 订阅或大量归档查询的生产流量而设计的。你已经超出它的迹象：

• 在高峰使用期间看到间歇性的 429 响应。
• 需要通过 WebSocket 使用 eth_subscribe 获取实时事件。
• 需要共享端点不暴露的历史状态或 trace 数据。
• 想要可预测的容量而不是尽力而为的共享。

此时，决定是在托管 RPC API 和专用节点之间。OnFinality 两者都提供：托管 RPC API 服务 适用于希望无需运行基础设施即可获得端点的团队，以及 专用节点 适用于需要隔离容量的工作负载。如果你在一般性地权衡提供商，提供商选择指南 介绍了标准。具体到 Base，请从 Base 网络页面 和 Base Sepolia 页面 开始，然后查看 定价 和完整的 支持网络 列表。

在 Base Sepolia 上测试而不浪费时间

Sepolia 是你运行大多数示例的地方，因此请一次性正确设置。链 ID 是 84532，浏览器是 sepolia.basescan.org，端点是 https://base-sepolia.api.onfinality.io/public。你需要测试 ETH 来部署合约或发送交易；从 Base Sepolia 水龙头获取，然后在调试其他任何内容之前使用 eth_getBalance 确认它已到达。

一个常见的陷阱：在 Sepolia 上部署的合约与主网上的同一合约具有不同的地址。切勿在两者之间复制地址。为每个网络保留单独的环境变量，并按链 ID 加载它们，这样测试网地址就永远不会泄漏到主网交易中。

关键要点

• Base 主网使用链 ID 8453；Base Sepolia 使用 84532。在调试其他任何内容之前，请使用 eth_chainId 确认。
• 公共 OnFinality 端点是 https://base.api.onfinality.io/public 和 https://base-sepolia.api.onfinality.io/public。
• JSON-RPC 错误可能以 HTTP 200 状态到达，因此请始终检查响应正文中的 error 字段。
• eth_getLogs 区块范围限制和 429 响应是工作示例在负载下中断的两个最常见原因。
• 当你需要 WebSocket 订阅、归档或 trace 数据，或可预测的容量时，请迁移到私有或专用端点。

常见问题

Base RPC URL 是什么？ 对于主网，公共 OnFinality 端点是 https://base.api.onfinality.io/public。对于测试网，使用 https://base-sepolia.api.onfinality.io/public。生产应用通常使用私有或专用端点。

Base 的链 ID 是什么？ Base 主网是 8453（十六进制 0x2105）。Base Sepolia 是 84532。

为什么我的 Base RPC 调用返回 HTTP 200 的错误？ JSON-RPC 在响应正文中报告应用级错误，而不是通过 HTTP 状态。检查 error 对象及其 code 字段。

我可以将 WebSocket 与 Base 一起使用吗？ WebSocket 支持取决于端点层级。公共 HTTP 端点用于基本调用；查看 Base 网络页面 了解支持的传输方式，并考虑使用专用节点进行订阅。

我需要 Base 的归档节点吗？ 仅当你查询历史状态或宽日志范围时。标准的近期区块查询在普通端点上工作。归档和 trace 访问通常是专用节点的功能。

如何避免 Base RPC 上的速率限制？ 尽可能批处理和缓存，避免紧密的轮询循环，并在请求量增长时迁移到私有或专用端点。有关层级，请参阅 RPC 定价。