Perguntas e respostas
O que os integradores perguntam antes do primeiro pedido, agrupado e respondido curto. Onde a resposta pertence ao contrato e não a um hábito nosso, a documentação da API diz o mesmo em detalhe.
Energia e preço
O que é energia na TRON?
Um recurso da rede que paga a execução de contratos inteligentes. Com energia suficiente na carteira de origem, uma transferência de USDT quase não queima TRX.
Por que sai mais barato que queimar?
Queimar precifica a energia pela taxa do protocolo, ~100 sun por unidade — um parâmetro da cadeia que a rede revisa de tempos em tempos; este ano ele foi cortado. Nós conseguimos energia delegada em volume e vendemos por uma fração dessa taxa; o preço em vigor agora está na página de preços.
Ver todos os preços →
E se eu perder a janela de envio?
No mode A a cobrança fica de pé: a energia foi entregue, e o que você paga é a entrega. No mode B não transmitimos nada depois que a janela fecha, então a posição falha e a reserva volta inteira. A janela vem com cada pedido — monte seu fluxo em torno dela.
Posso comprar energia em volume para uma única carteira?
De 65,000 a 50,000,000 unidades de energia por carteira em um único pedido, com preço por unidade na tarifa em vigor no momento em que o pedido é criado. Uma posição por carteira, e quanto desse volume o mercado consegue cobrir agora mesmo pode ser perguntado livremente com POST /v1/estimate antes de reservar qualquer coisa.
Acima de 131,000 unidades, o aluguel precisa ser de uma hora ou mais. Se o pedido é tudo ou nada é decidido antes da primeira compra (allow_partial); uma falta após a primeira compra é entregue e cobrada pelo que foi entregue.
Energia em volume na página de preços →
Perder a janela de envio custa o mesmo nos dois modos?
Não. No mode A a energia foi entregue, então a cobrança fica de pé — e no mode C também, onde não há transferência para esperar e a posição simplesmente expira quando a janela fecha. No mode B não transmitimos nada depois que a janela fecha: uma transferência enviada tarde encontraria uma carteira de onde a energia delegada já saiu, e queimaria o seu TRX. A posição fecha como failed com broadcast_window_missed, a reserva volta inteira, e a energia comprada para ela é prejuízo nosso.
Dinheiro e estornos
Como eu pago?
Créditos de serviço pré-pagos, denominados em TRX: envie TRX para o seu endereço pessoal e gaste em serviços. Os preços são travados na criação do pedido.
Qual token posso mandar para o meu endereço de depósito?
TRX, e só TRX. USDT enviado para um endereço de depósito não é creditado automaticamente: não assumimos risco de câmbio e não operamos serviço de conversão, então isso fica separado para uma pessoa olhar, e creditar ou não é decisão nossa, caso a caso. Mandou o token errado? Escreva para nós e não mande mais.
Em quanto tempo posso gastar um depósito?
Depois de 3 confirmações — cerca de dez segundos. Aí o saldo aparece em três partes: o total, o que está reservado para pedidos em andamento e o que está disponível. O pedido é criado a partir da parte disponível, nunca do total.
Dá para cancelar um pedido?
Só antes de a compra começar; depois disso a resposta é order_not_cancelable, porque a energia já foi comprada. Um pedido cancelado libera a reserva inteira e não cobra nada.
E os estornos?
As liberações são automáticas e nunca precisam de chamado. A regra é uma só: energia que não entregamos não é cobrada, e a reserva volta para o seu saldo em créditos de serviço — uma entrega que falhou, um pedido cancelado antes de a compra começar, a parte não gasta de um dia de Auto-refill. Energia entregue é cobrada, você tendo usado ou não. Uma exceção: excluir uma regra de Auto-refill antes de as recargas dela cobrirem o que pagamos antecipadamente ao nosso fornecedor pela carteira cobra a parte descoberta.
Segurança e chaves
De quais chaves vocês precisam?
Nenhuma. O mode A nunca vê a sua transação. O mode B recebe uma que você já assinou, e não podemos alterar um byte dela.
Vocês aceitam um remetente com multiassinatura?
No mode B, não: a transação precisa levar exatamente uma assinatura do dono, com Permission_id 0. O conjunto de chaves de uma conta multiassinatura vive na rede e muda sem o nosso conhecimento, então não podemos prometer que a transmissão seria aceita. No mode A nada sobre como você assina chega até nós — a transferência é você quem transmite.
O que vocês guardam, e por quanto tempo?
No mode B a sua transação assinada fica guardada criptografada e é apagada 7 dias depois de o pedido chegar a um status final. Pedidos, lançamentos do razão e depósitos ficam: isso é contabilidade, e é a parte que somos obrigados a manter. Nada mais seu está aqui — nem chaves privadas, nem frases-semente, nem custódia do seu dinheiro.
Integração
Existem limites?
120 pedidos por minuto por chave, até 500 transferências por pedido em lote. Passando do limite você recebe Retry-After, não um descarte silencioso.
O que completed quer dizer de verdade?
Que a energia foi entregue — não que a sua transferência saiu. O compromisso é a entrega, e o pedido fecha nela: no mode A, completed pode chegar antes de você ter enviado qualquer coisa. Fique de olho no send_before aparecendo no pedido, e não na palavra ready: consultando a cada dois segundos, você pode nunca ver ready.
Como funciona a idempotência?
Uma Idempotency-Key fica ligada aos bytes crus do corpo com que ela chegou. A mesma chave e um corpo idêntico byte a byte devolvem o mesmo pedido; a mesma chave com outro corpo é um conflito; um pedido barrado pela validação não gasta a chave, então dá para repetir com a mesma chave depois de corrigir o corpo. Serialize o corpo uma vez e reenvie exatamente aqueles bytes — outra ordem de chaves ou um espaço a mais já é outro corpo.
Dá para conferir um endereço sem pagar nada?
Dá, e é de graça. GET /v1/address-check conta o que sabemos de uma carteira, e POST /v1/estimate calcula até 500 destinatários pelas mesmas regras que um pedido usaria — inclusive quais deles o contrato do token põe na lista negra. Nenhum dos dois reserva nada nem cobra nada.
Sua conta
Uma carteira pode se manter abastecida sozinha?
Sim — uma regra de Auto-refill: um endereço mais um limite diário. A energia se recarrega depois de cada transferência; o limite é um teto diário rígido.
Em quanto devo deixar o balance.low?
O número é um ajuste seu — balance_low_threshold_trx em PATCH /v1/settings; balance.low é o evento que ele dispara. A medida útil é perto do seu giro de um dia: aí o aviso chega um dia antes de os pedidos começarem a receber insufficient_balance, em vez de chegar no lugar da primeira recusa. Bem mais baixo, e o evento vira aviso depois do fato; bem mais alto, e vira ruído. Zero desliga.
Minha equipe de operações pode ter acesso somente leitura?
Sim. Uma conta comporta quantas pessoas você convidar, cada uma com um dos quatro papéis — viewer, member, admin, owner — e cada papel faz tudo o que o anterior faz. Um viewer lê o saldo, o livro-razão, os pedidos e a tarifa, e não pode gastar nada; um member cria pedidos e estimativas; um admin gerencia chaves de API, webhooks, configurações e a equipe; o owner é a própria conta. Um convite concede viewer, member ou admin; o owner é a conta e não é convidado. Convites e papéis vivem no painel, e só regem o painel: uma chave de API pertence à conta, não a uma pessoa, e carrega acesso completo não importa quem a criou.
Existe sandbox, ou volume mínimo?
Sem volume mínimo, sem assinatura e sem pagar por tempo parado. Sandbox existe: https://sandbox.nrg.market/v1 é a mesma API sobre dinheiro de teste e uma rede simulada, e sandbox-app.nrg.market emite as chaves nrg_test_… dela. Ela prova o seu lado da integração — formatos de requisição, status, webhooks, tempos — mas não que a energia chega on-chain; isso só se descobre em produção. No host de produção, os endpoints de consulta, uma estimativa e um teste de webhook continuam sem custar nada.
https://sandbox.nrg.market/v1
sandbox-app.nrg.market