通过 REST API 实现多区块链集成
本文说明如何通过一个 REST API 对接多条区块链。内容包括各链的网络与代币端点、为客户分配充值地址并注册 Webhook 的流程、一笔 ERC20 提现的请求示例、失败通知的处理方式,以及手续费、Webhook 与钱包等方面仍然存在的差异。
审核: Maurice Sobiera
多区块链集成指后端通过单一接口与多条链通信,而非为每条链各用一个客户端库。使用 Chaingateway 时,您以 Bearer 令牌调用 REST 接口,覆盖七条链,但仍受各链自身限制。
API 支持哪些区块链与代币标准?
该 API 覆盖七条链,每条链都有测试网。使用请求头 X-Network: testnet 即可切换到测试网。支持的网络页面列出了各测试网。代币转账按链各有一个端点:
| 链 | OpenAPI 文件中的代币与 NFT 端点 | 测试网 |
|---|---|---|
| Ethereum | transactions/erc20、transactions/erc721 | Sepolia |
| BNB Smart Chain | transactions/bep20、transactions/bep721 | BSC 测试网 |
| Polygon | transactions/erc20、transactions/erc721 | Amoy |
| Arbitrum | transactions/erc20、transactions/erc721 | Arbitrum Sepolia |
| Tron | transactions/trc20、transactions/trc721、transactions/trc10 | Nile |
| Solana | transactions/SPL | Devnet |
| Bitcoin | transactions(仅原生币) | Testnet3 |
所有路径都以 /api/v2/<chain>/ 开头。完整列表见 OpenAPI 文件。
如何基于它搭建充值与提现服务?
托管式流程包含三个部分:为每位客户分配一个地址、为每个地址注册一个 Webhook,以及一次提现调用。每个部分都是一个请求,并且在每条支持的链上结构相同。
- 创建充值地址。在 EVM 链和 Tron 上,这一步是
POST /api/v2/<chain>/addresses,响应中包含该地址。传入password,私钥将以加密形式存储。若不传密码,响应中会包含私钥,您必须自行保存。 - 为该地址注册 Webhook。
POST /api/v2/<chain>/webhooks接收接收方的url、to中的地址以及type,例如ERC20或TRC20。可选填contractaddress,以及不超过 255 个字符的reference。 - 付款。一笔 ERC20 代币提现只需一个请求:
curl -X POST https://app.chaingateway.io/api/v2/ethereum/transactions/erc20 \ -H "Authorization: Bearer $CHAINGATEWAY_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "from": "0xHotWalletAddress", "to": "0xCustomerAddress", "contractaddress": "0xTokenContract", "amount": 100, "password": "hot-wallet-password" }'在 BNB Smart Chain 上,将 ethereum/transactions/erc20 替换为 bsc/transactions/bep20。在 Tron 上使用 tron/transactions/trc20,其字段与之相同,只是没有 Gas 设置。Solana 则不同:solana/transactions/SPL 需要发送方的 privatekey,不接受钱包密码。关于如何验证所收到通知的内容,请参阅 关于个人密钥的文章。
请求失败时会发生什么?
API 返回包含 status、ok 和 message 的 JSON 内容。消息为 “Wrong password provided” 的 401 表示钱包密码不匹配。422 会附带节点自身的错误信息,例如 insufficient funds for gas * price + value。原因取决于具体的链。在 Ethereum 上,ERC20 转账需要发送地址上有用于支付 Gas 的 ETH;TRC20 转账则需要能量与带宽,或用于燃烧的 TRX。重试前请先检查余额,因为重试无法解决手续费不足的问题。
失败的 Webhook 通知不会自动重发。使用 GET /api/v2/<chain>/webhooks/notifications/failed 列出它们,并通过重发端点逐一重发。重发的通知可能晚于其他通知到达,因此接收方应以 txid 实现幂等处理。
各链之间仍有哪些差异?
有若干差异依然存在,该 API 并不掩盖它们:
- 手续费:Ethereum、BNB Smart Chain、Polygon 和 Arbitrum 使用 Gas,每条链各有一个
gasprice端点。Tron 使用能量与带宽。 - Webhook:除 Solana 外的所有链都支持。
- 钱包:比特币使用具名的钱包,一个钱包可包含多个地址,通过
POST /api/v2/bitcoin/wallets创建。 - 资产:同一代币在两条链上是两种不同的资产,该 API 不在两者之间进行跨链转换。
应从哪条链开始?
从您的客户已在使用的链开始,之后通过复用相同的处理程序添加其他链。交易所的提现表单会标明网络,例如 ERC-20、BEP-20 或 TRC-20。在构建第二个集成之前,先询问您的首批客户他们持有 USDT 所用的网络。
每条链应存储哪些字段?
多链服务需要在每条记录中保存链信息,因为同一字符串可能在多条链上都有效。至少应保留以下字段:
| 字段 | 必要原因 |
|---|---|
chain 与 network | 0x 地址在 Ethereum、BNB Smart Chain、Polygon 和 Arbitrum 上都有效,而主网与测试网的地址看起来相似 |
链自身格式的 address | Tron 使用以 T 开头的 Base58 地址,原始节点数据中会出现带 41 前缀的十六进制形式 |
contractaddress 与 type | 同一代币在每条链上的合约不同 |
txid | 用于去重 Webhook 通知以及查询 |
reference | 您的订单或客户 ID,在注册 Webhook 时设置 |
| 链的最小单位金额 | 不同代币的小数位数不同,因此仅在显示层进行换算 |
为 (chain, network, txid) 添加唯一约束。定期与第二个数据源对账,例如失败通知列表与区块浏览器。
如何开始?
先在测试网上操作。在 Sepolia 和 Nile 上各创建一个地址,为每个地址注册 Webhook,发起一笔测试转账,并检查您的接收方能否处理这两条通知。7 天免费试用无需绑定银行卡,也无需 KYC。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。