Sponsor TRC20 Fees: TronFuel and Paymaster

The problem: tokens without TRX cannot move

A TRC20 transfer is a smart contract call. TRON charges energy and bandwidth for it, and an address pays for those resources either by burning TRX or by using resources it has staked or been delegated. The token itself never pays.

That produces a situation every TRON integration runs into sooner or later. A customer deposits USDT into a freshly created address. The address now holds tokens and nothing else. Sending those tokens onwards fails with status 422 and the message balance is not sufficient, because there is no TRX to cover the resource cost. Funding every deposit address with TRX in advance works, but it ties up TRX in addresses that may never be used.

Sponsoring the fee solves this from the other side. A third party pays the resource cost, and the wallet sends its tokens without ever holding TRX.

TronFuel is the recommended way

TronFuel is what we recommend for this today. It rents energy in bulk from stakers rather than burning TRX, which is where the saving compared with a plain burn comes from. The background is written up in Save Up to 60% on TRON TRC-20 Transaction Fees.

TronFuel is a separate service. It has no endpoint inside the Chaingateway API, so nothing in this documentation describes how to call it. Follow the link above for its own documentation.

The Paymaster is deprecated

The Chaingateway Paymaster did the same job inside the API: it covered bandwidth and energy so a wallet did not need TRX before sending TRC20 tokens, and it billed the cost against a credit balance on your account.

The service is deprecated. Integrations that already call the Paymaster endpoints keep working, and the endpoints are documented below for that reason. Do not build new integrations on them.

Endpoint	Purpose
POST /v2/tron/paymaster	Create a sponsored transaction request
GET /v2/tron/paymaster	List your requests and their status
GET /v2/tron/paymaster/{id}	Read one request
POST /v2/tron/paymaster/estimate	Estimate energy, bandwidth and fee
GET /v2/tron/paymaster/balance	Read your remaining credit balance

Estimating the cost first

How much energy and bandwidth a transaction needs depends on the transaction type and on the contract it calls, so the amount is not fixed. POST /v2/tron/paymaster/estimate takes the same body as the request itself and returns what the transaction would cost.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/paymaster/estimate\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: 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
  }
}

The fee is deducted from the credit balance once the request settles. A balance that does not cover it makes the request fail. GET /v2/tron/paymaster/balance returns what is left.

Creating a sponsored request

type accepts TRX, TRC10, TRC20 and TRC721. Together with from, to and amount it is required. For TRC20 and TRC721 you also pass contractaddress, for TRC721 and TRC10 the tokenid. Signing works as everywhere else in the API: password for a password-protected Chaingateway address, privatekey otherwise. An optional callback_url receives the result.

curl --request POST\
  --url https://api.chaingateway.io/v2/tron/paymaster\
  --header 'Accept: application/json'\
  --header 'content-type: application/json'\
  --header 'Authorization: YOUR_API_TOKEN'\
  --data '{
    "type": "TRC20",
    "from": "TLkkCeNdJKPNUwucdro84WjswkzM62LCTH",
    "to": "TUwmZghA7u2GxGxKaxM1mkCmsTF4wHs4vp",
    "contractaddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
    "amount": "1",
    "password": "test123",
    "callback_url": "https://example.com/callback"
}'

The answer is not a transaction hash but the id of the request:

{
  "status": 200,
  "ok": true,
  "message": "Successfully created paymaster request",
  "data": {
    "id": "9c72d676-8180-4cd2-a406-f0f1cd097506"
  }
}

Following a request

Poll GET /v2/tron/paymaster/{id} with that id, or list every request with GET /v2/tron/paymaster. The status field moves through pending while the request waits, processing while the transaction is on its way, and completed once it settled. A failure reads failed - [reason], with the reason spelled out after the dash. The resulting transaction hash appears in the record once the transaction is done.

{
  "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"
}

Staking as a third option

If the TRX is yours anyway, you can stake it once and reuse the resources instead of paying per transaction. POST /v2/tron/freeze stakes TRX for energy or bandwidth, POST /v2/tron/delegate hands those resources to another address, and POST /v2/tron/undelegate and POST /v2/tron/unfreeze reverse both steps. A single staked address can supply the deposit addresses behind it, which is the pattern that fits a payment flow with many receiving addresses.

Sending the transfer itself is covered in Create TRC20 Token Transactions.