波场指南

如何用 Python 购买波场能量(TronSave API,2026)

作者 TronSave 发布于 5 分钟阅读
本页目录

如果你的 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()

工作原理

  1. 先查看市场。get_order_book() 返回一组 {price, availableResourceAmount} 价格档位,最便宜的供应排在最前。如果你需要 500,000 能量,而最便宜的两档合计只有 300,000,那么成交价由第三档决定。这就是为什么在市场繁忙时,硬编码过低的 maxPriceAccepted 会悄无声息地失败。
  2. 检查余额。get_account_info() 返回 balance、depositAddress 和 representAddress——数值单位均为 SUN,且为字符串,需要先转换类型。1 TRX = 1,000,000 SUN,返回 "50000000" 即 50 TRX。
  3. 下单。buy_resource() 向 /v2/buy-resource 发送请求。设置好 API_KEY、RECEIVER_ADDRESS 以及要购买的能量数量——65,000 足够一笔 USDT 转账,向首次接收的地址转账约需 130,000(参见 一笔 USDT 转账需要多少能量)。若省略 durationSec,默认为 259,200(3 天)。成功后只会返回一个 orderId,这是正常的。
  4. 轮询成交状态。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
TronSave

TronSave 团队在 tronsave.io 运营波场能量与带宽市场,这些指南基于在波场主网上的实际测试撰写。

相关文章

我们使用 Google Analytics 了解哪些指南对读者有帮助。只有在您允许分析时才会设置 Cookie。本博客不投放广告。 隐私