能量租赁 · 接口

本文含两类 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 档位