TRON 能量租赁 API 文档

概述

通过 Open API，交易所、钱包和支付系统可以自动化租赁 TRON 能量：下单、查询订单状态、预估价格，并在订单完成时接收回调通知。

项目	值
Base URL	`https://api.tronhub.net`
请求方法	所有接口均为 `POST`
请求格式	`application/json`
金额单位	sun（1 TRX = 1,000,000 sun）
能量发放方式	链上委托到 `receive_address`

订单费用从账户余额中扣除。请在 API 密钥页面创建 API Key，API Secret 仅在创建时显示一次。

API 仅用于服务端之间调用，请勿在浏览器或移动端暴露 API Secret。

签名认证

每个请求都必须携带以下三个请求头：

Header	说明
`API-KEY`	API Key（以 `ak_` 开头）
`TIMESTAMP`	当前 Unix 时间戳（秒），与服务器时间相差超过 300 秒的请求会被拒绝
`SIGNATURE`	小写十六进制的 HMAC-SHA256 签名，见下文

签名算法

signature = hex( HMAC-SHA256( key = api_secret, message = TIMESTAMP + "&" + body ) )

body 是你实际发送的原始请求体字符串。请先序列化一次 JSON，对这个字符串签名，再原样发送；签名后不要重新序列化。
请求体为空时，对字符串 {} 签名。
直接使用 API Secret 字符串作为 HMAC 密钥（不要做十六进制解码）。
签名结果必须是小写十六进制。

Key 设置

权限：order（创建订单）、query（查询订单）、price（预估价格与市场数据）、balance（账户余额），或 * 表示全部。
IP 白名单：可选，多个 IP 用英文逗号分隔，需完全匹配；设置后其他 IP 的请求会被拒绝。
频率限制：可选，每个 Key 每分钟的请求上限（0 表示不限制）。

代码示例

import hashlib, hmac, json, time
import requests

API_KEY = "ak_your_api_key"
API_SECRET = "your_api_secret"
BASE_URL = "https://api.tronhub.net"

def call(path, payload=None):
    body = json.dumps(payload or {}, separators=(",", ":"))
    timestamp = str(int(time.time()))
    signature = hmac.new(API_SECRET.encode(), f"{timestamp}&{body}".encode(), hashlib.sha256).hexdigest()
    headers = {
        "Content-Type": "application/json",
        "API-KEY": API_KEY,
        "TIMESTAMP": timestamp,
        "SIGNATURE": signature,
    }
    # 发送的必须是签名时使用的同一个字符串
    return requests.post(BASE_URL + path, data=body, headers=headers, timeout=15).json()

print(call("/api/open/price", {"period": "1H", "energy_amount": 65000}))

import crypto from "node:crypto"

const API_KEY = "ak_your_api_key"
const API_SECRET = "your_api_secret"
const BASE_URL = "https://api.tronhub.net"

async function call(path, payload = {}) {
  const body = JSON.stringify(payload)
  const timestamp = Math.floor(Date.now() / 1000).toString()
  const signature = crypto.createHmac("sha256", API_SECRET).update(`${timestamp}&${body}`).digest("hex")
  const res = await fetch(BASE_URL + path, {
    method: "POST",
    headers: { "Content-Type": "application/json", "API-KEY": API_KEY, "TIMESTAMP": timestamp, "SIGNATURE": signature },
    body,
  })
  return res.json()
}

console.log(await call("/api/open/balance"))

func call(path string, payload any) (*http.Response, error) {
	body, _ := json.Marshal(payload)
	timestamp := strconv.FormatInt(time.Now().Unix(), 10)
	mac := hmac.New(sha256.New, []byte(apiSecret))
	mac.Write([]byte(timestamp + "&" + string(body)))
	signature := hex.EncodeToString(mac.Sum(nil))

	req, _ := http.NewRequest(http.MethodPost, baseURL+path, bytes.NewReader(body))
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("API-KEY", apiKey)
	req.Header.Set("TIMESTAMP", timestamp)
	req.Header.Set("SIGNATURE", signature)
	return http.DefaultClient.Do(req)
}

响应与错误

所有接口使用统一的响应结构。请根据 code 字段判断结果，而不是 HTTP 状态码：业务错误同样以 HTTP 200 返回。

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

data 仅在成功时返回；出错时 message 为错误说明。

错误信息默认为中文。如需英文，可在请求头中加上可选的 X-Locale: en：

X-Locale: en

X-Locale 请求头不参与签名。

code	含义	常见原因
`200`	成功	—
`400`	参数错误	缺少字段、字段不合法、JSON 格式错误
`401`	认证失败	缺少请求头、时间戳过期、Key 无效或已禁用、签名错误
`403`	无权限	Key 没有该接口权限，或 IP 不在白名单
`429`	请求过于频繁	超过该 Key 的频率限制
`500`	业务错误	余额不足、订单不存在、不支持的租赁周期、下单失败

系统还有按 IP 的全局限流，超出时返回 HTTP 429 且 code: 429，请退避后重试。

创建订单

POST /api/open/order/create · 权限 order

从账户余额扣除订单费用，并将能量委托到 receive_address。

参数	类型	必填	说明
`energy_amount`	int	是	能量数量，需在市场数据返回的范围内
`period`	string	是	租赁周期：`1H`、`1D`、`3D` 或 `30D`（区分大小写）
`receive_address`	string	是	接收能量的 TRON 地址（需已激活）
`callback_url`	string	否	订单完成或失败时的回调地址，须为公网可访问的 `http`/`https` 地址，内网、回环等地址会被拒绝，见回调通知
`out_trade_no`	string	否	你方订单号，同一账户内唯一。建议填写，可保证重试安全（见下文）

{
  "energy_amount": 65000,
  "period": "1H",
  "receive_address": "TXk8rQSAvPvBBNtqSoY6nCfsXWCSSpTVQF",
  "callback_url": "https://example.com/tron-energy/callback",
  "out_trade_no": "ORDER-10001"
}

扣费金额与预估价格返回的 total_price 一致，低于 small_amount 的订单包含小额手续费。

重试与 out_trade_no：下单请求超时时，请使用同一个 out_trade_no 重试：

out_trade_no 相同，且 energy_amount、period、receive_address 也相同：返回已有订单，不会重复扣费。
out_trade_no 相同但参数不同：请求被拒绝。
首次请求仍在处理中时重试：请求被拒绝，并提示稍后查询订单。

不传 out_trade_no 时，每次请求都会创建新订单。

响应 data：

字段	类型	说明
`order_no`	string	系统订单号
`energy_amount`	int	能量数量
`period`	string	租赁周期
`receive_address`	string	接收地址
`amount`	int	扣费金额（sun）
`status`	int	订单状态，正常为 `1`（处理中），见订单状态码
`out_trade_no`	string	你方订单号
`created_at`	string	创建时间（RFC 3339）

{
  "code": 200,
  "message": "success",
  "data": {
    "order_no": "E20260928103000a1b2c3d4",
    "energy_amount": 65000,
    "period": "1H",
    "receive_address": "TXk8rQSAvPvBBNtqSoY6nCfsXWCSSpTVQF",
    "amount": 1885000,
    "status": 1,
    "out_trade_no": "ORDER-10001",
    "created_at": "2026-09-28T10:30:00+08:00"
  }
}

如果下单失败，响应为 code: 500，费用会退回账户余额，且不会发送回调。

查询订单

POST /api/open/order/query · 权限 query

传 order_no 或 out_trade_no 之一；两者都传时以 order_no 为准。

参数	类型	必填	说明
`order_no`	string	二选一	系统订单号
`out_trade_no`	string	二选一	你方订单号

响应 data：

字段	类型	说明
`order_no`	string	系统订单号
`energy_amount`	int	能量数量
`period`	string	租赁周期
`receive_address`	string	接收地址
`status`	int	订单状态
`amount`	int	扣费金额（sun）
`refund_amount`	int	退款金额（sun）
`out_trade_no`	string	你方订单号
`api_name`	string	本次请求所用 API Key 的名称
`details`	array \| null	委托记录，按时间倒序；暂无记录时为 `null`
`created_at`	string	创建时间（RFC 3339）
`updated_at`	string	更新时间（RFC 3339）

details 中每一项：

字段	类型	说明
`txid`	string	委托交易哈希（委托完成前为空）
`energy_amount`	int	能量数量
`amount`	int	费用（sun）
`status`	int	`0` 等待结果、`1` 成功、`2` 失败、`3` 已退款
`created_at`	string	提交时间（RFC 3339）

预估价格

POST /api/open/price · 权限 price

参数	类型	必填	说明
`period`	string	是	`1H`、`1D`、`3D` 或 `30D`
`energy_amount`	int	是	能量数量

响应 data：

字段	类型	说明
`period`	string	租赁周期
`energy_amount`	int	能量数量
`price`	int	单价：`1H` 为 sun / 能量，按天的周期为 sun / 能量 / 天
`days`	int	计费天数：`1H` 为 `1`，其余为天数
`total_price`	int	`price × energy_amount × days` 加小额手续费（sun），即下单时的实际扣费金额
`addition`	int	小额手续费（sun）；`energy_amount` 不低于 `small_amount` 时为 `0`

市场数据

POST /api/open/market · 权限 price · 无需请求参数

响应 data：

字段	类型	说明
`tiered_pricing`	array	`[{ "period": "1H", "price": 29 }, ...]`。`1H` 单位为 sun / 能量；`1D`/`3D`/`30D` 为 sun / 能量 / 天（3 天的订单总价 = `price × 能量 × 3`）
`minimum_order_energy`	int	单笔最小能量
`maximum_order_energy`	int	单笔最大能量
`small_amount`	int	低于该能量的订单收取小额手续费
`small_addition`	number	小额手续费（TRX）
`usdt_energy_need_old`	int	向已持有 USDT 的地址转一笔 USDT 所需能量
`usdt_energy_need_new`	int	向从未持有 USDT 的地址转一笔 USDT 所需能量
`burn_rate`	int	不使用能量、直接燃烧 TRX 的成本（sun / 能量）

账户余额

POST /api/open/balance · 权限 balance · 无需请求参数

{ "code": 200, "message": "success", "data": { "balance": 150000000 } }

balance 单位为 sun（150,000,000 sun = 150 TRX）。

回调通知

订单进入最终状态（已完成 2 或失败 3）时，系统会向订单的 callback_url 发送 POST 请求，请求体为 JSON：

{
  "order_no": "E20260928103000a1b2c3d4",
  "out_trade_no": "ORDER-10001",
  "energy_amount": 65000,
  "period": "1H",
  "receive_address": "TXk8rQSAvPvBBNtqSoY6nCfsXWCSSpTVQF",
  "status": 2,
  "amount": 1885000,
  "refund_amount": 0
}

回调验签

回调携带 API-KEY、TIMESTAMP、SIGNATURE 请求头，签名方式与请求签名相同。请在解析 JSON 之前，使用原始请求体验签：

expected = hmac.new(API_SECRET.encode(), f"{timestamp}&{raw_body}".encode(), hashlib.sha256).hexdigest()
valid = hmac.compare_digest(expected, signature)

回调使用下单时所用 Key 的 Secret 签名；如果该 Key 已被禁用，则使用你最近创建的已启用 Key。如果没有任何已启用的 Key，回调不带签名请求头，请视为未验证，并通过查询订单确认。

投递规则

请返回 HTTP 200 表示接收成功，其他状态码（包括 201、204）均视为失败。
每次请求超时时间为 10 秒，最多共尝试 3 次，每次间隔几秒。
回调可能重复送达，也可能最终未送达。请保证处理逻辑幂等，并通过查询订单核对未确认的订单。

订单状态码

status	含义
`0`	待处理：已创建，尚未提交
`1`	处理中：已提交，等待委托
`2`	已完成：能量已委托
`3`	失败：费用已退回账户余额（见 `refund_amount`）
`4`	已退款（预留）