Quelle version de PHP est requise ?

PHP 7.4 ou ultérieur. Le package iexbase/tron-api nécessite les extensions GMP et bcmath.

Pourquoi ai-je besoin d'un assistant Node.js pour signer ?

La bibliothèque PHP iexbase/tron-api n'expose pas tronWeb.trx.signMessageV2(), ce qu'exige l'API TronEnergy. L'assistant Node.js est un petit wrapper qui effectue la signature et sort la signature pour que PHP la lise.

Intégration PHP | TronEnergy Docs

Intégration PHP complète avec la iexbase/tron-api librairie. Chaque étape est un bloc de code autonome que vous pouvez copier dans votre projet. Fonctionne avec n'importe quel framework PHP ou PHP pur.

Prérequis : PHP 7.4+, Composer, ext-gmp et ext-bcmath activées, un portefeuille Tron financé.

À propos de la signature en PHP : L'API TronEnergy nécessite une signature de portefeuille utilisant tronWeb.trx.signMessageV2(). La iexbase/tron-api librairie n'expose pas cette primitive de signature exacte, donc ce guide utilise un petit assistant Node.js pour l'étape de signature. Tout le reste (envoyer des TRX, appeler l'API, envoyer USDT) reste en PHP. Si vous avez une solution de signature en pur PHP qui produit une signature signMessageV2 valide, vous pouvez remplacer l'assistant sans modifier aucune autre étape.

Le processus

Pas de clé API. Pas d'inscription. Votre code envoie des TRX on-chain à l'adresse de paiement TronEnergy, signe un message prouvant la propriété, puis réclame la délégation. L'énergie arrive en environ 3 secondes. Ensuite, votre code envoie USDT en utilisant l'énergie déléguée.

Envoyer des TRX

Envoyez 4 TRX ou plus à l'adresse de paiement on-chain (min 4, max 1000).

Signer

Signez tx_hash:delegate_to pour prouver que vous êtes l'expéditeur.

Réclamer

POST /delegate avec le hash tx et la signature. L'énergie arrive en ~3s.

La tarification est linéaire : 16 250 Energy par TRX. Commande minimale 4 TRX (65 000 Energy — un transfert USDT standard), maximale 1 000 TRX (16,25M Energy). Le montant que vous envoyez détermine exactement la quantité d'Energy déléguée — pas de paliers, pas de forfaits. Pour un simple transfert standard, utilisez $trxAmount = 4. Pour un transfert de nouveau portefeuille, utilisez 8. Pour des travaux en batch, utilisez plus. Le code ci-dessous utilise une $trxAmount variable afin que vous puissiez la modifier en un seul endroit.

Étape par étape

1. Installer

composer

composer require iexbase/tron-api

2. Configuration

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

Ne codez jamais vos identifiants en dur. Chargez votre clé privée à partir de variables d'environnement ou d'un gestionnaire de secrets. Ne commitez jamais vos secrets sur git.

4. Envoyer des TRX

envoyer 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. Signer le message

L'API nécessite une signature qui prouve que le même portefeuille ayant envoyé les TRX demande la délégation. Nous le faisons avec un petit assistant Node.js. Enregistrez-le en tant que sign.js à côté de votre fichier 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); });

Installez TronWeb dans le même dossier : npm install tronweb. Appelez-le depuis PHP :

signer depuis 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. Réclamer la délégation

réclamer la délégation
// $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. Envoyer l'USDT

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

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

Gestion des erreurs

Enrobez l'appel de réclamation dans un petit assistant de retry. L'erreur la plus courante est payment_verification_failed quand la tx n'est pas encore indexée on-chain — attendez quelques secondes et réessayez une fois.

gestion des erreurs
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');
}

Exemple complet

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";
}