透過 API 自動租賃 TRON 能量

2026-05-13

如果您在維護熱錢包、交易所的提領引擎,或是替使用者發起 TRC-20 轉帳的智能合約,想必遇過這個問題:交易要送出的那一刻,TRON 能量就得已經到位。每天只有幾筆轉帳時,在介面上手動下單還撐得住,量一大就完全跟不上;一旦錯過時間點,交易就會改為燃燒傳送地址裡的 TRX,通常比事先租好的能量貴上不少。解法是讓後端在廣播交易前自動呼叫租賃 API,全程不需要人工介入;下面用 tronenergyrent.com 的 API 示範整套流程,最後附上一段可以直接放進服務裡的 Python 範例。

API 在鏈上做了什麼

動手寫程式之前,先搞懂鏈上的運作機制,否則除錯時會一頭霧水。

TRON 的資源模型把運算(能量)和交易體積(bandwidth)分開計算。一筆標準的 USDT TRC-20 轉帳,收款方已經持有 USDT 時大約消耗 65,000 能量,收款方的 USDT 餘額為零時則約需 130,000:第一筆入帳要負擔建立餘額紀錄的儲存費用,所以能量多寡完全由收款方決定,與傳送方無關。bandwidth 方面,一筆轉帳大約用掉 345,數量不大,大多數帳戶靠每日免費額度就夠用。

呼叫租賃 API 時,平台會用自己的 TRX 質押,再透過 Stake 2.0 的 DelegateResourceContract 把產生的能量委託給您指定的地址。委託綁定地址、附帶期限,租期一到,能量就由平台自動收回。

還有一個重點:租賃是非同步的。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 request body。

參數如下:

  • apiKey(必填):您在儀表板取得的 API 金鑰。
  • period(必填):租期,1h、1d、3d、30d 其中之一。
  • energyAmount(必填):要委託的能量數量,最少 15000。發給已持有 USDT 的收款方,65000 是安全值;發給第一次收 USDT 的地址,請用 130000。
  • destinationAddress(必填):接收能量的 TRON 地址(base58check 格式,以 T 開頭)。
  • preActivateDestinationAddress(選填,預設 0):目標地址從沒收過 TRX、尚未在鏈上啟用時設為 1,平台會先從預付餘額扣 1.5 TRX 啟用該地址,再委託能量。地址已經啟用就維持 0,省下這筆費用。

不論訂單成功與否,HTTP 狀態碼一律是 200,請用 JSON 回應裡的 status 欄位判斷,不要看 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 記下來。日後您需要請客服追查某筆租賃,他們就是用這個 ID 查詢。

訂單狀態

payload 裡的 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 裡。下單後每一兩秒輪詢一次,看到 ENERGY_DELEGATED 再送出 TRC-20 轉帳;實際上通常輪詢一到兩次就夠了。

Python 範例

下面是一個精簡、但已經有正式環境樣子的寫法:下單、輪詢到委託上鏈,出任何問題都丟出明確的錯誤訊息。

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

payload 裡有目前餘額和帳戶狀態。把它接進您的監控系統,就不會凌晨兩點被餘額歸零嚇一跳。另外,儲值到 tronenergyrent.com 的最低金額是 10 TRX。

正式環境裡最常見的三種失敗:

  1. INSUFFICIENT_BALANCE:預付餘額不夠支付這次租賃加上預先啟用的費用。不要重試,重試解決不了問題;請單獨攔截這個錯誤,觸發警示或儲值流程,並把 requestId 帶進警示內容。
  2. INVALID_ADDRESS:destinationAddress 在伺服器端的 base58check 解碼失敗。如果您的系統會動態組出地址(例如來自使用者輸入),呼叫 API 前先在本機驗證;tronpy 這個 Python 套件有 is_address() 可以用,在用戶端直接擋掉錯誤輸入,比等一次往返快得多。
  3. 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 的帳戶資料格式為準,串接時請對照最新的 TRON HTTP API 文件。把它當成軟性檢查,出錯時只記錄警示、不阻擋轉帳;租賃 API 下游偶爾出狀況時,這是很有用的預警訊號。多做這一步,碰到 API 顯示成功但鏈上另有狀況的那一次,就能幫您省下好幾個小時的追查。

想節省 TRON 交易費用?立即檢視能量價格。 價格估算
回到部落格