代付 TRC20 手续费:TronFuel 与 Paymaster
手续费代付是指由第三方支付 TRON 交易消耗的 energy 和 bandwidth,这样发送钱包就不需要持有 TRX。我们为此推荐 TronFuel。Chaingateway 的 Paymaster 曾在 API 内部完成同样的工作,现已弃用:现有集成仍可继续运行,但新的集成不应再使用它。
为什么有代币但没有 TRX 的 TRON 钱包无法发送代币?
Section titled “为什么有代币但没有 TRX 的 TRON 钱包无法发送代币?”TRC20 转账是一次智能合约调用。TRON 会为此收取 energy 和 bandwidth,地址要么燃烧 TRX 来支付这些资源,要么使用自己质押或被委托的资源。代币本身从不支付这笔费用。
这就造成了每个 TRON 集成迟早都会遇到的情况。客户把 USDT 存入一个新创建的地址,这个地址此时只持有代币,别无他物。把这些代币转出会失败,返回状态码 422 和消息 balance is not sufficient,因为没有 TRX 来支付资源成本。提前给每个存款地址充值 TRX 是可行的,但会把 TRX 占用在可能永远用不上的地址里。
代付手续费从另一个方向解决这个问题。由第三方支付资源成本,钱包发送代币时始终不需要持有 TRX。
用什么来代替 Paymaster?
Section titled “用什么来代替 Paymaster?”我们目前为此推荐 TronFuel。它从质押者那里批量租用 energy,而不是燃烧 TRX,相比直接燃烧的节省就来自这里。背景介绍见 《TRON 上的 TRC-20 交易手续费详解》。
TronFuel 是一项独立的服务。Chaingateway API 里没有它的端点,所以本文档不描述如何调用它。请通过上面的链接查阅它自己的文档。
Paymaster 还能用吗?
Section titled “Paymaster 还能用吗?”Chaingateway 的 Paymaster 在 API 内部完成同样的工作:它承担 bandwidth 和 energy,让钱包在发送 TRC20 代币之前不需要 TRX,并把成本计入你账户上的信用余额。
该服务已弃用。已经在调用 Paymaster 端点的集成仍可继续运行,因此下面仍保留了这些端点的文档。请不要在它们之上构建新的集成。
| 端点 | 用途 |
|---|---|
POST /api/v2/tron/paymaster | 创建代付交易请求 |
GET /api/v2/tron/paymaster | 列出你的请求及其状态 |
GET /api/v2/tron/paymaster/{id} | 读取单个请求 |
POST /api/v2/tron/paymaster/estimate | 估算 energy、bandwidth 和手续费 |
GET /api/v2/tron/paymaster/balance | 读取剩余的信用余额 |
一笔交易需要多少 energy 和 bandwidth,取决于交易类型和它调用的合约,所以这个数量并不固定。POST /api/v2/tron/paymaster/estimate 接收与请求本身相同的请求体,并返回这笔交易的预计成本。
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/paymaster/estimate\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "type": "TRC20", "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "1"}'{ "status": 200, "ok": true, "message": "Successfully estimated the fees", "data": { "energy_consumption": 32000, "bandwidth_consumption": 368, "paymaster_fee": 0.15 }}请求结算时,手续费会从信用余额中扣除。余额不足以覆盖时,请求会失败。GET /api/v2/tron/paymaster/balance 返回剩余的余额。
创建代付请求
Section titled “创建代付请求”type 接受 TRX、TRC10、TRC20 和 TRC721。它与 from、to 和 amount 一起为必填。对于 TRC20 和 TRC721,还要传入 contractaddress;对于 TRC721 和 TRC10,要传入 tokenid。签名方式与 API 其他地方相同:受密码保护的 Chaingateway 地址用 password,否则用 privatekey。可选的 callback_url 用来接收结果。
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/paymaster\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "type": "TRC20", "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp", "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "1", "password": "test123", "callback_url": "https://example.com/callback"}'返回的不是交易哈希,而是请求的 id:
{ "status": 200, "ok": true, "message": "Successfully created paymaster request", "data": { "id": "9c72d676-8180-4cd2-a406-f0f1cd097506" }}用这个 id 轮询 GET /api/v2/tron/paymaster/{id},或用 GET /api/v2/tron/paymaster 列出所有请求。status 字段在请求等待时为 pending,交易进行中为 processing,结算完成后为 completed。失败时显示为 failed - [reason],原因写在短横线之后。交易完成后,生成的交易哈希会出现在记录中。
{ "id": "9cfbfcaf-68b2-47e9-bf55-5b6b4875e84d", "type": "TRC20", "from": "THG9nncwASg3ub5rvVquocAHwwQbnKZxpH", "to": "TPUjdnMrS7XDUFp5W6zgh4QDCW34nXa2x1", "contract_address": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "amount": "200", "token_id": null, "transaction_hash": "80a223e0cb20ef692fbd23d3cbaf3cc1dfa2b9667aaef70c7da8ca8f707ec28b", "status": "success", "used_credits": "2.178413", "callback_url": "https://api.chaingateway.io/receiver/webhooks/tron", "created_at": "2024-09-11T15:28:57.000000Z"}能不能质押 TRX,而不是按笔付费?
Section titled “能不能质押 TRX,而不是按笔付费?”如果这些 TRX 本来就是你的,可以质押一次并重复使用这些资源,而不必按笔付费。POST /api/v2/tron/freeze 为 energy 或 bandwidth 质押 TRX,POST /api/v2/tron/delegate 把这些资源委托给另一个地址,POST /api/v2/tron/undelegate 和 POST /api/v2/tron/unfreeze 则分别撤销这两步。一个质押地址可以为它背后的存款地址供应资源,这正适合有大量收款地址的支付流程。
四个质押端点共用同一种请求体结构。字段 address、amount 和 resource 为必填,resource 取 BANDWIDTH 或 ENERGY。delegate 和 undelegate 另外要求必填的 receiver。与 API 其他地方一样,用 password 或 privatekey 签名。
curl --request POST\ --url https://app.chaingateway.io/api/v2/tron/freeze\ --header 'Accept: application/json'\ --header 'Content-Type: application/json'\ --header 'Authorization: Bearer YOUR_API_TOKEN'\ --data '{ "address": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH", "amount": 100, "resource": "ENERGY", "password": "test123"}'调用成功会返回 data.result: true 和质押交易的 txid。OpenAPI 文件中有两条规则适用于委托:余额必须先冻结才能委托,接收方必须不同于所有者地址。调用失败时返回状态码 422 和节点的消息,例如取消质押的数量超过已质押数量时为 no frozenBalance(Energy),取消委托从未委托过的资源时为 delegated Resource does not exist。质押的 TRX 如何转化为 energy 和 bandwidth,见 TRON 的资源模型。
哪种方案适合我的集成?
Section titled “哪种方案适合我的集成?”下表按所需条件和成本对各方案做了比较。
| 方案 | 你需要什么 | 成本模式 | 状态 |
|---|---|---|---|
| 给每个地址充值 TRX | 每个存款地址里都有 TRX | 每笔交易燃烧 TRX | 可行,但会占用 TRX |
| TronFuel | 独立的 TronFuel 服务,在 Chaingateway API 之外 | 租用 energy,而不是燃烧 TRX | 推荐 |
| 质押并委托 | 你可以锁定的 TRX | 由质押的 TRX 提供资源,而不是燃烧 | 可行 |
| Paymaster | Chaingateway 账户上的信用余额 | 手续费从信用余额中扣除 | 已弃用 |
发送之前,请用 GET /api/v2/tron/balances/{address} 检查地址的 TRX 余额。既没有 TRX 也没有被委托资源的地址,会以上文提到的 balance is not sufficient 消息失败。
转账本身的发送方法见创建 TRC20 代币交易。
- TRON resource model 定义了 energy、bandwidth、质押和委托。
- TRC20 protocol interface 描述了转账所调用的合约函数。