Polygon RPC API：端点设置、方法与调试

Polygon RPC API 是您的应用程序用来读取 Polygon PoS 状态和广播交易的 JSON-RPC 接口。如果您正在连接钱包、后端索引器或 dApp 前端，您需要三样东西：正确的链设置、可用的请求模式，以及清楚了解哪些故障是您的代码问题，哪些是端点问题。本页为您提供这三样内容，然后帮助您决定共享公共端点还是专用 Polygon 节点更适合您的工作负载。

链设置一览

在发送单个请求之前，请确认网络参数。Polygon PoS 主网和 Polygon Amoy 测试网使用不同的链 ID 和不同的原生货币符号，混淆它们是设置中最常见的错误之一。

这些公共端点对于快速测试和低流量读取很有用。对于生产流量，会应用速率限制和共享容量，因此大多数团队会转向托管或专用端点。您可以查看完整的 Polygon RPC 网络页面 了解支持的传输方式和当前访问选项。

如果您要将 Polygon 添加到钱包或前端网络切换器，配置通常如下所示：

const polygonMainnet = {
  chainId: '0x89', // 137
  chainName: 'Polygon Mainnet',
  nativeCurrency: { name: 'POL', symbol: 'POL', decimals: 18 },
  rpcUrls: ['https://polygon.api.onfinality.io/public'],
  blockExplorerUrls: ['https://polygonscan.com'],
};

如何决定：公共端点还是专用节点

决策通常取决于工作负载形态，而不是抽象地比较哪个端点“更好”。使用下表来定位您自己的流量模式。

一个实用的规则：如果您的应用可以容忍偶尔的 429 响应，并且您只读取最近状态，那么共享端点就足够了。如果您依赖日志查询、历史状态、跟踪调用或可预测的吞吐量，请规划托管或专用设置。OnFinality 为需要隔离容量的团队提供托管 RPC API 访问和 专用节点。

发送您的第一个 Polygon JSON-RPC 请求

每个 Polygon RPC 调用都遵循相同的 JSON-RPC 2.0 信封。从简单的健康检查开始，确认端点可达并返回预期的链。

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

正确的响应会以十六进制字符串返回链 ID：

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

如果您得到 0x89，则您在 Polygon 主网上。如果您得到 0x13882，则您在 Amoy 测试网（80002）上。如果您得到完全不同的值，则您的端点指向另一个网络。

读取余额遵循相同的结构：

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

在 JavaScript 中，通过 ethers 的相同调用如下所示：

import { JsonRpcProvider } from 'ethers';

const provider = new JsonRpcProvider('https://polygon.api.onfinality.io/public');
const block = await provider.getBlockNumber();
const balance = await provider.getBalance('0x0000000000000000000000000000000000001010');
console.log({ block, balance: balance.toString() });

您实际会用到的 Polygon RPC 方法

Polygon PoS 与 EVM 兼容，因此方法集与以太坊匹配。以下方法涵盖了大多数生产流量。

有两个 Polygon 特有的细节值得记住。首先，原生 gas 代币是 POL，著名的费用地址 0x0000000000000000000000000000000000001010 用于 gas 计算。其次，由于 Polygon PoS 历史上曾出现重组和状态同步延迟，索引日志的后端应跟踪确认数，而不是假设区块一出现就是最终确定的。

用于实时数据的 WebSocket 订阅

如果您需要推送更新而不是轮询，请通过 WebSocket 连接。OnFinality Polygon 端点同时支持 HTTP 和 WebSocket 传输。

import WebSocket from 'ws';

const ws = new WebSocket('wss://polygon.api.onfinality.io/public/ws');

ws.on('open', () => {
  ws.send(JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_subscribe',
    params: ['newHeads'],
  }));
});

ws.on('message', (data) => {
  const msg = JSON.parse(data.toString());
  if (msg.method === 'eth_subscription') {
    console.log('New head:', msg.params.result.number);
  }
});

WebSocket 连接是有状态的。如果您的进程重启或套接字断开，您必须重新订阅。构建带有退避的重连逻辑，并在重连时重新获取最新区块，以免在间隙期间错过事件。

调试路径：常见的 Polygon RPC 故障

当请求失败时，错误消息通常会指出原因。使用此表从症状转向修复。

针对故障端点的快速诊断循环：

# 1. 端点是否存活并在正确的链上？
curl -s https://polygon.api.onfinality.io/public -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"eth_chainId","params":[]}'

# 2. 是否同步到头部？
curl -s https://polygon.api.onfinality.io/public -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"eth_blockNumber","params":[]}'

如果 eth_chainId 正确但 eth_blockNumber 落后于公共区块浏览器，则节点可能正在追赶。如果两者都成功但您的应用仍然失败，问题可能出在您的请求负载、ABI 或 nonce 处理上，而不是端点。

生产就绪检查清单

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

• 链 ID 和原生货币与您打算使用的网络匹配（主网为 137，Amoy 为 80002）。
• 您有备用端点或提供商，以防主端点不可用。
• 日志查询被分块为端点接受的范围。
• WebSocket 客户端实现重连和重新订阅。
• 您监控错误率、延迟和区块高度滞后，而不仅仅是检查正常运行时间。
• 归档和跟踪需求在启动前与提供商确认，而不是之后。

一个简单的监控探针可以让您提前发现故障：

async function probe(url) {
  const start = Date.now();
  const res = await fetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] }),
  });
  const json = await res.json();
  return { ok: res.ok, latencyMs: Date.now() - start, block: parseInt(json.result, 16) };
}

定期运行此探针，并在延迟上升或区块高度停止前进时发出警报。

OnFinality 的定位

OnFinality 为 Polygon 和许多其他网络提供 RPC API 访问和专用节点基础设施。对于快速测试，上述公共端点就足够了。对于需要可预测吞吐量、归档访问或隔离容量的生产应用，托管或专用设置消除了共享端点的限制。您可以在 RPC 定价页面 上比较计划，并在 支持的 RPC 网络 列表中浏览其他链。如果您仍在权衡提供商，RPC 提供商选择指南 会介绍最重要的评估标准。

关键要点

• Polygon 主网使用链 ID 137 和 POL 作为原生货币；Amoy 测试网使用 80002。
• Polygon RPC API 与 EVM 兼容，因此适用标准的以太坊 JSON-RPC 方法。
• 公共端点适合测试和轻量读取，但日志查询、归档数据和高吞吐量通常需要托管或专用端点。
• 大多数故障可追溯到速率限制、日志范围限制、nonce 同步或缺少归档数据，每个都有特定的修复方法。
• 监控延迟和区块高度滞后，而不仅仅是正常运行时间，并始终保留备用端点。

常见问题

什么是 Polygon RPC API？

它是 JSON-RPC 接口，允许您的应用程序通过节点读取 Polygon PoS 状态并提交交易。它遵循 JSON-RPC 2.0 标准，并支持与以太坊相同的方法集，因为 Polygon PoS 与 EVM 兼容。

Polygon 链 ID 是什么？

Polygon 主网使用链 ID 137（0x89）。Polygon Amoy 测试网使用链 ID 80002（0x13882）。在发送交易之前，请始终使用 eth_chainId 确认链 ID。

Polygon RPC 支持 WebSocket 吗？

是的。OnFinality Polygon 端点同时支持 HTTP 和 WebSocket 传输，这使您可以订阅 newHeads、日志和其他事件，而不是轮询。

为什么 eth_getLogs 在 Polygon 上失败？

大多数日志查询失败源于请求的区块范围太宽。共享端点限制范围以保护容量。将查询拆分为更小的窗口，或使用支持更宽范围的提供商。

我可以在生产环境中使用公共 Polygon RPC 端点吗？

可以，但共享公共端点会应用速率限制，并且可能不提供归档或跟踪数据。对于生产流量，托管或专用端点可提供更可预测的行为。

如何获取 Amoy 测试网 POL？

使用 Polygon Amoy 水龙头请求测试网 POL 用于开发。Amoy 网络使用与主网相同的 POL 代币符号，但在单独的链上，因此测试网资金没有主网价值。