For the complete documentation index, see llms.txt. This page is also available as Markdown.

Quickstart

Make your first energy rental in about five minutes, once you have credentials.

This guide takes one USDT transfer from estimate to reclaim: check capacity, estimate the energy, rent it, broadcast inside the 10-second window and confirm the reclaim. Steps 2 to 6 have cURL, Node.js and Python code.

Before you begin

  • Credentials from our team. An API key, an API secret and the base URL. Getting access explains how to request them.

  • Node.js 18 or later, or Python 3.9 or later with requests (pip install requests). The cURL examples also need openssl, which ships with macOS and most Linux distributions.

  • A synced clock. We reject a request whose timestamp is more than 30 seconds from our clock, so keep your machine on network time.

  • A USDT sending address. A TRON address that holds USDT (TRC-20), is activated on chain and can sign transfers with your existing signing setup. Keep a few TRX on it for bandwidth beyond the free daily allowance. The API calls this address the receiver: it sends the transfer and receives the energy. Check an address shows whether it is activated, and Activate an address activates a new one.

Export your values. Sample IDs, addresses and hashes are illustrative: replace them with your own sending address and a recipient you control.

env.sh
export BASE_URL="https://<your-base-url>"   # shared with your credentials; leave out any trailing /v1
export API_KEY="<your-api-key>"
export API_SECRET="<your-api-secret>"
export SENDER="TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg"      # your USDT sending address
export RECIPIENT="TDyfoQmyKQoimRXgKfGsK94JBpZh2aVe3Y"   # the address that receives the USDT
export AMOUNT="1000000"                                  # 1 USDT, in the smallest unit

Make your first rental

1

Set up the signing helper

Every request is signed with HMAC-SHA256 and your API secret. Save the signing helper for your language from Authentication and signing › Signing helpers: tron_energy.sh (cURL), tron_energy.mjs (Node.js) or tron_energy.py (Python). Steps 2 to 6 call it. Run source env.sh in the shell you use, and for cURL also source tron_energy.sh. Nothing is sent in this step.

2

Check capacity

GET /v1/capacity returns the energy available now and the current wait. It is a signed GET with no body.

capacity.sh
signed_curl GET /v1/capacity

Save as capacity.mjs and run node capacity.mjs.

capacity.mjs
import { signedRequest } from "./tron_energy.mjs";

const { status, data } = await signedRequest("GET", "/v1/capacity");
console.log(status);
console.log(JSON.stringify(data, null, 2));

Save as capacity.py and run python3 capacity.py.

capacity.py
import json

from tron_energy import signed_request

status, data = signed_request("GET", "/v1/capacity")
print(status)
print(json.dumps(data, indent=2))

Expected response:

200 OK
{
  "status": "busy",
  "energy_available_now": 0,
  "max_single_rental": 140000,
  "daily_remaining": 41000000,
  "queue_length": 2,
  "estimated_wait_seconds": 31
}

In this sample the status is busy, so a new rental would be queued for about 31 seconds. When the status is ok, a rental returns 201 and the energy is on your address at once. Check capacity lists every status.

3

Estimate energy

POST /v1/estimate simulates your USDT transfer and returns the energy and bandwidth it needs. Both addresses are screened.

estimate.sh
BODY=$(printf '{"from":"%s","to":"%s","token":"USDT","amount":"%s"}' "$SENDER" "$RECIPIENT" "$AMOUNT")
signed_curl POST /v1/estimate "$BODY"

Save as estimate.mjs and run node estimate.mjs.

estimate.mjs
import { signedRequest } from "./tron_energy.mjs";

const { SENDER, RECIPIENT, AMOUNT } = process.env;
const { status, data } = await signedRequest("POST", "/v1/estimate", {
  from: SENDER,
  to: RECIPIENT,
  token: "USDT",
  amount: AMOUNT,
});
console.log(status);
console.log(JSON.stringify(data, null, 2));

Save as estimate.py and run python3 estimate.py.

estimate.py
import json
import os

from tron_energy import signed_request

status, data = signed_request("POST", "/v1/estimate", {
    "from": os.environ["SENDER"],
    "to": os.environ["RECIPIENT"],
    "token": "USDT",
    "amount": os.environ["AMOUNT"],
})
print(status)
print(json.dumps(data, indent=2))

Expected response:

200 OK
{
  "energy_required": 64285,
  "recipient_holds_token": true,
  "bandwidth_required": 346,
  "sender_free_bandwidth_left": 600,
  "burn_cost_trx_if_unsponsored": 6.43,
  "receiver_activated": true
}

energy_required is the energy the transfer needs: about 64,285 when the recipient already holds USDT and about 130,285 when it has never held USDT. burn_cost_trx_if_unsponsored is the TRX the network would burn without delegated energy, 6.43 TRX in this sample.

4

Create a rental

POST /v1/rentals in transaction mode simulates your transfer and delegates the energy it needs, plus 5%, to the receiver. The status code tells you where the rental stands:

  • 201 Created: the energy is on your sending address and the 10-second window is open.

  • 202 Accepted: the request is queued. Poll GET /v1/rentals/{id} every 2 to 5 seconds until status is active.

The window opens as soon as the rental is active, so have your signed transfer ready first. Step 5 signs the transfer, calls the code below and broadcasts.

cURL shows the responses, but a rental made by hand usually expires before you can broadcast, so use the Node.js or Python code for steps 4 and 5. A response with "status": "pending" means the request is queued: paste its rental_id below and repeat the call until status is active.

rental.sh
BODY=$(printf '{"mode":"transaction","receiver":"%s","transaction":{"token":"USDT","to":"%s","amount":"%s"},"max_wait_seconds":300}' "$SENDER" "$RECIPIENT" "$AMOUNT")
signed_curl POST /v1/rentals "$BODY"

RENTAL_ID="rnt_01J9X5..."   # paste the rental_id from the response above
signed_curl GET "/v1/rentals/$RENTAL_ID"

Save as rental.mjs. The file defines createRental, which returns the rental once it is active. Step 5 calls it, so do not run it on its own.

rental.mjs
import { signedRequest } from "./tron_energy.mjs";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Creates a transaction-mode rental and returns it once it is active.
// 201: the energy is already on the receiver. 202: queued, so poll until active.
export async function createRental(sender, recipient, amount, maxWaitSeconds = 300) {
  let { status, data } = await signedRequest("POST", "/v1/rentals", {
    mode: "transaction",
    receiver: sender, // the address that sends the transfer and receives the energy
    transaction: { token: "USDT", to: recipient, amount },
    max_wait_seconds: maxWaitSeconds,
  });
  if (status !== 201 && status !== 202) {
    throw new Error(`Rental request failed: HTTP ${status} ${JSON.stringify(data)}`);
  }

  const rentalId = data.rental_id;
  while (data.status === "pending") {
    await sleep(2000); // poll every 2 to 5 seconds
    ({ status, data } = await signedRequest("GET", `/v1/rentals/${rentalId}`));
    if (status !== 200) {
      throw new Error(`Rental lookup failed: HTTP ${status} ${JSON.stringify(data)}`);
    }
  }

  if (data.status !== "active") {
    throw new Error(`Rental ${rentalId} ended as ${data.status} (${data.failure_reason ?? "no failure reason"})`);
  }
  return data;
}

Save as rental.py. The file defines create_rental, which returns the rental once it is active. Step 5 calls it, so do not run it on its own.

Expected response:

{
  "rental_id": "rnt_01J9X4...",
  "status": "active",
  "mode": "transaction",
  "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  "energy_delegated": 67500,
  "energy_used": null,
  "delegator": "T...",
  "delegate_tx": "8f3c...",
  "activation_tx": null,
  "created_at": "2026-10-19T10:00:00Z",
  "starts_at": "2026-10-19T10:00:03Z",
  "expires_at": "2026-10-19T10:00:13Z"
}
{
  "rental_id": "rnt_01J9X5...",
  "status": "pending",
  "pending_reason": "waiting_for_energy",
  "reason": "busy",
  "estimated_wait_seconds": 31,
  "estimated_ready_at": "2026-10-19T10:00:31Z",
  "queue_position": 1,
  "serve_by": "2026-10-19T10:05:00Z",
  "receiver": "TJdhGqPPUGMhLWxZdMU87f7muvoN14LPpg",
  "created_at": "2026-10-19T10:00:00Z"
}

energy_delegated is the simulated need plus 5%: 64,285 energy becomes 67,500. A queued rental is served first in, first out, and ends as expired if it is still waiting at serve_by. Rental lifecycle covers the queue and every status.

5

Broadcast your signed transfer

The energy is on the receiver for 10 seconds, from starts_at to expires_at. Sign the USDT transfer before you create the rental, hold it, and broadcast it the moment the rental is active. The Node.js and Python code does this in one run: it signs, calls createRental or create_rental from step 4, then broadcasts.

TronWeb (Node.js) and tronpy (Python) stand in for your existing signing setup. Replace the marked block with your own signer and key custody. Your private key never reaches Luganodes: only the signed transaction leaves your system, and it goes to a TRON node.

TRON libraries set a transaction to expire 60 seconds after it is built, so the code extends the expiry by max_wait_seconds to outlast a queued rental.

Run this from a script the moment the rental is active: typed by hand, it usually misses the window. signed-transaction.json is the signed transaction from your own signing setup, since cURL cannot sign it.

broadcast.sh
export TRON_NODE_URL="https://<your-tron-node>"   # the TRON node or RPC provider you already use
curl -sS -X POST "$TRON_NODE_URL/wallet/broadcasttransaction" \
  -H "Content-Type: application/json" \
  --data-binary @signed-transaction.json

Run npm install tronweb, then set TRON_NODE_URL to the node you already use and SENDER_PRIVATE_KEY to the key of your sending address. Save as transfer.mjs and run node transfer.mjs.

transfer.mjs
import { TronWeb } from "tronweb";
import { createRental } from "./rental.mjs";

const { SENDER, RECIPIENT, AMOUNT, TRON_NODE_URL, SENDER_PRIVATE_KEY } = process.env;
const USDT = "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t"; // USDT (TRC-20) on TRON mainnet
const MAX_WAIT_SECONDS = 300;

// Your existing signing setup: replace this block with your own signer.
const tronWeb = new TronWeb({ fullHost: TRON_NODE_URL, privateKey: SENDER_PRIVATE_KEY });
const { transaction } = await tronWeb.transactionBuilder.triggerSmartContract(
  USDT,
  "transfer(address,uint256)",
  { feeLimit: 30000000 }, // caps the TRX burned if the energy falls short: 30 TRX, in sun
  [
    { type: "address", value: RECIPIENT },
    { type: "uint256", value: AMOUNT },
  ],
  SENDER,
);
// A transaction expires 60 seconds after it is built. Extend it to outlast a queued rental.
const extended = await tronWeb.transactionBuilder.extendExpiration(transaction, MAX_WAIT_SECONDS);
const signedTransaction = await tronWeb.trx.sign(extended);

// Create the rental and wait until it is active.
const rental = await createRental(SENDER, RECIPIENT, AMOUNT, MAX_WAIT_SECONDS);
console.log(`Rental ${rental.rental_id} is active until ${rental.expires_at}`);

// Broadcast at once, inside the 10-second window.
const result = await tronWeb.trx.sendRawTransaction(signedTransaction);
console.log(JSON.stringify({ result: result.result, txid: result.txid, code: result.code, message: result.message }, null, 2));
if (!result.result) process.exitCode = 1;

Run pip install tronpy, then set TRON_NODE_URL to the node you already use and SENDER_PRIVATE_KEY to the hex key of your sending address. Save as transfer.py and run python3 transfer.py.

Expected output:

Output
Rental rnt_01J9X5... is active until 2026-10-19T10:00:41Z
{
  "result": true,
  "txid": "4f9a..."
}

"result": true means the transaction was accepted for broadcast. Keep the rental_id for step 6.

6

Confirm the reclaim

After the window closes we reclaim the energy. GET /v1/rentals/{id} then shows the final status, the energy_used and the reclaim_tx.

confirm.sh
export RENTAL_ID="rnt_01J9X5..."   # the rental_id from step 4
signed_curl GET "/v1/rentals/$RENTAL_ID"

Set RENTAL_ID, save as confirm.mjs and run node confirm.mjs.

confirm.mjs
import { signedRequest } from "./tron_energy.mjs";

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
const path = `/v1/rentals/${process.env.RENTAL_ID}`;

// The reclaim follows the end of the window. Poll until the rental reaches a final status.
let { status, data } = await signedRequest("GET", path);
for (let attempt = 0; attempt < 20 && status === 200 && ["pending", "active"].includes(data.status); attempt++) {
  await sleep(3000);
  ({ status, data } = await signedRequest("GET", path));
}
console.log(status);
console.log(JSON.stringify(data, null, 2));

Set RENTAL_ID, save as confirm.py and run python3 confirm.py.

confirm.py
import json
import os
import time

from tron_energy import signed_request

path = f"/v1/rentals/{os.environ['RENTAL_ID']}"

# The reclaim follows the end of the window. Poll until the rental reaches a final status.
status, data = signed_request("GET", path)
for _ in range(20):
    if status != 200 or data["status"] not in ("pending", "active"):
        break
    time.sleep(3)
    status, data = signed_request("GET", path)

print(status)
print(json.dumps(data, indent=2))

Expected response:

200 OK
{
  "rental_id": "rnt_01J9X5...",
  "status": "reclaimed",
  "energy_delegated": 67500,
  "energy_used": 64285,
  "delegate_tx": "8f3c...",
  "reclaim_tx": "a91d...",
  "queued_at": "2026-10-19T10:00:00Z",
  "starts_at": "2026-10-19T10:00:31Z",
  "expires_at": "2026-10-19T10:00:41Z",
  "reclaimed_at": "2026-10-19T10:00:44Z",
  "failure_reason": null
}

status: reclaimed means the window closed and the energy was reclaimed. energy_used is the energy your transfer consumed and is final, and reclaim_tx is the hash of the reclaim transaction.

To verify on chain, open delegate_tx, your transfer's txid and reclaim_tx on Tronscan. A transaction page is at https://tronscan.org/#/transaction/<hash>.

If it fails

Every error uses the format described in Errors, which lists every code and whether to retry. These are the most likely problems on a first run.

Symptom
Cause
Fix

401 UNAUTHORIZED on any call

A wrong key or secret, a clock more than 30 seconds off, or a signature that does not match the request

Work through the causes in Authentication and signing

422 RECEIVER_NOT_ACTIVATED in step 4

The sending address has never been activated on chain

Call Activate an address, or set activate_if_needed to true on the rental

422 SIMULATION_FAILED in step 3 or 4

The transfer would fail on chain, usually because the sending address holds too little USDT

Check the sender's USDT balance. details.chain_message holds the chain's message

409 ACTIVE_RENTAL_EXISTS in step 4

The address already has a pending or active rental

Poll the rental in details.rental_id until it ends, then create a new one

503 CAPACITY_EXHAUSTED in step 4

The estimated wait is longer than max_wait_seconds, or no energy is available

Check capacity again and retry later, or send the transfer and pay TRX

The transfer fails or burns TRX in step 5

The window closed before the broadcast, or the signed transaction expired in the queue

Create a new rental, sign with a longer expiration and broadcast as soon as it is active. See Rental lifecycle

Next steps