وثائق المطورين
PHP INTEGRATION
قم بدمج تفويض Energy TronEnergy باستخدام iexbase/tron-api في PHP. يتضمن ذلك تثبيت Composer، وأمثلة برمجية جاهزة للنسخ واللصق.
عنوان الدفع API برمجة التطبيقات
TFqUiCu1JwLHHnBNeaaVKH7Csm4aA3YhZx
أرسل TRX إلى هذا العنوان. سيتم استخدام رمز تجزئة معاملتك للمطالبة بتفويض الطاقة.
تكامل كامل مع لغة PHP باستخدام iexbase/tron-api مكتبة برمجية. كل خطوة عبارة عن كتلة برمجية مستقلة يمكنك نسخها إلى مشروعك. تعمل مع أي إطار عمل PHP أو PHP العادي.
المتطلبات الأساسية: PHP 7.4+، Composer، ext-gmp و ext-bcmath مفعلة، محفظة Tron ممولة.
حول تسجيل الدخول في لغة PHP: تتطلب API TronEnergy توقيع محفظة باستخدام
tronWeb.trx.signMessageV2(). ال iexbase/tron-api لا توفر المكتبة هذه الآلية الأساسية للتوقيع، لذا يستخدم هذا الدليل أداة مساعدة صغيرة في Node.js لخطوة التوقيع. أما باقي العمليات (إرسال TRX ، واستدعاء API ، وإرسال USDT ) فتبقى مكتوبة بلغة PHP. إذا كان لديك حل توقيع مكتوب بلغة PHP بالكامل يُنتج توقيع signMessageV2 صالحًا، فيمكنك استبدال الأداة المساعدة دون تغيير أي خطوة أخرى.
التدفق
لا حاجة لمفتاح API أو التسجيل. يقوم برنامجك بإرسال TRX على سلسلة الكتل إلى عنوان دفع TronEnergy ، ويوقع رسالة تثبت ملكيته، ثم يطالب بالتفويض. تصل Energy في غضون 3 ثوانٍ تقريبًا. بعد ذلك، يرسل برنامجك USDT باستخدام الطاقة المفوضة.
1
إرسال TRX
أرسل 4 أو أكثر من TRX إلى عنوان الدفع الموجود على سلسلة الكتل (الحد الأدنى 4، والحد الأقصى 1000).
2
لافتة
قم بتوقيع tx_hash:delegate_to لإثبات أنك المرسل.
3
مطالبة
أرسل طلب POST إلى /delegate مع رمز التجزئة والتوقيع الخاصين بالمعاملة. تصل Energy في غضون 3 ثوانٍ تقريبًا.
التسعير خطي: 16250 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.
خطوة بخطوة
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
لا تقم أبدًا بتضمين بيانات الاعتماد بشكل ثابت في التعليمات البرمجية. Use environment variables or a secrets manager. The example above is for illustration only.
3. الحصول على معلومات الدفع (اختياري)
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";
4. إرسال 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";
5. وقّع الرسالة
تتطلب 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";
6. المطالبة بالتفويض
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";
7. أرسل 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";
معالجة الأخطاء
قم بتغليف استدعاء المطالبة بدالة مساعدة صغيرة لإعادة المحاولة. الخطأ الأكثر شيوعًا هو 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";
}