ما إصدار PHP المطلوب؟

PHP 7.4 أو إصدار أحدث. تتطلب حزمة iexbase/tron-api ملحقات GMP و bcmath.

لماذا أحتاج إلى مساعد Node.js للتوقيع؟

لا تُعرّض مكتبة iexbase/tron-api في PHP الدالة tronWeb.trx.signMessageV2()، وهي ما تتطلبه API الخاصة بـ TronEnergy. مساعد Node.js هو غلاف صغير يقوم بالتوقيع وينتج التوقيع لقراءة PHP.

دمج PHP | TronEnergy Docs

دمج PHP كامل باستخدام مكتبة iexbase/tron-api. كل خطوة عبارة عن كتلة كود مستقلة يمكنك نسخها إلى مشروعك. يعمل مع أي إطار عمل PHP أو PHP عادي.

المتطلبات الأساسية: PHP 7.4+، Composer، تفعيل ext-gmp و ext-bcmath، محفظة Tron ممولة.

حول التوقيع في PHP: تطلب TronEnergy API توقيع محفظة باستخدام tronWeb.trx.signMessageV2(). مكتبة iexbase/tron-api لا تعرّض هذا البدائي التوقيع بالضبط، لذا يستخدم هذا الدليل مساعد Node.js صغير لخطوة التوقيع. كل شيء آخر (إرسال TRX، استدعاء API، إرسال USDT) يبقى في PHP. إذا كان لديك حل توقيع PHP نقي ينتج توقيع signMessageV2 صحيح، يمكنك استبدال المساعد دون تغيير أي خطوة أخرى.

سير العمل

بلا مفتاح API. بلا تسجيل. يرسل الكود الخاص بك TRX على السلسلة إلى عنوان الدفع TronEnergy، ويوقّع رسالة تثبت الملكية، ثم يطالب بالتفويض. تصل الطاقة في حوالي 3 ثوانٍ. ثم يرسل الكود الخاص بك USDT باستخدام الطاقة المفوضة.

إرسال TRX

أرسل 4 TRX أو أكثر إلى عنوان الدفع على السلسلة (الحد الأدنى 4، الحد الأقصى 1000).

توقيع

وقّع tx_hash:delegate_to لإثبات أنك المرسل.

المطالبة

POST /delegate مع hash المعاملة والتوقيع. تصل الطاقة في ~3 ثوان.

التسعير خطي: 16,250 طاقة لكل TRX. الحد الأدنى للطلب 4 TRX (65,000 طاقة — تحويل USDT واحد قياسي)، والحد الأقصى 1,000 TRX (16.25M طاقة). المبلغ الذي تُرسله يحدد بالضبط مقدار الطاقة المفوَّضة — لا توجد مستويات ولا حزم. لتحويل قياسي واحد، استخدم $trxAmount = 4. لتحويل محفظة جديدة، استخدم 8. للعمل الجماعي، استخدم أكثر. الكود أدناه يستخدم متغير $trxAmount حتى تتمكن من تغييره في مكان واحد.

خطوة بخطوة

1. التثبيت

composer

composer require iexbase/tron-api

2. الإعداد

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

لا تُدرج بيانات الاعتماد مباشرة في الكود. احمِل مفتاحك الخاص من متغيرات البيئة أو مدير الأسرار. لا تُلزم الأسرار في git.

4. أرسل TRX

إرسال 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. وقّع الرسالة

تتطلب API توقيعًا يثبت أن المحفظة التي أرسلت TRX هي نفسها التي تطلب التفويض. نفعل هذا بمساعد Node.js صغير. احفظه باسم sign.js بجانب ملف 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); });

ثبّت TronWeb في نفس المجلد: npm install tronweb. ثم استدعه من PHP:

التوقيع من 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. المطالبة بالتفويض

استرجاع التفويض
// $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. أرسل USDT

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

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

معالجة الأخطاء

ضع استدعاء المطالبة داخل مساعد إعادة محاولة صغير. الخطأ الأكثر شيوعًا هو payment_verification_failed عندما لا تكون المعاملة مفهرسة على السلسلة بعد — انتظر بضع ثوان وأعد المحاولة مرة واحدة.

معالجة الأخطاء
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";
}