O que uma API de energia TRON realmente faz
Uma API de energia TRON vende uma coisa só, e não é desconto em taxa. A sua conta precisa de energia para executar o contrato do USDT, e sem ela a rede cobra em TRX, a 100 sun por unidade. Uma API de energia faz com que outra conta — uma que tenha feito stake de TRX — empreste a energia dela ao endereço que vai assinar a sua transferência, por alguns minutos. Tudo o que vem abaixo é o formato das requisições em volta desse único fato on-chain.
On-chain é uma delegação, e você não assina nada dela
A conta que empresta assina uma delegação nomeando o seu endereço. O seu endereço não assina nada, não aprova nada e não concede nada em troca: a rede eleva o limite de energia dele, e o evento é isso e mais nada (o que é energia). É por isso que uma API de energia pede um endereço e nunca uma chave — a única assinatura do arranjo é a do outro lado.
O menor fluxo que funciona
A URL base é https://api.nrg.market/v1 e a chave viaja em um cabeçalho só, Authorization: Bearer nrg_live_…. Ela aparece uma única vez, na emissão, e pode ser fixada a uma lista de IPs. Chame do seu servidor: os endpoints autenticados não liberam origem de navegador nenhuma, porque uma chave que chega a uma página é uma chave que todo mundo tem. Existe uma segunda URL base, num subdomínio sandbox de nrg.market — a mesma superfície /v1 sobre dinheiro de teste e uma rede simulada, com chaves nrg_test_… próprias e um painel próprio, documentada em docs.nrg.market.
Comece pelo POST /v1/estimate. Ele não reserva nada e não cobra nada, aceita até 500 destinatários numa chamada e devolve o que um pedido calcularia.
curl -s https://api.nrg.market/v1/estimate \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-d '{"duration_s":300,
"transfers":[{"from":"TQ5NMqJjW8sBGqcpvUcXhbXm3jGnyDCmwK",
"to":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9"}]}'
{"items":[{"to":"TN3W…","kind":"single","energy_units":65000,"warnings":[]}],
"zone":"day","duration_s":300}
# resumido — a resposta também traz price_trx por item, total_trx e burn_cost_trx
kind é single para um destinatário que já tem USDT, double para um que não tem e precisa que a conta de token seja criada antes, e custom para um contrato, precificado a partir de um dry-run e não de um dos dois números padrão. from é opcional e não move preço nenhum; informá-lo compra duas respostas sobre o remetente — inactive_sender e blacklisted_sender entre os warnings — antes que um pedido no modo que você usa possa recusar por causa de uma delas.
Depois, o pedido. O mode a é aquele em que você mesmo transmite a transferência.
curl -s https://api.nrg.market/v1/orders \
-H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
-H "Idempotency-Key: 8f3c1e02-6b47-4a1d-9d5c-0b2e7c4a1f90" \
-d '{"mode":"a","client_ref":"invoice-1042",
"transfers":[{"from":"TQ5NMqJjW8sBGqcpvUcXhbXm3jGnyDCmwK",
"to":"TN3W4H6rK2ce4vX9YnFQHwKENnHjoxb3m9"}]}'
A resposta é 202 com dois cabeçalhos que vale ler em vez de montar: Location, a URL do próprio pedido, e Retry-After, os segundos a esperar antes da primeira consulta e entre as consultas. O corpo é o pedido, normalmente com status em funded e send_before ainda null — o dinheiro está reservado e a compra começou.
send_before aparece quando a energia é confirmada on-chain e o pedido chega a ready. É uma janela de cerca de quatro minutos, contada a partir da última delegação confirmada, então todos os itens de um lote dividem um mesmo prazo; leia o campo em vez de supor os quatro minutos. E fique de olho no campo aparecendo, não na palavra ready: um pedido no mode A é cumprido pela entrega de energia e não pela sua transferência, então completed pode chegar antes de você ter enviado qualquer coisa.
Duas recusas valem ser tratadas antes do primeiro pedido de verdade: 402 insufficient_balance, decidida antes de qualquer dinheiro se mover e trazendo required_trx e available_trx, e 422 invalid_address com details.reason em inactive_wallet — a carteira que envia nunca foi ativada, então não há conta para receber a delegação (as falhas por trás dessas).
A chave de idempotência
POST /v1/orders exige uma Idempotency-Key, e ela fica ligada aos bytes crus do corpo, não ao JSON já interpretado. Os mesmos bytes devolvem o pedido original; um corpo diferente sob a mesma chave é 409 idempotency_conflict e não um segundo pedido; uma requisição barrada pela validação não gasta a chave. No tamanho de um lote é isso que transforma um timeout de rede numa pergunta com resposta.
O que os cabeçalhos de limite dizem
Três contadores correm por chave de API: pedidos a 120 por minuto, requisições de consulta a 600, e GET /v1/address-check a 60, porque cada furo no cache dele é uma pergunta à cadeia. Toda resposta de um contador com chave, inclusive as bem-sucedidas, traz RateLimit-Limit, RateLimit-Remaining e RateLimit-Reset, para que um cliente possa desacelerar antes da recusa em vez de depois dela; passando do limite é 429 rate_limited com Retry-After. Um outro 429 quer dizer quase o contrário — too_many_auth_failures, onde esperar não adianta porque é a própria credencial que está sendo recusada. Ramifique pelo code, nunca pela message.
Webhooks, para o ciclo não virar uma consulta em loop
Registre um receptor com POST /v1/webhooks: a url tem que ser https, resolver para um host público e não carregar credenciais. O segredo de assinatura volta uma única vez, na criação, e uma conta mantém no máximo cinco endpoints ativos. Assine o que o fluxo precisar — order.ready, order.completed, order.partially_completed, order.failed, mais os de item, order.item.sent e order.item.expired. Toda entrega traz X-NRG-Timestamp, X-NRG-Event-Id e X-NRG-Signature, um HMAC-SHA256 sobre o timestamp, um ponto e o corpo cru: verifique contra os bytes que você recebeu, não contra um JSON que você recodificou, e deduplique pelo event_id. POST /v1/webhooks/{webhook_id}/test manda uma entrega assinada de verdade pelo caminho real e conta o que o seu endpoint respondeu, sem custo nenhum.
Mode B: você assina, nós transmitimos
O mode b troca from e to por signed_tx, a transação assinada em hex, e nós a transmitimos assim que a energia chega — ninguém fica sentado esperando uma janela de quatro minutos. O que é aceito é estreito de propósito: uma chamada transfer do contrato do USDT e nada mais, uma assinatura do dono, nenhum TRX anexado, e multiassinatura recusada, porque o conjunto de chaves de uma permissão vive na rede e pode mudar sem o nosso conhecimento. A transação precisa ter três minutos de vida sobrando quando o pedido é criado, e a expiração dela encurta a janela — send_before nunca passa desse prazo menos uma margem de transmissão. Se não der para repassá-la a tempo, o item fecha em failed com broadcast_window_missed, reserva de volta inteira.
Mode C: energia sem destinatário nomeado
O mode c aceita from e kind e destinatário nenhum — para uma carteira que você quer pronta antes de o lote existir. kind é single ou double, e acertar é com você: sem destinatário não há de onde ler o volume, então single onde double era preciso deixa a transferência curta e a diferença queima TRX. custom deliberadamente não é oferecido aqui, por ser o resultado de um dry-run contra um destinatário que é um contrato específico. Os itens levam to: null, nunca chegam a sent, e viram expired quando a janela fecha: o prazo acabou, o que é o fim normal e não uma falha — e é cobrado, porque a energia foi entregue.
O que nunca está na requisição
Não existe campo para chave privada em lugar nenhum do contrato, em modo nenhum. O mode A nunca vê a sua transação. O mode B vê uma que você já assinou, e que não podemos alterar em um byte sem quebrar essa assinatura; ela fica guardada criptografada e é apagada sete dias depois de o pedido ser final. O mode C não tem transação para ver. O que a API recebe são endereços (o resto do que guardamos e do que não guardamos).
As partes que não pedem chave
Os endpoints de consulta e o contrato não pedem chave nenhuma, e são limitados por IP em vez de por chave. GET /v1/tariff responde o preço de uma unidade de energia em sun agora, a faixa em vigor, next_change_at e uma tabela de referência — é o que a página de preços lê a cada carregamento. GET /v1/market responde o que os fornecedores que acompanhamos publicam sobre si mesmos, cada número carimbado com o instante em que foi lido e o nosso próprio preço classificado entre eles, que é a página do mercado. Cite o endpoint em vez de um número: o nosso preço é recalculado a cada poucos minutos.
O contrato em si está em https://docs.nrg.market/openapi.yaml, e byte a byte o mesmo documento em https://api.nrg.market/v1/contract.yaml — vale saber, porque o host da documentação fica atrás de uma borda que recusa alguns clientes programáticos antes de a requisição chegar até nós. O ETag ali é o SHA-256 do corpo, então If-None-Match devolve um 304 quando nada mudou. Gere o seu cliente a partir desse arquivo: esta página é um resumo, e o arquivo é aquilo a que estamos obrigados.