如果你的应用、交易所或机器人需要大规模发送 USDT(TRC-20),就不应该再手动购买能量。官方 TronSave SDK 让你直接在后端预估、购买、续期和跟踪能量订单,支持 Node.js、Python、Rust、Java 和 PHP。本指南带你从安装一路走到第一笔链上能量订单。
SDK 一览
所有 SDK 都基于 v2 API,封装的是同一组接口,因此每种语言提供的操作完全相同:
| 语言 | 包名 | 安装 | 环境要求 |
|---|---|---|---|
| TypeScript / JS | tronsave-sdk |
npm install tronsave-sdk |
Node.js 18+ |
| Python | tronsave |
pip install tronsave |
Python 3.9+ |
| Rust | tronsave |
cargo add tronsave |
— |
| Java | io.tronsave:sdk |
Maven / Gradle | — |
| PHP | tronsave/sdk |
composer require tronsave/sdk |
PHP 8.1+ |
Rust、Python、Java 和 PHP 的包版本均为 2.0.0。Java 的坐标是 io.tronsave:sdk:2.0.0:在 pom.xml 中添加为依赖,或在 build.gradle 中写成 implementation 'io.tronsave:sdk:2.0.0'。
每个 SDK 都包含哪些功能
接口刻意保持精简。无论选择哪种语言,你都会得到同样的七个操作:
- Estimate Buy Resource:下单前先预估购买价格。
- Buy Resource:下单购买能量或带宽,返回订单 ID。
- Get Order / Get Orders:查询单个订单状态或订单历史。
- Get Order Book:按价格档位读取实时供应,最便宜的排在最前。
- Get User Info:内部账户余额和充值地址。
- Get Extendable Delegates:列出可以续期的代理。
- Extend Request:续期已有的代理,而不是重新购买新订单。
最后这两个操作比看上去更重要。如果接收地址已经有代理的能量,你只是需要它持续更久,那么续期才是正确的做法,详见 Extend 续期功能指南。
快速上手(Node.js)
最快的方式是 API Key 流程:创建 SDK 实例、预估费用,然后下单。在 TronSave 控制台获取 API Key(参见身份验证)。
import { TronsaveSDK } from "tronsave-sdk";
const main = async () => {
const sdk = new TronsaveSDK({ network: "mainnet", apiKey: "your_api_key" });
const userInfo = await sdk.getUserInfo();
// Estimate cost for 65,000 ENERGY for 1 hour (one USDT transfer)
const estimate = await sdk.estimateBuyResource({
receiver: "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
resourceType: "ENERGY",
durationSec: 3600,
resourceAmount: 65000,
});
if (estimate.estimateTrx > Number(userInfo.balance)) throw new Error("Insufficient balance");
const { orderId } = await sdk.buyResource({
receiver: "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
resourceType: "ENERGY",
durationSec: 3600,
resourceAmount: 65000,
});
await new Promise((r) => setTimeout(r, 5000)); // wait ~5s to fill
const order = await sdk.getOrder(orderId);
console.log(order.fulfilledPercent < 100 ? "Not filled" : "Filled");
};
main();
提示:开发时使用 network: "testnet"(Nile),无需真实 TRX;上线时再切换到 "mainnet"。
运行前有两个细节值得了解。userInfo.balance 以 SUN 为单位、以字符串形式返回(1 TRX = 1,000,000 SUN),所以比较时要先转换类型。另外 durationSec 是可选参数:不填时订单默认时长为 259,200 秒,即 3 天。
用 Python 完成同样的任务
Python 包通过 pip install tronsave 安装,提供同样的“预估 → 购买 → 跟踪”流程;各语言的方法签名见 SDK 参考文档。如果你想清楚看到底层到底发出了哪些 HTTP 请求,下面是直接调用 v2 接口完成的同一任务(预估、购买、轮询):
import time, requests
API = "https://api.tronsave.io" # testnet: https://api-dev.tronsave.io
HEADERS = {"apikey": "your_api_key", "Content-Type": "application/json"}
ORDER = {
"receiver": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"resourceType": "ENERGY",
"resourceAmount": 65000,
"durationSec": 3600,
"unitPrice": "MEDIUM",
}
estimate = requests.post(f"{API}/v2/estimate-buy-resource", json=ORDER).json()["data"]
print(estimate["estimateTrx"] / 1e6, "TRX", estimate["availableResource"], "available")
order = requests.post(f"{API}/v2/buy-resource", headers=HEADERS,
json={**ORDER, "options": {"allowPartialFill": True,
"maxPriceAccepted": 100}}).json()
order_id = order["data"]["orderId"]
time.sleep(5)
detail = requests.get(f"{API}/v2/order/{order_id}", headers=HEADERS).json()["data"]
print("Filled" if detail["fulfilledPercent"] == 100 else "Not filled")
同样的三步、同样的字段名、同样的响应结构。SDK 的价值在于类型和重试,而不是另一套 API,所以按你的技术栈选择即可。包含订单簿用量计算和错误分支的完整 Python 脚本,请看如何用 Python 购买波场能量。
购买前先预估
预估接口值得单独说明,因为它的响应会告诉你两件不同的事。estimateTrx 是以 SUN 计的费用。availableResource 是市场此刻实际能提供的数量。如果 availableResource 小于你请求的 resourceAmount,订单当下就无法完全成交,这时由你通过 options 决定如何处理:allowPartialFill: true 表示接受现有的量,onlyCreateWhenFulfilled: true 表示不能完全成交就不下单。对于频繁重试的机器人,preventDuplicateIncompleteOrders: true 可以防止重复调用堆积相同的未完成订单。
错误与限制
接口限速为每秒 15 次请求;超出后返回 HTTP 429 和 "Rate limit reached",用简单的 1 秒/2 秒/4 秒退避重试即可。应用错误以 error: true 返回,message 中带有机器可读的错误码,如 INVALID_API_KEY、INTERNAL_BALANCE_ACCOUNT_TOO_LOW、PRICE_EXCEED_MAX_PRICE_REQUIRED、CANNOT_FULFILLED。请根据错误码分支处理,提示文字可能会变。
用 AI 智能体驱动 TronSave
如果你的集成是智能体而不是服务,TronSave 还提供 MCP 服务器,地址为 https://mcp.tronsave.io/mcp,使用 Streamable HTTP 传输(测试网为 https://mcp.tronsave.io/testnet/mcp)。它提供 53 个 MCP 工具(服务器版本 1.3.0,2026年11月),包括 tronsave_estimate_buy_resource、tronsave_list_order_books、tronsave_internal_order_create 等,支持 API Key 或钱包签名会话。将任意兼容 MCP 的客户端指向该地址即可;我们的 TronSave MCP 服务器指南介绍了登录方式、两类工具和安全模型。
更喜欢直接用 HTTP?SDK 封装的就是 API 的同一组接口,参见我们的 API 自动化指南、TronSave 订单类型详解,以及面向大交易量的批量购买能量。
常见问题(FAQ)
需要 API Key 吗?
API Key 流程最简单;你也可以用私钥签名。在控制台获取 Key。区别在于资金托管:API Key 从预先充值的 TronSave 内部账户扣款,而签名交易流程每次购买都从你自己的钱包付款,并且需要 TronWeb。
支持哪些语言?
Node.js/TypeScript、Python、Rust、Java 和 PHP,全部基于 v2 API。各语言的详细教程:Python、Java、PHP 和 Rust。
一笔 USDT 转账需要多少能量?
约 65,000(如果收款地址从未持有过 USDT,则约 130,000)。详见一笔 USDT 转账需要多少能量。
能否不花真实 TRX 进行测试?
可以。设置 network: "testnet"(或把基础 URL 指向 https://api-dev.tronsave.io)即可在 Nile 上运行。各环境的 Key、余额和订单相互独立,因此请在 testnet.tronsave.io 申请 Nile 的 Key,主网 Key 会被拒绝。不支持 Shasta。
开始开发:阅读 TronSave 文档,并在市场控制台获取 API Key。
Python 开发者?请看专门的教程:如何用 Python 购买波场能量(完整可运行脚本)。


