Guias de TRON

Como comprar energia TRON em Rust com o SDK da TronSave (2026)

Por TronSave Publicado 10 min de leitura
Nesta página

O jeito mais rápido de comprar energia TRON em Rust é o crate oficial da TronSave: adicione tronsave = "2", crie um cliente e depois estime, faça o pedido e consulte o status. São quatro chamadas com await, um erro tipado em que você realmente consegue fazer match, e retries e rate limiting já resolvidos. Este guia cobre a integração inteira: instalação, valores padrão, os códigos de erro documentados e como o pedido é pago.

Por que a energia importa para serviços em Rust

Rust aparece exatamente nos lugares que movimentam stablecoins em volume: backends de exchanges, processadores de pagamento, serviços de custódia, bots de alto desempenho. Todos esbarram na mesma conta na TRON: cada transferência de USDT (TRC-20) consome energia, e a energia que você não tem é paga queimando TRX pelas tarifas do protocolo. A 100 sun por unidade de energia, isso dá cerca de 6,43 TRX por transferência padrão (em novembro de 2026), pagos de novo a cada envio.

Alugar a energia logo antes de um lote de pagamentos custa menos do que queimá-la (em 28 de outubro de 2026, cerca de um terço a menos num aluguel de uma hora e cerca de 59% a menos por transferência num aluguel de 30 dias), e fazer isso no código significa que o serviço se recarrega sozinho em vez de acionar alguém. Se quiser ver primeiro o nível dos endpoints, leia nosso guia de automação com a API; aqui está o mesmo fluxo com tipos Rust e async.

O mercado de energia em que um serviço em Rust compra energia TRON pelo SDK da TronSave
O SDK cria pedidos no mesmo mercado de energia usado pela interface web. Fonte: TronSave

O que é o SDK da TronSave para Rust?

É o cliente oficial assíncrono em Rust para a API v2 da TronSave, publicado no crates.io como tronsave (versão 2.0.0, licença MIT, edition 2021, MSRV 1.75). A referência da API gerada fica no docs.rs. É um de cinco clientes oficiais (TypeScript, Python, Java, PHP e Rust), que encapsulam os mesmos endpoints e seguem uma suíte de conformidade comum entre linguagens, então o comportamento não diverge entre eles.

O crate é propositalmente enxuto:

  • Async sobre tokio, construído com reqwest e serde. Toda chamada é uma async fn que retorna tronsave::Result<T>.
  • rustls, não OpenSSL. O reqwest entra com default-features = false e a feature rustls-tls, então não há OpenSSL do sistema para linkar, exatamente o que você quer num contêiner musl, Alpine ou distroless.
  • DTOs tipados. UserInfo, EstimateBuyResource, Order, Delegate e OrderBookLevel são structs serde simples, com o mapeamento para camelCase já feito.
  • Árvore de dependências pequena. reqwest, serde, serde_json, thiserror, fastrand e tokio (apenas as features time e sync).

Instalação

[dependencies]
tronsave = "2"
tokio = { version = "1", features = ["full"] }

Depois defina TRONSAVE_API_KEY no seu ambiente. Network::Testnet aponta o cliente para a API de teste Nile, onde nada custa TRX de verdade; Network::Mainnet opera para valer. Os dois resolvem a própria URL base via Network::base_url(), então nenhum hostname fica fixo na sua configuração.

O mesmo enum expõe fund_address(), o endereço de depósito para o fluxo com transação assinada. Ler esse endereço do enum em vez de colar uma string na configuração é o hábito mais seguro: um endereço de depósito copiado de uma mensagem de chat ou de um resultado de busca é um caminho conhecido para perder uma recarga.

Comprando energia do início ao fim

use tronsave::{TronsaveClient, Network, models::BuyParams};

#[tokio::main]
async fn main() -> tronsave::Result<()> {
    let sdk = TronsaveClient::new(
        std::env::var("TRONSAVE_API_KEY").ok(),
        Network::Mainnet,
    )?;

    // 1. Who am I, and can I afford this run?
    let me = sdk.get_user_info().await?;
    println!("balance: {} SUN", me.balance);

    // 2. What will it cost? (no API key needed for this call)
    let est = sdk.estimate_buy_resource(BuyParams {
        receiver: "TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM".into(),
        resource_amount: 65_000,          // ENERGY must be > 64_000
        duration_sec: Some(3600),
        ..Default::default()
    }).await?;
    println!("estimate: {} SUN", est.estimate_trx);

    // 3. Place the order.
    let order = sdk.buy_resource(BuyParams {
        receiver: "TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM".into(),
        resource_amount: 65_000,
        duration_sec: Some(3600),
        ..Default::default()
    }).await?;

    // 4. Poll until the energy is actually delegated.
    let status = sdk.get_order(&order.order_id).await?;
    println!("{}% filled, {} left", status.fulfilled_percent, status.remain_amount);
    for d in &status.delegates {
        println!("  {} sent {} (tx {})", d.delegator, d.amount, d.txid);
    }
    Ok(())
}

Três pontos merecem destaque.

..Default::default() é toda a ergonomia. BuyParams tem nove campos, mas só dois são obrigatórios; o resto são Options omitidos por completo na serialização quando não definidos. Você informa o que quer e os valores padrão completam o restante.

estimate_buy_resource não exige autenticação. Você pode cotar um pedido antes de ter uma chave, e uma chamada de preço num hot path nunca gasta seu orçamento de autenticação.

O pedido não está concluído quando buy_resource retorna. Ele devolve um order_id; a delegação chega alguns segundos depois. Consulte get_order até fulfilled_percent chegar a 100 antes de transmitir a transferência que precisa da energia, e confira de fato, porque um preenchimento parcial pode não ser suficiente.

Valores padrão e limites que vale conhecer

Comportamento Valor
Tipo de recurso padrão ENERGY
Faixa de preço padrão MEDIUM (também FAST, SLOW ou um preço direto em SUN)
Duração padrão 259_200 segundos: 3 dias
Pedido mínimo de energia Precisa ser maior que 64.000
Rate limit no lado do cliente 15 requisições/segundo; 1/segundo para get_extendable_delegates
Timeout / retries padrão 30.000 ms / 3 retries
Formato de extend_to Timestamp Unix em segundos
Tamanho de página padrão 10

O mínimo de 64.000 é verificado antes de a requisição sair do seu processo, então um loop com defeito não consegue gastar o rate limit redescobrindo a mesma recusa. O rate limiter é um token bucket por endpoint que cadencia suas próprias chamadas em vez de esperar a bronca de um 429. E quando cabe um retry, o backoff é exponencial com full jitter: 300 ms, dobrando a cada tentativa, com teto de 10 segundos, e depois aleatorizado em toda essa janela. Esse último detalhe importa mais do que parece: sem jitter, uma frota de workers que recebe um 429 no mesmo instante tenta de novo em sincronia e sobrecarrega o endpoint outra vez.

Os retries disparam em 408, 425, 429, 500, 502, 503 e 504, e respeitam o header Retry-After quando o servidor o envia.

Um tipo de erro, seis categorias

Rust não trabalha com hierarquias de exceções, e o SDK não finge o contrário. Toda chamada retorna tronsave::Result<T>, e o único struct Error traz um kind, um code documentado, o status HTTP, retry_after_ms e o corpo raw para depuração. Você faz match nele:

use tronsave::ErrorKind;

match sdk.buy_resource(params).await {
    Ok(order) => tracing::info!(order_id = %order.order_id, "energy ordered"),

    Err(e) if e.kind == ErrorKind::RateLimit => {
        let wait = e.retry_after_ms.unwrap_or(1_000);
        tokio::time::sleep(std::time::Duration::from_millis(wait)).await;
    }

    Err(e) if e.kind == ErrorKind::Business => match e.code.as_str() {
        "INTERNAL_BALANCE_ACCOUNT_TOO_LOW" => top_up_and_alert().await,
        "PRICE_EXCEED_MAX_PRICE_REQUIRED" => skip_until_price_falls(),
        "CANNOT_FULFILLED" => queue_for_retry(),
        _ => tracing::warn!(code = %e.code, "order rejected"),
    },

    Err(e) => tracing::error!(code = %e.code, kind = ?e.kind, status = ?e.status, "buy failed"),
}

O kind indica a categoria do problema. O code indica o que realmente aconteceu e, ao contrário de uma mensagem em texto livre, é um valor documentado e estável, compartilhado pelos cinco SDKs:

Categoria Códigos O que significa para o seu código
Auth API_KEY_REQUIRED, INVALID_API_KEY Corrija a chave. Nunca tente de novo.
Validation MISSING_PARAMS, INVALID_PARAMS, MIN_PRICE_INVALID Corrija a chamada. Nunca tente de novo.
Business INTERNAL_ACCOUNT_NOT_FOUND, INTERNAL_BALANCE_ACCOUNT_TOO_LOW, CANNOT_FULFILLED, MUST_BE_WAIT_PREVIOUS_ORDER_FILLED, PRICE_EXCEED_MAX_PRICE_REQUIRED, SOME_DELEGATE_CANNOT_EXTEND A requisição era válida, mas foi recusada. Trate conforme o código.
RateLimit RATE_LIMIT Aguarde retry_after_ms.
Network NETWORK_ERROR Falha de transporte. Pode tentar de novo com segurança.
Unknown UNKNOWN Resposta não reconhecida. Registre o raw.

Esses códigos de negócio são os que valem um comportamento real. INTERNAL_BALANCE_ACCOUNT_TOO_LOW significa recarregar. PRICE_EXCEED_MAX_PRICE_REQUIRED significa que o mercado passou do teto que você definiu e você deve esperar em vez de aumentá-lo às cegas. MUST_BE_WAIT_PREVIOUS_ORDER_FILLED significa que você está enfileirando pedidos mais rápido do que eles são liquidados.

Como o pedido é pago

O cliente escolhe a forma de pagamento conforme o que você passa:

  • Saldo pré-pago (recomendado para servidores). Deixe signed_tx como None e o pedido se autentica com sua chave de API e é liquidado contra o seu saldo na TronSave. Sua chave privada da TRON nunca entra no serviço.
  • On-chain por pedido. Informe uma signed_tx que você mesmo montou e assinou, e essa transação paga o pedido.

Existe também um helper get_signed_transaction() que assina no servidor. O próprio comentário de documentação dele recomenda assinar localmente, e vale seguir o conselho: essa chamada envia uma chave privada pela rede. Para um serviço de backend, o caminho pré-pago é mais simples e mais seguro.

Estender em vez de comprar de novo

Quando uma delegação que você já tem está perto de expirar, estendê-la é melhor do que comprar um pedido novo. Chame get_extendable_delegates com um destinatário e um timestamp Unix extend_to; ele retorna is_able_to_extend, total_estimate_trx e um payload extend_data que você repassa direto para extend_request. Atenção ao limite de 1 por segundo nessa primeira chamada: é o único endpoint que o SDK cadencia com mais rigor que os demais. Nosso guia do recurso Extend explica quando estender é a melhor opção.

Perguntas frequentes (FAQ)

Qual versão do Rust eu preciso?

1.75 ou posterior: essa é a MSRV declarada do crate, com edition 2021.

Ele obriga a usar um runtime async específico?

Ele depende do tokio para timers e sincronização, então o tokio é o runtime suportado. Só as features time e sync entram como dependências reais; a feature full no trecho de instalação serve apenas para o seu próprio #[tokio::main].

Ele vai trazer o OpenSSL para o meu build?

Não. O reqwest está configurado com default-features = false e rustls-tls, então o TLS é Rust puro. É isso que o torna tranquilo em musl e em imagens distroless.

Posso testar sem gastar TRX de verdade?

Sim: crie o cliente com Network::Testnet para a rede de teste Nile, num host de API separado. Troque esse único valor do enum para entrar em produção.

Quanta energia devo comprar para uma transferência de USDT?

Cerca de 65.000 se o destinatário já tem USDT, cerca de 130.000 se nunca teve; veja quanta energia uma transferência de USDT precisa. Como o mínimo precisa ser maior que 64.000, 65.000 é o menor pedido de energia viável na prática.

O cliente Rust está atrás dos outros?

Não. Os cinco SDKs miram a v2 na mesma versão e compartilham uma suíte de conformidade. Se você trabalha com várias linguagens, o guia de TypeScript e o guia de PHP descrevem o mesmo fluxo.

Conclusão

Se o seu serviço em Rust movimenta USDT na TRON, a energia é um custo recorrente que você pode reduzir bastante alugando em vez de queimando, e o crate transforma isso numa integração de quatro chamadas, não num projeto. Adicione a dependência, cote o pedido sem chave, compre contra o saldo pré-pago para que nenhuma chave privada toque o serviço, faça match em ErrorKind nos casos que exigem tratamento real e consulte até 100% antes de enviar.

O SDK da TronSave é publicado pela TronSave, editora deste blog. As versões, valores padrão e limites descritos aqui refletem o crate 2.0.0 e podem mudar em versões futuras; confira o crates.io e o docs.rs antes de fixar uma versão. Isto não é aconselhamento financeiro.

TronSave
TronSave

A equipe da TronSave desenvolve o mercado de energia e largura de banda da TRON em tronsave.io e escreve estes guias com base em testes reais na rede principal da TRON.

Artigos relacionados

Usamos o Google Analytics para saber quais guias ajudam os leitores. Ele só grava cookies se você permitir a análise. O blog não exibe anúncios. Privacidade