What PHP version is required?

PHP 7.4 or later. The iexbase/tron-api package requires the GMP and bcmath extensions.

Why do I need a Node.js helper for signing?

The iexbase/tron-api PHP library does not expose tronWeb.trx.signMessageV2(), which is what the TronEnergy API requires. The Node.js helper is a small wrapper that does the signing and outputs the signature for PHP to read.

ادغام PHP | TronEnergy Docs

ادغام کامل PHP با استفاده از iexbase/tron-api کتابخانه. هر مرحله یک بلوک کد مستقل است که می‌توانید آن را در پروژه خود کپی کنید. با هر چارچوب PHP یا PHP ساده کار می‌کند.

پیش‌نیازها: پی‌اچ‌پی ۷.۴+، کامپوزر، ext-gmp و ext-bcmath فعال، یک کیف پول Tron با پشتیبانی مالی.

درباره ورود به سیستم PHP: API TronEnergy به امضای کیف پول با استفاده از ... نیاز دارد. tronWeb.trx.signMessageV2(). (این) iexbase/tron-api کتابخانه دقیقاً این تابع اولیه امضا را نمایش نمی‌دهد، بنابراین این راهنما از یک تابع کمکی کوچک Node.js برای مرحله امضا استفاده می‌کند. هر چیز دیگری (ارسال TRX ، فراخوانی API ، ارسال USDT ) در PHP باقی می‌ماند. اگر یک راه‌حل امضای pure-PHP دارید که امضای معتبر signMessageV2 تولید می‌کند، می‌توانید بدون تغییر هیچ مرحله دیگری، تابع کمکی را تغییر دهید.

جریان

بدون کلید API . بدون ثبت نام. کد شما TRX را به صورت درون زنجیره‌ای به آدرس پرداخت TronEnergy ارسال می‌کند، پیامی را برای اثبات مالکیت امضا می‌کند، سپس وکالت را مطالبه می‌کند. Energy تقریباً در عرض ۳ ثانیه می‌رسد. سپس کد شما USDT را با استفاده از انرژی وکالت داده شده ارسال می‌کند.

ارسال TRX

۴ یا بیشتر TRX به آدرس پرداخت درون زنجیره‌ای ارسال کنید (حداقل ۴، حداکثر ۱۰۰۰).

علامت

برای اثبات اینکه شما فرستنده هستید، tx_hash:delegate_to را امضا کنید.

ادعا

دستور POST/delegate به همراه هش تراکنش و امضا اجرا می‌شود. Energy در حدود ۳ ثانیه می‌رسد.

قیمت‌گذاری خطی است: ۱۶۲۵۰ Energy به ازای هر TRX . Minimum order 4 TRX (65,000 Energy — one standard USDT transfer), maximum 1,000 TRX (16.25M Energy). The amount you send determines exactly how much Energy is delegated back — no tiers, no packages. For a single standard transfer, use $trxAmount = 4. For a new-wallet transfer, use 8. For batch work, use more. The code below uses a $trxAmount variable so you can change it in one place.

گام به گام

۱. نصب

composer

composer require iexbase/tron-api

۲. راه‌اندازی

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

هرگز اعتبارنامه‌ها را به صورت کد ثابت وارد نکنید. Use environment variables or a secrets manager. The example above is for illustration only.

۳. دریافت اطلاعات پرداخت (اختیاری)

get payment info
// Get pricing and payment address (optional, energy is always available)
$supply = json_decode(
    file_get_contents("${api}/supply"),
    true
);

echo "Pay to: " . $supply['pay_to'] . "\n";
echo "Energy per TRX: " . $supply['energy_per_trx'] . "\n";

۴. ارسال TRX

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

۵. پیام را امضا کنید

این API به امضایی نیاز دارد که ثابت کند همان کیف پولی که TRX را ارسال کرده، درخواست نمایندگی را نیز دارد. ما این کار را با یک کمکی کوچک Node.js انجام می‌دهیم. آن را به عنوان ذخیره کنید sign.js در کنار فایل PHP شما:

sign.js (run with node)
// 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); });

TronWeb در همان پوشه نصب کنید: npm install tronwebسپس آن را از PHP فراخوانی کنید:

sign from 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";

۶. درخواست نمایندگی

claim delegation
// $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,
    ]),
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if (isset($result['error'])) {
    throw new Exception("Delegation failed: " . $result['message']);
}

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

۷. ارسال USDT

send USDT
// Send USDT using the delegated energy
$usdtContract = $tron->contract($usdt);

// Amount in smallest unit (6 decimals for USDT)
// 10 USDT = 10 * 1,000,000 = 10000000
$amount    = 10 * pow(10, 6);
$recipient = 'TRecipientAddress';

$transfer = $usdtContract->transfer($recipient, $amount);

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

مدیریت خطا

فراخوانی Claim را در یک تابع کمکی retry کوچک قرار دهید. رایج‌ترین خطا این است: payment_verification_failed وقتی تراکنش هنوز روی زنجیره ایندکس نشده است - چند ثانیه صبر کنید و دوباره امتحان کنید.

error handling
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');
}

مثال کامل

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