Cómo automatizar el alquiler de energía TRON con la API
Si operas una hot wallet, el motor de retiros de un exchange o un contrato que envía transferencias TRC-20 en nombre de usuarios, necesitas energía TRON lista en el mismo segundo en que se lanza la transacción. Recargar a mano desde una interfaz no escala más allá de unas pocas transferencias al día, y si se te pasa la ventana, la transacción quema TRX de la dirección emisora, normalmente a un costo mucho mayor que el de la energía alquilada a tiempo. La solución es llamar a la API de alquiler justo antes de que tu backend difunda la transacción, de modo que la energía se aprovisione sin intervención humana.
Qué hace la API en la cadena
TRON separa el cómputo (energía) del tamaño de la transacción (bandwidth). Una transferencia estándar de USDT TRC-20 consume alrededor de 65,000 de energía cuando el destinatario ya tiene USDT y unos 130,000 cuando su saldo de USDT es cero, porque la primera transferencia entrante paga la creación de la entrada de saldo; el costo depende del destinatario, no del emisor. El bandwidth ronda los 345 bytes, tan poco que la mayoría de las cuentas lo cubre con su asignación diaria gratuita.
Cuando llamas a la API de alquiler, el servicio bloquea sus propios TRX y delega la energía resultante a la dirección que indiques, mediante DelegateResourceContract de Stake 2.0. La delegación está atada a esa dirección y al período de alquiler, y cuando el período termina el servicio recupera la energía automáticamente.
El alquiler es asíncrono. La llamada devuelve de inmediato un orderId y el estado PAID_BY_USER; la transacción de delegación se difunde en segundo plano y suele confirmarse en pocos segundos. Trata la primera respuesta como confirmación de que el pedido se aceptó y se pagó, y luego consulta el endpoint de detalles del pedido hasta que el estado sea ENERGY_DELEGATED.
Elegir la duración
El parámetro period admite cuatro valores: 1h, 1d, 3d, 30d. Los precios siguen el mercado de energía on-chain y varían durante el día, así que los números en vivo están en la página de precios. El orden es estable: 1h es el más barato por llamada y 30d el más barato cuando se reparte entre muchas transferencias desde la misma dirección.
Para un sistema basado en eventos que alquila una vez por cada transferencia saliente, 1h es casi siempre la opción correcta: el costo absoluto más bajo, y la energía se consume segundos después de delegarse. 1d y los tramos más largos sirven para cargas por lotes predecibles, como un proceso nocturno de pagos, donde alquilas un bloque grande una sola vez en lugar de llamar a la API decenas de veces. Si una dirección envía de forma constante más de 20-30 transferencias por hora, un bloque 1d dimensionado a tu volumen esperado es más limpio que las llamadas por transferencia: más costo inicial, pero las idas y vueltas a la API y la latencia de confirmación on-chain salen de la ruta crítica.
Autenticación y forma de la solicitud
El endpoint de alquiler es:
GET https://api.tronenergyrent.com/place-energy-order
Un GET simple con parámetros de consulta. La autenticación es el parámetro apiKey, que generas en tu panel después de registrarte y recargar tu cuenta. No hay autenticación por cabecera ni cuerpo JSON.
Los parámetros:
apiKey(obligatorio): tu clave API del panel.period(obligatorio): la duración del alquiler, uno de1h,1d,3d,30d.energyAmount(obligatorio): cuánta energía delegar; el mínimo es15000. Para una transferencia estándar de USDT a un destinatario que ya tiene USDT,65000es el número seguro; para una primera transferencia a alguien que todavía no tiene USDT, usa130000.destinationAddress(obligatorio): la dirección TRON (base58check, empieza conT) que recibe la energía.preActivateDestinationAddress(opcional, por defecto0): ponlo en1si la dirección de destino nunca recibió TRX y por lo tanto no está activada on-chain. El servicio entonces envía1.5 TRXde tu saldo prepagado para activarla antes de delegar. Si la dirección ya está activa, déjalo en0para evitar el costo adicional.
El estado HTTP siempre es 200, tenga éxito o no el pedido, así que ramifica según el campo status del cuerpo JSON. Una respuesta exitosa:
{
"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"
}
}
Una respuesta de error tiene status: "ERROR", un errorCode legible por máquina y un errorDescription legible por humanos:
{
"status": "ERROR",
"errorCode": "INVALID_ENERGY_AMOUNT",
"errorDescription": "energyAmount is less than 15000",
"requestId": "71431087-4",
"payload": null
}
Registra el requestId en ambas ramas; es lo que soporte busca cuando pides rastrear un pedido.
Ciclo de vida del pedido
El campo state avanza por una secuencia corta y fija:
PAID_BY_USER: el pedido está pagado desde tu saldo; todavía no pasó nada on-chain.WAITING_DELEGATION: el servicio tomó el pedido y está preparando la transacción de delegación.ENERGY_DELEGATED: la delegación está confirmada on-chain. La dirección de destino ya tiene la energía y puede gastarla en su siguiente transacción saliente.ERROR_DELEGATION: la delegación falló. Raro, pero posible con mucha congestión en la red.CANCELLED: el pedido se canceló y los fondos volvieron a tu saldo.
Para comprobar el estado actual:
GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID
La respuesta usa el mismo envoltorio status / errorCode / payload, con el state actual dentro de payload. Consulta cada uno o dos segundos después de hacer el pedido y envía la transferencia TRC-20 solo cuando veas ENERGY_DELEGATED; en la práctica son una o dos consultas.
Una integración en Python
Un patrón mínimo pero con forma de producción: hace el pedido, consulta hasta que la delegación está on-chain y lanza un error claro si algo sale mal.
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
Tres detalles importan. La comprobación explícita de status == "SUCCESS", porque el estado HTTP siempre es 200 y resp.raise_for_status() por sí solo no dice nada del resultado. El tiempo límite estricto del bucle de consulta, para que un pedido trabado no bloquee tu pipeline de transferencias. Y la ramificación explícita según state para los tres resultados terminales (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) en lugar de un genérico «no fue éxito».
En tu flujo de transferencia, llama primero a rent_energy() y difunde la transferencia TRC-20 cuando devuelva. Si difundes primero, la transacción quema TRX del emisor porque la delegación todavía no se confirmó.
Saldo prepagado
Los alquileres se pagan del saldo prepagado de tu cuenta en tronenergyrent.com. Configura una alerta o una recarga automática para cuando baje de un umbral; un mínimo razonable es lo que cubra dos horas de volumen pico. La recarga mínima es de 10 TRX. Para leer el saldo de forma programática:
GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY
El payload incluye el saldo actual y el estado de la cuenta. Conéctalo a tu monitoreo y un saldo agotado a las 2 de la mañana deja de ser una sorpresa.
Errores que vas a ver
Tres fallas aparecen con más frecuencia en producción. Los códigos son los de la API real, así que puedes ramificar sobre ellos.
INSUFFICIENT_BALANCE: el saldo prepagado no cubre el alquiler más la preactivación, si la hay. Reintentar no sirve; captúralo, dispara una alerta o un flujo de recarga e incluye elrequestIden la alerta.INVALID_ADDRESS: ladestinationAddressno pasó la decodificación base58check en el servidor. Si construyes direcciones a partir de entradas de usuarios, valídalas localmente antes; la libreríatronpytieneis_address(), y rechazar la entrada mala en el cliente es más rápido que esperar la ida y vuelta.INACTIVE_DESTINATION_ADDRESS_ERROR: la dirección de destino nunca se activó on-chain y no le pediste al servicio que lo hiciera. Envíale un poco de TRX desde otro lugar, o pasapreActivateDestinationAddress=1en la siguiente llamada para que el servicio la active por1.5 TRX.
Un caso más sutil: ORDER_IS_ALREADY_IN_PROGRESS aparece cuando varios workers hacen alquileres para el mismo destino al mismo tiempo. Se arregla de tu lado, con un bloqueo distribuido (Redis funciona bien) con clave en la dirección de destino, mantenido hasta que la delegación se complete.
Verificación on-chain
Para la mayoría de las integraciones basta con consultar /single-order-details hasta ENERGY_DELEGATED. Si quieres una comprobación extra, consulta el nodo completo de TRON una vez confirmada la delegación:
GET https://api.trongrid.io/v1/accounts/{destinationAddress}
La respuesta contiene el estado actual de recursos de la dirección, incluida la energía delegada hacia ella desde otras direcciones. El nombre exacto del campo depende de la vista actual de Stake 2.0, así que revisa la documentación en vivo de la API HTTP de TRON al integrarlo. Ejecútalo como una comprobación blanda que registra una advertencia en lugar de bloquear la transferencia: detecta el caso raro en que el alquiler se ve bien en la API y algo salió mal on-chain, y esa única vez te ahorra horas de depuración.