Gnosis API 暴露了什么，以及如何连接到它？

Gnosis API 是 Gnosis Chain 节点向应用程序暴露的 JSON-RPC 接口。如果您正在将钱包、基于 Safe 的资金管理工具、支付后端或索引器连接到 Gnosis，这就是您要调用的接口。本页面为您提供链设置、一个可用的请求、对典型 Gnosis 工作负载至关重要的方法，以及一种决定您实际需要哪种端点的方式。

哪种 Gnosis 端点适合您的工作负载？

在复制任何 URL 之前，请将端点类型与您的应用程序功能相匹配。Gnosis 流量通常是轻量读取和较重日志查询的混合，正确的选择取决于流量和一致性需求，而不是链本身。

如果您的调用是偶尔且只读的，共享端点是一个合理的起点。如果您在循环中轮询收据、跨大区块范围扫描日志，或者需要在负载下保持一致的响应时间，请规划托管或专用设置。您可以查看 RPC 定价 和 Gnosis 网络页面，在做出承诺之前了解可用选项。

Gnosis Chain 设置一览

这些是您输入到钱包、Hardhat 或 Foundry 配置或 ethers/viem 提供程序中的值。它们是稳定的，可以安全地硬编码在客户端配置中。

Gnosis 使用 xDAI 作为其 gas 代币，这与使用波动性资产支付 gas 的链有显著区别。对于支付和薪资用例，这简化了费用核算，但也意味着您的用户在发送交易之前需要手头有 xDAI。

钱包网络配置

大多数 EVM 钱包接受自定义网络条目。字段直接映射到上表：

{
  "chainId": "0x64",
  "chainName": "Gnosis",
  "nativeCurrency": { "name": "xDAI", "symbol": "XDAI", "decimals": 18 },
  "rpcUrls": ["https://gnosis.api.onfinality.io/public"],
  "blockExplorerUrls": ["https://gnosisscan.io"]
}

请注意，0x64 是链 ID 100 的十六进制形式。期望十六进制的钱包会拒绝十进制值，因此在调试连接错误时请保留两种形式。

发出您的第一个 Gnosis API 请求

每个 Gnosis API 调用都是一个 JSON-RPC POST。其形状与任何 EVM 链相同，因此一旦设置了端点和链 ID，现有工具无需修改即可工作。

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

成功的响应会以十六进制字符串返回最新区块高度。从那里开始，常见的后续调用是用于 xDAI 余额的 eth_getBalance、用于合约读取的 eth_call 和用于事件历史的 eth_getLogs。

在 JavaScript 中，通过提供程序库发出的相同请求如下所示：

import { JsonRpcProvider, formatEther } from "ethers";

const provider = new JsonRpcProvider(
  "https://gnosis.api.onfinality.io/public",
  { chainId: 100, name: "gnosis" }
);

const block = await provider.getBlockNumber();
const balance = await provider.getBalance("0xYourAddressHere");
console.log(block, formatEther(balance));

显式传递链 ID 有助于库尽早检测到不匹配，而不是静默查询错误的网络。

对 Gnosis 工作负载重要的方法

Gnosis 与 EVM 兼容，因此标准方法集适用。在实践中，少数方法承载了大部分流量：

• eth_call — 无需交易即可读取合约状态。这是 Safe 余额检查、代币元数据读取和大多数仪表板查询的支柱。
• eth_getLogs — 检索事件。日志查询是速率压力的最常见来源，因为单个请求可能跨越数千个区块。
• eth_getTransactionReceipt — 确认提交的交易是否已上链。支付服务大量轮询此方法。
• eth_sendRawTransaction — 广播已签名的交易。这是端点可靠性最重要的地方，因为广播丢失可能会让用户等待。
• eth_estimateGas 和 eth_gasPrice — 在签名前估算交易大小并设置费用。
• eth_getCode 和 eth_getStorageAt — 检查已部署的合约和原始状态，对工具和调试很有用。

如果您依赖实时事件流而不是轮询，请检查您选择的端点是否支持 WebSocket 订阅，例如用于新块头或日志的 eth_subscribe。并非每个共享端点都暴露 WebSocket 传输，因此在围绕订阅进行设计之前请确认这一点。

调试常见的 Gnosis API 故障

大多数 Gnosis API 问题都属于少数几类。最快的路径是在更改其他任何内容之前将症状与原因匹配。

一个有用的第一个诊断是单个 eth_chainId 调用。如果它没有返回 0x64，则您的客户端指向了错误的网络，下游的任何内容都不会按预期运行。

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

当共享端点不够用时

共享公共端点很方便，适用于开发、原型和低流量读取。当您的应用程序依赖一致的吞吐量或长时间运行的查询时，它们会成为瓶颈。

您已经超出共享端点的信号通常是操作性的而非戏剧性的：需要拆分为许多较小调用的日志查询、偶尔超时的收据轮询，或高峰时段 429 响应的激增。此时问题不是 Gnosis 是否有效，而是您的访问模式是否需要预留容量。

专用节点为您的应用程序提供自己的 Gnosis 节点，而不是共享池的一部分。这对于扫描宽日志范围的索引器、需要稳定 WebSocket 连接的中继器以及无法容忍其他租户流量影响其响应时间的服务来说很重要。OnFinality 同时提供托管 RPC API 访问和专用节点基础设施，因此您可以从共享端点开始，然后迁移到预留容量，而无需更改应用程序代码（除了 URL）。有关该过渡如何工作，请参阅 专用节点。

发布前的操作检查清单

一份简短的检查清单可以在用户之前捕获大多数生产问题：

1. 在您的提供程序配置中确认链 ID 100，而不仅仅是在 URL 中。
2. 添加备用端点，以便单个提供程序中断不会导致您的应用程序宕机。
3. 在您的库支持的情况下批量处理独立读取，而不是按顺序触发它们。
4. 限制 eth_getLogs 区块范围并分页，而不是一次性请求所有内容。
5. 为 429 和 5xx 响应添加指数退避。
6. 将原始 JSON-RPC 错误代码与您的应用程序错误一起记录，以便区分客户端错误和端点限制。
7. 对于 WebSocket 使用，实现重新连接和重新订阅，而不是假设持久连接。

如果您仍在端点类型之间做决定，RPC 提供商选择指南 更深入地介绍了评估标准，支持的 RPC 网络 显示了 Gnosis 在目录中的位置。

关键要点

• Gnosis API 是标准的 EVM JSON-RPC，因此一旦设置了链 ID 100，现有的 ethers、viem、Hardhat 和 Foundry 工具即可工作。
• Gnosis 使用 xDAI 支付 gas，这简化了费用核算，但要求用户在交易前持有 xDAI。
• eth_call、eth_getLogs 和 eth_getTransactionReceipt 驱动了大部分 Gnosis 流量；日志查询是速率压力的常见来源。
• 共享端点适用于开发和轻量读取；专用节点对索引器、中继器和高流量后端有意义。
• 在调试意外行为时，始终验证 eth_chainId 返回 0x64。

常见问题解答

Gnosis API 与 Ethereum API 相同吗？

在协议层面，是的。Gnosis 与 EVM 兼容，因此它使用相同的 JSON-RPC 方法名称和请求格式。区别在于链 ID（100）、gas 代币（xDAI）以及网络上的特定合约和状态。

Gnosis Chain ID 是什么？

Gnosis Chain 使用链 ID 100，十六进制为 0x64。期望十六进制的钱包和库会拒绝十进制形式。

使用 Gnosis API 需要 API 密钥吗？

这取决于端点。公共端点通常是开放的并受速率限制，而托管和专用端点使用与您的账户绑定的 API 密钥，以便您的流量获得自己的容量和支持路径。

我可以在 Gnosis 上使用 WebSocket 吗？

Gnosis 在节点级别支持 WebSocket 订阅，但并非每个共享端点都暴露 WebSocket 传输。在围绕 eth_subscribe 进行设计之前，请与您的提供商确认可用性。

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

大区块范围是最常见的原因。将范围拆分为较小的窗口并分页浏览结果，而不是在一次调用中请求宽范围。

如何从公共端点迁移到专用 Gnosis 节点？

在大多数情况下，您更改端点 URL 并添加 API 密钥。应用程序逻辑保持不变，因为 JSON-RPC 接口不变。查看 RPC 定价 和 Gnosis 网络页面 来规划迁移。