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, ~210 sun por unidade — um número que nunca se move. 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 4 minutos?
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.
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.
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.
Existe sandbox, ou volume mínimo?
Sem volume mínimo, sem assinatura e sem pagar por tempo parado. Sandbox também não existe: a URL base é a de produção, e outra não há. Os endpoints de consulta, uma estimativa e um teste de webhook não custam nada, então boa parte da integração dá para construir antes de existir um único pedido.