区块链 API 的六种应用场景与对应的 Chaingateway 端点
区块链 API 的六种应用场景:收款、付款、钱包后端、地址监控、链上数据查询和 NFT 核查,并列出每个场景使用的 Chaingateway 端点。文中还说明各网络的功能支持差异、哪些场景不适合 API,以及如何先在测试网上试用。
审核: Maurice Sobiera
区块链 API 是一种 Web 服务,让应用无需运行节点,即可通过 HTTPS 创建地址、读取余额、发送交易并接收通知。它把底层的 JSON-RPC 节点接口封装为一组更小的调用。下文说明每个场景需要哪些调用。
区块链 API 用来做什么?
常见用途可归结为六项工作。每一项都对应 Chaingateway REST API 的几个端点,除非另有说明,同样的模式适用于所有受支持的网络。
| 应用场景 | 应用的具体工作 | 主要端点(以以太坊为例) |
|---|---|---|
| 接受加密货币付款 | 为每笔订单创建一个充值地址,并等待付款 | POST /addresses、POST /webhooks、GET /balances/{address} |
| 批量付款或空投代币 | 向多个地址发送原生代币或代币 | POST /transactions、POST /transactions/erc20 |
| 运行钱包后端 | 创建、导入和导出地址 | POST /addresses、POST /addresses/import、GET /addresses/export/{address} |
| 监控地址 | 对转入和转出的转账作出反应 | POST /webhooks、GET /webhooks/notifications |
| 查询链上数据 | 读取区块、交易和收据 | GET /blocks/{block_number}、GET /transactions/{txid} |
| 核查 NFT | 读取代币的所有者和元数据 URI | GET /nfts/{contract_address}/owner/{token_id} |
所有路径均以 /api/v2/{blockchain} 开头,例如 /api/v2/ethereum/addresses。完整列表请参阅 API 参考。
如何通过 API 接受加密货币付款?
为每笔订单创建一个充值地址,并为其注册一个 Webhook,把 Webhook 视为付款到账的信号。地址接口返回一个新地址。Webhook 接口需要地址(to)、url 和 type(例如 ETH、ERC20 或 ERC721),此外还可以提供一个最多 255 个字符的可选 reference,您可以将其用作订单号。
# 1. Create a password-protected deposit addresscurl -X POST https://app.chaingateway.io/api/v2/ethereum/addresses \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{"password": "a-long-random-password"}'
# 2. Watch it for incoming ERC-20 transferscurl -X POST https://app.chaingateway.io/api/v2/ethereum/webhooks \ -H "Authorization: Bearer YOUR_API_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "to": "0xDepositAddressFromStep1", "contractaddress": "0xTokenContractAddress", "type": "ERC20", "url": "https://shop.example.com/hooks/chaingateway", "reference": "order-10231" }'当出现匹配的转账时,Chaingateway 会向您的 URL 发送通知。在放货之前,请校验其 X-Signature 请求头,然后对照链上数据确认金额。Webhook 不会自动重试:失败的通知会列在 /webhooks/notifications/failed 下,并可重新发送。Solana 没有 Webhook,因此请改为轮询余额端点。完整流程请参阅我们的付款 Webhook 指南。
如何发送付款或空投?
从脚本中为每位收款人单独调用一次交易端点。对于代币,请使用 POST /api/v2/ethereum/transactions/erc20,并提供发送方、合约地址、接收方和金额。
每笔转账都需要发送地址上有该网络原生代币的 Gas。在进行大批量发送之前,请先查询 GET /gasprice,并且对每个发送地址按顺序发送转账,以免 nonce 冲突。NFT 转账使用 erc721 端点,相关说明见通过 API 转移 NFT。
API 能否运行钱包后端?
在一定范围内可以。地址端点用于创建地址,password 参数会将私钥加密存储在服务器上,因此您可以用密码而非私钥发送交易。您也可以导入已有地址,并在之后导出私钥。钱包管理指南列出了各种取舍,而我们的安全建议解释了为何长期资金应存放在冷存储中。
原生代币余额通过 GET /balances/{address} 获取,代币余额则通过 GET /balances/{address}/erc20 获取。交易列表端点只显示通过 Chaingateway API 创建的交易,它不会为某个地址索引全部交易,因此如果您还需要转入的转账,请使用 Webhook。
如何监控地址并查询链上数据?
事件使用 Webhook,历史记录使用查询端点。Webhook 覆盖您注册的地址和合约。除此之外,您可以按区块号读取区块,按哈希读取交易,或读取解码后的交易。比特币在 /api/v2/bitcoin 下有自己基于钱包的端点。若您需要直接访问节点,而不是使用这些调用,相关方法记录在 以太坊 JSON-RPC 参考和比特币 RPC 参考中。
哪些网络支持哪些应用场景?
各网络的支持情况不同,OpenAPI 文件对此有所体现。在围绕某项功能进行设计之前,请先查看下表。
| 网络 | Webhook | 代币转账 | NFT 所有者与 URI 查询 | 钱包模型 |
|---|---|---|---|---|
| Ethereum、Polygon、Arbitrum | 支持 | ERC-20 和 ERC-721 | 支持 | 单一地址 |
| BNB 智能链 | 支持 | BEP-20 和 BEP-721 | 支持 | 单一地址 |
| TRON | 支持 | TRC-20 和 TRC-721 | 无查询端点 | 单一地址 |
| Solana | 不支持 | SPL | 支持 | 单一地址 |
| Bitcoin | 支持 | 仅原生代币 | 不适用 | 持有地址的钱包 |
因此,依赖 Webhook 的付款流程在 Solana 上需要轮询作为备用方案。依赖 NFT 所有权核查的流程,在 TRON 上则需要另一种数据来源。
如何在没有真实资金的情况下试用这些场景?
先在测试网上运行。在任意请求中添加请求头 X-Network: testnet,同样的端点即可针对测试网运行,而不是主网。去掉该请求头,或将其设为 mainnet,即可切换回来。这样,在涉及任何真实价值之前,您就可以测试地址创建、转账以及包括签名校验在内的 Webhook 往返流程。
Chaingateway 提供无需绑定银行卡的 7 天免费试用,开始使用也无需身份核实。步骤很简单:
- 创建账户,并从控制面板复制您的 API 令牌。
- 创建一个测试地址,并从您所选测试网的公共水龙头为其充值。
- 注册一个 Webhook,指向您接收端的公开 URL。
- 发送一笔测试转账,检查通知是否到达,以及其签名是否校验通过。
我们的快速入门指南以代码示例演示了同样的步骤。
哪些应用场景并不适合?
此类 API 不适合需要任意地址完整链上历史的工作,例如数据分析、税务申报或借贷决策。这些工作需要一个存储每笔交易的索引器,而不是一个只负责发送交易、并就您注册的地址发出通知的服务。请单独构建或采购该部分,并将 API 用于交易与通知这一侧。
准备好自己动手构建了吗? 获取你的 API key — 7 天试用,无需信用卡 — 或查看 区块链 API 获取完整的 endpoint 参考。