Polygon Blockchain API:低 Gas 稳定币支付
通过一个 REST API 在 Polygon 上接受 USDC 和 USDT 支付。低 Gas 手续费、存款 Webhook,无需运行节点。
Chaingateway 的 Polygon API 是一个 REST API。它在 Polygon 权益证明链上转移 POL,以及 USDC、USDT 等 ERC-20 代币。它通过 HTTPS 发送代币,并在有存款到账时向你的服务器发送一条 Webhook。它不是 Polygon.io 那样的市场数据服务。7 天免费试用无需 KYC。
先说明一点。如果你在寻找股票和期权市场数据,你要找的是 Polygon.io,一家与本产品无关的公司。本页讲的是在 Polygon 链上转移代币,其中 POL(原 MATIC)用于支付 gas。
认证方式是 Bearer 令牌,响应是 JSON。注册只需一分钟。
Polygon 存款如何到达我的应用?
Polygon 存款以签名 Webhook 的形式到达你的应用。你通过 REST API 导入钱包,API 监控 Polygon,并把这笔转账发送到你的服务器。
两个 Polygon:区块链与市场数据公司
「polygon api」的搜索结果中,有一半指向了错误的产品。所以这个名称冲突值得再花两段来说清楚。
Polygon.io 是一家美国公司,销售市场数据源:股票报价、期权链、外汇 K 线。它的 API 回答的是「AAPL 昨天的成交价是多少」这类问题。它没有区块链,没有代币,与本页所讲的网络也没有任何关系。
Polygon 区块链由 Polygon Labs 运营。它是一条兼容 EVM 的权益证明网络,负责结算代币交易。无论是原始的 JSON-RPC,还是像 Chaingateway 这样的支付层,它的 API 接口都回答「客户的 USDC 到账了吗」这类问题。它们也执行「支付 50 USDT」这类指令。
如果你需要的是股票代码和 OHLC K 线,关掉这个标签页去搜索 Polygon.io。如果你需要以几分之一美分的 gas 费转移稳定币,请继续阅读。
在 Polygon 上构建所需的一切
Webhook(IPN)
Polygon 大约每 2 秒产生一个区块。当 USDC 或 USDT 到达你的某个存款地址时,Chaingateway 会在转账结算后立即把解码后的事件 POST 到你的服务器。
通常在几秒内完成。设置个人密钥后,通知会在 X-Signature 请求头中携带 HMAC 签名。你的接口错过的投递会保留在一个失败通知列表中,供你重放。
简单的交易
Polygon 上的代币转账只需几分钱,而不是几美元。因此在以太坊主网上不划算的批量付款,在这里是家常便饭。一次 POST 请求即可发送 POL 或任意 ERC-20 代币;gas 参数由 API 处理。
安全的地址处理
Polygon 兼容 EVM:使用与以太坊相同的 0x 地址和 EIP-55 校验和。API 会在构建交易前校验每一个地址,平台是非托管的,因此你的密钥始终由你自己保管。
解码后的查询
合约事件和代币转账以解码后的 JSON 返回,而不是原始日志,金额已按代币小数位调整完毕。
Polygon 接口参考
RPC 提供商把 Polygon 文档组织成一长串分类。执行方法在这里,调试方法在那里,每一类都有几十个条目。一次支付集成需要的是更简短的地图。
Chaingateway 的 Polygon 接口面覆盖大约三十个接口。它们包括地址、余额、区块、gas 价格、解码后的交易、NFT 和 Webhook。但一个支付流程主要依赖其中几个:
| 类别 | 方法 | 接口 | 作用 |
|---|---|---|---|
| 地址与密钥 | POST | /api/v2/polygon/addresses | 创建新的存款地址 |
| 地址与密钥 | POST | /api/v2/polygon/addresses/import | 注册一个已有私钥,让 API 能从该地址发送 |
| 交易 | POST | /api/v2/polygon/transactions | 发送 POL |
| 交易 | POST | /api/v2/polygon/transactions/erc20 | 构建、签名并广播一笔 ERC-20 转账 |
| 存款通知 | POST | /api/v2/polygon/webhooks | 为某个地址创建 Webhook |
| 存款通知 | GET | /api/v2/polygon/webhooks/notifications | 列出发送到你服务器的每一条 Webhook 通知 |
| 账户 | GET | /api/account | 检查你的账户和套餐状态 |
它们全部使用同一个 Bearer 令牌进行认证。添加 X-Network: testnet 请求头可以把任意请求指向 Amoy 测试网而非主网。请求和响应结构见 API 参考文档。
稳定币支付:选择 Polygon 的理由
在 Chaingateway 的 Polygon 接口上,最常见的构建对象是稳定币支付处理。经济学能解释原因。
每一笔 ERC-20 转账都需要 gas。在以太坊主网上,一笔 USDT 转账的 gas 成本可能超过这笔小额付款本身。在 Polygon 上,同样的转账最多只需几分钱。
在这里向某人收取 2 USDC 购买一件数字商品是可行的。在 L1 上则不可行。
数字能佐证这一点。截至 2026 年年中,手续费追踪工具显示 Polygon PoS 上一笔典型的 USDT 转账费用在十分之一美分到两美分之间。即使网络繁忙,也很少超过几美分。同样的转账在以太坊主网上,从清淡周的远低于一美元,到拥堵高峰期的数美元不等。
这个差距会随 gas 市场波动,但多年来一直维持在两到三个数量级。对于建立在小额支付之上的商业模式来说,这个差距就是整个商业逻辑本身。
一次典型的结账是这样的。你的后端为客户分配一个存款地址并展示二维码,客户从任意钱包或交易所发送 USDC 或 USDT。
大约两秒后,转账就进入了某个区块。Webhook 被触发,你的服务器验证 HMAC 签名,订单切换为已付款。没有卡组织网络,没有拒付,也无需等待银行营业时间。
Polygon PoS 数据一览
链上事实会随时间漂移,因此下面给出带日期的当前数据。截至 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 上的 gas,POL 又是什么?
发送地址以 POL 支付 gas,这个代币在 2024 年 9 月以 1:1 的比例取代了 MATIC。它需要为此保留少量 POL 余额;接收代币对收款方来说不花任何成本。gas 价格由 API 自动设定,因此集成很少需要手动调整。
PoS 链上的余额已自动从 MATIC 迁移到 POL。因此仍然提到 MATIC 的旧文档,今天指的就是 POL。
常见做法是为付款准备一个充值好的热钱包,外加从存款地址发起的合并转账。你可以按需为这些地址充值 POL。由于单笔转账只会燃烧极小一部分 POL,适量的储备就能覆盖大量流量。
在 Polygon 上收发任意代币,包括你自己的代币
每一个标准 ERC-20 合约在 Polygon 上都能正常工作。USDT、USDC 和 DAI 开箱即用,含小数位处理。如果你发行了自己的代币,把它的合约地址传给同一个接口,它的表现会和其他代币一样。NFT 和 DeFi 代币遵循同样的规则。
API 在各链上是一致的。因此为 Polygon 编写的代码也能运行在 Ethereum、BSC 或 Arbitrum 上。只需在 URL 中替换链名段。
为什么开发者选择 Polygon
吞吐量足以支撑游戏等高频负载。成本又足够低,使得那些在以太坊 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 专用库。
三次请求,无需 Polygon 专用库——创建账户,在 Amoy 测试网上运行它们。
从存款地址到订单入账
下面是完整的收款流程,以生产环境而非演示项目的方式呈现。
地址映射与归属
每位客户或每笔订单都拥有自己的存款地址,存放在一张表里:你的内部 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 的价格,这点金额小到可以批量预先充值。
如何避免在 Polygon 上重复发送付款?
入队前先校验地址,发送前先写入数据库记录。提现是错误会直接导致资金损失的流程,这两个习惯能消除大部分风险。
入队前先校验。目标地址必须能解码为一个 20 字节的 0x 值。
当它包含大小写混合字母时,EIP-55 校验和必须匹配。在表单阶段就拒绝失败的输入,让用户能够修正拼写错误。API 在广播前会再次校验,但发现得越早,成本就越低。
先写入,再发送。为每笔付款在数据库中创建一行记录,配合一个状态机(queued、sent、confirmed)。让一个工作进程为每一行恰好调用一次 POST /api/v2/polygon/transactions/erc20,并立即存储返回的交易哈希。
把这个哈希作为 PolygonScan 链接展示给用户。他们就能自行追踪提现进度,而不必写信给客服。如果 API 调用超时,不要凭直觉再发一次。先检查通知列表和你自己的记录以确认什么都没有发出去,再谨慎地重试。
热钱包需要一份 POL 浮动余额用于 gas。在 Polygon 上,少量余额就能覆盖数千笔转账,因此每月充值一次就够了。
上主网之前,如何在 Amoy 上测试?
加一个请求头,本页每个接口就能运行在 Amoy 上。Amoy 是 Polygon 锚定在 Sepolia 上的测试网,2024 年初取代了 Mumbai:
X-Network: testnet
不需要单独的账户,不需要第二个密钥,也没有其他改动。测试用 POL 可以从公共的 Amoy 水龙头获取,地址和机制与主网完全一致。
把测试运行花在失败路径上,而不是理想路径上。关闭你的 Webhook 接口,发送一笔存款,再恢复接口。然后读取失败通知列表,通过重试接口重放这次投递。
重放一条你已经处理过的通知,确认你的幂等性检查会拒绝它。把同一笔付款提交两次,验证只有一笔真正发出。每一次演练在 Amoy 上只需几分钟,却能防止之后一次真实的事故。当这三项都通过后,删除该请求头,同一份代码就已经在生产环境中运行。
Webhook 安全实践
你的 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 转账形式执行的空投和归属计划。还有以稳定币计费的周期性订阅账单,以及手续费只是几分钱而不是百分比的跨境支付。
三步完成集成
获取你的 API 密钥。注册后密钥立即出现在你的仪表盘中。7 天试用无需 KYC。
发出你的第一个请求。快速入门指南会带你从注册走到第一笔交易。
设置 Webhook 并上线。注册一个回调后,存款就会推送到你的服务器,Webhook 指南涵盖了签名和通知历史。然后移除 X-Network: testnet 请求头,同一份代码即可运行在主网上。
各条链支持哪些功能
Polygon 遵循与以太坊相同的 ERC-20 请求模式,但 gas 成本只是其一小部分。下表将它与该 API 覆盖的其他六条链并列展示。
| 链 | 地址 | 代币转账 | 存款 Webhook |
|---|---|---|---|
| Bitcoin | POST /api/v2/bitcoin/wallets/{wallet}/addresses | —(无代币标准) | GET /api/v2/bitcoin/webhooks/notifications |
| Ethereum | POST /api/v2/ethereum/addresses/import | ERC-20:POST /api/v2/ethereum/transactions/erc20 | GET /api/v2/ethereum/webhooks/notifications |
| TRON | POST /api/v2/tron/addresses/import | TRC-20 和 TRC-10:POST /api/v2/tron/transactions/trc20 和 .../trc10 | GET /api/v2/tron/webhooks/notifications |
| Solana | POST /api/v2/solana/addresses | SPL:POST /api/v2/solana/transactions/SPL | — |
| BNB Smart Chain | POST /api/v2/bsc/addresses/import | BEP-20:POST /api/v2/bsc/transactions/bep20 | GET /api/v2/bsc/webhooks/notifications |
| Polygon | POST /api/v2/polygon/addresses/import | ERC-20:POST /api/v2/polygon/transactions/erc20 | GET /api/v2/polygon/webhooks/notifications |
| Arbitrum | POST /api/v2/arbitrum/addresses/import | ERC-20:POST /api/v2/arbitrum/transactions/erc20 | GET /api/v2/arbitrum/webhooks/notifications |
正确理解此表需要两点说明。第一:TRON 是平台上集成最深的链。除上述路由外,参考文档还记录了质押(POST /api/v2/tron/freeze 和 /delegate)和链参数。
另外还有一对自签名接口。/transactions/trc20/build 用于构建交易。/transactions/broadcast 用于提交本地签名后的交易。你的合规团队可能坚持要求私钥永远不离开你的服务器。这时就用 build-and-broadcast 模式。
第二:表格中的破折号表示当前参考文档尚未记录该单元格对应的 v2 路由。这并不意味着该网络是二等公民。
Bitcoin 没有代币标准,因此代币列为空。原生 BTC 通过自己的钱包模型运行。用 POST /api/v2/bitcoin/wallets 创建密码加密的钱包,并在其下派生存款地址。再通过 POST /api/v2/bitcoin/transactions 发送。
Solana 的参考文档涵盖地址创建、SOL 和 SPL 转账,以及余额和区块查询。但它尚无 Webhook。此处未列出的内容,请参阅 API 参考文档 获取当前状态。
来源与延伸阅读
以下一手资料记录了本页所述的标准和链上行为:
- PoS:Polygon 开发者文档,介绍权益证明链。
- Migrate to POL:Polygon 开发者文档,涵盖从 MATIC 到 POL 的迁移。
- Finality:Polygon 开发者文档,涵盖检查点和最终确定。
- ERC-20: Token Standard:USDC 和 USDT 在 Polygon 上使用的代币接口规范。