TRON Energy Rental API — نقل و انتقالات USDT TRC-20 را خودکار کنید

TRON Energy Rental API: بررسی اجمالی و موارد استفاده

Quick Rent API راهی برای اجاره TRON Energy به صورت خودکار، بدون کار دستی است. انرژی نقل و انتقالات USDT (TRC-20) و سایر تماس های قرارداد هوشمند را ارزان تر از سوزاندن TRX می کند.

به عبارت ساده: برنامه شما (یک سایت، ربات یا سرویس) خودش انرژی را می خرد، دقیقاً در زمانی که نیاز است - به عنوان مثال، قبل از هر انتقال USDT که مشتری شما انجام می دهد.

به یک دستگاه فروش خودکار فکر کنید: شما قیمت را بررسی می کنید، پول وارد می کنید، کالای خود را دریافت می کنید. API همان مجموعه دکمه‌ها است - فقط برنامه شما آنها را فشار می‌دهد.

شروع سریع: از صفر به انرژی

یک مثال کامل از پایان به انتها در ساده ترین سناریو (روی زنجیره). چهار قدم و انرژی روی کیف پول است.

در زیر آنچه در هر مرحله اتفاق می‌افتد و آنچه 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 پایه API تولید

Quick Rent API به خدمات شما اجازه می دهد تا TRON Energy را به صورت خودکار اجاره کند، بنابراین انتقال USDT TRC-20 و سایر تماس های قرارداد هوشمند هزینه کمتری نسبت به سوزاندن TRX دارند.

همه نقاط پایانی یک URL پایه مشترک دارند.

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

مجوز

هر درخواستی باید کلید API شما را به‌عنوان یک توکن حامل در سرصفحه Authorization قرار دهد.

کلید را فقط در سمت سرور نگه دارید (پشتیبان، اسرار CI). هرگز آن را در کد فرانت اند یا مخازن عمومی ارسال نکنید. کلید به یک حساب TronBid متصل است (کیف پولی که در زمان اعطای دسترسی تنظیم شده است). پرداخت های موجود فقط از آن حساب قابل برداشت است.

اگر از حد مجاز تجاوز کنید، API با HTTP 429 پاسخ می‌دهد.

Authorization: Bearer <API_KEY>

حالت های پرداخت

دو روش برای پرداخت هزینه سفارش وجود دارد. On-chain پیش فرض است و نیازی به تنظیم ندارد. پرداخت موجودی اختیاری است و باید برای کلید شما فعال شود.

بدون فعال‌سازی، یک درخواست با pay_mode: موجودی 403 BALANCE_PAYMENT_NOT_ENABLED را برمی‌گرداند. برای فعال کردن آن، با پشتیبانی TronBid تماس بگیرید.

کاتالوگ بسته

انرژی_مقدار و مدت_دقیقه باید با بسته اجاره سریع فعال مطابقت داشته باشد — معمولاً 65000 یا 131000 انرژی و 15 یا 60 دقیقه.

کاتالوگ فعلی را در هر زمان واکشی کنید (بدون نیاز به تأیید اعتبار):

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

جریان روی زنجیره

مرحله 1 - برای اطلاع از قیمت، POST /quote. مرحله 2 - POST / orders برای ایجاد سفارش و دریافت pay_address، مبلغ_trx و expires_at. مرحله 3 - دقیقا مقدار_trx TRX را به pay_address از payer_address خود ارسال کنید. مرحله 4 - نظرسنجی GET /orders/:id را تا زمانی که وضعیت واگذار شود (یا ناموفق / منقضی شده / لغو شود).

target_address اختیاری است - اگر حذف شود، انرژی به payer_address واگذار می‌شود.

فقط یک سفارش زنجیره ای باز (pending_payment) در هر آدرس_payer مجاز است. در غیر این صورت 409 PENDING_PAYMENT_INTENT_EXISTS دریافت خواهید کرد. در صورت پرداخت کمتر/بیش از حد، انرژی نهایی ممکن است متفاوت باشد - effect_energy_amount را در 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 خود، /balance را دریافت کنید. مرحله 2 - POST / نقل قول برای قیمت. مرحله 3 - POST / orders with payment_mode: موجودی تا بدهی و شروع تفویض اختیار. مرحله 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..."
}

وضعیت سفارش

هر سفارش از طریق این وضعیت ها حرکت می کند. نظرسنجی GET /orders/:id را دنبال کنید.

ناتوانی

idempotency_key (8 تا 128 نویسه) یک شناسه سفارش منحصر به فرد در سمت شما است. تکرار POST /orders با یک کلید (برای مشتری API یکسان) همان ترتیب را با "تکراری" برمی گرداند: true.

از یک 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 را دریافت کنید

قیمت فعلی یک بسته را برمی‌گرداند: price_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 ایجاد کنید

یک سفارش اجاره ایجاد می کند. برای on-chain، payer_address را ارسال کنید و مبلغ بازگشتی_trx را به pay_address پرداخت کنید. برای موجودی، pay_mode: موجودی را اضافه کنید و حساب پیوند شده بلافاصله شارژ می‌شود.

target_address اختیاری است (پیش‌فرض به payer_address). به قوانین 409 توجه کنید: یک سفارش زنجیره‌ای باز برای هر پرداخت‌کننده، و هیچ نمایندگی اجاره سریع فعال در حال حاضر در هدف (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..."
  }'

وضعیت سفارش را دریافت کنید

در صورت عدم موفقیت، وضعیت فعلی، حالت پرداخت، مبالغ، آدرس‌ها و error_code / error_message را برمی‌گرداند. effect_energy_amount منعکس کننده انرژی واقعی واگذار شده پس از پرداخت کمتر/بیش از حد است.

{
  "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"

لغو سفارش

سفارشی را که هنوز در انتظار_payment است (فقط در زنجیره) لغو می کند. پس از واگذاری انرژی، دیگر نمی توان سفارش را لغو کرد.

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

پرداخت کننده را تغییر دهید

کیف پول پرداختی را برای سفارش زنجیره‌ای pending_payment تغییر می‌دهد - اگر مشتری تصمیم بگیرد قبل از ارسال 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..."}'

موجودی API TronBid را بررسی کنید

موجودی TRX حساب TronBid مرتبط با کلید API شما (موجودی درون برنامه شما، نه کیف پول زنجیره ای) را برمی گرداند. به هدر Authorization نیاز دارد.

{ "balance_trx": "150.500000" }

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

کدهای خطا

خطاها وضعیت HTTP و فیلد خطا را برمی‌گردانند. در اینجا مواردی هستند که ممکن است با آنها روبرو شوید.

اگر مشکلی پیش بیاید

موقعیت های رایج و کارهایی که باید انجام داد، به زبان ساده.

پشتیبانی از ادغام TRON Energy API

آیا نیاز به دسترسی به API، محدودیت‌های بالاتر یا پرداخت موجودی دارید؟ تماس بگیرید و ما کمک خواهیم کرد.