Guias de TRON

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

Por TronSave Publicado 9 min de leitura
Nesta página

O jeito mais rápido de comprar energia TRON em PHP é o SDK oficial da TronSave: composer require tronsave/sdk, crie um cliente com sua API key, estime o custo, faça a ordem e consulte até chegar a 100%. Quatro chamadas tipadas, sem HTTP na mão e sem loop de retry improvisado. Este guia cobre a integração inteira: instalação, padrões, tratamento de erros e como a ordem é paga de fato.

Por que um backend PHP precisa disso

O PHP roda uma fatia enorme da web de comércio: lojas WooCommerce, serviços de pagamento em Laravel, painéis de cobrança sob medida. Assim que um deles começa a pagar ou receber USDT (TRC-20) na TRON, cai na mesma conta que todo mundo: cada transferência consome energia, e a energia que você não tem é paga queimando TRX pela tarifa do protocolo. É assim que um único pagamento em stablecoin acaba queimando cerca de 6,43 TRX, ou cerca de 13,03 TRX para quem nunca recebeu USDT (em novembro de 2026).

Alugar a energia logo antes de uma rodada de pagamentos costuma custar uma fração de queimá-la. Fazer isso pelo código significa que o serviço se recarrega sozinho: ninguém de olho num painel às 3 da manhã, nenhum lote travado porque uma carteira ficou sem saldo. Se quiser primeiro a visão no nível dos endpoints, leia nosso guia de automação com a API; este post é o mesmo fluxo com tipos PHP em vez de requisições cruas.

O mercado de energia em que um backend PHP compra energia TRON pelo SDK da TronSave
O SDK coloca as ordens no mesmo mercado de energia usado pela interface web. Fonte: TronSave

O que é o SDK PHP da TronSave?

É o cliente PHP oficial da API v2 da TronSave, publicado no Packagist como tronsave/sdk (versão 2.0.0, licença MIT, PHP 8.1+). Ele existe ao lado dos SDKs oficiais para TypeScript, Python, Java e Rust — todos encapsulam os mesmos endpoints com o mesmo comportamento, verificado por uma suíte de conformidade compartilhada entre linguagens, e não à mão.

O cliente PHP é pequeno, mas feito para produção:

  • Resultados tipados. As respostas voltam como classes readonly — UserInfo, EstimateBuyResource, Order, OrderBookLevel — e não como arrays associativos que você precisa adivinhar.
  • Enums de verdade. ResourceType, PriceTier, OrderType, OrderStatus e Network são backed enums do PHP 8.1, então um erro de digitação vira fatal error no ponto da chamada, e não um 400 do servidor.
  • Transporte PSR-18. Guzzle por padrão, mas você pode injetar qualquer cliente PSR-18 — útil se o seu framework já tem uma pilha HTTP configurada e instrumentada.
  • Retries e rate limiting embutidos. Ambos vêm ligados por padrão e são descritos abaixo.

Instalação e configuração

composer require tronsave/sdk

Depois crie um cliente. Todo argumento do construtor é opcional e nomeado, então você só define o que precisa:

use Tronsave\TronsaveClient;
use Tronsave\Network;

$sdk = new TronsaveClient(
    apiKey: getenv('TRONSAVE_API_KEY'),
    network: Network::Testnet,   // Network::Mainnet to go live
    timeoutMs: 30000,            // default
    maxRetries: 3,               // default
);

Network carrega a própria URL base, então você nunca fixa um hostname no código: Network::Testnet aponta para a API de teste Nile e Network::Mainnet para produção. Desenvolva na testnet, onde nada custa TRX de verdade, e depois troque o enum.

O mesmo enum também expõe fundAddress(), o endereço onde seu saldo pré-pago é recarregado. Ler esse valor 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 jeito clássico de perder uma recarga.

Comprando energia do início ao fim

Quatro chamadas. A primeira é opcional, mas vale colocar num health check.

use Tronsave\TronsaveClient;
use Tronsave\Network;

$sdk = new TronsaveClient(apiKey: getenv('TRONSAVE_API_KEY'), network: Network::Mainnet);

// 1. Who am I, and can I afford this run?
$me = $sdk->getUserInfo();
// $me->id, $me->balance, $me->representAddress, $me->depositAddress

// 2. What will it cost? (no API key required for this call)
$est = $sdk->estimateBuyResource([
    'receiver'       => 'TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM',
    'resourceType'   => 'ENERGY',
    'resourceAmount' => 65000,
    'durationSec'    => 3600,
]);
// $est->estimateTrx, $est->unitPrice, $est->durationSec, $est->availableResource

// 3. Place the order.
$order = $sdk->buyResource(
    ['receiver' => 'TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM', 'resourceAmount' => 65000, 'durationSec' => 3600],
    ['allowPartialFill' => true, 'maxPriceAccepted' => 100],
);

// 4. Poll until the energy is actually delegated.
$status = $sdk->getOrder($order->orderId);
echo $status->fulfilledPercent;   // 100 = fully delegated
echo $status->remainAmount;       // 0 when nothing is left to fill
foreach ($status->delegates as $d) {
    // $d->delegator, $d->amount, $d->txid
}

Dois detalhes desse trecho fazem diferença. estimateBuyResource não exige autenticação: você consegue cotar uma compra antes de ter uma key, e uma chamada de preço num caminho crítico nunca gasta sua cota de rate limit com autenticação. E o segundo argumento de buyResource é o array de opções: allowPartialFill deixa a ordem ser preenchida por vários provedores em vez de esperar por um grande, e maxPriceAccepted é o seu teto em SUN por unidade — a linha entre uma integração resiliente e uma que paga demais num pico de preço.

A ordem não está concluída quando buyResource retorna — o retorno é um orderId. A delegação chega alguns segundos depois. Consulte getOrder até fulfilledPercent chegar a 100 antes de transmitir a transferência que precisa da energia.

Padrões 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 em SUN)
Duração padrão 259200 segundos — 3 dias
Ordem mínima de energia Precisa ser maior que 64.000
Rate limit no cliente 15 requisições/segundo; 1/segundo para getExtendableDelegates
Timeout / retries padrão 30.000 ms / 3 retries
Formato de extendTo Timestamp Unix em segundos

O mínimo de 64.000 é aplicado no cliente: uma ordem pequena demais lança exceção antes de qualquer requisição HTTP, então um loop com bug não gasta seu rate limit descobrindo a mesma rejeição de novo e de novo. O rate limiter também roda no cliente — ele cadencia suas próprias chamadas em vez de deixar o servidor responder 429.

Tratamento de erros que aguenta produção

Toda falha é uma exceção tipada que estende Tronsave\TronsaveException e traz ->code, ->status e ->raw:

Exceção Quando O que fazer
TronsaveAuthException 401 Corrija a key. Nunca tente de novo.
TronsaveValidationException 400, parâmetros inválidos Corrija a chamada. Nunca tente de novo.
TronsaveBusinessException 400, recusada pelo mérito Leia ->code e trate cada caso.
TronsaveRateLimitException 429 Aguarde ->retryAfterMs.
TronsaveNetworkException Falha de transporte Pode tentar de novo com segurança.
use Tronsave\{TronsaveBusinessException, TronsaveRateLimitException};

try {
    $order = $sdk->buyResource(['receiver' => $addr, 'resourceAmount' => 65000]);
} catch (TronsaveRateLimitException $e) {
    usleep($e->retryAfterMs * 1000);
} catch (TronsaveBusinessException $e) {
    $log->warning('order rejected', ['code' => $e->code, 'raw' => $e->raw]);
}

A separação importa porque diz o que pode ser repetido sem adivinhação. O SDK já repete os casos transitórios para você — 408, 425, 429, 500, 502, 503 e 504 — com backoff exponencial e jitter, respeitando o cabeçalho Retry-After quando o servidor o envia. O que chega ao seu bloco catch já foi repetido, então as exceções acima são as que o seu código realmente precisa decidir.

Como a ordem é paga

Há dois caminhos de pagamento, e o SDK escolhe conforme o que você passa:

  • Saldo pré-pago (recomendado para servidores). Chame buyResource sem signedTx e a ordem se autentica com sua API key e é liquidada no seu saldo da TronSave. Sua chave privada da TRON nunca encosta na integração — exatamente o que você quer num servidor web.
  • On-chain por ordem. Passe um signedTx que você mesmo montou e assinou, e a ordem é paga por essa transação.

O cliente também expõe getSignedTransaction(), que assina no servidor. O próprio docblock recomenda assinar localmente, e vale seguir: essa chamada envia uma chave privada pela rede. Para um backend PHP, o saldo pré-pago é mais simples e mais seguro — use-o.

Estender em vez de comprar de novo

Se uma delegação que você já tem está perto de expirar, estendê-la sai mais barato do que comprar uma ordem nova. Chame getExtendableDelegates() com um destinatário e um timestamp Unix extendTo; ela retorna isAbleToExtend, totalEstimateTrx e um payload extendData que você passa direto para extendRequest(). Atenção ao limite mais apertado de 1 por segundo nessa primeira chamada — é o único endpoint que o SDK cadencia mais que os outros.

Nosso guia do recurso Extend explica quando estender compensa mais do que comprar de novo.

Perguntas frequentes (FAQ)

Qual versão do PHP eu preciso?

PHP 8.1 ou mais recente. O SDK usa backed enums, propriedades readonly e argumentos nomeados, recursos que chegaram no PHP 8.0 e 8.1.

Preciso do Guzzle?

Ele é o padrão, então funciona sem configuração. Mas o transporte é PSR-18, então você pode injetar qualquer cliente compatível — útil se sua aplicação já tem um configurado com logging, proxy ou política de timeout próprios.

Dá para testar sem gastar TRX de verdade?

Sim. Crie o cliente com Network::Testnet e você estará na rede de teste Nile, com um host de API separado. Lá nada custa dinheiro de verdade. Troque esse único valor do enum para ir para produção.

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

Cerca de 65.000 para um destinatário que já tem USDT e cerca de 130.000 para quem nunca teve — veja quanta energia uma transferência de USDT precisa. Lembre que o mínimo da ordem é maior que 64.000, então 65.000 é a menor ordem de energia na prática.

O SDK PHP está atrás do de TypeScript?

Não. Os cinco clientes miram a mesma API v2 na mesma versão e precisam passar por uma suíte de conformidade compartilhada, então o comportamento não diverge entre linguagens. Se você trabalha com várias linguagens, os guias do SDK para TypeScript, Java e Rust descrevem o mesmo fluxo.

O que acontece se uma ordem for preenchida só em parte?

Com allowPartialFill ativado, você recebe o que o mercado conseguiu fornecer, e fulfilledPercent informa quanto. Confira antes de transmitir a transação que depende da energia — uma ordem parcialmente preenchida pode não cobrir sua transferência.

Resumo

Se o seu serviço PHP movimenta USDT na TRON, a energia é um custo recorrente que você pode cortar em até 80%, e o SDK transforma isso numa integração de quatro chamadas em vez de um projeto. Instale, cote a ordem sem key, compre com seu saldo pré-pago para que nenhuma chave privada encoste no seu servidor web, e consulte até 100% antes de enviar.

O SDK da TronSave é publicado pela TronSave, editora deste blog. As versões do pacote, os padrões e os limites descritos aqui refletem a v2.0.0 e podem mudar em versões futuras — confira a documentação oficial do SDK 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