能量租賃 · 接口

本文含兩類 HTTP：

轉 TRX 檔位詢價 GET|POST /energy-rental/trx-quote：無需 API Key。傳入需要的能量，返回應付 TRX。
積分下單 /energy-rental/quote 與 /energy-rental/orders：要 X-API-Key。

轉原生 TRX 到平台地址本身不是 HTTP；詢價只告訴你該轉多少。能量時長固定 1 小時。到帳後不能退款。

Base URL

https://gateway.gelabs.org

認證

/energy-rental/trx-quote 不要帶 API Key。

積分下單每個請求都要帶：

X-API-Key: your-api-key
Content-Type: application/json

Key 在 Console 的 App 詳情產生。該 App 必須已開通能量租賃。積分接口不必傳 appId，也不必傳 durationHours。

回應格式

與開始接入相同：

{
  "code": 0,
  "message": "success",
  "data": {}
}

code 為 0 才是成功。JSON 用 camelCase。

接口一覽

方法	路徑	說明	認證
GET / POST	`/energy-rental/trx-quote`	按能量算出應付 TRX	無
POST	`/energy-rental/quote`	積分詢價，不扣費	`X-API-Key`
POST	`/energy-rental/orders`	下單	`X-API-Key`
GET	`/energy-rental/orders`	訂單列表	`X-API-Key`
GET	`/energy-rental/orders/:orderNo`	訂單詳情	`X-API-Key`

積分下單後用詳情接口輪詢，直到 status 為 SUCCESS 或 FAILED。

GET / POST /energy-rental/trx-quote

按轉 TRX 檔位，把「需要的能量」向上取成應付 TRX。無需 API Key，不扣積分，也不會自動轉帳。

用法：

調本接口，傳入 energyAmount。
確認信封 code === 0。
轉 data.trxAmount 個原生 TRX 到 data.payAddress。
能量打到付款地址，數量是 data.energyGranted，時長 data.durationHours 小時。用區塊瀏覽器確認，沒有訂單號。

這條接口與下面的 POST /energy-rental/quote 無關：後者按積分 / USDT 計價，必須帶 Key。

請求

GET 用查詢參數，POST 用 JSON 體。

欄位	類型	必填	說明
`energyAmount`	integer	是	需要的能量，必須 > 0

請求示例

curl "https://gateway.gelabs.org/energy-rental/trx-quote?energyAmount=80000"

curl -X POST \
  -H "Content-Type: application/json" \
  https://gateway.gelabs.org/energy-rental/trx-quote \
  -d '{"energyAmount":80000}'

回應 `data`

欄位	類型	說明
`energyAmount`	integer	你傳入的能量
`trxAmount`	integer	該轉的原生 TRX
`energyGranted`	integer	轉夠 `trxAmount` 後實際到帳的能量（≥ 你要的）
`payAddress`	string	收款地址，目前為 `TEtK5Gfm24Bp3yc6LomkZGqr1wQrTE7Gx2`
`durationHours`	integer	時長，固定 `1`

{
  "code": 0,
  "message": "success",
  "data": {
    "energyAmount": 80000,
    "trxAmount": 8,
    "energyGranted": 131000,
    "payAddress": "TEtK5Gfm24Bp3yc6LomkZGqr1wQrTE7Gx2",
    "durationHours": 1
  }
}

energyAmount ≤ 0 或無法解析時 HTTP 400 / code=10001。

POST /energy-rental/quote

按能量數量算出將扣的積分 / USDT，並告訴你當前餘額夠不夠。不扣費。

建議先調詢價再下單。data.sufficient 為 false 時不要下單。

請求頭

欄位	必填	說明
`X-API-Key`	是	Console 產生的 Key
`Content-Type`	是	`application/json`

請求體

欄位	類型	必填	說明
`energyAmount`	integer	是	要租的能量，≥ `65000`
`receiverAddress`	string	否	TRON Base58，`T` 開頭。傳了會校驗格式；下單時必填
`durationHours`	integer	否	只能是 `1` 或省略

請求示例

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  https://gateway.gelabs.org/energy-rental/quote \
  -d '{"energyAmount":65000,"receiverAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"}'

回應 `data`

欄位	類型	說明
`energyAmount`	integer	本次詢價的能量
`durationHours`	integer	時長，固定 `1`
`creditsRequired`	integer	按能量公式算出的所需積分
`planCode`	string	當前套餐代碼
`creditsPerUsdt`	integer	1 USDT 對應多少積分
`creditsToDeduct`	integer	本次將扣的積分
`usdtToDeductMicro`	integer	積分不夠時將扣的 USDT；單位 micro，`1 USDT = 1_000_000`
`availableCredits`	integer	當前可用積分
`availableUsdtMicro`	integer	當前可用 USDT micro
`sufficient`	boolean	餘額是否夠扣
`pricingBaseEnergy`	integer	計價基準能量，目前 `65000`
`pricingBaseCredits`	integer	基準能量對應積分，目前 `90000`
`creditsPerEnergyDisplay`	string	超出基準後每單位能量的積分展示值，目前 `"1.3846"`
`equivalentTrx`	string	本次所需積分按 `creditsPerUsdt` 折成 USDT，再按詢價當下的 TRX 美元價換成 TRX。十進制字串，向上取整到 1 sun（`1 TRX = 1_000_000` sun）。價格不可用時本接口回 `503`

{
  "code": 0,
  "message": "success",
  "data": {
    "energyAmount": 65000,
    "durationHours": 1,
    "creditsRequired": 90000,
    "planCode": "basic",
    "creditsPerUsdt": 61224,
    "creditsToDeduct": 90000,
    "usdtToDeductMicro": 0,
    "availableCredits": 500000,
    "availableUsdtMicro": 0,
    "sufficient": true,
    "pricingBaseEnergy": 65000,
    "pricingBaseCredits": 90000,
    "creditsPerEnergyDisplay": "1.3846",
    "equivalentTrx": "5.880048"
  }
}

上面示例裡的 `"5.880048"` 是按當時 TRX 價格 `0.25` 美元算出的，價格變了這個數會變。

POST /energy-rental/orders

建立一筆租賃訂單：先預留積分，再把能量代理到 receiverAddress。

請求頭

欄位	必填	說明
`X-API-Key`	是	與詢價相同
`Content-Type`	是	`application/json`
`Idempotency-Key`	是	冪等鍵，建議 UUID

請求體

欄位	類型	必填	說明
`energyAmount`	integer	是	與詢價一致，≥ `65000`
`receiverAddress`	string	是	能量打到的 TRON 地址，Base58，`T` 開頭
`durationHours`	integer	否	只能是 `1` 或省略
`gatewayOrderNo`	string	否	不要傳。平台生成 `GER_…`
`authorizationId`	string	否	產品 API 不要傳

冪等

Idempotency-Key 用來避免超時重試時重複扣費：

情況	結果
第一次使用這把 Key	建立新單並預留積分
同一 Key，地址和能量相同	返回原單，不再扣費
同一 Key，地址或能量不同	`409` / `code=10003`
再租一次（哪怕同一地址）	換一把新 Key

請求示例

curl -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  https://gateway.gelabs.org/energy-rental/orders \
  -d '{"energyAmount":65000,"receiverAddress":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf"}'

成功時 data 是一筆訂單，欄位見下方「訂單欄位」。網路超時用同一把 Idempotency-Key 重試。

GET /energy-rental/orders

列出當前 App 的訂單。

請求頭

X-API-Key

查詢參數

參數	類型	必填	說明
`status`	string	否	`PROCESSING` / `SUCCESS` / `FAILED`
`orderNo`	string	否	精確匹配履約單號
`receiverAddress`	string	否	精確匹配接收地址
`page`	integer	否	預設 `1`
`pageSize`	integer	否	預設 `50`

請求示例

curl -H "X-API-Key: $API_KEY" \
  "https://gateway.gelabs.org/energy-rental/orders?page=1&pageSize=20"

回應 `data`

欄位	類型	說明
`list`	object[]	當前頁訂單
`total`	integer	總筆數
`page`	integer	當前頁
`pageSize`	integer	每頁筆數

GET /energy-rental/orders/:orderNo

查一筆訂單。路徑參數是下單返回的 orderNo，不是 gatewayOrderNo。

curl -H "X-API-Key: $API_KEY" \
  https://gateway.gelabs.org/energy-rental/orders/ER_20260915120000_123456

data 就是下面的訂單欄位，沒有 list 包一層。

建議每 2–3 秒輪詢，直到 SUCCESS 或 FAILED。

訂單欄位

時間是 UTC Unix 秒；尚未發生為 null。

欄位	類型	說明
`orderNo`	string	履約單號，用來查詳情
`gatewayOrderNo`	string	平台生成的 `GER_…`
`appId`	string	所屬 App
`receiverAddress`	string	能量接收地址
`status`	string	`PROCESSING` / `SUCCESS` / `FAILED`
`creditsReserved`	integer	預留積分；確認前還不算已扣
`usdtReservedMicro`	integer	預留 USDT micro
`creditsCharged`	integer	已扣積分；處理中為 `0`
`usdtCharged`	string	已扣 USDT，固定 6 位小數
`usdtChargedMicro`	integer	已扣 USDT micro
`energyAmount`	integer	下單能量
`completedEnergyAmount`	integer	已到帳能量；成功前為 `0`
`durationHours`	integer	時長，目前固定 `1`
`paidAt`	integer / null	預留成功時間
`delegatedAt`	integer / null	能量委託時間
`expiresAt`	integer / null	能量到期時間
`source`	string	`api` 或 `console`
`upstreamOrderId`	string / null	上游單號；未提交為 `null`
`createdAt`	integer	建立時間
`updatedAt`	integer	最後更新
`failReason`	string / null	失敗原因；處理中或成功為 `null`

{
  "code": 0,
  "message": "success",
  "data": {
    "orderNo": "ER_20260915120000_123456",
    "gatewayOrderNo": "GER_20260915120000_123456",
    "appId": "app_xxx",
    "receiverAddress": "TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf",
    "status": "PROCESSING",
    "creditsReserved": 90000,
    "usdtReservedMicro": 0,
    "creditsCharged": 0,
    "usdtCharged": "0.000000",
    "usdtChargedMicro": 0,
    "energyAmount": 65000,
    "completedEnergyAmount": 0,
    "durationHours": 1,
    "paidAt": 1757923200,
    "delegatedAt": null,
    "expiresAt": null,
    "source": "api",
    "upstreamOrderId": null,
    "createdAt": 1757923200,
    "updatedAt": 1757923200,
    "failReason": null
  }
}

狀態

`status`	含義
`PROCESSING`	已預留，正在代理能量
`SUCCESS`	能量已打到 `receiverAddress`，積分已實扣
`FAILED`	失敗，預留已釋放

如何確認能量已到帳

詳情接口 status 為 SUCCESS，且 completedEnergyAmount > 0。
到 TronScan 打開 receiverAddress，查看 Energy。
可選，調 TRON 節點：

curl -X POST https://api.trongrid.io/wallet/getaccountresource \
  -H "Content-Type: application/json" \
  -d '{"address":"TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf","visible":true}'

看回應裡的 EnergyLimit / EnergyUsed。

錯誤碼

HTTP 狀態碼與信封 code 一起看。code !== 0 不要當成成功。

HTTP	`code`	何時出現
400	`10001`	參數非法：能量 ≤ 0（TRX 詢價）、能量低於 65000（積分接口）、地址不是 `T` 開頭、時長不是 1
401	`20001`	缺少或無效 `X-API-Key`
403	`20002`	App 未開通能量租賃
404	`10002`	單號不存在或不屬於此 App
409	`10003`	同一 `Idempotency-Key` 但地址 / 能量與原單不同
402	`50001`	積分 / USDT 不足（先看詢價 `sufficient`）
503	`10005`	上游暫時不可用

轉 TRX 檔位

轉 原生 TRX 到 TEtK5Gfm24Bp3yc6LomkZGqr1wQrTE7Gx2。能量打到付款地址。到帳金額向下靠檔。

到帳 TRX	得到的能量
少於 4	不租，TRX 留下
4	65,000
8	131,000（特例，不是 130,000）
`4n`（n≥3）	`65000 × n`

已知能量、要算應付 TRX 時向上取檔，或調 GET|POST /energy-rental/trx-quote。要 80,000 能量就轉 8 TRX（實際得到 131,000）。

Base URL​

認證​

回應格式​

接口一覽​

GET / POST /energy-rental/trx-quote​

請求​

請求示例​

回應 data​

POST /energy-rental/quote​

請求頭​

請求體​

請求示例​

回應 data​

POST /energy-rental/orders​

請求頭​

請求體​

冪等​

請求示例​

GET /energy-rental/orders​

請求頭​

查詢參數​

請求示例​

回應 data​

GET /energy-rental/orders/:orderNo​

訂單欄位​

狀態​

如何確認能量已到帳​

錯誤碼​

轉 TRX 檔位​

Base URL

認證

回應格式

接口一覽

GET / POST /energy-rental/trx-quote

請求

請求示例

回應 `data`

POST /energy-rental/quote

請求頭

請求體

請求示例

回應 `data`

POST /energy-rental/orders

請求頭

請求體

冪等

請求示例

GET /energy-rental/orders

請求頭

查詢參數

請求示例

回應 `data`

GET /energy-rental/orders/:orderNo

訂單欄位

狀態

如何確認能量已到帳

錯誤碼

轉 TRX 檔位