Cómo automatizar el alquiler de energía TRON con la API

2026-05-13

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 de 1h, 1d, 3d, 30d.
  • energyAmount (obligatorio): cuánta energía delegar; el mínimo es 15000. Para una transferencia estándar de USDT a un destinatario que ya tiene USDT, 65000 es el número seguro; para una primera transferencia a alguien que todavía no tiene USDT, usa 130000.
  • destinationAddress (obligatorio): la dirección TRON (base58check, empieza con T) que recibe la energía.
  • preActivateDestinationAddress (opcional, por defecto 0): ponlo en 1 si la dirección de destino nunca recibió TRX y por lo tanto no está activada on-chain. El servicio entonces envía 1.5 TRX de tu saldo prepagado para activarla antes de delegar. Si la dirección ya está activa, déjalo en 0 para 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.

  1. 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 el requestId en la alerta.
  2. INVALID_ADDRESS: la destinationAddress no pasó la decodificación base58check en el servidor. Si construyes direcciones a partir de entradas de usuarios, valídalas localmente antes; la librería tronpy tiene is_address(), y rechazar la entrada mala en el cliente es más rápido que esperar la ida y vuelta.
  3. 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 pasa preActivateDestinationAddress=1 en la siguiente llamada para que el servicio la active por 1.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.

¿Quieres ahorrar en comisiones de TRON? Consulta ahora los precios de la energía. Estimación de precio
Volver al blog