怎样通过 API 自动化 TRON 能量租赁

2026-05-13

为什么要把能量租赁自动化

如果你跑着一个热钱包、一个交易所提币引擎,或者一份替用户触发 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,可以放心按它们分支。

  1. INSUFFICIENT_BALANCE:预付余额不够付这次租赁和可能的预激活费。不要重试,重试解决不了问题;专门捕获它,触发告警或充值流程,并把 requestId 带进告警内容。
  2. INVALID_ADDRESS:destinationAddress 在服务端 base58check 解码失败。如果地址是动态构造的(比如来自用户输入),调用 API 之前先在本地校验。Python 库 tronpy 提供了 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 交易费用?立即查看能量价格。 价格估算
返回博客