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 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,OrderStatuseNetworksã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
buyResourcesemsignedTxe 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
signedTxque 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.
Comece a integrar: rode composer require tronsave/sdk, pegue uma key no painel da TronSave e cote sua primeira ordem no mercado de energia ao vivo.
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.


