怎样通过 API 自动化 TRON 能量租赁
为什么要把能量租赁自动化
如果你跑着一个热钱包、一个交易所提币引擎,或者一份替用户触发 TRC-20 转账的合约,你应该已经体会过这种痛:交易一发出去,TRON 能量就得立刻到位。通过界面手动补能量,每天几笔转账还能凑合,量一上来就完全跟不上;错过窗口,交易就改为消耗发送地址里的 TRX,成本通常远高于提前租好的能量。
解决办法是在后端即将广播交易的那一刻调用租赁 API,让能量程序化地到位,全程不需要人工介入。
这个 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 请求,带 query 参数。认证通过 apiKey query 参数完成,注册并给账户充值后,在仪表板生成。没有基于请求头的认证,也没有 JSON 请求体。
参数如下:
apiKey(必填):仪表板里拿到的 API 密钥。period(必填):租期,1h、1d、3d、30d之一。energyAmount(必填):要委托的能量数量,最小15000。发给已持有 USDT 的收款方的标准 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。
错误处理
生产环境最常见的三种失败。下面的错误码都来自真实的 API,可以放心按它们分支。
INSUFFICIENT_BALANCE:预付余额不够付这次租赁和可能的预激活费。不要重试,重试解决不了问题;专门捕获它,触发告警或充值流程,并把requestId带进告警内容。INVALID_ADDRESS:destinationAddress在服务端 base58check 解码失败。如果地址是动态构造的(比如来自用户输入),调用 API 之前先在本地校验。Python 库tronpy提供了is_address(),在客户端直接拒掉错误输入,比等一次往返快得多。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 里看着一切正常、链上却出了别的状况,这道额外检查能帮你省下几小时排查。