Como automatizar o aluguel de energia TRON pela API
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 de1h,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, use130000.destinationAddress(obrigatório): o endereço TRON (base58check, começa comT) que recebe a energia.preActivateDestinationAddress(opcional, padrão0): defina1se o endereço de destino nunca recebeu TRX e, portanto, não está ativado on-chain. O serviço então envia1.5 TRXdo seu saldo para ativá-lo antes de delegar. Se o endereço já está ativo, deixe0para 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.
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 orequestIdno payload do alerta.INVALID_ADDRESS: odestinationAddressfalhou 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 Pythontronpytemis_address()para isso, e rejeitar entrada ruim no cliente é mais rápido do que esperar a ida e volta.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 passandopreActivateDestinationAddress=1na próxima chamada, para que o serviço o ative por1.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.