如果你的 Python 后端需要发送 USDT(TRC-20)——无论是机器人、交易所还是支付服务——你会希望用 Python 自动购买波场(TRON)能量,而不是手动操作。本文提供一个基于 TronSave API 的完整可运行示例:查询余额、下单购买能量,并轮询直到能量到账。
开始之前
- 在 TronSave 控制台获取 API 密钥(它从你的 TronSave 内部余额中扣费——切勿在客户端暴露)。
- 安装 HTTP 客户端:
pip install requests。更喜欢带类型的封装?可以改用官方 SDK:pip install tronsave——详见 SDK 概览。 - 为内部账户充值。每笔最低充值 10 TRX,首次充值需额外约 1 TRX 用于激活新地址。余额约 3 秒后更新。
接口说明
脚本使用四个 v2 接口,通过 apikey 请求头进行认证:
GET /v2/user-info——内部账户余额。GET /v2/order-book——可用流动性与价格。POST /v2/buy-resource——下单,返回orderId。GET /v2/order/{orderId}——轮询直到fulfilledPercent达到 100。
每个接口的速率限制均为每秒 15 次请求,且返回相同的结构:error、message 和一个 data 对象。解析逻辑写一次即可通用。
完整 Python 示例
import time, requests
API_KEY = "your_api_key"
TRONSAVE_API_URL = "https://api.tronsave.io" # testnet: https://api-dev.tronsave.io
RECEIVER_ADDRESS = "your_receiver_address"
BUY_AMOUNT = 65000 # ~1 USDT (TRC-20) transfer
DURATION = 3600 # rental duration, in seconds (1 hour)
MAX_PRICE_ACCEPTED = 100 # max price in SUN per unit
RESOURCE_TYPE = "ENERGY" # ENERGY or BANDWIDTH
HEADERS = {"apikey": API_KEY}
def get_account_info():
return requests.get(f"{TRONSAVE_API_URL}/v2/user-info", headers=HEADERS).json()
def get_order_book():
return requests.get(f"{TRONSAVE_API_URL}/v2/order-book",
headers=HEADERS,
params={"address": RECEIVER_ADDRESS}).json()
def buy_resource():
body = {
"resourceType": RESOURCE_TYPE,
"unitPrice": "MEDIUM", # a price in SUN, or SLOW / MEDIUM / FAST
"resourceAmount": BUY_AMOUNT,
"receiver": RECEIVER_ADDRESS,
"durationSec": DURATION,
"options": {
"allowPartialFill": True,
"maxPriceAccepted": MAX_PRICE_ACCEPTED,
"preventDuplicateIncompleteOrders": True,
},
}
return requests.post(f"{TRONSAVE_API_URL}/v2/buy-resource",
headers={**HEADERS, "Content-Type": "application/json"},
json=body).json()
def get_order(order_id):
return requests.get(f"{TRONSAVE_API_URL}/v2/order/{order_id}", headers=HEADERS).json()
def main():
print(get_order_book()["data"]) # [{"price": 54, "availableResourceAmount": 2403704}, ...]
balance = int(get_account_info()["data"]["balance"])
if balance < MAX_PRICE_ACCEPTED * BUY_AMOUNT:
raise SystemExit("Insufficient TronSave balance")
order = buy_resource()
if order["error"]:
raise SystemExit(f"Buy failed: {order['message']}")
order_id = order["data"]["orderId"]
while True: # poll until the energy is delivered
time.sleep(3)
detail = get_order(order_id)["data"]
if detail["fulfilledPercent"] == 100 or detail["remainAmount"] == 0:
print(f"Energy delivered - paid {detail['payoutAmount'] / 1e6} TRX")
for d in detail["delegates"]:
print(d["delegator"], d["amount"], d["txid"])
break
print(f"Waiting for fill... {detail['fulfilledPercent']}%")
if __name__ == "__main__":
main()
工作原理
- 先查看市场。
get_order_book()返回一组{price, availableResourceAmount}价格档位,最便宜的供应排在最前。如果你需要 500,000 能量,而最便宜的两档合计只有 300,000,那么成交价由第三档决定。这就是为什么在市场繁忙时,硬编码过低的maxPriceAccepted会悄无声息地失败。 - 检查余额。
get_account_info()返回balance、depositAddress和representAddress——数值单位均为 SUN,且为字符串,需要先转换类型。1 TRX = 1,000,000 SUN,返回"50000000"即 50 TRX。 - 下单。
buy_resource()向/v2/buy-resource发送请求。设置好API_KEY、RECEIVER_ADDRESS以及要购买的能量数量——65,000 足够一笔 USDT 转账,向首次接收的地址转账约需 130,000(参见 一笔 USDT 转账需要多少能量)。若省略durationSec,默认为 259,200(3 天)。成功后只会返回一个orderId,这是正常的。 - 轮询成交状态。
get_order()返回实时订单信息:fulfilledPercent(0 = 待成交,1–99 = 部分成交,100 = 全部完成)、remainAmount、实际支付的price(SUN)、payoutAmount(SUN),以及delegates数组,其中包含每笔匹配的提供方地址、数量和链上txid。请记录这些 txid——它们就是你的凭证,可在 Tronscan 上核验。
如何选择 unitPrice
unitPrice 可以是以 SUN 计的整数价格,也可以是三个档位之一。这些档位基于实时订单簿计算,而非固定加价:
| 取值 | 行为 | 适用场景 |
|---|---|---|
"SLOW" |
订单可设置的最低价格 | 不赶时间,省钱比速度更重要 |
"MEDIUM" |
默认值。能获得最大市场成交量的最低价格;若市场完全无法成交,MEDIUM = SLOW + 10 | 绝大多数情况 |
"FAST" |
若市场 100% 就绪,FAST = MEDIUM;低于该水平时为 MEDIUM + 10;就绪度为 0% 时为 SLOW + 20 | 转账必须立即发出 |
80(数字) |
以 SUN 计的固定价格,完全自主控制 | 你自己根据订单簿定价 |
处理实际会遇到的错误
非 2xx 响应会返回 error: true,并在 message 中包含错误码,例如 TSAS:106 API_KEY_REQUIRED。请根据错误码而不是描述文字进行分支处理——文字可能会变。Python 机器人在生产环境中常见的错误有:
INTERNAL_BALANCE_ACCOUNT_TOO_LOW——为内部账户充值。最好在余额不足之前就设置告警,而不是事后补救。PRICE_EXCEED_MAX_PRICE_REQUIRED——市场价格已高于你的maxPriceAccepted。重新读取订单簿并以更高上限重试,或者等待。CANNOT_FULFILLED——你设置了onlyCreateWhenFulfilled: true,而市场当前无法 100% 成交。去掉该参数或启用allowPartialFill。MUST_BE_WAIT_PREVIOUS_ORDER_FILLED——在之前的订单尚未完成时,你提交了相同参数的订单。这正是preventDuplicateIncompleteOrders: true在发挥作用,它能防止重试循环重复购买。429 RATE_LIMIT——采用指数退避(1 秒、2 秒、4 秒),并保持在每秒 15 次请求以内。
参数校验失败的表现不同:它们来自 HTTP 层,错误为 FST_ERR_VALIDATION,并会指出缺失的字段,例如 "body must have required property 'receiver'"。这在开发阶段很有用,它说明代码有 bug,而不是市场状况问题。
测试网与主网
开发时使用测试网 https://api-dev.tronsave.io(Nile,无需真实 TRX),上线时切换到 https://api.tronsave.io。只需更换域名——所有路径完全相同,因此只要修改一个 TRONSAVE_API_URL 常量即可。
将钱包切换到 Nile 网络后,在 testnet.tronsave.io 获取 Nile 密钥,再通过 Nile 水龙头充值。需要提前注意:两个环境的 API 密钥、余额和订单完全独立。主网密钥请求测试网地址会返回 INVALID_API_KEY,这是正确行为,但深夜排查时很容易让人困惑。TronSave 不支持 Shasta,请使用 Nile。
使用其他语言开发?同样的流程也提供 Node.js、Rust、Java 和 PHP 版 SDK,另有通用的 API 自动化指南。如果你完全不想运行轮询循环,Auto-Buy 会在你设定的阈值下为监控地址自动补充能量。完整参考请见 TronSave 文档。
常见问题
需要 TronWeb 吗?
上述 API 密钥流程不需要——普通的 requests 就够了。只有在使用私钥直接签名并付款(即签名交易流程)时才需要 TronWeb。
每笔 USDT 转账需要多少能量?
约 65,000(向从未持有过 USDT 的钱包转账约需 130,000)。
付款从哪里扣除?
从你预充值的 TronSave 余额中扣除,可在控制台充值。每笔订单都无需链上签名,所以脚本不需要私钥。
如果订单只部分成交怎么办?
设置 allowPartialFill: true 后,你会获得市场能匹配的全部数量,fulfilledPercent 介于 1 到 99 之间,并且只按已匹配部分计费。可以根据 remainAmount 循环,为差额追加下单;或设置 onlyCreateWhenFulfilled: true,使订单仅在能全部完成时才会创建。
开始构建:在 TronSave 市场获取 API 密钥,并阅读开发者文档。


