كيف تؤتمت استئجار طاقة TRON عبر API مع مثال بايثون
إن كنت تشغّل محفظة ساخنة أو محرك سحب لمنصة تداول أو عقدًا يُطلق تحويلات TRC-20 نيابةً عن المستخدمين، فأنت تعرف المشكلة: تحتاج إلى طاقة TRON جاهزة في اللحظة التي تنطلق فيها المعاملة. شحن الطاقة يدويًا من الواجهة لا يصمد بعد بضعة تحويلات في اليوم، وإن فاتتك اللحظة حرقت المعاملة TRX من عنوان المرسل، وغالبًا بتكلفة أعلى بكثير من طاقة مستأجرة مسبقًا. الحل أن تستدعي API الاستئجار في اللحظة التي يتهيأ فيها الـ backend لبث المعاملة، فتُجهَّز الطاقة برمجيًا دون تدخل بشري. فيما يلي كيف تفعل ذلك مع tronenergyrent.com: شكل الطلب، ودورة حياة الطلب غير المتزامنة، واختيار المدة، ومثال بايثون تدمجه في خدمتك مباشرة.
ما يفعله API على السلسلة
يفصل نموذج موارد TRON بين الحوسبة (الطاقة) وحجم المعاملة (bandwidth). يستهلك تحويل USDT TRC-20 القياسي نحو 65,000 وحدة من الطاقة إن كان المستلم يملك USDT بالفعل، ونحو 130,000 إن كان رصيده صفرًا؛ فالتحويل الوارد الأول يدفع تكلفة تخزين إنشاء سجل الرصيد، ولهذا تتعلق التكلفة بالمستلم لا بالمرسل. أما bandwidth فنحو 345 بايت، حجم صغير تغطيه أغلب الحسابات من حصتها اليومية المجانية.
حين تستدعي API الاستئجار، تجمّد الخدمة TRX الخاص بها وتفوّض الطاقة الناتجة إلى العنوان الذي تحدده عبر DelegateResourceContract من Stake 2.0. التفويض مخصص لعنوان واحد ومحدد بوقت، وعند انتهاء المدة تستردّ الخدمة الطاقة تلقائيًا.
تفصيل مهم: الاستئجار غير متزامن. يعود استدعاء API فورًا بـ orderId وحالة PAID_BY_USER، لكن معاملة التفويض تُبث في الخلفية وتُنفَّذ عادةً خلال ثوانٍ. على تكاملك أن يعامل الاستجابة الأولى كتأكيد لقبول الطلب ودفعه، ثم يستطلع نقطة تفاصيل الطلب حتى تنتقل الحالة إلى ENERGY_DELEGATED.
اختيار مدة الاستئجار
يقبل API معامل period بأربع قيم: 1h، 1d، 3d، 30d. تتذبذب الأسعار مع سوق الطاقة على السلسلة وتتغير خلال اليوم، فالأرقام الحية دائمًا على صفحة الأسعار. الترتيب النسبي ثابت: 1h الأرخص لكل استدعاء، و30d الأرخص حين تُوزَّع التكلفة على عدد كبير من التحويلات من العنوان نفسه.
لنظام مبني على الأحداث يطلق استئجارًا لكل تحويل صادر، فئة 1h هي الخيار الصحيح غالبًا: تدفع أدنى تكلفة مطلقة وتُستهلك الطاقة خلال ثوانٍ من تفويضها. أما 1d والفئات الأطول فمنطقية حين تشغّل أحمالًا مجمّعة متوقعة، كوظيفة دفعات ليلية، وتريد استئجار كتلة طاقة كبيرة مرة واحدة بدلًا من استدعاء API عشرات المرات. وإن كان نظامك يطلق باستمرار أكثر من 20-30 تحويلًا في الساعة من العنوان نفسه، فاستئجار كتلة 1d بحجم يغطي توقعك أنظف من استدعاء لكل تحويل: ترتفع التكلفة الأولية، لكن يخرج حِمل API وزمن التأكيد على السلسلة من المسار الحرج.
المصادقة وبنية الطلب
نقطة نهاية الاستئجار:
GET https://api.tronenergyrent.com/place-energy-order
طلب GET بسيط بمعاملات استعلام. المصادقة عبر معامل apiKey الذي تولّده من لوحة التحكم بعد التسجيل وشحن رصيدك. لا مصادقة بالترويسات ولا جسم JSON لهذه النقطة. المعاملات:
apiKey(مطلوب): مفتاح API الخاص بك من لوحة التحكم.period(مطلوب): مدة الاستئجار، إحدى1h،1d،3d،30d.energyAmount(مطلوب): كمية الطاقة المطلوب تفويضها. الحد الأدنى15000. لتحويل USDT قياسي واحد إلى مستلم يملك USDT بالفعل، الرقم الآمن65000؛ ولأول تحويل إلى من لا يملك USDT استخدم130000.destinationAddress(مطلوب): عنوان TRON (بصيغة base58check، يبدأ بـT) الذي سيستقبل الطاقة المفوّضة.preActivateDestinationAddress(اختياري، الافتراضي0): اضبطه على1إن لم يستلم عنوان الوجهة أي TRX من قبل، أي أنه غير مفعّل على السلسلة. ترسل الخدمة حينها1.5 TRXمن رصيدك المدفوع مسبقًا لتفعيل العنوان قبل تفويض الطاقة. وإن كان العنوان مفعّلًا فاتركه على0تجنبًا للتكلفة الإضافية.
تعود الاستجابة دائمًا بحالة HTTP 200، نجح الطلب أو فشل. تفرّع على حقل status في جسم JSON لا على حالة HTTP. جسم النجاح:
{
"status": "SUCCESS",
"errorCode": null,
"errorDescription": null,
"requestId": "2651eacd-2428",
"payload": {
"orderId": "128de799-501e-44b2-8d6f-1fa825c2deed",
"totalPriceSun": 5662800,
"totalPriceTrx": 5.6628,
"state": "PAID_BY_USER"
}
}
أما جسم الخطأ فيحمل status: "ERROR" مع errorCode قابل للقراءة آليًا وerrorDescription قابل للقراءة بشريًا:
{
"status": "ERROR",
"errorCode": "INVALID_ENERGY_AMOUNT",
"errorDescription": "energyAmount is less than 15000",
"requestId": "71431087-4",
"payload": null
}
سجّل requestId دائمًا في الفرعَين. إن احتجت يومًا إلى أن يتتبع الدعم عملية استئجار محددة، فهذا المعرّف الذي يبحثون به.
دورة حياة الطلب
يتقدم حقل state في الحمولة عبر سلسلة قصيرة ثابتة:
PAID_BY_USER: الحالة الأولى، دُفع الطلب من رصيدك ولم يحدث شيء على السلسلة بعد.WAITING_DELEGATION: التقطت الخدمة الطلب وتجهّز معاملة التفويض.ENERGY_DELEGATED: نُفِّذت معاملة التفويض على السلسلة، وصار لدى عنوان الوجهة الطاقة المستأجرة ويستطيع إنفاقها على المعاملة الصادرة التالية.ERROR_DELEGATION: فشل التفويض لسبب ما. نادر، لكنه ممكن في أوقات الازدحام الشديد.CANCELLED: أُلغي الطلب وأُعيد المبلغ إلى رصيدك.
للتحقق من الحالة الحالية استدعِ:
GET https://api.tronenergyrent.com/single-order-details?apiKey=YOUR_API_KEY&orderId=ORDER_ID
تستخدم الاستجابة المظروف نفسه status / errorCode / payload، مع state الحالية داخل payload. استطلعها كل ثانية أو ثانيتين بعد تقديم الطلب، ولا تبثّ تحويل TRC-20 إلا بعد أن ترى ENERGY_DELEGATED. عمليًا يكفي استطلاع أو اثنان.
تكامل بايثون
نمط بسيط بشكل إنتاجي: يقدّم الاستئجار، ويستطلع حتى يُنفَّذ التفويض على السلسلة، ويفشل بخطأ واضح إن حدث شيء.
import logging
import time
import requests
API_BASE = "https://api.tronenergyrent.com"
API_KEY = "your_api_key_here"
ENERGY_FOR_TRANSFER = 65_000 # use 130_000 if recipient has zero USDT balance
HTTP_TIMEOUT_SECS = 10
POLL_INTERVAL_SECS = 1
POLL_TIMEOUT_SECS = 30
def place_order(destination_address: str, period: str = "1h",
energy_amount: int = ENERGY_FOR_TRANSFER) -> dict:
resp = requests.get(
f"{API_BASE}/place-energy-order",
params={
"apiKey": API_KEY,
"period": period,
"energyAmount": energy_amount,
"destinationAddress": destination_address,
"preActivateDestinationAddress": 0,
},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"place-energy-order failed: {body.get('errorCode')} "
f"({body.get('errorDescription')}) requestId={body.get('requestId')}"
)
return body["payload"]
def wait_for_delegation(order_id: str) -> dict:
deadline = time.monotonic() + POLL_TIMEOUT_SECS
while time.monotonic() < deadline:
resp = requests.get(
f"{API_BASE}/single-order-details",
params={"apiKey": API_KEY, "orderId": order_id},
timeout=HTTP_TIMEOUT_SECS,
)
resp.raise_for_status()
body = resp.json()
if body.get("status") != "SUCCESS":
raise RuntimeError(
f"single-order-details failed: {body.get('errorCode')} "
f"({body.get('errorDescription')})"
)
state = body["payload"]["state"]
if state == "ENERGY_DELEGATED":
return body["payload"]
if state == "ERROR_DELEGATION":
raise RuntimeError(f"Delegation failed for order {order_id}")
if state == "CANCELLED":
raise RuntimeError(f"Order {order_id} was cancelled")
time.sleep(POLL_INTERVAL_SECS)
raise TimeoutError(f"Order {order_id} did not reach ENERGY_DELEGATED in {POLL_TIMEOUT_SECS}s")
def rent_energy(destination_address: str) -> dict:
placed = place_order(destination_address)
logging.info(
"Order placed: id=%s priceSun=%s priceTrx=%s",
placed["orderId"], placed["totalPriceSun"], placed["totalPriceTrx"],
)
delegated = wait_for_delegation(placed["orderId"])
logging.info("Order delegated: id=%s", delegated["orderId"])
return delegated
نقاط تستحق الإبراز. الفحص الصريح لـ status == "SUCCESS" ضروري لأن حالة HTTP دائمًا 200، فـ resp.raise_for_status() وحدها لا تقول شيئًا عن النتيجة الفعلية. ولحلقة الاستطلاع مهلة صلبة حتى لا يحجب طلب معلّق خط التحويل إلى ما لا نهاية. والتفرّع على state يعالج النتائج النهائية الثلاث (ENERGY_DELEGATED، ERROR_DELEGATION، CANCELLED) صراحةً بدلًا من الاعتماد على «ليس نجاحًا» العام.
في سير عمل التحويل، استدعِ rent_energy() أولًا ثم ابثّ تحويل TRC-20. الترتيب مهم: إن بثثت أولًا حرقت المعاملة TRX من المرسل لأن التفويض لم يُنفَّذ بعد.
حجم رصيدك المدفوع مسبقًا
تُخصم تكلفة الاستئجار من رصيد مدفوع مسبقًا في حسابك على tronenergyrent.com. أعدّ تنبيهًا أو شحنًا تلقائيًا حين ينخفض الرصيد دون عتبة معينة؛ حد أدنى معقول هو ما يغطي ساعتَين من حجم الذروة. ولقراءة الرصيد الحالي برمجيًا:
GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY
تتضمن الحمولة رصيدك الحالي وحالة الحساب. اربطها بمنظومة المراقبة ولن يفاجئك رصيد منضوب في الثانية صباحًا. الحد الأدنى لشحن الرصيد على tronenergyrent.com هو 10 TRX.
التعامل مع الأخطاء
ثلاث حالات فشل تظهر أكثر من غيرها في الإنتاج. رموز الأخطاء أدناه من API الفعلي ويمكنك التفرّع عليها بأمان.
INSUFFICIENT_BALANCE: رصيدك المدفوع مسبقًا لا يغطي الاستئجار المطلوب مع أي تفعيل مسبق. لا تُعِد المحاولة، فهي لن تصلح شيئًا؛ التقط هذا الخطأ تحديدًا وأطلق تدفق تنبيه أو شحن، وأضفrequestIdإلى حمولة التنبيه.INVALID_ADDRESS: فشل فك ترميزdestinationAddressبصيغة base58check على الخادم. إن كان نظامك يبني العناوين ديناميكيًا، من إدخال المستخدم مثلًا، فتحقق منها محليًا قبل استدعاء API؛ في مكتبةtronpyلبايثون دالةis_address()لهذا الغرض، ورفض الإدخال السيء من جانب العميل أسرع من انتظار رحلة الذهاب والإياب.INACTIVE_DESTINATION_ADDRESS_ERROR: لم يُفعَّل عنوان الوجهة على السلسلة من قبل ولم تطلب من الخدمة تفعيله. أصلحه إما بتمويل العنوان مسبقًا بقليل من TRX من مكان آخر، أو بتمريرpreActivateDestinationAddress=1في الاستدعاء التالي لتفعّله الخدمة مقابل1.5 TRX.
حالة أدق: قد يعود ORDER_IS_ALREADY_IN_PROGRESS إن كان لديك عدة عمّال يقدّمون استئجارات للوجهة نفسها في الوقت ذاته. الإصلاح في جانب العملية لا في API: استخدم قفلًا موزعًا (Redis يصلح) مرتبطًا بعنوان الوجهة ومحفوظًا حتى يكتمل التفويض.
التحقق على السلسلة
لأغلب التكاملات يكفي استطلاع /single-order-details حتى ENERGY_DELEGATED. وإن أردت تحققًا مضاعفًا، فاستعلم مباشرة من عقدة TRON كاملة بعد تنفيذ التفويض:
GET https://api.trongrid.io/v1/accounts/{destinationAddress}
تحمل الاستجابة حالة الموارد الحالية للعنوان، بما فيها الطاقة المفوّضة إليه من عناوين خارجية. يعتمد اسم الحقل الدقيق على عرض Stake 2.0 الحالي، فراجع مستندات HTTP API الحية لـ TRON عند توصيله. كفحص ناعم يسجل تحذيرًا بدلًا من حجب التحويل، فهو مؤشر مفيد للحالة النادرة التي يسوء فيها شيء بعد API نفسه، ويوفر عليك ساعات من التصحيح في المرة التي يبدو فيها الاستئجار ناجحًا في API بينما يحدث شيء آخر على السلسلة.