Polygon MATIC API：开发者应该了解什么？

快速决策指南：你需要哪个 Polygon API？

在深入研究端点和 SDK 之前，先了解 Polygon API 的概况会有所帮助。“Polygon MATIC API”这个术语可能指代多种不同的东西，选错会浪费工程时间。

对于大多数 dApp 开发者，原始 JSON-RPC 端点是基础。它提供完全控制，并可与任何以太坊工具（ethers、viem、web3.js）配合使用。如果你需要索引数据或支付特定功能，可以在其上添加专门的 API。

如果你正在构建生产级应用，你需要一个可靠的 RPC 提供商。OnFinality 提供托管的 Polygon RPC 端点，支持 HTTP 和 WebSocket，你可以比较定价以确定专用节点是否适合你的工作负载。

什么是 Polygon MATIC API？

Polygon（前身为 Matic Network）是一个兼容以太坊的权益证明链。“Polygon MATIC API”通常指用于与此链交互的接口。核心是 JSON-RPC API，它与以太坊的完全相同，因此任何以太坊库都可以直接使用。

历史上，MATIC 是用于支付 gas 的原生代币。在 POL 升级后，POL 现在是原生代币，但许多文档和工具仍引用 MATIC。API 本身没有变化——你仍然在发送交易和查询状态。

还有更高级别的 API：

• Matic.js：用于与 Polygon 桥合约交互的旧版 SDK。它仍在文档中，但正在逐步淘汰。
• 索引 API：像 Bitquery 这样的服务，提供 GraphQL 或 REST 端点，用于历史数据、代币余额和分析。
• 支付 API：像 Chaingateway 这样的服务，抽象了节点管理，并为存款提供 webhooks。

Polygon 链设置一览

配置应用时，你需要正确的链 ID 和 RPC URL。以下是 Polygon 主网的官方设置：

对于测试网，Polygon Amoy 测试网使用链 ID 80002 和公共 RPC URL https://polygon-amoy.api.onfinality.io/public。你可以在 Polygon 网络页面 上找到更多详细信息。

如何使用 JSON-RPC 连接到 Polygon

你可以使用任何兼容以太坊的库。以下是一个使用 ethers.js 读取余额和发送交易的示例：

const { ethers } = require("ethers");

const provider = new ethers.JsonRpcProvider("https://polygon.api.onfinality.io/public");

async function getBalance(address) {
  const balance = await provider.getBalance(address);
  console.log(`Balance: ${ethers.formatEther(balance)} POL`);
}

async function sendTransaction(signer, to, amount) {
  const tx = await signer.sendTransaction({
    to,
    value: ethers.parseEther(amount),
  });
  await tx.wait();
  console.log(`Tx hash: ${tx.hash}`);
}

对于原始 JSON-RPC 调用，你可以使用 curl：

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

这将返回最新的区块号，确认你的端点可用。

使用 Matic.js 进行桥操作

Matic.js 是用于与 Polygon 桥交互的旧版 SDK。它仍在文档中，但 Polygon Labs 推荐使用更新的替代方案来转移资金。如果你在维护现有代码，这里有一个快速示例：

const { POSClient, use } = require("@maticnetwork/maticjs");
const { Web3ClientPlugin } = require("@maticnetwork/maticjs-web3");
const HDWalletProvider = require("@truffle/hdwallet-provider");

use(Web3ClientPlugin);

const posClient = new POSClient();
await posClient.init({
  network: "mainnet",
  version: "v1",
  parent: {
    provider: new HDWalletProvider(privateKey, "https://ethereum-rpc.example.com"),
    defaultConfig: { from: userAddress },
  },
  child: {
    provider: new HDWalletProvider(privateKey, "https://polygon.api.onfinality.io/public"),
    defaultConfig: { from: userAddress },
  },
});

const erc20 = posClient.erc20("<token-address>");
const balance = await erc20.getBalance(userAddress);

请注意，Matic.js 已弃用，不适用于新项目。对于现代桥交互，请考虑使用官方 Polygon 桥 UI 或支付 API。

用于余额和历史的索引 API

如果你需要查询历史余额或代币持有者，像 Bitquery 这样的索引 API 可能比自己扫描区块更高效。例如，要获取地址的原生 POL 余额：

query {
  EVM(network: matic, dataset: combined) {
    Balances(
      where: {
        Balance: {
          Address: { is: "0x..." }
        }
      }
    ) {
      Currency { Symbol }
      Balance { Amount }
    }
  }
}

这些 API 对于分析仪表板、审计跟踪和钱包应用非常有用。它们通常需要 API 密钥，并有使用限制。

在公共、托管和专用 RPC 之间选择

对于生产应用，公共端点不够可靠。你有三个主要选项：

OnFinality 提供托管的 Polygon RPC，处理负载均衡和故障转移等基础设施问题。对于高吞吐量或存档需求，专用节点可能值得成本。

常见陷阱和故障排除

• 链 ID 不匹配：确保你的钱包使用主网链 ID 137，而不是 80001（旧 Mumbai 测试网）或 80002（Amoy）。
• 速率限制：公共端点经常限制请求。如果你看到 429 错误，请切换到托管提供商。
• WebSocket 断开：对于实时更新，使用 WebSocket，但实现重连逻辑。
• MATIC 与 POL：一些工具仍期望 MATIC。请检查你的库的文档以获取正确的符号。

关键要点

• Polygon MATIC API 主要是 JSON-RPC，与以太坊工具兼容。
• 选择正确的 API 层：原始 RPC 用于控制，索引 API 用于分析，支付 API 用于稳定币流程。
• 使用正确的链 ID (137) 和可靠的 RPC 提供商用于生产。
• OnFinality 提供托管的 Polygon RPC，支持 HTTP 和 WebSocket。

常见问题

MATIC 和 POL 有什么区别？

MATIC 是原始的原生代币。2024 年，Polygon 升级到 POL，现在作为 gas 代币和质押代币。API 和链 ID 保持不变。

我可以将以太坊库与 Polygon 一起使用吗？

可以，Polygon 与 EVM 兼容，因此 ethers.js、viem 和 web3.js 无需修改即可使用。只需将它们指向 Polygon RPC 端点即可。

公共 Polygon RPC 端点免费吗？

是的，公共端点 https://polygon.api.onfinality.io/public 免费使用，但有速率限制。对于生产环境，请考虑托管 RPC 计划。

如何为 Amoy 获取测试网 POL？

你可以使用 Amoy 水龙头，它链接在 Polygon 网络页面 上。

Matic.js 有什么用途？

Matic.js 是用于与 Polygon 桥交互的旧版 SDK。它已弃用，不适用于新项目，但现有代码可能仍在使用它。

OnFinality 是否支持 Polygon 的 WebSocket？

是的，OnFinality 的 Polygon 端点支持 HTTP 和 WebSocket。请查看网络页面了解详情。

如何在托管 RPC 和专用节点之间选择？

如果你需要高吞吐量、存档数据或自定义配置，专用节点可能更好。对于大多数应用，托管 RPC 在成本和可靠性之间提供了良好的平衡。有关更多信息，请参阅我们的 RPC 提供商选择指南。

公共端点的速率限制是多少？

公共端点受到速率限制以确保公平使用。要获得更高的限制，请在 OnFinality 上注册免费 API 密钥。

我可以将 Polygon 与 viem 一起使用吗？

可以，viem 开箱即用地支持 Polygon。你可以使用 createPublicClient({ chain: polygon, transport: http("https://polygon.api.onfinality.io/public") }) 创建客户端。

我在哪里可以找到受支持网络的完整列表？

访问支持的网络页面查看 OnFinality 支持的所有链。