Como automatizar o aluguel de energia TRON pela API

2026-05-13

Se você opera uma carteira quente, um motor de saques de exchange ou um contrato que dispara transferências TRC-20 em nome dos usuários, conhece o problema: a energia TRON precisa estar lá no segundo em que a transação sai. Recarregar energia à mão em uma interface não escala além de algumas transferências por dia, e, se a janela passa, a transação queima TRX do endereço remetente, em geral bem mais caro do que a energia alugada com antecedência. A saída é chamar a API de aluguel no momento em que o backend vai transmitir a transação, para que a energia seja provisionada por código, sem ninguém no circuito.

O que a API faz on-chain

O modelo de recursos da TRON separa computação (energia) de tamanho da transação (bandwidth). Uma transferência padrão de USDT TRC-20 consome cerca de 65,000 de energia quando o destinatário já tem USDT e cerca de 130,000 quando o saldo de USDT dele é zero: a primeira transferência recebida paga a criação do registro de saldo, e por isso o custo depende do destinatário, não do remetente. O bandwidth de uma transferência fica em cerca de 345 bytes, pequeno o bastante para a cota gratuita diária da maioria das contas.

Quando você chama a API, o serviço faz staking do próprio TRX e delega a energia resultante ao endereço informado, com o DelegateResourceContract do Stake 2.0. A delegação é por endereço e tem prazo; quando o período expira, o serviço recupera a energia automaticamente.

O aluguel é assíncrono. A chamada retorna na hora com um orderId e o estado PAID_BY_USER, mas a transação de delegação é transmitida em segundo plano e costuma confirmar em poucos segundos. Trate a resposta inicial como confirmação de que o pedido foi aceito e pago, e consulte o endpoint de detalhes do pedido até o estado virar ENERGY_DELEGATED.

Qual duração escolher

O parâmetro period aceita quatro valores: 1h, 1d, 3d e 30d. Os preços acompanham o mercado de energia on-chain e mudam ao longo do dia, então os valores atuais estão sempre na página de preços. A ordem é estável: 1h é o mais barato por chamada, 30d o mais barato quando amortizado entre muitas transferências do mesmo endereço.

Em um sistema orientado a eventos, com um aluguel por transferência de saída, 1h é quase sempre a escolha certa: menor custo absoluto, e a energia é consumida segundos depois de delegada. Os níveis 1d e mais longos fazem sentido para cargas em lote previsíveis, como um job noturno de pagamentos, em que você aluga um bloco grande de uma vez em vez de chamar a API dezenas de vezes. Se o mesmo endereço dispara consistentemente mais de 20-30 transferências por hora, um bloco 1d dimensionado para o volume esperado é mais limpo do que uma chamada por transferência: o custo inicial sobe, mas o overhead da API e a latência de confirmação saem do caminho crítico.

Autenticação e formato da requisição

O endpoint de aluguel é:

GET https://api.tronenergyrent.com/place-energy-order

É um GET simples com parâmetros de query. A autenticação é o parâmetro apiKey, gerado no seu painel depois de criar a conta e recarregar o saldo. Não há header de autenticação nem corpo JSON. Os parâmetros:

  • apiKey (obrigatório): sua chave de API do painel.
  • period (obrigatório): a duração, um de 1h, 1d, 3d, 30d.
  • energyAmount (obrigatório): quanta energia delegar. O mínimo é 15000. Para uma transferência padrão de USDT a quem já tem USDT, 65000 é o valor seguro; para a primeira transferência a um endereço sem USDT, use 130000.
  • destinationAddress (obrigatório): o endereço TRON (base58check, começa com T) que recebe a energia.
  • preActivateDestinationAddress (opcional, padrão 0): defina 1 se o endereço de destino nunca recebeu TRX e, portanto, não está ativado on-chain. O serviço então envia 1.5 TRX do seu saldo para ativá-lo antes de delegar. Se o endereço já está ativo, deixe 0 para não pagar isso à toa.

A resposta vem sempre com HTTP 200, tenha o pedido dado certo ou não. Decida pelo campo status do JSON, não pelo status HTTP. Um sucesso:

{
  "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"
  }
}

Um erro traz status: "ERROR", um errorCode para a máquina e um errorDescription para gente:

{
  "status": "ERROR",
  "errorCode": "INVALID_ENERGY_AMOUNT",
  "errorDescription": "energyAmount is less than 15000",
  "requestId": "71431087-4",
  "payload": null
}

Registre o requestId nos dois casos. Se um dia precisar que o suporte rastreie um aluguel, é por esse ID que ele procura.

O ciclo de vida do pedido

O campo state do payload passa por uma sequência curta e fixa:

  • PAID_BY_USER: estado inicial, o pedido foi pago do seu saldo, nada aconteceu on-chain ainda.
  • WAITING_DELEGATION: o serviço pegou o pedido e está preparando a transação de delegação.
  • ENERGY_DELEGATED: a delegação foi confirmada on-chain. O endereço de destino já tem a energia e pode gastá-la na próxima transação.
  • ERROR_DELEGATION: a delegação falhou. Raro, mas possível em congestionamento forte da rede.
  • CANCELLED: o pedido foi cancelado e o valor voltou ao seu saldo.

Para consultar o estado atual:

GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID

A resposta usa o mesmo envelope status / errorCode / payload, com o state atual dentro de payload. Consulte a cada um ou dois segundos depois de fazer o pedido e só transmita a transferência TRC-20 depois de ver ENERGY_DELEGATED; na prática, uma ou duas consultas bastam.

Integração em Python

Um padrão mínimo, mas com cara de produção: faz o pedido, consulta até a delegação estar on-chain e levanta um erro claro se algo falhar.

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

Alguns pontos. A verificação explícita de status == "SUCCESS" importa porque o HTTP é sempre 200, então resp.raise_for_status() sozinho não diz nada sobre o resultado. O loop de polling tem timeout rígido, para que um pedido travado não bloqueie o pipeline indefinidamente. E o state é tratado nos três desfechos terminais (ENERGY_DELEGATED, ERROR_DELEGATION, CANCELLED) de forma explícita, em vez de um genérico “não deu certo”.

No seu fluxo, chame rent_energy() primeiro e só depois transmita a transferência TRC-20. A ordem importa: transmitir antes faz a transação queimar TRX do remetente, porque a delegação ainda não foi confirmada.

Saldo da conta

O aluguel é debitado do saldo pré-pago que você mantém na sua conta do tronenergyrent.com. Configure um alerta ou uma recarga automática quando ele cair abaixo de um piso; duas horas de volume de pico é um piso razoável. Para ler o saldo por código:

GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY

O payload traz o saldo atual e o estado da conta. Ligue isso ao seu monitoramento e um saldo zerado às 2h da manhã nunca mais pega você de surpresa. A recarga mínima do saldo no tronenergyrent.com é 10 TRX.

Erros que aparecem em produção

Três falhas são as mais comuns. Os códigos abaixo vêm da API real, e dá para ramificar neles com segurança.

  1. INSUFFICIENT_BALANCE: o saldo não cobre o aluguel pedido mais a pré-ativação, se houver. Repetir não resolve; trate esse caso à parte e dispare um alerta ou um fluxo de recarga, com o requestId no payload do alerta.
  2. INVALID_ADDRESS: o destinationAddress falhou no decode base58check no servidor. Se o seu sistema monta endereços dinamicamente, por exemplo a partir de entrada do usuário, valide-os localmente antes de chamar a API; a biblioteca Python tronpy tem is_address() para isso, e rejeitar entrada ruim no cliente é mais rápido do que esperar a ida e volta.
  3. INACTIVE_DESTINATION_ADDRESS_ERROR: o endereço de destino nunca foi ativado on-chain e você não pediu ao serviço para ativá-lo. Resolva enviando um pouco de TRX ao endereço por outra fonte ou passando preActivateDestinationAddress=1 na próxima chamada, para que o serviço o ative por 1.5 TRX.

Um caso mais sutil: ORDER_IS_ALREADY_IN_PROGRESS pode voltar quando vários workers fazem aluguéis para o mesmo destino ao mesmo tempo. A correção é no seu processo, não na API: use um lock distribuído (Redis funciona bem) com chave no endereço de destino, mantido até a delegação terminar.

Verificação on-chain

Para a maioria das integrações, consultar /single-order-details até ENERGY_DELEGATED basta. Se quiser uma segunda garantia, consulte o full node da TRON diretamente depois da confirmação:

GET https://api.trongrid.io/v1/accounts/{destinationAddress}

A resposta traz o estado atual de recursos do endereço, incluindo a energia delegada a ele por outros endereços. O nome exato do campo depende da visão atual do Stake 2.0, então confira a documentação da TRON HTTP API ao integrar. Como verificação leve, que só registra um aviso em vez de bloquear a transferência, ela serve de canário para o caso raro em que algo dá errado depois da própria API de aluguel, e economiza horas de depuração na única vez em que o aluguel parecer bem-sucedido na API mas algo sair errado on-chain.

Quer economizar nas taxas de transação TRON? Confira os preços de energia agora. Estimativa de Preço
Voltar ao Blog