GasFree4you / API
HomeOpen account
DEVELOPER DOCS

API documentation

Integrate TRON Energy into your product: prepare a USDT transfer in one call, or manage Energy orders step by step.

Getting started

Sign in to your personal account and open the API tab to obtain your Base URL and API key.

Open account

Set these variables in your terminal. Copy the Base URL from your account without a trailing slash.

cURL / Shell
export BASE_URL="https://YOUR_API_BASE_URL"
export API_KEY="YOUR_API_KEY"

Send X-API-Key for balance, tariffs and orders. The fee estimate endpoint is public and needs no API key. Keep your key on your backend, not in browser code.

Check balance → estimate Energy → fetch tariffs → place an order

Energy is delegated to the wallet sending USDT. recipient_wallet in the estimator is the destination of the USDT transfer.

New: prepare a USDT transfer in one call — we check the addresses, order Energy and Bandwidth for the sender and tell you when to send.

Go to transfer preparation →

POST/v1/transfers/prepareNEW

Prepare a USDT transfer

X-API-Key required

Checks the sender (and, on request, the recipient), orders Energy and Bandwidth for the sender if needed, and tells you when the transfer can be sent.

Create a preparation → poll its status → send USDT when status = ready

Authorization: the X-API-Key header on every request.

How it works, visually →

Headers

X-API-Key Required
Your API key.
Idempotency-Key Required
A unique string, 1–128 characters. Use the same key when retrying the same request.
Content-Type
application/json

Request body

JSON
{
  "sender": "TFCyGqE4QtizzWP******Sq28dVjQtDqk8od",
  "recipient": "TCV4qdpTxoMyq******XmhH5JFxMvmT",
  "check_recipient": true
}
sender string
USDT sender address; receives Energy and Bandwidth.
recipient string
USDT recipient address.
check_recipient bool · default false
Screen the recipient for sanctions and other stop factors.

Request

cURL / Shell
curl -s -X POST "$BASE_URL/v1/transfers/prepare" \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: 94d00c23-d08e-4fc9-95e5-f23d86f46261" \
  -H "Content-Type: application/json" \
  -d '{"sender":"TFCyGqE4Qti******Sq28dVjQtDqk8od","recipient":"TCV4qdpTxo******hH5JFxMvmT","check_recipient":true}'

Response 200 — a preparation object (see below) with status = processing, or ready right away.

GET/v1/transfers/prepare/{prepare_id}

Get preparation status

X-API-Key required

Poll every 2–3 seconds while status = processing. Returns the same preparation object.

Request

cURL / Shell
curl -s "$BASE_URL/v1/transfers/prepare/6" \
  -H "X-API-Key: $API_KEY"

Example: preparation is ready

JSON
{
  "prepare_id": 6,
  "status": "ready",
  "can_transfer": true,
  "required_energy": 131000,
  "energy_package": 131000,
  "bandwidth_required": false,
  "sender_activated": true,
  "estimated_cost_trx": "5.4",
  "charged": {"total_trx": "5.4", "energy_trx": "5.4", "bandwidth_trx": "0", "activation_trx": "0"},
  "sender_energy_available": 130999,
  "sender_bandwidth_available": 600,
  "energy_tx_id": null,
  "topup_tx_id": null,
  "error_code": null,
  "message": null,
  "created_at": "2026-11-12T21:04:50.070890",
  "completed_at": "2026-11-12T21:04:50.070890"
}

Preparation object

FieldDescription
prepare_idPreparation ID.
statusprocessing / ready / failed / unknown.
can_transfertrue — the transfer can be sent.
required_energyEnergy needed: 65000 (recipient holds USDT) or 131000.
energy_packageOrdered package; null if the sender already had enough Energy.
bandwidth_requiredWhether Bandwidth had to be bought.
sender_activatedWhether the sender address was activated before the order.
estimated_cost_trxEstimated cost at creation time.
chargedActual charge; null while processing.
sender_energy_available, sender_bandwidth_availableLatest data from the network.
error_code, messageReason when status is failed or unknown.

charged · charged after completion

JSON
{"total_trx": "5.4", "energy_trx": "5.4", "bandwidth_trx": "0", "activation_trx": "0"}

Statuses

statusWhat to do
processingKeep polling.
readyResources are confirmed on-chain — send the transfer.
failedThe order was not fulfilled; you can create a new preparation with a new key.
unknownThe result is not confirmed — do not create a new order, contact support.

Errors on creation

Returned immediately, with no charge. Error body: {"detail": {"error": "<code>", "message": "<text>", ...}}

HTTPerrorReason
400INVALID_TRON_ADDRESSInvalid address.
400SAME_ADDRESSSender is the same as the recipient.
402INSUFFICIENT_BALANCELess than 2 TRX available, or not enough for the full cost (required_sun, available_sun).
404TARIFF_NOT_FOUNDNo tariff for the required package.
409IDEMPOTENCY_KEY_REUSEDThe key was already used with different parameters.
451SENDER_SANCTIONED
RECIPIENT_SANCTIONED
Stop factor; the reason is in message, details in matches.
503SANCTIONS_DATA_NOT_READY
ADDRESS_ACTIVATION_CHECK_UNAVAILABLE
TRON_DATA_UNAVAILABLE
Temporarily unavailable — retry later with the same key.
422—Missing Idempotency-Key or invalid body.

Example: recipient on a sanctions list

HTTP 451 · JSON
{
  "detail": {
    "error": "RECIPIENT_SANCTIONED",
    "message": "Address is present in sanctions lists.",
    "party": "recipient",
    "reason": "sanctions_hit",
    "matches": [
      {
        "source": "ofac_sdn",
        "asset": "TRX",
        "list_version": "11/09/2026"
      }
    ]
  }
}

Example: another stop factor — mass-spam sender

HTTP 451 · JSON
{
  "detail": {
    "error": "RECIPIENT_SANCTIONED",
    "message": "Address is identified as a mass-spam sender.",
    "party": "recipient",
    "reason": "sanctions_hit",
    "matches": [
      {
        "source": "blockchain_data",
        "asset": "TRX",
        "list_version": null,
        "category": "spam_sender",
        "reason_code": "SPAM_SENDER",
        "reason": "Address is identified as a mass-spam sender.",
        "label": null
      }
    ]
  }
}

Retries

  • Repeating a POST with the same Idempotency-Key and the same fields returns the same preparation — no new order and no new charge.
  • On a timeout or a dropped connection, retry with the same key. A new key means a new paid order.

Full example

cURL / Shell
curl -s -X POST "$BASE_URL/v1/transfers/prepare" \
  -H "X-API-Key: $API_KEY" \
  -H "Idempotency-Key: 94d00c23-d08e-4fc9-95e5-f23d86f46261" \
  -H "Content-Type: application/json" \
  -d '{"sender":"TFCyGqE4Qti******Sq28dVjQtDqk8od","recipient":"TCV4qdpTxo******hH5JFxMvmT","check_recipient":true}'

curl -s "$BASE_URL/v1/transfers/prepare/6" \
  -H "X-API-Key: $API_KEY"

Examples are illustrative; tariff and order prices may differ.

GET/v1/me/balance

Get balance

X-API-Key required

Returns the available service balance in TRX, with its SUN equivalent.

Request

cURL / Shell
curl "$BASE_URL/v1/me/balance" \
  -H "X-API-Key: $API_KEY"

Example response

JSON
{
  "balance_sun": 19795000,
  "balance_trx": 19.795
}
GET/v1/public/fee-estimate

Estimate required Energy

Public · no API key

Determines the required Energy package. With a sender address, it also checks the resources available in that wallet.

Parameters

recipient_wallet Required
Recipient TRON address. Used to determine whether 65,000 or 130,000 Energy is required.
sender_wallet Optional
Optional sender TRON address. Adds its Energy, Bandwidth and TRX balance to the estimate.

Recipient and sender

Request

cURL / Shell
curl "$BASE_URL/v1/public/fee-estimate?recipient_wallet=TTAFuzcJZyJidjNvbi9S9UviPaietqZ9if&sender_wallet=TTAFuzcJZyJidjNvbi9S9UviPaietqZ9if"

Example response

JSON
{
  "bandwidth_deficit": 0,
  "code": "SENDER_LACKS_ENERGY",
  "energy_deficit": 64991,
  "has_enough_bandwidth": true,
  "has_enough_energy": false,
  "has_enough_trx_for_bandwidth": true,
  "recipient_has_usdt": true,
  "recommended_trx_topup": "0",
  "required_energy": 65000,
  "sender_bandwidth_available": 515,
  "sender_energy_available": 9,
  "sender_trx_balance": "36.279462"
}

Recipient only

Request

cURL / Shell
curl "$BASE_URL/v1/public/fee-estimate?recipient_wallet=TTAFuzcJZyJidjNvbi9S9UviPaietqZ9if"

Example response

JSON
{
  "bandwidth_deficit": null,
  "code": "RECIPIENT_USDT_65000",
  "energy_deficit": null,
  "has_enough_bandwidth": null,
  "has_enough_energy": null,
  "has_enough_trx_for_bandwidth": null,
  "recipient_has_usdt": true,
  "recommended_trx_topup": null,
  "required_energy": 65000,
  "sender_bandwidth_available": null,
  "sender_energy_available": null,
  "sender_trx_balance": null
}

Without sender_wallet, sender resource fields are null: they have not been checked.

GET/v1/me/tariffs

Current tariffs

X-API-Key required

Returns the Energy packages available to your account. Prices below are examples; use this endpoint for your current price.

Request

cURL / Shell
curl "$BASE_URL/v1/me/tariffs" \
  -H "X-API-Key: $API_KEY"

Example response

JSON
[
  {
    "energy": 65000,
    "price_trx": 2.7,
    "currency": "TRX",
    "_src": "public",
    "discount_percent": null,
    "discount_starts_at": null,
    "discount_ends_at": null
  },
  {
    "energy": 130000,
    "price_trx": 4.5,
    "currency": "TRX",
    "_src": "personal",
    "discount_percent": null,
    "discount_starts_at": null,
    "discount_ends_at": null
  }
]
POST/v1/order

Order Energy

X-API-Key required

Delegates the selected Energy package to a TRON wallet and deducts its cost from your service balance.

Energy is valid for 1 hour after delegation or until the first transfer, whichever comes first.

If the wallet is not activated, we activate it before delegating Energy. Activation costs an additional 1.2 TRX.

Calculate the required Energy before ordering →

Request

cURL / Shell
curl -X POST "$BASE_URL/v1/order" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "TYourTronWalletAddress",
    "energy": 65000,
    "trx_topup": false,
    "trx_topup_amount": 0
  }'

Parameters

wallet Required
TRON address receiving the Energy delegation — the wallet that will send USDT.
energy Required
Energy amount from the current tariffs. Before every order, use GET /v1/public/fee-estimate to calculate the required package; do not choose it at random.
trx_topup Optional
Guaranteed cost coverage. A separate 0.5 TRX fee is deducted from the service balance. The method is selected automatically: 400 Bandwidth for 1 hour or 0.345 TRX sent to the sender wallet.
trx_topup_amount Optional
Use 0.345 when enabled and 0 when disabled. This is the service denomination, not the fee: do not use 0.5 here.

Only these two combinations are valid

Coverage off

JSON
{"trx_topup": false, "trx_topup_amount": 0}

Coverage on

JSON
{"trx_topup": true, "trx_topup_amount": 0.345}

price_trx includes only Energy. The 0.5 TRX coverage fee is charged separately.

trx_topup_sent=true means TRX was sent or a Bandwidth order was accepted; delegation may still be in progress. trx_topup_blockchain_tx_id can be null until the transaction hash is available. Your client does not need to poll Netts.

Example response

JSON
{
  "price_trx": 2.8,
  "balance_trx_after": 122.7
}

Examples are illustrative; tariff and order prices may differ.