一个 Blockchain API，覆盖加密支付的七条链
在 Bitcoin、Ethereum、TRON、Solana、BNB Smart Chain、Polygon 和 Arbitrum 上接收和发送加密支付。一个 REST API，覆盖钱包、代币转账和存款 Webhook。
Chaingateway 是一个用于区块链支付的 REST API。你用普通的 HTTPS 调用生成钱包地址并发送代币，当存款到达你的某个地址时，Webhook 会实时通知你的服务器。同一个 API 覆盖 Bitcoin、Ethereum、TRON、Solana、BNB Smart Chain、Polygon 和 Arbitrum。
这种覆盖范围比任何单一功能都更重要。大多数 blockchain API 只处理一条网络；添加第二条链的团队通常会得到第二套代码库，因为每条网络都有自己的 RPC 格式和客户端库。Chaingateway 消除了这种割裂。以太坊上 ERC-20 转账的路由是 POST /api/v2/ethereum/transactions/erc20；在 Polygon 上则是 POST /api/v2/polygon/transactions/erc20。改一个路径片段，你现有的代码就能在下一条链上运行。
无需同步节点，也无需安装 SDK。认证方式是 Authorization 头中的 Bearer 令牌。再加一个请求头 X-Network: testnet，就能把任意调用指向测试网络而非主网。7 天免费试用无需 KYC 即可开始。
API 覆盖的范围
钱包与地址
为 Ethereum、BSC、Polygon 和 TRON 创建密码保护的钱包，或通过 POST /api/v2/ethereum/addresses/import 等导入接口接入已有密钥。私钥使用只有你知道的密码加密存储——Chaingateway 不会以明文形式保存密钥或密码，因此没有你的凭据，资金就动不了。Solana 地址通过 POST /api/v2/solana/addresses 生成。对支付类产品来说，常见做法是每个客户或每笔订单对应一个地址，这让归属变得毫不费力：任何到达地址 X 的资金都属于客户 X，无需按金额或备注匹配。
原生代币与代币交易
一次调用即可发送 ETH、BNB、POL、TRX 或 BTC，并通过同一接口转移 ERC-20、BEP-20、TRC-20 和 SPL 代币。Gas、gas 价格和 nonce 都是可选请求字段——省略它们，API 会自动填充，因此你只需传入收款方和金额，无需手动组装原始交易。金额单位是代币单位，而不是最小单位：100 表示你所指定合约地址下的 100 个代币。TRON 比其他链走得更远：freeze 和 delegate 接口覆盖质押（unfreeze 和 undelegate 用于撤销），TRC-10 与 TRC-20 并存。
解码后的链上数据
响应以可读的 JSON 形式返回，而不是十六进制。一笔解码后的 TRON 交易包含发送方、接收方、以代币单位表示的金额、区块号以及当前确认数。这正是 blockchain data API 应当返回的内容——你的应用无需 ABI 解析器就能存储和展示的值。
面向入账支付的 Webhook
订阅链上事件，一旦存款在链上结算即可收到通知。在你的账户中设置一个私密密钥，每条通知都会携带一个可由你服务器验证的 X-Signature 请求头。投递失败的会由 API 列出，并可通过一次调用重新发送。
各条链支持哪些功能
此表把当前 API 参考文档浓缩成一张视图：哪些链有地址接口，可以发送哪些代币标准，以及存款 Webhook 记录在何处。
| 链 | 地址 | 代币转账 | 存款 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 参考文档 获取当前状态。
Blockchain API 示例：四种语言的第一次调用
先获取一个 API 密钥（见下一节），再确认它是否有效。GET /api/account 会返回你的账户详情并证明该密钥有效。
curl https://app.chaingateway.io/api/account \
-H "Authorization: Bearer YOUR_API_KEY"这就是完整的认证检查——创建账户，用同一个调用即可证明你自己的密钥有效。
如何获取 blockchain API 密钥
在 app.chaingateway.io/register 注册。7 天试用无需 KYC 即可开始。
从你的仪表盘复制 API 密钥。
在每个请求中以 Authorization: Bearer 你的API密钥 的形式携带它，并且只保存在服务器端。客户端代码会把它暴露给任何打开浏览器控制台的人。账户面板还可以额外将密钥限制在你服务器的 IP 地址范围内，这样即使密钥泄露，在其他地方也无法使用。更多加固步骤见我们的 blockchain API 安全提示。
接收存款：Webhook 流程
一次支付集成通常是这样的：
为每位客户创建或导入一个存款地址。
客户向该地址发送代币或原生币。
一旦转账结算，Chaingateway 会向你的回调 URL 发送一条 POST 通知——如果你设置了私密密钥，还会附带 X-Signature 请求头。
你的服务器验证签名并为客户账户入账。
Webhook 安全实践
Webhook 接口是通往你后端的一扇门，而这扇门恰好负责入账。Chaingateway 为你提供三种防护机制；生产环境的处理程序应该三者都用上。这适用于拥有存款 Webhook 的六条链——Solana 的存款检测使用轮询，在下文介绍。
1. 验证签名
在个人资料设置中设置一个私密密钥——从那时起，每条通知都会携带一个 X-Signature 请求头，其构造方式是对 payload 的 txid 字段做 HMAC-SHA256 并用该密钥作为密钥，再以 base64 编码。收到通知后从 txid 重新计算一次，在为任何金额入账之前与请求头的值比较，并使用恒定时间比较——大多数标准库都提供这种方法。校验失败一律返回 401。这样可以堵住最明显的攻击：任何发现你回调 URL 的人都可以向它 POST 伪造的存款，如果没有签名校验，你的商店就会为从未发生过的付款发货。
2. 为重复投递设计
一条通知可能不止一次到达你这里——你可以通过 API 重新发送失败的通知，而且两者之间没有任何机制保证「恰好一次」投递。让你的入账逻辑以交易哈希为键，而不是以收到的回调次数为键——在哈希列上使用一条 INSERT ... ON CONFLICT DO NOTHING，只需一行代码就能消除整整一类「重复入账」的错误。一旦通知被持久化，就立即返回 2xx，把耗时的处理放到之后进行；在处理程序中内联执行繁重工作会导致超时，把一笔存款变成一张支持工单。
3. 使用恢复接口
如果你的接口曾经宕机或返回了错误，该次投递会进入失败列表：GET /api/v2/{chain}/webhooks/notifications/failed 显示未能送达的内容，POST /api/v2/{chain}/webhooks/notifications/{id}/retry 可以按你的指令逐条重新发送。对于其他情况——数据库故障转移、一次糟糕的部署、过期的 TLS 证书——GET /api/v2/{chain}/webhooks/notifications 返回完整的投递历史，让每晚的对账任务可以将其与你的账本比对并修复差异。Payload 细节和验证代码见 Webhook 指南。
在测试网上测试，上线同一份代码
每条路由都接受一个额外的请求头 X-Network: testnet，并运行在测试网络而不是主网上。接口、请求体和响应结构保持不变；代币没有任何价值。正是这最后一点才是关键所在。你的集成测试可以整天创建地址、转移代币、接收 Webhook，而完全不触碰真实资金。
一个实用的设置方式是这样的：把这个请求头放到环境变量后面，让 staging 发送它、生产环境不发送——两者之间没有代码差异。给 staging 单独的回调 URL，否则测试存款会落到你的生产 Webhook 处理程序中，扰乱账本。测试代币可以从各生态系统运行的公共水龙头免费获取；文档中的受支持网络页面列出了每条链对应的测试网——以太坊是 Sepolia，TRON 是 Nile，Polygon 是 Amoy，Bitcoin 是 testnet3。
当整个流程端到端跑通——地址已创建、存款已检测到、Webhook 已验证、余额已入账——删除那个请求头即可，其余一切都不需要改动。这种对称性是刻意设计的，也正因如此，上线只是一次配置变更，而不是第二个集成项目。
三个实操集成案例
功能列表很难说明集成的实际工作量，这里是我们经常见到的三种搭建方式，每一种都被拆解为其活动部件。
在线商店的存款
一家商店想在结账时接受 USDT。当客户选择加密货币付款时，你的后端为该订单分配一个地址，并将它与金额一起展示。之后的工作交给 Webhook。转账在链上结算后通知就会到达；把订单标记为「已检测到付款」并展示给客户，因为快速反馈正是让加密收银台显得可信的原因。如果你的策略对较大金额要求更深的确认，用 GET /api/v2/{chain}/transactions/{txid} 检查交易，直到达到你的阈值，再把订单标记为已付款并开始履约。
有两个边界情形决定了这套方案是否达到生产级别。少付：客户有时会发送略少于账单金额的数目，通常是因为他们的钱包从输入金额中扣除了网络手续费。提前决定容忍度——吸收小额差额，或者暂缓订单并要求补足差价。多付更少见也更容易处理：为其入账或退款，但无论哪种都要记录日志。这两种情形都源于将通知金额与账单金额进行比较，而不是把任何回调都当作「已付款」处理。
批量付款
一个联盟营销平台每月要向数百个合作伙伴支付稳定币，选在 Polygon 上进行，因为那里的手续费相对付款金额来说很小。这套方案的核心是一个队列加一个循环：
import requests
payouts = load_pending_payouts() # [{"address": ..., "amount": ...}, ...]
for p in payouts:
r = requests.post(
"https://app.chaingateway.io/api/v2/polygon/transactions/erc20",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"contractaddress": "0xTokenContract...",
"from": "0xTreasuryWallet...",
"to": p["address"],
"amount": p["amount"],
"password": "treasury-wallet-password",
},
)
record_result(p, r.json()) # 在进入下一次迭代前先持久化
队列比循环本身更重要。在发送之前先持久化每笔付款的状态，立即保存 API 响应，并且永远不要只因为 HTTP 调用超时就重试发送——那笔交易可能其实已经成功了。检查你保存的结果和 GET /api/v2/polygon/transactions（它列出了通过 API 创建的每一笔交易），只重新发送那些确实从未发生过的付款。正是这一条规则，把能经受住审计的付款系统与最终沦为表格考古学的付款系统区分开来。
SaaS 的链上计费
一家 B2B 工具因为收单机构不断拒绝其商户类别，转而每月以稳定币向客户计费。这套方案复用了商店那种模式，只有一处不同：每张发票对应一个全新的存款地址，而不是每位客户一个。按发票分配地址让匹配变得毫不费力——任何到达 4711 号发票地址的金额都属于该发票——也消除了在两张发票金额恰好相同时按金额匹配付款所带来的猜测。Webhook 把发票标记为已付款；一个定时任务让过期的发票失效并发送提醒。这套流程完全不需要钱包界面、浏览器扩展，也不要求客户具备除发送一次转账之外的任何加密货币知识。
支持的区块链
每条链都有自己的接口和代码示例页面：
- Bitcoin API——最早的链。从密码加密钱包发起的原生 BTC 转账，加上面向入账支付的存款 Webhook。
- Ethereum API——采用最广泛的智能合约平台，支持 ERC-20 代币转账和 ERC-721 NFT。
- TRON API——TRC-10 和 TRC-20 交易、通过 freeze 和 delegate 实现的质押，以及自签名的 build/broadcast 路由。用 TRON 手续费计算器提前估算转账成本。
- Solana API——在高吞吐量链上创建地址并进行 SPL 代币交易。
- BNB Smart Chain API——BEP-20 转账，路由结构与你在以太坊上使用的一致。
- Polygon API——在以太坊的扩容链上进行 ERC-20 转账，费用只是主网 gas 成本的一小部分。这是 Polygon 区块链的 API，不是 Polygon.io 的股票数据服务。
- Arbitrum API——面向高吞吐量的以太坊 L2，接口布局与主网一致。
从 JSON-RPC 迁移到 REST
Blockchain API 用一次经过认证的 REST 请求替代每个动作所需的原始 JSON-RPC 调用。JSON-RPC 每笔转账需要多次往返，加上手动的 ABI 编码、nonce 追踪和签名，而像 POST /api/v2/{chain}/transactions/erc20（在 BNB Smart Chain 上是 bep20）这样的调用，把这一切都压缩进了一个请求。
许多团队来到这里时已经有一套正在运行的集成：面向付费 RPC 端点的 web3.js，或是代码库更早时期手写的 JSON-RPC 客户端。这次迁移并不像听起来那么戏剧化，因为 API 吸收的是整类整类的代码，而不是逐个调用地替换。
以经典的 EVM 发送路径为例。通过 JSON-RPC，一笔代币转账是一连串步骤：用 eth_getTransactionCount 获取 nonce，用 eth_gasPrice 或一次费用历史调用来定价，针对 ABI 编码后的 calldata 调用 eth_estimateGas，本地签名，然后用 eth_sendRawTransaction 广播。每一步都有你现在代码要处理的失败模式——或者悄悄没有处理。这五步全部合并为对 /api/v2/{chain}/transactions/erc20 的一次认证 POST 请求，而 nonce 记账——「交易卡住」类工单的常见根源——则彻底从你的代码库中消失。
事件检测在形态上的变化比在逻辑上的变化更大。原本你用区块游标轮询 eth_getLogs，或者维护一个在每次重连 bug 中都要处理的 WebSocket 订阅，现在你只需注册一个 Webhook 并删除轮询器。你的下游逻辑——解析转账、匹配客户、为余额入账——保持不变；变化的只是输入方式，从拉取变为推送。
无法直接映射的部分：共识相关工具、自定义索引器，以及任何需要原始区块访问的场景。为这些工作保留一个 RPC 端点；两者可以毫无摩擦地共存。支付通常是最值得先迁移的负载，因为它每行代码承担的运维风险最高。更详尽的对比，包括节点更合适的场景，见 blockchain API 与 blockchain node 对比。
当请求失败时
支付 API 的错误处理值得比一个通用的 catch 块更用心，因为「请求失败」和「交易失败」是两回事。
HTTP 层遵循 REST 的常规约定。401 意味着 Bearer 令牌缺失、错误或已过期——修正凭据，不要重试。4xx 范围内的其他响应说明请求本身有问题：地址格式错误、字段缺失、校验失败。记录下指明具体问题的响应体，把这些当作需要修复的 bug，而不是可以重试的临时状况来对待。5xx 范围和网络层超时属于临时性错误，这时用指数退避重试才是正确的反应。
但有一个例外，而且是很重要的例外。永远不要盲目重试一个会转移资金的请求。超时只能说明你没有收到响应，并不能说明交易失败了。安全的做法是：利用你保存的结果和 GET /api/v2/{chain}/transactions（列出你的密钥创建的交易）先确认转账是否已发出，只有在能证明它确实从未发生时才重新发送。在你这边设置与自己的付款或订单 ID 绑定的幂等键，能让这项检查变得很廉价。
从第一天起就内置可观测性。为每一次涉及资金转移的调用记录请求-响应对，并且不仅在 5xx 上告警，也要在 4xx 比例上告警——校验错误的突然激增，通常意味着某次部署破坏了你的请求格式。在几分钟内而不是几天内发现这一点，是「一次事故」和「一个脚注」之间的差别。
自建节点还是使用 API？
自己运行节点能给你完全的控制权，也不依赖第三方。但这也意味着每条链一台机器、磁盘和带宽预算、同步监控和版本升级——如果你想要上文描述的全部覆盖范围，这些工作要乘以七。我们的 blockchain API 与 blockchain node 对比详细分析了这一权衡。简而言之：需要共识层面的控制权时运行节点，需要本周就把支付功能跑起来时使用 API。
常见问题
准备好接受加密支付了吗？
在 app.chaingateway.io/register 创建账户，从上面七条链中选一条并发送一笔测试转账。完整接口参考见 文档，套餐和速率限制列在单独的页面上。