API تأجير طاقة TRON
استأجر طاقة TRON برمجيًا بدل حرق TRX لدفع الرسوم، مع إمكانية توفير 70–80% لكل تحويل TRC-20 بحسب حالة الشبكة وسعر الاستئجار.
- الطلبات: حدد عنوان المستلم ومقدار الطاقة ومدة الاستئجار؛ يصل التفويض خلال ثوانٍ
- الاستعلامات: تحقق من حالة التفويض والانتهاء بمعرّف الطلب أو العنوان
- الأسعار: سعر الوحدة الحالي ومستويات التسعير لتخطيط التكلفة
- Webhook: أحداث نجاح التفويض والانتهاء، موقعة باستخدام HMAC
GET / POST /api/v1/energy/*
المصادقة
تستخدم API الطاقة مفتاح المستخدم للمصادقة. ضمّن الترويسات التالية بكل طلب:
اللوحة → الأدوات والإعدادات → إدارة API؛ أنشئ وفعّل مفتاحًا للحصول على X-API-Key وX-Secret-Key.
استدعاءات موقّعة للنقاط المدفوعة
إنشاء الطلب وطلب المرة الواحدة والاسترداد نقاط مدفوعة. مفاتيح API الجديدة تشترط لها افتراضيًا طلبات موقّعة (X-Key-ID / X-Timestamp / X-Nonce / X-Sign-Version / X-Signature)؛ وفي الأسفل مثال كامل لإنشاء طلب. ما زالت نقاط الاستعلام تقبل X-API-Key + X-Secret-Key وحدهما. إذا عطّلت «اشتراط توقيع الطلبات التي تفرض رسومًا أو تصل إلى بيانات حساسة» في إعدادات المفتاح، فإن النقاط المدفوعة تقبل أيضًا X-Secret-Key العادي، لكن ذلك غير موصى به.
نظرة عامة
تستهلك تحويلات USDT على TRON طاقة. يدفع العنوان دون TRX مجمّد نحو ~6.5-13 TRX للمعاملة. مع الطاقة المستأجرة يستخدم التحويل تلك الطاقة بدل حرق TRX؛ ويتوقف مقدار التوفير على سعر الاستئجار عند الطلب.
تحويل إلى عنوان يملك USDT: نحو ~65,000 وحدة طاقة
تحويل لعنوان لم يستقبل USDT: نحو ~135,000 وحدة طاقة
جلب معلومات المنصة
GET /api/v1/energy/info
اجلب معلومات التأجير العامة: الطاقة المتاحة ومستويات الأسعار والحدود.
استعلام رصيد الحساب
GET /api/v1/energy/balance
استعلم عن رصيد الحساب الذي ينتمي إليه مفتاح API هذا. تأجير الطاقة عمليات كثيرة التكرار وصغيرة القيمة، ونفاد الرصيد فيها أمر معتاد — استعلم عنه قبل الطلبات المجمّعة واضبط تنبيهًا عند انخفاض الرصيد.
قائمة مدد التأجير، نقطة نهاية
GET /api/v1/energy/periods
يعيد قيم period المدعومة. يُرفض غيرها بـ400 دون إنشاء طلب.
تقدير السعر
GET /api/v1/energy/price
قدّر الرسوم وفق المدّة والكمية؛ يعيد سعر API بـ TRX.
تقدير استهلاك الطاقة
GET /api/v1/energy/estimate-energy
قدّر طاقة تحويل USDT إلى عنوان معيّن.
إنشاء طلب تأجير
POST /api/v1/energy/order
اطلب تأجير طاقة؛ تُخصم من رصيد USD.
حقول الرد
عند نقص الرصيد يُعاد code: 400, message: "Insufficient account balance, please top up first"
طلب طاقة لمرة واحدة
POST /api/v1/energy/order/onetime
طلب باستراتيجية لكل معاملة؛ يعيّن النظام energy_amount تلقائيًا.
استعلام قائمة الطلبات
GET /api/v1/energy/orders
استعلم عن طلبات طاقتك.
استعلام طلب واحد
GET /api/v1/energy/order/:serial
استعلم عن التفاصيل وزامن أحدث حالة.
استعلام برقم معاملتك
GET /api/v1/energy/order/by-trade-no/:out_trade_no
ابحث بـ out_trade_no دون رقمنا التسلسلي.
⚠️ عند انتهاء المهلة، تعيد نقطة الإنشاء 504، وكل ما لديك في تلك اللحظة هو out_trade_no (الرقم التسلسلي serial نولّده نحن ولا يظهر في رد انتهاء المهلة). هذه النقطة موجودة لهذه الحالة تحديدًا: اجلب النتيجة النهائية باستخدام out_trade_no نفسه.
استرداد طلب
POST /api/v1/energy/order/reclaim
استردّ طلب تأجير غير منتهٍ مبكرًا.
استدعاء نتيجة الطلب
للطلبات المنشأة مع callback_url (ومنها طلبات المرة الواحدة)، ترسل المنصة النتيجة إلى ذلك العنوان مرة واحدة، عند تسوية الطلب لأول مرة كناجح (status=40) أو فاشل (status=41). سواء تأكدت الحالة عبر إشعار الحالة الفوري أو الاستعلام الدوري عن الطلب أو المطابقة أو استرداد طلب تعذّر حفظه، يُرسل كل طلب مرة واحدة فقط، وتُعاد محاولات التسليم الفاشلة تلقائيًا. الاستثناء هو الطلب الذي أعاد طلب إنشائه 504 مع نتيجة غير معروفة (يُسجَّل داخليًا كعنصر نائب يبدأ رقمه serial بـ LOCAL-): يُحسم يدويًا ولا يُرسل تلقائيًا أبدًا، فتأكد من نتيجته بالاستعلام برقم طلبك الخاص. ترسل المنصة ردود callback وتوقّعها بنفسها؛ وصيغة callback القديمة لم تعد مستخدمة، لذا على التكاملات القائمة تحديث التحليل وفحوص التوقيع لتطابق هذا القسم.
الطلب من نوع POST مع Content-Type: application/json. الجسم كائن JSON مسطّح كل قيمة فيه سلسلة نصية (بما فيها status و energy_amount و timestamp)، ولا يحتوي على حقول أسعار. لا تتبع المنصة إعادات التوجيه، وتنتهي مهلة كل طلب بعد 10 ثوانٍ.
التحقّق من التوقيع
الخوارزمية مطابقة لردود callback لطلبات الدفع: خذ كل حقل قيمته غير فارغة ما عدا sign، ورتّب بحسب اسم الحقل ترتيب ASCII، واجمعها بالشكل k1=v1&k2=v2&…، واحسب HMAC-SHA256؛ والنتيجة سداسية عشرية بأحرف صغيرة. المفتاح هو Secret Key لمفتاح API المستخدم في إنشاء الطلب؛ وللطلبات المنشأة ببيانات اعتماد تطبيق دفع فهو Push Secret لذلك التطبيق (WebhookSecret، ويظهر في صفحة تفاصيل التطبيق بلوحة التحكم — المفتاح نفسه المستخدم في ردود طلبات الدفع)؛ والتطبيقات الأقدم التي لم تولّد Push Secret تستخدم App Key.
لا يحمل الإرسال الحقل sign عندما يكون دعم المنصة قد أنشأ الطلب نيابةً عنك (لا يوجد مفتاح له)، أو عندما يكون مفتاح API أو تطبيق الدفع المستخدم في إنشاء الطلب قد حُذف لاحقًا. عند استلام إرسال بلا sign، تأكد من حالة الطلب عبر نقطة استعلام الطلبات قبل التصرف بناءً عليه.
الرد والإعادات
أي رمز حالة 2xx يُعد تسليمًا ناجحًا؛ ولا يُفحص جسم الرد. الحالة غير 2xx أو انتهاء المهلة أو فشل الاتصال أو إعادة التوجيه تُعد فشلًا، وتعيد المنصة المحاولة بعد 30 ثانية ثم دقيقة ثم دقيقتين ثم 5 دقائق، ثم كل 10 دقائق، حتى 10 محاولات (تتوقف بعد نحو 70 دقيقة). تعيد المحاولات إرسال الجسم نفسه تمامًا، بما فيه notify_id و sign.
إذا انقطعت الشبكة بعد أن عالج خادمك الإرسال وقبل أن تستلم المنصة 2xx، فسيُرسل الطلب نفسه مرة أخرى. أزل التكرار اعتمادًا على notify_id أو serial وتأكد من أن المعالجة مرتين لا تُحدث آثارًا جانبية. الإرسال إشعار وليس المصدر الوحيد للحقيقة: إذا لم يصلك أبدًا، أو فشل التسليم نهائيًا، فتأكد من النتيجة عبر GET /api/v1/energy/order/:serial أو بالاستعلام برقم طلبك الخاص.
مدد التأجير
هذه كل المدد المدعومة حاليًا. يمكنك أيضًا جلبها من GET /api/v1/energy/periods. أي قيمة أخرى تعيد 400 ولا يُنشأ أي طلب.
الأسئلة الشائعة
كم توفر API لاستئجار الطاقة فعليًا؟
كمثال توضيحي، قد يكلف حرق TRX مباشرةً لتحويل USDT واحد عبر TRC-20 نحو 6.5-13 TRX. قد يوفر استئجار الطاقة 70–80%؛ ويعتمد التوفير الفعلي، بما فيه التحويل الجماعي، على حالة الشبكة وسعر الاستئجار.
ما سرعة التفويض، وهل يمكنني تحديد عنوان آخر؟
يصل التفويض خلال ثوانٍ، ويكون عنوان المستلم هو العنوان الذي تمرره في الطلب؛ لا يلزم أن يكون حساب مقدم الطلب، لذا يمكنك توفير الطاقة لعناوين أعمال متعددة بصورة جماعية.
صفحات ذات صلة: تأجير طاقة TRON · وثائق الواجهة البرمجية · مدفوعات مشفّرة متعددة السلاسل
جارٍ التحميل…