Qual versão do PHP é necessária?

PHP 7.4 ou posterior. O pacote iexbase/tron-api requer as extensões GMP e bcmath.

Por que preciso de um helper Node.js para assinatura?

A biblioteca PHP iexbase/tron-api não expõe tronWeb.trx.signMessageV2(), que é o que a API TronEnergy requer. O helper Node.js é um pequeno wrapper que faz a assinatura e gera a assinatura para o PHP ler.

Integração PHP | TronEnergy Docs

Integração PHP completa usando a iexbase/tron-api biblioteca. Cada passo é um bloco de código independente que você pode copiar para seu projeto. Funciona com qualquer framework PHP ou PHP puro.

Pré-requisitos: PHP 7.4+, Composer, ext-gmp e ext-bcmath habilitados, uma carteira Tron com saldo.

Sobre assinatura em PHP: A API TronEnergy requer uma assinatura de carteira usando tronWeb.trx.signMessageV2(). A iexbase/tron-api biblioteca não expõe esse primitivo de assinatura exato, então este guia usa um pequeno auxiliar Node.js para a etapa de assinatura. Tudo o mais (enviar TRX, chamar a API, enviar USDT) permanece em PHP. Se você tiver uma solução de assinatura pura em PHP que produza uma assinatura signMessageV2 válida, você pode trocar o auxiliar sem alterar nenhuma outra etapa.

O Fluxo

Sem chave de API. Sem cadastro. Seu código envia TRX on-chain para o endereço de pagamento TronEnergy, assina uma mensagem comprovando propriedade, depois reclama a delegação. A energia chega em aproximadamente 3 segundos. Depois seu código envia USDT usando a energia delegada.

Enviar TRX

Envie 4 ou mais TRX para o endereço de pagamento on-chain (mín. 4, máx. 1000).

Assinar

Assine tx_hash:delegate_to para provar que você é o remetente.

Reclamar

POST /delegate com o hash da transação e assinatura. A energia chega em ~3s.

O preço é linear: 16.250 Energy por TRX. Pedido mínimo 4 TRX (65.000 Energy — uma transferência USDT padrão), máximo 1.000 TRX (16,25M Energy). O valor que você envia determina exatamente quanto Energy é delegado de volta — sem tiers, sem pacotes. Para uma única transferência padrão, use $trxAmount = 4. Para uma transferência de carteira nova, use 8. Para trabalho em lote, use mais. O código abaixo usa uma variável $trxAmount para que você possa alterá-la em um único lugar.

Passo a Passo

1. Instale

composer

composer require iexbase/tron-api

2. Configure

setup.php
require_once 'vendor/autoload.php';

use IEXBase\TronAPI\Tron;

$tron = new Tron();
$tron->setPrivateKey('YOUR_PRIVATE_KEY');
$tron->setAddress('YOUR_WALLET_ADDRESS');

$api  = 'https://api.tronnrg.com';
$addr = 'TFqUiCu1JwLHHnBNeaaVKH7Csm4aA3YhZx'; // API payment address
$usdt = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'; // USDT contract

Nunca codifique credenciais. Carregue sua chave privada de variáveis de ambiente ou de um gerenciador de segredos. Nunca faça commit de segredos no git.

4. Envie TRX

enviar TRX
// Send TRX to the API payment address — pricing is linear.
// 16,250 energy per TRX. Min 4 TRX, max 1,000 TRX.
//   $trxAmount = 4    → 65,000 energy   (standard USDT transfer)
//   $trxAmount = 8    → 130,000 energy  (new wallet transfer)
//   $trxAmount = 40   → 650,000 energy  (10 standard transfers)
//   $trxAmount = 1000 → 16,250,000 energy (max)

$trxAmount = 4;

$payment = $tron->sendTrx($addr, $trxAmount);

if (!isset($payment['result']) || !$payment['result']) {
    throw new Exception('TRX transfer failed');
}

$txHash = $payment['txid'];
echo "Payment sent: ${txHash}\n";

5. Assine a Mensagem

A API requer uma assinatura que comprove que a mesma carteira que enviou o TRX está solicitando a delegação. Fazemos isso com um pequeno helper Node.js. Salve como sign.js ao lado do seu arquivo PHP:

sign.js
// Usage: node sign.js <tx_hash> <delegate_to>
// Outputs the signature to stdout. Reads private key from TRON_PRIVATE_KEY env var.
const { TronWeb } = require('tronweb');

const [, , txHash, delegateTo] = process.argv;
const tronWeb = new TronWeb({
  fullHost: 'https://api.trongrid.io',
  privateKey: process.env.TRON_PRIVATE_KEY,
});

tronWeb.trx.signMessageV2(`${txHash}:${delegateTo}`)
  .then(sig => process.stdout.write(sig))
  .catch(e => { console.error(e.message); process.exit(1); });

Instale TronWeb na mesma pasta: npm install tronweb. Depois chame a partir do PHP:

assinar do PHP
// Both the sender (in $tron) and the signer must be the SAME wallet.
// Make sure TRON_PRIVATE_KEY in your environment matches the wallet that sent the TRX.
$delegateTo = 'TWalletThatNeedsEnergy';

$signature = trim(shell_exec(
    sprintf('node sign.js %s %s',
        escapeshellarg($txHash),
        escapeshellarg($delegateTo)
    )
));

if (!$signature) {
    throw new Exception('Signing failed. Check that node and tronweb are installed and TRON_PRIVATE_KEY is set.');
}

echo "Signed: " . substr($signature, 0, 20) . "...\n";

6. Reivindique a Delegação

reivindicar delegação
// $txHash, $delegateTo, and $signature are all defined in the previous steps.
$ch = curl_init("${api}/delegate");
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'tx_hash'     => $txHash,
        'delegate_to' => $delegateTo,
        'signature'   => $signature,
    ]),
]);

$result = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Energy: " . $result['energy'] . "\n";
echo "Ref: " . $result['ref'] . "\n";

7. Envie USDT

enviar USDT
// Energy is now delegated. Send USDT.
$contract = $tron->contract($usdt);
$transfer = $contract->transfer($delegateTo, 10 * pow(10, 6));

echo "USDT sent: " . $transfer . "\n";

Tratamento de Erros

Envolva a chamada de reivindica em um pequeno helper de retry. O erro mais comum é payment_verification_failed quando a tx ainda não foi indexada on-chain — aguarde alguns segundos e tente novamente uma vez.

tratamento de erros
function claimDelegation($api, $txHash, $delegateTo, $signature, $retries = 3) {
    for ($i = 0; $i < $retries; $i++) {
        $ch = curl_init("${api}/delegate");
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
            CURLOPT_POSTFIELDS     => json_encode([
                'tx_hash'     => $txHash,
                'delegate_to' => $delegateTo,
                'signature'   => $signature,
            ]),
        ]);

        $result = json_decode(curl_exec($ch), true);
        curl_close($ch);

        if (!isset($result['error'])) {
            return $result; // Success
        }

        switch ($result['error']) {
            case 'payment_verification_failed':
                // Most common: tx not yet indexed. Wait and retry.
                sleep(3);
                continue 2;

            case 'hash_already_used':
                throw new Exception('This tx hash has already been claimed');

            case 'signature_mismatch':
                throw new Exception('Signer does not match payment sender. Sign with the same wallet that sent TRX.');

            case 'delegation_failed':
                // Refund queued automatically if payment was verified
                throw new Exception('Delegation failed: ' . $result['message']);

            default:
                throw new Exception($result['message'] ?? 'Unknown error');
        }
    }

    throw new Exception('Transaction not found after retries');
}

Exemplo Completo

delegate-energy.php
<?php
require_once 'vendor/autoload.php';

use IEXBase\TronAPI\Tron;

$tron = new Tron();
$tron->setPrivateKey(getenv('TRON_PRIVATE_KEY'));
$tron->setAddress(getenv('TRON_WALLET_ADDRESS'));

$api  = 'https://api.tronnrg.com';
$addr = 'TFqUiCu1JwLHHnBNeaaVKH7Csm4aA3YhZx';

try {
    $delegateTo = 'TRecipientWallet';
    $trxAmount = 4; // min 4, max 1000 — energy = trxAmount × 16,250

    // 1. Send TRX (linear pricing: 16,250 energy per TRX)
    $payment = $tron->sendTrx($addr, $trxAmount);
    $txHash  = $payment['txid'];
    echo "Payment: ${txHash}\n";

    // 2. Sign via Node helper (see Step 5 above)
    $signature = trim(shell_exec(
        sprintf('node sign.js %s %s',
            escapeshellarg($txHash),
            escapeshellarg($delegateTo)
        )
    ));
    if (!$signature) throw new Exception('Signing failed');

    // 3. Claim delegation (with retry)
    $result = claimDelegation($api, $txHash, $delegateTo, $signature);
    echo "Energy: " . $result['energy'] . "\n";
    echo "Ref: "    . $result['ref'] . "\n";

    // 4. Send USDT (energy is now available)
    $contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t');
    $transfer = $contract->transfer($delegateTo, 10 * pow(10, 6));
    echo "USDT sent: ${transfer}\n";

} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}