واجهة برمجة تطبيقات TRON Energy Rental - أتمتة عمليات نقل USDT TRC-20

واجهة برمجة تطبيقات TRON Energy Rental: نظرة عامة وحالات الاستخدام

تعد Quick Rent API وسيلة لتأجير TRON Energy تلقائيًا، دون الحاجة إلى عمل يدوي. تجعل الطاقة تحويلات USDT (TRC-20) ومكالمات العقود الذكية الأخرى أرخص من حرق TRX.

بكلمات واضحة: يشتري برنامجك (موقع أو روبوت أو خدمة) الطاقة بنفسه، بالضبط عند الحاجة إليها - على سبيل المثال، قبل كل عملية تحويل USDT يقوم بها عميلك.

فكر في آلة البيع: يمكنك التحقق من السعر، وإدخال الأموال، والحصول على العنصر الخاص بك. واجهة برمجة التطبيقات (API) هي نفس مجموعة الأزرار — برنامجك فقط هو الذي يضغط عليها.

البداية السريعة: من الصفر إلى الطاقة

مثال كامل وشامل على أبسط السيناريوهات (على السلسلة). أربع خطوات والطاقة في المحفظة.

فيما يلي ما يحدث في كل خطوة وما ترجعه واجهة برمجة التطبيقات. قم بتوصيل مفتاح API والعناوين ومعرف الطلب.

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

# poll every 3s until the order is done
while true; do
  STATUS=$(curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
    -H "Authorization: Bearer $API_KEY" | jq -r .status)
  echo "status: $STATUS"
  case "$STATUS" in
    delegated|failed|expired|cancelled) break ;;
  esac
  sleep 3
done

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

مسرد

شرح مختصر للكلمات المستخدمة في هذه الوثائق.

قبل أن تبدأ

ما يجب تحضيره قبل تقديم طلبك الأول.

عنوان URL الأساسي لواجهة برمجة تطبيقات الإنتاج

تتيح واجهة برمجة التطبيقات Quick Rent لخدمتك استئجار TRON Energy تلقائيًا، لذا فإن عمليات نقل USDT TRC-20 ومكالمات العقود الذكية الأخرى تكلف أقل من حرق TRX.

تشترك جميع نقاط النهاية في عنوان URL أساسي واحد.

https://tronbid.com/api/v2/quick-rent

إذن

يجب أن يتضمن كل طلب مفتاح API الخاص بك كرمز مميز لحامل في رأس التفويض.

احتفظ بالمفتاح من جانب الخادم فقط (الواجهة الخلفية، أسرار CI). لا تقم أبدًا بشحنها في كود الواجهة الأمامية أو المستودعات العامة. المفتاح مرتبط بحساب TronBid واحد (تم تعيين المحفظة عند منح الوصول)؛ لا يمكن سحب مدفوعات الرصيد إلا من هذا الحساب.

إذا تجاوزت الحد الأقصى للمعدل، فستستجيب واجهة برمجة التطبيقات (API) بـ HTTP 429.

Authorization: Bearer <API_KEY>

طرق الدفع

هناك طريقتان للدفع مقابل الطلب. On-chain هو الإعداد الافتراضي ولا يحتاج إلى أي إعداد. يعد دفع الرصيد اختياريًا ويجب تمكينه لمفتاحك.

بدون تفعيل، طلب مع Payment_mode: إرجاع الرصيد 403 BALANCE_PAYMENT_NOT_ENABLED. لتمكينه، اتصل بدعم TronBid.

كتالوج الحزمة

يجب أن يتطابق مقدار الطاقة ومدة_الدقائق مع باقة Quick Rent النشطة — عادةً ما تكون 65000 أو 131000 طاقة و15 أو 60 دقيقة.

جلب الكتالوج الحالي في أي وقت (لا يلزم المصادقة):

curl -sS https://tronbid.com/api/public/quick-rent/skus

التدفق على السلسلة

الخطوة 1 - نشر / عرض الأسعار لمعرفة السعر. الخطوة 2 - نشر /الطلبات لإنشاء الطلب واستلام pay_address وmount_trx وexpires_at. الخطوة 3 - أرسل بالضبط المبلغ_trx TRX إلى pay_address من payer_address الخاص بك. الخطوة 4 - استقصاء GET /orders/:id حتى يتم تفويض الحالة (أو الفشل / انتهاء الصلاحية / الإلغاء).

يعد target_address اختياريًا — إذا تم حذفه، فسيتم تفويض الطاقة إلى payer_address.

يُسمح فقط بأمر واحد مفتوح على السلسلة (في انتظار الدفع) لكل عنوان payer_address في المرة الواحدة؛ وإلا فإنك تحصل على 409 PENDING_PAYMENT_INTENT_EXISTS. في حالة الدفع الزائد/الناقص، قد تختلف الطاقة النهائية - تحقق من كمية الطاقة الفعالة في GET /orders/:id.

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-001",
  "payer_address": "TPayerWalletXXXXXXXXXXXXXXXXXXXXXX",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

تدفق الرصيد

الخطوة 1 - احصل على /الرصيد للتحقق من TRX الخاص بك. الخطوة 2 - نشر / عرض الأسعار. الخطوة 3 - نشر /الطلبات باستخدام وضع الدفع: الرصيد للخصم وبدء التفويض. الخطوة 4 - استقصاء GET /orders/:id حتى يتم تفويضه (عند حدوث خطأ في التفويض، يصبح الأمر فاشلاً ويتم رد TRX إلى رصيدك).

ليست هناك حاجة إلى payer_address — فالحساب المرتبط بمفتاح API الخاص بك هو الذي يدفع. يمكن أن تكون كمية الطاقة في الاستجابة أعلى من SKU المطلوبة (مكافأة مصفوفة السعر).

{
  "energy_amount": 131000,
  "duration_minutes": 15,
  "idempotency_key": "your-unique-key-balance-001",
  "payment_mode": "balance",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX"
}

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

حالات الطلب

يتحرك كل أمر من خلال هذه الحالات. استطلاع الحصول على /orders/:id لمتابعته.

العجز

Idempotency_key (8–128 حرفًا) هو معرف طلب فريد من جانبك. تكرار POST /orders بنفس المفتاح (لنفس عميل API) يؤدي إلى إرجاع نفس الترتيب مع "duplicate": صحيح.

لا تقم بإعادة استخدام مفتاح idempotency_key واحد عبر أوضاع الدفع المختلفة (onchain مقابل الرصيد) - الذي يُرجع 409 IDEMPOTENCY_PAYMENT_MODE_MISMATCH.

حساب متطلبات تأجير الطاقة TRON

قم بتقدير مقدار الطاقة التي يحتاجها العنوان لعملية النقل. قم بتمرير محفظة المستلم وما إذا كانت تحتوي بالفعل على USDT.

{
  "wallet_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "has_usdt": true
}

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/calculator" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address":"TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX","has_usdt":true}'

احصل على عرض أسعار لتأجير TRON Energy

إرجاع السعر الحالي لحزمة: السعر_trx، والتوفر، و save_percent ومدة صلاحية عرض الأسعار (expires_in_sec).

{
  "price_trx": "3.200000",
  "available": true,
  "save_percent": 62,
  "expires_in_sec": 30
}

export BASE_URL="https://tronbid.com"
export API_KEY="your_api_key"

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/quote" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"energy_amount":131000,"duration_minutes":15}'

قم بإنشاء أمر تأجير TRON Energy

إنشاء أمر الإيجار. بالنسبة إلى السلسلة، قم بتمرير payer_address وادفع المبلغ المرتجع إلى pay_address. بالنسبة للرصيد، أضف Payment_mode: الرصيد وسيتم تحصيل الرسوم من الحساب المرتبط على الفور.

يعد target_address اختياريًا (الإعداد الافتراضي هو payer_address). انتبه إلى القواعد 409: أمر واحد مفتوح على السلسلة لكل دافع، ولا يوجد تفويض Quick Rent نشط بالفعل على الهدف (ACTIVE_DELEGATION_EXISTS).

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "pay_address": "TDeposit...",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": "2026-04-29T13:15:00.000Z",
  "qr_payload": "tron:TDeposit...?amount=3.200000",
  "duplicate": false,
  "target_address": "TTarget..."
}

{
  "id": "uuid",
  "status": "delegating",
  "payment_mode": "balance",
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 132310,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-onchain-001",
    "payer_address": "TPayer...",
    "target_address": "TTarget..."
  }'

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "energy_amount": 131000,
    "duration_minutes": 15,
    "idempotency_key": "partner-balance-001",
    "payment_mode": "balance",
    "target_address": "TTarget..."
  }'

الحصول على حالة الطلب

إرجاع الحالة الحالية، وطريقة الدفع، والمبالغ، والعناوين، ورمز_الخطأ / رسالة الخطأ في حالة فشل شيء ما. يعكس مقدار الطاقة الفعالة الطاقة الفعلية المفوضة بعد الدفع الزائد/الناقص.

{
  "id": "uuid",
  "status": "delegated",
  "payment_mode": "onchain",
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "effective_energy_amount": 131000,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

curl -sS "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID" \
  -H "Authorization: Bearer $API_KEY"

إلغاء الطلب

يلغي طلبًا لا يزال في انتظار الدفع (على السلسلة فقط). بمجرد تفويض الطاقة، لم يعد من الممكن إلغاء الطلب.

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $API_KEY"

تغيير الدافع

تغيير محفظة الدفع لأمر معلق على السلسلة - مفيد إذا قرر العميل الدفع من محفظة مختلفة قبل إرسال TRX.

curl -sS -X POST "$BASE_URL/api/v2/quick-rent/orders/$ORDER_ID/set-payer" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payer_address":"TNewPayer..."}'

تحقق من رصيد TronBid API

إرجاع رصيد TRX لحساب TronBid المرتبط بمفتاح API الخاص بك (رصيدك داخل التطبيق، وليس المحفظة الموجودة على السلسلة). يتطلب رأس التفويض.

{ "balance_trx": "150.500000" }

curl -sS "$BASE_URL/api/v2/quick-rent/balance" \
  -H "Authorization: Bearer $API_KEY"

رموز الخطأ

تُرجع الأخطاء حالة HTTP وحقل خطأ. وهنا تلك التي قد تواجهها.

إذا حدث خطأ ما

المواقف الشائعة وماذا تفعل، بكلمات واضحة.

دعم تكامل TRON Energy API

هل تحتاج إلى الوصول إلى واجهة برمجة التطبيقات (API)، أو حدود أعلى، أو تمكين دفع الرصيد؟ تواصل معنا وسنساعدك.