How to automate TRON energy rental with the API
If you run a hot wallet, an exchange withdrawal engine or a contract that sends TRC-20 transfers on behalf of users, you need TRON energy ready the moment a transaction fires. Topping up by hand in a UI does not scale past a handful of transfers a day, and if you miss the window the transaction burns TRX from the sending address instead, usually at a much higher cost than rented energy. The fix is to call the rental API right before your backend broadcasts, so energy is provisioned with no human in the loop.
What the API does on-chain
TRON splits computation (energy) from transaction size (bandwidth). A standard USDT TRC-20 transfer takes roughly 65,000 energy when the recipient already holds USDT and about 130,000 when the recipient's USDT balance is zero, because the first incoming transfer pays for creating the balance entry; the cost depends on the recipient, not the sender. Bandwidth is around 345 bytes, small enough that most accounts cover it from the free daily allowance.
When you call the rental API, the service stakes its own TRX and delegates the resulting energy to the address you name, using DelegateResourceContract from Stake 2.0. The delegation is tied to that address and to the rental period, and when the period ends the service reclaims the energy automatically.
The rental is asynchronous. The call returns at once with an orderId and the state PAID_BY_USER; the delegation transaction is broadcast in the background and usually lands within a few seconds. Treat the first response as confirmation that the order was accepted and paid, then poll the order details endpoint until the state is ENERGY_DELEGATED.
Picking a duration
period takes one of four values: 1h, 1d, 3d, 30d. Prices follow the on-chain energy market and move during the day, so the live numbers are on the pricing page. The order is stable: 1h is the cheapest per call, 30d the cheapest when spread across many transfers from the same address.
For an event-driven system that rents once per outgoing transfer, 1h is almost always right: the lowest absolute cost, and the energy is spent seconds after it is delegated. 1d and longer suit predictable batch jobs such as a nightly payout, where you rent one large block instead of calling the API dozens of times. If one address consistently sends more than 20-30 transfers an hour, a 1d block sized to your expected volume is cleaner than per-transfer calls: more upfront cost, but the API round trips and the on-chain confirmation latency leave the hot path.
Request shape
The rental endpoint is:
GET https://api.tronenergyrent.com/place-energy-order
A plain GET with query parameters. Authentication is the apiKey parameter, generated in your dashboard once you have registered and funded the account. There is no header auth and no JSON body.
The parameters:
apiKey(required): your API key from the dashboard.period(required): one of1h,1d,3d,30d.energyAmount(required): how much energy to delegate, minimum15000. For one standard USDT transfer to a recipient who already holds USDT,65000is the safe number; for a first transfer to a new USDT holder, use130000.destinationAddress(required): the TRON address (base58check, starting withT) that receives the energy.preActivateDestinationAddress(optional, default0): set to1if the destination has never received TRX and is therefore not activated on-chain. The service then sends1.5 TRXfrom your prepaid balance to activate it before delegating. Leave it at0for an active address to avoid the extra cost.
The HTTP status is always 200, whether the order succeeded or not, so branch on the status field in the JSON body. A success body:
{
"status": "SUCCESS",
"errorCode": null,
"errorDescription": null,
"requestId": "2651eacd-2428",
"payload": {
"orderId": "128de799-501e-44b2-8d6f-1fa825c2deed",
"totalPriceSun": 5662800,
"totalPriceTrx": 5.6628,
"state": "PAID_BY_USER"
}
}
An error body has status: "ERROR", a machine-readable errorCode and a human-readable errorDescription:
{
"status": "ERROR",
"errorCode": "INVALID_ENERGY_AMOUNT",
"errorDescription": "energyAmount is less than 15000",
"requestId": "71431087-4",
"payload": null
}
Log requestId on both branches; it is what support searches for when you ask them to trace an order.
Order lifecycle
The state field moves through a short fixed sequence:
PAID_BY_USER: the order is paid from your balance; nothing has happened on-chain yet.WAITING_DELEGATION: the service has picked up the order and is preparing the delegation transaction.ENERGY_DELEGATED: the delegation is on-chain. The destination address holds the energy and can spend it on its next outbound transaction.ERROR_DELEGATION: the delegation failed. Rare, but possible under heavy network congestion.CANCELLED: the order was cancelled and the funds refunded to your balance.
To check the current state:
GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID
The response uses the same status / errorCode / payload envelope, with state inside payload. Poll every second or two after placing the order and send the TRC-20 transfer only once you see ENERGY_DELEGATED; in practice that is one or two polls.
A Python integration
A minimal but production-shaped version: it places the order, polls until the delegation is on-chain and raises a clear error if anything goes wrong.
import logging
import time
import requests
API_BASE = "https://api.tronenergyrent.com"
API_KEY = "your_api_key_here"
ENERGY_FOR_TRANSFER = 65_000 # use 130_000 if recipient has zero USDT balance
HTTP_TIMEOUT_SECS = 10
POLL_INTERVAL_SECS = 1
POLL_TIMEOUT_SECS = 30
def place_order(destination_address: str, period: str = "1h",
energy_amount: int = ENERGY_FOR_TRANSFER) -> dict:
resp = requests.get(
f"{API_BASE}/place-energy-order",
params={
"apiKey": API_KEY,
"period": period,
"energyAmount": energy_amount,
"destinationAddress": destination_address,
"preActivateDestinationAddress": 0,
},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"place-energy-order failed: {body.get('errorCode')} "
f"({body.get('errorDescription')}) requestId={body.get('requestId')}"
)
return body["payload"]
def wait_for_delegation(order_id: str) -> dict:
deadline = time.monotonic() + POLL_TIMEOUT_SECS
while time.monotonic() < deadline:
resp = requests.get(
f"{API_BASE}/single-order-details",
params={"apiKey": API_KEY, "orderId": order_id},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"single-order-details failed: {body.get('errorCode')} "
f"({body.get('errorDescription')})"
)
state = body["payload"]["state"]
if state == "ENERGY_DELEGATED":
return body["payload"]
if state == "ERROR_DELEGATION":
raise RuntimeError(f"Delegation failed for order {order_id}")
if state == "CANCELLED":
raise RuntimeError(f"Order {order_id} was cancelled")
time.sleep(POLL_INTERVAL_SECS)
raise TimeoutError(f"Order {order_id} did not reach ENERGY_DELEGATED in {POLL_TIMEOUT_SECS}s")
def rent_energy(destination_address: str) -> dict:
placed = place_order(destination_address)
logging.info(
"Order placed: id=%s priceSun=%s priceTrx=%s",
placed["orderId"], placed["totalPriceSun"], placed["totalPriceTrx"],
)
delegated = wait_for_delegation(placed["orderId"])
logging.info("Order delegated: id=%s", delegated["orderId"])
return delegated
Three details matter. The explicit status == "SUCCESS" check, because the HTTP status is always 200 and resp.raise_for_status() alone says nothing about the outcome. The hard timeout on the polling loop, so a stuck order cannot block your transfer pipeline. And the explicit branching on state for the three terminal outcomes (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) instead of a generic "not success".
In the transfer workflow, call rent_energy() first and broadcast the TRC-20 transfer after it returns. Broadcast first and the transaction burns TRX from the sender, because the delegation has not landed yet.
Prepaid balance
Rentals are paid from the prepaid balance of your tronenergyrent.com account. Set an alert or an automatic top-up for when it drops below a threshold; a reasonable floor is two hours of peak volume. The minimum top-up is 10 TRX. To read the balance programmatically:
GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY
The payload includes the current balance and account state. Feed it into your monitoring and a depleted balance at 2am stops being a surprise.
Errors you will see
Three failure modes come up most often in production. The codes are the real API's, so you can branch on them.
INSUFFICIENT_BALANCE: the prepaid balance does not cover the rental plus any pre-activation. Retrying will not help; catch it, raise an alert or trigger a top-up, and include therequestIdin the alert.INVALID_ADDRESS:destinationAddressfailed base58check decoding on the server. If you build addresses from user input, validate them locally first; thetronpylibrary hasis_address(), and rejecting bad input client-side beats waiting for the round trip.INACTIVE_DESTINATION_ADDRESS_ERROR: the destination has never been activated on-chain and you did not ask the service to do it. Either fund the address with a little TRX from elsewhere, or passpreActivateDestinationAddress=1on the next call and the service activates it for1.5 TRX.
A subtler one: ORDER_IS_ALREADY_IN_PROGRESS comes back when several workers place rentals for the same destination at the same time. Fix it on your side with a distributed lock (Redis is fine) keyed on the destination address and held until the delegation completes.
Verifying on-chain
For most integrations, polling /single-order-details until ENERGY_DELEGATED is enough. If you want an extra check, query the TRON full node after the delegation lands:
GET https://api.trongrid.io/v1/accounts/{destinationAddress}
The response has the address's current resource state, including energy delegated to it from other addresses. The exact field name depends on the current Stake 2.0 view, so check the live TRON HTTP API docs when wiring it in. Run it as a soft check that logs a warning instead of blocking the transfer. It catches the rare case where the rental looks fine in the API and something downstream went wrong on-chain, and that one time it will save you hours of debugging.