---
title: Como comprar energia TRON em PHP com o SDK da TronSave (2026)
description: "Compre energia TRON em PHP com o SDK oficial da TronSave: Composer, modelos tipados, retries e rate limit embutidos e compra em 4 chamadas."
url: https://blog.tronsave.io/pt/comprar-energia-tron-com-php/
canonical: https://blog.tronsave.io/pt/comprar-energia-tron-com-php/
lang: pt-BR
datePublished: 2026-11-18T16:37:32+00:00
dateModified: 2026-11-18T16:37:32+00:00
author: TronSave
publisher: TronSave (https://tronsave.io/)
categories:
  - Guias de TRON
keywords: comprar energia TRON em PHP
translations:
  en: https://blog.tronsave.io/how-to-buy-tron-energy-in-php-sdk-guide/
  ru: https://blog.tronsave.io/ru/kak-kupit-energiyu-tron-na-php/
  es: https://blog.tronsave.io/es/comprar-energia-tron-con-php/
  zh: https://blog.tronsave.io/zh/php-goumai-bochang-nengliang/
  de: https://blog.tronsave.io/de/tron-energie-mit-php-kaufen/
---

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

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](https://blog.tronsave.io/pt/comprar-energia-tron-com-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](https://blog.tronsave.io/wp-content/uploads/2025/09/Energy-rental-interface-on-Tronsave-copy.png)

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](https://blog.tronsave.io/pt/extend-estender-e-recarregar-energia-tron/) 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](https://blog.tronsave.io/pt/quanto-trx-preciso-para-enviar-usdt/). 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](https://blog.tronsave.io/pt/comprar-energia-tron-com-codigo-sdk-tronsave/), [Java](https://blog.tronsave.io/pt/comprar-energia-tron-com-java/) e [Rust](https://blog.tronsave.io/pt/comprar-energia-tron-com-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](https://tronsave.io/pt-BR) e cote sua primeira ordem no [mercado de energia ao vivo](https://tronsave.io/pt-BR/market).

*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.*
