Polygon Blockchain API：低 Gas 稳定币支付

这个名称冲突值得再花两段来说清楚，因为「polygon api」的搜索结果中，有一半指向了错误的产品。Polygon.io 是一家美国公司，销售市场数据源：股票报价、期权链、外汇 K 线。它的 API 回答的是「AAPL 昨天的成交价是多少」这类问题。它没有区块链，没有代币，与本页所讲的网络也没有任何关系。

由 Polygon Labs 运营的 Polygon 区块链，是一条兼容 EVM 的权益证明网络，负责结算代币交易。无论是原始的 JSON-RPC，还是像 Chaingateway 这样的支付层，它的 API 接口回答的是「客户的 USDC 到账了吗」这类问题，执行的是「支付 50 USDT」这类指令。如果你需要的是股票代码和 OHLC K 线，关掉这个标签页去搜索 Polygon.io。如果你需要以几分之一美分的 gas 费转移稳定币，请继续阅读。

在 Chaingateway 的 Polygon 接口上，最常见的构建对象是稳定币支付处理，经济学能解释原因。每一笔 ERC-20 转账都需要 gas。在以太坊主网上，一笔 USDT 转账的 gas 成本可能超过这笔小额付款本身；在 Polygon 上，同样的转账最多只需几分钱。在这里向某人收取 2 USDC 购买一件数字商品是可行的。在 L1 上则不可行。

数字能佐证这一点。截至 2026 年年中，手续费追踪工具显示 Polygon PoS 上一笔典型的 USDT 转账费用在十分之一美分到两美分之间，即使网络繁忙也很少超过几美分。同样的转账在以太坊主网上，从清淡周的远低于一美元，到拥堵高峰期的数美元不等。这个差距会随 gas 市场波动，但多年来一直维持在两到三个数量级，对于建立在小额支付之上的商业模式来说，这个差距就是整个商业逻辑本身。

一次典型的结账是这样的：你的后端为客户分配一个存款地址并展示二维码，客户从任意钱包或交易所发送 USDC 或 USDT。大约两秒后，转账就进入了某个区块。Webhook 被触发，你的服务器验证 HMAC 签名，订单切换为已付款。没有卡组织网络，没有拒付，也无需等待银行营业时间。

链上事实会随时间漂移，因此下面给出带日期的当前数据。截至 2026 年 7 月初：

根据 PolygonScan 的出块时间数据，区块平均每 2 到 2.3 秒到达一次，交易最终确定时间大约为 5 秒。对存款而言，这意味着「客户按下发送」到「可以安全入账」之间的间隔只有个位数秒。

gas 代币是 POL。从 MATIC 的迁移发生在 2024 年 9 月 4 日，按 1:1 的比例进行，PoS 链上的余额被自动转换；Polygon 报告称迁移在大约一年后完成了 99%。此后，Polygon PoS 上的每一笔交易都以 POL 支付 gas。

测试网是 Amoy，锚定在以太坊的 Sepolia 上。它取代了较早的 Mumbai 测试网，后者与其依赖的 Goerli 网络一起于 2024 年 4 月 13 日退役。仍然提到 Mumbai 的教程已经过时；它们描述的流程通常在 Amoy 上原样可用。

每一笔 Polygon 交易都以 POL 支付 gas，这个代币在 2024 年 9 月以 1:1 的比例取代了 MATIC。发送地址需要为此保留少量 POL 余额；接收代币对收款方来说不花任何成本。gas 价格由 API 自动设定，因此集成很少需要手动调整。

PoS 链上的余额已自动从 MATIC 迁移到 POL，因此仍然提到 MATIC 的旧文档，今天指的就是 POL。常见做法是为付款准备一个充值好的热钱包，外加从存款地址发起的合并转账，你可以按需为这些地址充值 POL。由于单笔转账只会燃烧极小一部分 POL，适量的储备就能覆盖大量流量。

每一个标准 ERC-20 合约在 Polygon 上都能正常工作。USDT、USDC 和 DAI 开箱即用，含小数位处理。如果你发行了自己的代币，把它的合约地址传给同一个接口，它的表现会和其他代币一样。NFT 和 DeFi 代币遵循同样的规则。由于 API 在各链上是一致的，为 Polygon 编写的代码，只需在 URL 中替换链名段，就能同样运行在 Ethereum、BSC 或 Arbitrum 上。

吞吐量足以支撑游戏等高频负载，成本又足够低，使得那些在以太坊 L1 上因价格过高而无法实现的用例变得可行。大型消费品牌已经在 Polygon 上推出了忠诚度计划和收藏品，这把主流用户吸引到了这条网络上，机构项目也持续选择它作为结算层。对你的团队而言，入门成本很低：这条链兼容 EVM，你在以太坊上积累的一切知识都可以原样迁移过来。

三次请求就能覆盖整个支付循环。确切的请求结构见 API 参考文档；如需在 Polygon 测试网（Amoy）上演练，添加请求头 X-Network: testnet。

导入一个已有钱包：

curl -X POST https://app.chaingateway.io/api/v2/polygon/addresses/import \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xYourAddress",
    "privatekey": "0xYourPrivateKey",
    "password": "YourWalletPassword"
  }'

该密码用于在平台上保护导入的私钥；之后从该地址发起的发送操作会使用这个密码，而不是原始私钥。

在 Polygon 上发送 USDT（合约地址 0xc2132D05D31c914a87C6611C10748AEb04B58e8F）：

curl -X POST https://app.chaingateway.io/api/v2/polygon/transactions/erc20 \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contractaddress": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "from": "0xYourSenderAddress",
    "to": "0xRecipientAddress",
    "amount": 5,
    "password": "YourWalletPassword"
  }'

获取历史 Webhook 通知列表，这是与你的数据库核对存款的最快方式：

curl https://app.chaingateway.io/api/v2/polygon/webhooks/notifications \
  -H "Authorization: Bearer $CHAINGATEWAY_API_KEY"

同样这三次调用可以用任何标准 HTTP 客户端直接翻译成 PHP、Python 或 Node；这里没有需要安装的 Polygon 专用库。

下面是完整的收款流程，以生产环境而非演示项目的方式呈现。

地址映射与归属

每位客户或每笔订单都拥有自己的存款地址，存放在一张表里：你的内部 ID、地址、时间戳。传入 Webhook payload 中的地址就是把转账与订单绑定的查找键，在该列上建立唯一索引可以保证任何一笔存款都不会匹配到两笔订单上。如果你的平台已经在管理密钥，可以通过 POST /api/v2/polygon/addresses/import 一次性注册它们，并按 Webhook 指南中的说明挂接 Webhook。

验证并为存款入账

客户付款后，转账大约两秒内就会进入某个区块，通知会在片刻之后到达你的接口。你的处理程序首先验证 HMAC 签名，按地址查找订单，然后在入账前再检查一件事：它是否曾经见过这笔交易哈希。用唯一约束存储每一个已处理的哈希，让数据库拒绝重复项。你的服务器错过的一次投递并没有丢失：它会出现在 GET /api/v2/polygon/webhooks/notifications/failed 中，POST /api/v2/polygon/webhooks/notifications/{id}/retry 会再次发送它，因此你这边的超时永远不会导致存款丢失；幂等处理正是防止重放通知造成重复入账的关键。

放行商品前应该等多久

这是一项业务决策，而不是技术决策。Polygon 上的最终确定大约在打包入区块后 5 秒到达，因此即使是谨慎的策略成本也很低：一笔 3 USDC 的购买可以在收到第一条通知时就入账，一笔四位数的存款则等到你对照 GET /api/v2/polygon/webhooks/notifications 完成对账检查后再放行。这个接口也可以充当你的审计轨迹；每晚与你自己的账本进行一次差异比对，能捕获两小时故障期间可能掩盖的任何问题。

清扫存款地址

存款地址会随时间积累余额，因此要安排定期清扫：用同一个 POST /api/v2/polygon/transactions/erc20 调用，把 from 设为存款地址，把余额合并到你的资金库钱包。每个被清扫的地址都需要一点点 POL 用于 gas，按 Polygon 的价格，这点金额小到可以批量预先充值。

提现是错误会直接导致资金损失的流程，两个习惯能消除大部分风险。

入队前先校验。目标地址必须能解码为一个 20 字节的 0x 值，当它包含大小写混合字母时，EIP-55 校验和必须匹配。在表单阶段就拒绝失败的输入，让用户能够修正拼写错误；API 在广播前会再次校验，但发现得越早，成本就越低。

先写入，再发送。为每笔付款在数据库中创建一行记录，配合一个状态机（queued、sent、confirmed），让一个工作进程为每一行恰好调用一次 POST /api/v2/polygon/transactions/erc20，并立即存储返回的交易哈希。把这个哈希作为 PolygonScan 链接展示给用户，他们就能自行追踪提现进度，而不必写信给客服。如果 API 调用超时，不要凭直觉再发一次：先检查通知列表和你自己的记录以确认什么都没有发出去，再谨慎地重试。热钱包需要一份 POL 浮动余额用于 gas；在 Polygon 上，少量余额就能覆盖数千笔转账，因此每月充值一次就够了。

Amoy 是 Polygon 锚定在 Sepolia 上的测试网，自 2024 年初作为 Mumbai 的替代者上线，本页每个接口只需加一个请求头就能运行在它上面：

X-Network: testnet

不需要单独的账户，不需要第二个密钥，也没有其他改动。测试用 POL 可以从公共的 Amoy 水龙头获取，地址和机制与主网完全一致。

把测试运行花在失败路径上，而不是理想路径上。关闭你的 Webhook 接口，发送一笔存款，恢复接口，然后读取失败通知列表，通过重试接口重放这次投递。重放一条你已经处理过的通知，确认你的幂等性检查会拒绝它。把同一笔付款提交两次，验证只有一笔真正发出。每一次演练在 Amoy 上只需几分钟，却能防止之后一次真实的事故；当这三项都通过后，删除该请求头，同一份代码就已经在生产环境中运行。

你的 Webhook 接口向账本供数，因此要像对待其他任何涉及资金的输入一样加固它。

签名优先。在个人资料设置中设置一个私密密钥，每条通知都会携带一个 X-Signature 请求头：对 payload 的 txid 做 HMAC-SHA256 并以该密钥为键，再用 base64 编码。在处理 payload 的其他内容之前，重新计算它并以恒定时间进行比较。任何校验失败的请求都返回 4xx 响应，不做处理。Python、Java、PHP 和 JavaScript 的验证示例见 Webhook 指南。

Chaingateway 的 IP 白名单守护着反方向：在账户面板中，你可以把 API 访问限制为你自己服务器 IP 的一个列表，这样泄露的 API 密钥在其他任何地方都无法使用。它保护的是你的密钥，而不是你的 Webhook 接收端——对于接收端，签名才是真实性校验。针对重放的通知——按定义它们携带有效签名——你的交易哈希约束是防线；重复项会被确认但丢弃。只通过 HTTPS 提供该接口，并让密钥远离 URL，因为 URL 会泄露进你无法控制的基础设施的日志中。

错误以标准的 HTTP 状态码和 JSON 响应体返回，因此你惯用的处理模式可以原样适用。

401 是认证问题：Bearer 令牌缺失、被撤销或拼写错误。其他 4xx 响应属于校验失败，例如错误的校验和或未知字段，响应体会指明问题所在；重试相同的请求不可能成功。429 表示已达到套餐的速率限制；用逐渐增加的延迟退避，如果在正常运营（而不是突发流量）中频繁触及它，请查看定价页面。

对于 5xx 响应，读操作可以放心重试。只有在通过通知列表和你自己的付款记录确认第一次尝试确实没有被广播之后，才重试发送操作。把完整的响应体和触发它的请求一起记录在日志中；这种配对能缩短每一次调试过程和支持沟通。每个接口的状态码和错误结构见 API 参考文档。

核心模式是接受支付：每笔订单一个存款地址，每笔传入转账一个 Webhook，几秒内完成结算。商户用它来做收银，平台用它来管理用户余额，通过同一批接口监控数千个地址的存款并处理提现。

低廉的 gas 成本还开启了在其他地方根本行不通的模式：向内容创作者发放的小额付款、以普通 ERC-20 转账形式执行的空投和归属计划、以稳定币计费的周期性订阅账单，以及手续费只是几分钱而不是百分比的跨境支付。