چطور اجاره انرژی TRON را با API خودکار کنید

2026-05-13

چرا اجاره انرژی را خودکار کنید

اگر کیف پول گرم، موتور برداشت صرافی یا قراردادی دارید که از طرف کاربران انتقال TRC-20 می‌فرستد، این درد را می‌شناسید: هر وقت تراکنشی می‌رود، انرژی TRON باید از قبل آماده باشد. شارژ دستی انرژی از رابط کاربری برای بیش از چند انتقال در روز جواب نمی‌دهد، و اگر دیر شود تراکنش به‌جای انرژی از آدرس فرستنده TRX می‌سوزاند، معمولاً گران‌تر از انرژی از پیش اجاره‌شده.

راه‌حل این است که بک‌اند شما درست پیش از پخش تراکنش، API اجاره را صدا بزند و انرژی بدون دخالت آدم تأمین شود. در ادامه همین کار را با tronenergyrent.com می‌بینید: ساختار واقعی درخواست، چرخه ناهمزمان سفارش، انتخاب مدت و یک نمونه Python که می‌توانید در سرویس خودتان بگذارید.

API روی زنجیره چه می‌کند

مدل منابع TRON محاسبات (انرژی) را از اندازه تراکنش (bandwidth) جدا می‌کند. یک انتقال معمولی USDT TRC-20 حدود 65,000 انرژی می‌خواهد وقتی گیرنده از قبل USDT دارد، و حدود 130,000 وقتی موجودی USDT گیرنده صفر است: اولین انتقال، هزینه ذخیره‌سازی ساختن ردیف موجودی را می‌دهد و برای همین هزینه به گیرنده بستگی دارد، نه فرستنده. bandwidth یک انتقال حدود 345 بایت است، آن‌قدر کم که بیشتر حساب‌ها از سهمیه رایگان روزانه پوشش می‌دهند.

وقتی API اجاره را صدا می‌زنید، سرویس TRX خودش را استیک می‌کند و انرژی حاصل را با DelegateResourceContract از Stake 2.0 به آدرسی که داده‌اید واگذار می‌کند. واگذاری مخصوص آن آدرس و محدود به زمان است و با پایان دوره اجاره سرویس آن را خودکار پس می‌گیرد.

نکته مهم: اجاره ناهمزمان است. فراخوانی API بلافاصله با یک orderId و وضعیت PAID_BY_USER برمی‌گردد، اما تراکنش واگذاری در پس‌زمینه پخش می‌شود و معمولاً ظرف چند ثانیه روی زنجیره می‌نشیند. یکپارچه‌سازی شما باید پاسخ اولیه را تأیید پذیرش و پرداخت سفارش بداند و بعد اندپوینت جزئیات سفارش را تا رسیدن وضعیت به ENERGY_DELEGATED poll کند.

انتخاب مدت اجاره

پارامتر 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): اگر آدرس مقصد هرگز TRX نگرفته و در نتیجه روی زنجیره فعال نشده، آن را 1 کنید. سرویس پیش از واگذاری انرژی 1.5 TRX از موجودی شما می‌فرستد تا آدرس فعال شود. اگر آدرس از قبل فعال است، برای اینکه هزینه اضافه ندهید آن را 0 بگذارید.

پاسخ همیشه با کد HTTP 200 برمی‌گردد، موفق یا ناموفق. به‌جای کد HTTP روی فیلد status در بدنه JSON شاخه بزنید. بدنه موفق این شکل است:

{
  "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 در payload از یک دنباله کوچک و ثابت می‌گذرد:

  • 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. پس از ثبت سفارش هر یک یا دو ثانیه این را poll کنید و فقط بعد از دیدن ENERGY_DELEGATED انتقال TRC-20 را بفرستید. در عمل معمولاً یک یا دو poll کافی است.

نمونه کاربردی Python

یک الگوی مینیمال اما با شکل آماده برای تولید: سفارش را می‌زند، تا ثبت واگذاری روی زنجیره poll می‌کند و اگر چیزی خراب شد خطای روشنی می‌دهد.

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() به‌تنهایی چیزی از نتیجه واقعی نمی‌گوید. حلقه poll مهلت سختی دارد تا یک سفارش گیرکرده خط انتقال شما را بی‌نهایت نبندد. شاخه‌بندی روی state سه نتیجه نهایی (ENERGY_DELEGATED، ERROR_DELEGATION، CANCELLED) را صریح مدیریت می‌کند، نه با یک «شکست» عمومی.

در جریان انتقال، اول rent_energy() را صدا بزنید و بعد انتقال TRC-20 را پخش کنید. ترتیب مهم است: اگر اول پخش کنید، تراکنش از فرستنده TRX می‌سوزاند، چون واگذاری هنوز ثبت نشده.

اندازه موجودی حساب

هزینه اجاره از موجودی حساب شما در tronenergyrent.com کسر می‌شود. برای وقتی موجودی زیر آستانه‌ای می‌رود هشدار یا شارژ خودکار بگذارید؛ کف منطقی، مبلغی است که دو ساعت حجم اوج را پوشش دهد. موجودی فعلی را برنامه‌نویسی‌شده این‌طور بخوانید:

GET https://api.tronenergyrent.com/account-info?apiKey=YOUR_API_KEY

payload موجودی فعلی و وضعیت حساب را دارد. آن را به سیستم پایش وصل کنید تا ساعت 2 بامداد با موجودی خالی غافلگیر نشوید. حداقل شارژ موجودی در tronenergyrent.com 10 TRX است.

مدیریت خطا در عمل

سه حالت شکست در تولید بیشتر از همه پیش می‌آید. این کدها از API واقعی هستند و می‌توانید با اطمینان روی آن‌ها شاخه بزنید.

  1. INSUFFICIENT_BALANCE: موجودی شما برای اجاره درخواستی به‌علاوه پیش‌فعال‌سازی احتمالی کم است. تلاش دوباره نکنید، چیزی را حل نمی‌کند؛ این خطا را جدا بگیرید، هشدار یا جریان شارژ راه بیندازید و requestId را در payload هشدار بگذارید.
  2. INVALID_ADDRESS: destinationAddress در سرور از رمزگشایی base58check رد نشد. اگر آدرس‌ها را پویا می‌سازید، مثلاً از ورودی کاربر، پیش از فراخوانی API آن‌ها را محلی اعتبارسنجی کنید. کتابخانه Python tronpy برای این کار is_address() دارد؛ رد کردن ورودی بد سمت کلاینت سریع‌تر از انتظار برای رفت و برگشت است.
  3. INACTIVE_DESTINATION_ADDRESS_ERROR: آدرس مقصد روی زنجیره فعال نشده و از سرویس هم نخواسته‌اید فعالش کند. یا مقدار کمی TRX از جای دیگری به آدرس بفرستید، یا در فراخوانی بعدی preActivateDestinationAddress=1 بدهید تا سرویس با 1.5 TRX فعال کند.

یک حالت ظریف‌تر: اگر چند worker هم‌زمان برای یک مقصد اجاره بزنند، ORDER_IS_ALREADY_IN_PROGRESS برمی‌گردد. راه‌حل سمت فرآیند است، نه API: یک قفل توزیع‌شده (Redis خوب جواب می‌دهد) با کلید آدرس مقصد بگیرید و تا پایان واگذاری نگه دارید.

تأیید روی زنجیره

برای بیشتر یکپارچه‌سازی‌ها poll کردن /single-order-details تا ENERGY_DELEGATED کافی است. اگر اطمینان دوچندان می‌خواهید، پس از ثبت واگذاری می‌توانید مستقیم از گره کامل TRON هم بپرسید:

GET https://api.trongrid.io/v1/accounts/{destinationAddress}

پاسخ وضعیت فعلی منابع آدرس را دارد، از جمله انرژی واگذارشده از آدرس‌های دیگر. نام دقیق فیلد به نمای فعلی Stake 2.0 بستگی دارد، پس هنگام پیاده‌سازی به مستندات زنده HTTP API TRON نگاه کنید. به شکل یک بررسی نرم که به‌جای مسدود کردن انتقال فقط هشدار لاگ می‌کند، قناری خوبی است برای آن مورد نادری که اجاره در API موفق به نظر می‌رسد اما چیز دیگری روی زنجیره خراب است، و ساعت‌ها اشکال‌زدایی را نجات می‌دهد.

می‌خواهید در کارمزد تراکنش‌های TRON صرفه‌جویی کنید؟ قیمت انرژی را بررسی کنید. تخمین قیمت
بازگشت به وبلاگ