TRON Energy Rental API for Automated USDT TRC-20 Transfers

Overview: what it is and who it's for

The Quick Rent API is a way to rent TRON Energy automatically, with no manual work. Energy makes USDT (TRC-20) transfers and other smart-contract calls cheaper than burning TRX.

In plain words: your program (a site, bot, or service) buys energy itself, exactly when it's needed — for example, before each USDT transfer your customer makes.

Think of a vending machine: you check the price, insert money, get your item. The API is the same set of buttons — only your program presses them.

Glossary

Short explanations of the words used in this documentation.

Before you start

What to prepare before making your first request.

Introduction

The Quick Rent API lets your service rent TRON Energy automatically, so USDT TRC-20 transfers and other smart-contract calls cost less than burning TRX.

All endpoints share one base URL.

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

Authorization

Every request must include your API key as a Bearer token in the Authorization header.

Keep the key server-side only (backend, CI secrets). Never ship it in frontend code or public repositories. The key is bound to a single TronBid account (the wallet set when access was granted); balance payments can only draw from that account.

If you exceed the rate limit, the API responds with HTTP 429.

Authorization: Bearer <API_KEY>

Payment Modes

There are two ways to pay for an order. On-chain is the default and needs no setup. Balance payment is optional and must be enabled for your key.

Without activation, a request with payment_mode: balance returns 403 BALANCE_PAYMENT_NOT_ENABLED. To enable it, contact TronBid support.

Package Catalog

energy_amount and duration_minutes must match an active Quick Rent package. Energy packages are 65000, 131000, 196500, 262000, 524000 and 1048000, for 15 or 60 minutes. The 196500 package costs three times the current 65000/15-minute price for 15 minutes; its 60-minute price is that total plus 0.7 TRX. Prices are dynamic: request a fresh quote before creating an order. An existing order keeps its captured price.

Fetch the current catalog any time (no auth required):

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

Quickstart: from zero to energy

A full end-to-end example on the simplest scenario (on-chain). Four steps and energy is on the wallet.

Below is what happens at each step and what the API returns. Plug in your API key, addresses and order id.

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

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "payment_sender_mode": "any_wallet",
  "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",
  "delivery_complete": true,
  "txid_delegate": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "txids_delegate": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
  "payment_mode": "onchain",
  "payment_sender_mode": "any_wallet",
  "amount_trx": "3.200000",
  "expected_amount_trx": "3.200000",
  "paid_amount_trx": "3.200000",
  "effective_price_trx": null,
  "energy_amount": "131000",
  "effective_energy_amount": null,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

On-chain Flow

Send the package, idempotency_key and target_address (resource recipient). The response contains pay_address, amount_trx, expires_at and payment_sender_mode.

Send one TRX transfer from ANY wallet to the issued pay_address before expires_at. The resource goes to target_address, not automatically to the sender.

Use target_address for the resource recipient. payer_address remains a backward-compatible recipient alias when target_address is omitted; new orders do not restrict the sending wallet.

Each order gets one available payment address for 15 minutes. If none is available, HTTP 503 PAYMENT_WALLETS_BUSY asks you to retry the same request later. Underpayment or overpayment adjusts effective_energy_amount; separate payments are not combined. The payment detection minimum is 0.9 TRX.

Do not send after expires_at or reuse a payment address. Addresses are reassigned: a later transfer is credited to the order currently using that address.

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

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "payment_sender_mode": "any_wallet",
  "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..."
}

Balance Flow

Step 1 — GET /balance to check your TRX. Step 2 — POST /quote for the price. Step 3 — POST /orders with payment_mode: balance to debit and start delegation. Step 4 — poll GET /orders/:id until delegated (on a delegation error it becomes failed and TRX is refunded to your balance).

payer_address is not needed — the account linked to your API key pays. The +1% Energy bonus applies only to the 524000 and 1048000 packages for 15 or 60 minutes: you receive 529240 and 1058480 Energy respectively. All other packages have no bonus. Existing orders retain their captured Energy amount.

{
  "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",
  "payment_sender_mode": null,
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "duration_minutes": 15,
  "expires_at": null,
  "qr_payload": null,
  "duplicate": false,
  "target_address": "TTarget..."
}

Custom Locked: 1–15 minutes (Energy API)

Add custom_lock_minutes to POST /quote and POST /orders to choose a whole-minute Energy lock: 1, 2, 3, …, 15. Custom orders require your API key and support both on-chain payment and enabled balance payment. This option is not available for Bandwidth, the website checkout or the Telegram bot.

Keep duration_minutes at 15: it selects the pricing package. custom_lock_minutes sets the actual lock. Use an active 15-minute energy_amount from the catalog. The price and Energy bonus are exactly those of that package, with no per-minute discount. Read the current price from /quote; examples do not fix a price.

The field is optional. Omit it to keep the existing 15/60-minute behavior, pricing and response format. It has no implicit default. Send a JSON integer; strings, fractions, null, 0, negative values and values above 15 are rejected with HTTP 400. Custom Locked with duration_minutes: 60 or resource_type: bandwidth is also rejected.

Send one TRX transfer from ANY wallet to the issued pay_address before expires_at. The resource goes to target_address, not automatically to the sender. Use target_address for the resource recipient. payer_address remains a backward-compatible recipient alias when target_address is omitted; new orders do not restrict the sending wallet. For balance orders, pass target_address and payment_mode: balance; your API key must have balance payment enabled.

The lock begins when the delegation is included on TRON, not when you request a quote, create an order or pay. One minute is 20 TRON blocks (approximately 60 seconds). We store the actual on-chain delegation_expires_at. expires_at in the payment response is a separate payment deadline.

Poll GET /orders/:id (for example, every 3 seconds). Custom responses include custom_lock_minutes and lock_period_blocks. The status endpoint also returns delegation_expires_at, reclaim_status, txid_delegate, txid_reclaim and reclaimed_at. Unavailable timestamps/transaction IDs are null.

Lifecycle: pending_payment (on-chain only) → delegating → delegated → undelegating → completed. delegated means Energy has been delivered. undelegating means the lock has ended and Reclaim is being processed; reclaim_status is pending. completed and reclaim_status: confirmed mean the return transaction is solidified on-chain. No separate Reclaim request is needed.

Custom orders have a dedicated recovery scan every 3 seconds. Reclaim is attempted as soon as TRON reports the delegation unlocked, independently of the five-minute pool sweep. Block production, queue load and RPC availability can delay submission; network confirmation takes additional time. We do not reclaim before the network lock expires.

Orders, signed transactions and reclaim attempts are persisted. A restart or RPC timeout resumes the same transaction; it does not create another rental. Provider failures retry automatically. The source/recipient pair stays reserved until Reclaim is confirmed; another free pool wallet may serve a new order.

Reuse the same idempotency_key for retries. Changing, adding or removing custom_lock_minutes on an existing key returns 409 IDEMPOTENCY_CUSTOM_LOCK_MISMATCH. Use a new key for a different lock. Existing payment-mode mismatch rules still apply.

Configured webhooks keep their existing signature and delivery mechanism. Custom events include the optional lock fields: quick_buy.delegated when delivered, quick_buy.expired with status: completed and txid_reclaim after confirmed Reclaim, or quick_buy.failed for a verified unsuccessful delegation. Deduplicate by event_id. On provider uncertainty, poll the existing order instead of placing another one.

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/quote \
  -H "Content-Type: application/json" \
  -d '{
  "energy_amount": 131000,
  "resource_type": "energy",
  "duration_minutes": 15,
  "custom_lock_minutes": 5
}'

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/orders \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "energy_amount": 131000,
  "resource_type": "energy",
  "duration_minutes": 15,
  "custom_lock_minutes": 5,
  "payment_mode": "balance",
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX",
  "idempotency_key": "partner-custom-5min-balance-001"
}'

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/orders \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "energy_amount": 131000,
  "resource_type": "energy",
  "duration_minutes": 15,
  "custom_lock_minutes": 5,
  "target_address": "TTargetWalletXXXXXXXXXXXXXXXXXXXXX",
  "idempotency_key": "partner-custom-5min-onchain-001"
}'

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "delegated",
  "duration_minutes": 15,
  "custom_lock_minutes": 5,
  "lock_period_blocks": 100,
  "delegation_expires_at": "2026-09-27T12:05:00.000Z",
  "reclaim_status": "not_started",
  "txid_delegate": "<delegation transaction hash>",
  "txid_reclaim": null,
  "reclaimed_at": null
}

Order Statuses

Every order moves through these statuses. Poll GET /orders/:id to follow it.

Idempotency

idempotency_key (8–128 chars) is a unique order id on your side. Repeating POST /orders with the same key (for the same API client) returns the same order with "duplicate": true.

Do not reuse one idempotency_key across different payment modes (onchain vs balance) — that returns 409 IDEMPOTENCY_PAYMENT_MODE_MISMATCH.

Recipient pool availability

Check whether at least one enabled Quick Rent Energy pool is free for a recipient before submitting an order. POST /api/v2/quick-rent/availability uses your existing Bearer API key and the same per-key and per-IP rate limits as the other authenticated API methods. No idempotency key is required.

Send target_address (a valid TRON Base58 address). resource_type is optional and only accepts energy. Do not send energy_amount, duration_minutes, custom_lock_minutes or payment details to this endpoint. Bandwidth is not supported by this check.

HTTP 200 with available: true and reason: AVAILABLE means at least one pool-to-recipient pair has no active Energy lock or pending Quick Rent reservation. HTTP 200 with available: false and reason: ALL_POOLS_BUSY means every eligible pool is occupied for this recipient. NO_ELIGIBLE_POOLS means no enabled source can serve this address (including the case where the only source is the recipient itself). Busy is a normal result, not an HTTP error.

The check uses the existing order reservation rules, including delegating, delegate_confirming, undelegating and active delegated orders. Custom Locked orders continue to occupy their source until their return is processed, even after the lock time has passed. The check reads current pool configuration and database reservations and requests fresh blockchain lock checks for unreserved pairs. checked_at is the UTC completion time, not a guaranteed unlock time.

HTTP 400: INVALID_REQUEST for malformed JSON, missing/unknown fields or an unsupported resource; INVALID_TARGET_ADDRESS for an invalid address/checksum. HTTP 401: missing, invalid or disabled API key. HTTP 429: rate limit exceeded. HTTP 503: QUICK_RENT_DISABLED or AVAILABILITY_CHECK_UNAVAILABLE when the database, signer configuration or blockchain cannot be verified. A 503 is an unknown result; do not interpret it as available or busy.

Recommended flow: check availability, request a quote for the desired amount, then submit your existing order request. If busy, wait or use another recipient. Retry uncertain checks with backoff; do not poll in a tight loop. All existing endpoints and responses remain unchanged; using this endpoint is optional.

curl -sS -X POST https://tronbid.com/api/v2/quick-rent/availability \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "target_address": "TWLaGaf3k6dbiEWvif1tNLeKuTErk2Tron"
}'

{
  "resource_type": "energy",
  "target_address": "TWLaGaf3k6dbiEWvif1tNLeKuTErk2Tron",
  "available": true,
  "reason": "AVAILABLE",
  "checked_at": "2026-09-30T12:00:00.000Z"
}

{
  "resource_type": "energy",
  "target_address": "TWLaGaf3k6dbiEWvif1tNLeKuTErk2Tron",
  "available": false,
  "reason": "ALL_POOLS_BUSY",
  "checked_at": "2026-09-30T12:00:00.000Z"
}

{
  "error": "AVAILABILITY_CHECK_UNAVAILABLE",
  "message": "Availability could not be verified. Retry later."
}

Calculator

Estimate how much energy an address needs for a transfer. Pass the recipient wallet and whether it already holds 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}'

Get Quote

Returns the current price for a package: price_trx, availability, save_percent and how long the quote is valid (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}'

Create Order

Creates a rental order. For on-chain payment, pass target_address and pay from any wallet to the returned pay_address. For balance payment, pass payment_mode: balance; the linked account is charged immediately.

Use target_address for the resource recipient. payer_address remains a backward-compatible recipient alias when target_address is omitted; new orders do not restrict the sending wallet.

Each order gets one available payment address for 15 minutes. If none is available, HTTP 503 PAYMENT_WALLETS_BUSY asks you to retry the same request later. Underpayment or overpayment adjusts effective_energy_amount; separate payments are not combined.

{
  "id": "uuid",
  "status": "pending_payment",
  "payment_mode": "onchain",
  "payment_sender_mode": "any_wallet",
  "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",
  "payment_sender_mode": null,
  "pay_address": null,
  "amount_trx": "3.200000",
  "energy_amount": 131000,
  "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",
    "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..."
  }'

Get Order Status

Returns the current status, payment_mode, amounts, addresses, and error_code / error_message if something failed. effective_energy_amount reflects the actual delegated energy after under/overpayment.

amount_trx is a TRX decimal string (for example, "1.500000"). For balance payments it is the recorded order charge; for on-chain payments it is the expected payment, as in the order-creation response. Legacy orders without an expected amount use their stored price. This field alone does not prove payment, delivery or a refund. Existing fields keep their meaning: paid_amount_trx is the recorded incoming payment and may be null for balance orders; expected_amount_trx is the expected payment; effective_price_trx may record the adjusted rental price after underpayment or overpayment. Check status and delivery_complete to determine fulfilment.

refund is an object only when a completed balance refund is recorded for the current payment attempt; otherwise it is null. status: completed confirms the credit, amount_trx is the refunded TRX decimal string, refunded_at is an ISO 8601 UTC timestamp, and destination is account_balance or bot_balance. A failed order alone does not confirm a refund. null does not prove that no historical refund occurred: older orders may lack a receipt. The refund may exclude an already completed wallet activation. amount_trx at the top level remains the original order charge, not the net charge after a refund. A paid retry starts a new payment attempt; an earlier refund is not reported as a refund of that new payment.

txid_delegate is the TRON delegation transaction hash for both standard and Custom Locked orders. It is not the TronBid order ID or the payment_txid payment hash. When status is delegated, the stored delegation hash is returned in the same response and remains available after the rental ends. It is null until the primary hash is stored; historical records without a saved hash may also return null.

txids_delegate is an array of stored delegation hashes without duplicates. It usually contains one hash; orders fulfilled by multiple transactions, including supplier delivery and own-pool fallback, include all stored hashes. txid_delegate remains a single string or null; when present, the primary hash is first in the array. With no stored hashes, the array is []. A hash may appear before confirmation, and partial transactions before full delivery: check status and delivery_complete rather than the presence of a hash alone.

View a transaction at https://tronscan.org/#/transaction/{txid}. These fields extend the existing GET /api/v2/quick-rent/orders/{id} response: the API URL, keys, request parameters, existing fields and statuses are unchanged. Existing integrations that ignore unknown response fields continue to work unchanged. Strict schema validators should allow additional fields. No new key or extra request parameter is required to receive hashes.

payment_sender_mode is any_wallet for new invoices, specified_wallet for legacy invoices and null for balance. pay_address belongs to this invoice only. payer_address in status is the actual sender after a detected on-chain payment; it is not the resource recipient.

{
  "id": "uuid",
  "status": "delegated",
  "delivery_complete": true,
  "txid_delegate": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "txids_delegate": ["aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"],
  "payment_mode": "onchain",
  "payment_sender_mode": "any_wallet",
  "amount_trx": "3.200000",
  "expected_amount_trx": "3.200000",
  "paid_amount_trx": "3.200000",
  "effective_price_trx": null,
  "energy_amount": "131000",
  "effective_energy_amount": null,
  "duration_minutes": 15,
  "pay_address": "TDeposit...",
  "payer_address": "TPayer...",
  "target_address": "TTarget...",
  "error_code": null,
  "error_message": null
}

{
  "id": "uuid",
  "status": "delegated",
  "delivery_complete": true,
  "txid_delegate": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "txids_delegate": [
    "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
  ]
}

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

Cancel Order

Cancels an order that is still pending_payment (on-chain only). Once energy has been delegated, the order can no longer be cancelled.

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

Change Payer

Only for legacy invoices with payment_sender_mode: specified_wallet. New invoices accept any wallet and do not need set-payer; attempting it returns HTTP 409 PAYMENT_SENDER_NOT_REQUIRED.

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..."}'

Get Balance

Returns the TRX balance of the TronBid account linked to your API key (your in-app balance, not an on-chain wallet). Requires the Authorization header.

{ "balance_trx": "150.500000" }

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

Error Codes

Errors return an HTTP status and an error field. Here are the ones you may encounter.

If something goes wrong

Common situations and what to do, in plain words.

Support

Need API access, higher limits, or balance payment enabled? Reach out and we'll help.