波场指南

如何用 Rust 购买波场能量:TronSave SDK 指南(2026)

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

在 Rust 中购买波场能量最快的方式是使用 TronSave 官方 crate:添加 tronsave = "2",创建客户端,然后估价、下单、轮询。只需四次 await 调用,得到一个真正可以 match 的类型化错误,重试和限流也已内置处理。本指南涵盖完整集成:安装、默认值、文档化的错误码,以及订单如何支付。

为什么 Rust 服务需要关心能量

Rust 恰恰出现在大规模转移稳定币的地方:交易所后端、支付处理商、托管服务、高吞吐量机器人。它们在波场(TRON)上都面临同一笔账:每笔 USDT(TRC-20)转账都会消耗能量,而你没有持有的能量要按协议费率燃烧TRX来支付。按每单位能量 100 sun 计算,一笔标准转账约需 6.43 TRX(截至2026年11月),而且每次发送都要再付一次。

在批量付款前临时租赁能量比燃烧TRX更便宜(2026年10月28日的数据:租赁一小时约便宜三分之一,租赁 30 天按每笔转账计约便宜 59%),而在代码中完成这一步,服务就能自动补充能量,无需人工值守。如果你想先了解接口层面的细节,请阅读我们的API 自动化指南;本文是同一流程的 Rust 类型与 async 版本。

Rust 服务通过 TronSave SDK 购买波场能量所使用的能量市场
SDK 下单使用的是与网页界面相同的能量市场。来源:TronSave

什么是 TronSave Rust SDK?

它是 TronSave v2 API 的官方异步 Rust 客户端,以 tronsave 之名发布在 crates.io(版本 2.0.0,MIT 许可,edition 2021,MSRV 1.75)。生成的 API 参考文档位于 docs.rs。它是五个官方客户端之一(TypeScript、Python、Java、PHP 和 Rust),全部封装相同的接口,并遵循同一套跨语言一致性测试,因此各客户端之间的行为不会出现偏差。

这个 crate 刻意保持轻量:

  • 基于 tokio 的异步实现,构建于 reqwest 和 serde 之上。每个调用都是返回 tronsave::Result<T> 的 async fn。
  • 使用 rustls,而非 OpenSSL。reqwest 以 default-features = false 和 rustls-tls 特性引入,无需链接系统 OpenSSL——这正是 musl、Alpine 或 distroless 容器所需要的。
  • 类型化 DTO。UserInfo、EstimateBuyResource、Order、Delegate、OrderBookLevel 都是普通的 serde 结构体,camelCase 映射已为你处理好。
  • 依赖树小。reqwest、serde、serde_json、thiserror、fastrand 和 tokio(仅 time 与 sync 特性)。

安装

[dependencies]
tronsave = "2"
tokio = { version = "1", features = ["full"] }

然后在环境中设置 TRONSAVE_API_KEY。Network::Testnet 让客户端连接 Nile 测试 API,不消耗真实 TRX;Network::Mainnet 则用于主网。两者都通过 Network::base_url() 解析各自的基础 URL,因此配置中永远不会硬编码主机名。

同一个枚举还提供 fund_address(),即签名交易流程所用的充值地址。从枚举读取地址,而不是把字符串粘贴进配置,是更安全的习惯——从聊天消息或搜索结果中复制的充值地址,是丢失充值资金的常见原因。

完整的能量购买流程

use tronsave::{TronsaveClient, Network, models::BuyParams};

#[tokio::main]
async fn main() -> tronsave::Result<()> {
    let sdk = TronsaveClient::new(
        std::env::var("TRONSAVE_API_KEY").ok(),
        Network::Mainnet,
    )?;

    // 1. Who am I, and can I afford this run?
    let me = sdk.get_user_info().await?;
    println!("balance: {} SUN", me.balance);

    // 2. What will it cost? (no API key needed for this call)
    let est = sdk.estimate_buy_resource(BuyParams {
        receiver: "TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM".into(),
        resource_amount: 65_000,          // ENERGY must be > 64_000
        duration_sec: Some(3600),
        ..Default::default()
    }).await?;
    println!("estimate: {} SUN", est.estimate_trx);

    // 3. Place the order.
    let order = sdk.buy_resource(BuyParams {
        receiver: "TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM".into(),
        resource_amount: 65_000,
        duration_sec: Some(3600),
        ..Default::default()
    }).await?;

    // 4. Poll until the energy is actually delegated.
    let status = sdk.get_order(&order.order_id).await?;
    println!("{}% filled, {} left", status.fulfilled_percent, status.remain_amount);
    for d in &status.delegates {
        println!("  {} sent {} (tx {})", d.delegator, d.amount, d.txid);
    }
    Ok(())
}

其中有三点值得特别说明。

..Default::default() 就是全部的易用性所在。BuyParams 有九个字段,但只有两个是必填;其余都是 Option,未设置时在序列化中会被完全跳过。你只需写明自己要的,其余由默认值补齐。

estimate_buy_resource 无需认证。你可以在拿到密钥之前就为订单估价,而热路径中的估价调用也永远不会消耗你的认证配额。

buy_resource 返回时订单并未完成。它返回一个 order_id;代理会在几秒后到账。请轮询 get_order,直到 fulfilled_percent 达到 100,再广播需要能量的转账——务必检查,因为部分成交可能不够用。

需要了解的默认值与限制

行为 值
默认资源类型 ENERGY
默认价格档位 MEDIUM(另有 FAST、SLOW 或直接指定 SUN 价格)
默认时长 259_200 秒,即 3 天
最低能量订单 必须大于 64,000
客户端限流 每秒 15 次请求;get_extendable_delegates 每秒 1 次
默认超时 / 重试 30,000 毫秒 / 重试 3 次
extend_to 格式 以秒为单位的 Unix 时间戳
默认分页大小 10

64,000 的最低限制在请求离开你的进程之前就会校验,因此错误的循环不会把限流额度浪费在反复遭遇同一个拒绝上。限流器是按接口划分的令牌桶,会主动控制你的调用节奏,而不是等到收到 429 才停下。需要重试时,退避策略是带完全抖动(full jitter)的指数退避:从 300 毫秒开始,每次尝试翻倍,上限 10 秒,再在整个窗口内随机化。最后这一点比听起来更重要:没有抖动的话,一批同时收到 429 的 worker 会同步重试,再次冲垮接口。

遇到 408、425、429、500、502、503 和 504 时会触发重试,若服务器返回 Retry-After 头,也会遵循它。

一种错误类型,六个类别

Rust 没有异常层级,SDK 也不假装有。每个调用都返回 tronsave::Result<T>,唯一的 Error 结构体包含 kind、文档化的 code、HTTP status、retry_after_ms 以及用于调试的 raw 响应体。你可以对它进行 match:

use tronsave::ErrorKind;

match sdk.buy_resource(params).await {
    Ok(order) => tracing::info!(order_id = %order.order_id, "energy ordered"),

    Err(e) if e.kind == ErrorKind::RateLimit => {
        let wait = e.retry_after_ms.unwrap_or(1_000);
        tokio::time::sleep(std::time::Duration::from_millis(wait)).await;
    }

    Err(e) if e.kind == ErrorKind::Business => match e.code.as_str() {
        "INTERNAL_BALANCE_ACCOUNT_TOO_LOW" => top_up_and_alert().await,
        "PRICE_EXCEED_MAX_PRICE_REQUIRED" => skip_until_price_falls(),
        "CANNOT_FULFILLED" => queue_for_retry(),
        _ => tracing::warn!(code = %e.code, "order rejected"),
    },

    Err(e) => tracing::error!(code = %e.code, kind = ?e.kind, status = ?e.status, "buy failed"),
}

kind 告诉你问题的类别,code 告诉你实际发生了什么——与自由文本消息不同,它是文档化的稳定值,在全部五个 SDK 中通用:

类别 错误码 对你的代码意味着什么
Auth API_KEY_REQUIRED、INVALID_API_KEY 修正密钥。切勿重试。
Validation MISSING_PARAMS、INVALID_PARAMS、MIN_PRICE_INVALID 修正调用。切勿重试。
Business INTERNAL_ACCOUNT_NOT_FOUND、INTERNAL_BALANCE_ACCOUNT_TOO_LOW、CANNOT_FULFILLED、MUST_BE_WAIT_PREVIOUS_ORDER_FILLED、PRICE_EXCEED_MAX_PRICE_REQUIRED、SOME_DELEGATE_CANNOT_EXTEND 请求有效但被拒绝。按错误码分支处理。
RateLimit RATE_LIMIT 等待 retry_after_ms。
Network NETWORK_ERROR 传输失败。可以安全重试。
Unknown UNKNOWN 无法识别的响应。记录 raw。

这些业务错误码值得绑定真正的处理逻辑。INTERNAL_BALANCE_ACCOUNT_TOO_LOW 表示需要充值。PRICE_EXCEED_MAX_PRICE_REQUIRED 表示市场价格已超过你设定的上限,应当等待,而不是盲目提高上限。MUST_BE_WAIT_PREVIOUS_ORDER_FILLED 表示你下单的速度快于订单结算的速度。

订单如何支付

客户端会根据你传入的参数选择支付方式:

  • 预付余额(服务器推荐)。将 signed_tx 保持为 None,订单将使用你的 API 密钥认证,并从你的 TronSave 余额中结算。你的波场私钥永远不会进入服务。
  • 每单链上支付。传入你自己构建并签名的 signed_tx,由该交易支付订单。

另外还有一个在服务端签名的辅助方法 get_signed_transaction()。它自己的文档注释就建议优先本地签名,你应当照做——该调用会通过网络发送私钥。对于后端服务,预付余额方式既更简单也更安全。

延期而不是重新购买

当你已持有的代理即将到期时,延期比重新下单更划算。调用 get_extendable_delegates,传入接收地址和 extend_to Unix 时间戳;它会返回 is_able_to_extend、total_estimate_trx 以及可直接传给 extend_request 的 extend_data 数据。注意第一个调用每秒仅限 1 次——这是 SDK 限流最严格的接口。我们的 Extend 功能指南介绍了何时延期是更好的选择。

常见问题(FAQ)

需要哪个 Rust 版本?

1.75 或更高——这是该 crate 声明的 MSRV,使用 edition 2021。

它是否强制使用特定的异步运行时?

它依赖 tokio 实现定时器和同步,因此支持的运行时是 tokio。作为实际依赖引入的只有 time 和 sync 特性;安装示例中的 full 特性只是为了你自己的 #[tokio::main]。

它会把 OpenSSL 带进我的构建吗?

不会。reqwest 配置为 default-features = false 和 rustls-tls,TLS 完全由 Rust 实现。因此在 musl 和 distroless 镜像中使用毫无障碍。

能否在不花费真实 TRX 的情况下测试?

可以——使用 Network::Testnet 创建客户端,即可连接位于独立 API 主机上的 Nile 测试网。上线时只需修改这一个枚举值。

一笔 USDT 转账需要购买多少能量?

如果收款方已持有 USDT,约需 65,000;如果从未持有过,约需 130,000——详见一笔 USDT 转账需要多少能量。由于最低订单必须大于 64,000,65,000 是实际可用的最小能量订单。

Rust 客户端是否落后于其他客户端?

不会。五个 SDK 都以相同版本对接 v2,并共享同一套一致性测试。如果你跨语言开发,TypeScript 指南和 PHP 指南介绍的是同一流程。

总结

如果你的 Rust 服务在波场上转移 USDT,能量就是一项持续成本,用租赁代替燃烧TRX可以大幅降低这项成本,而这个 crate 让它变成四次调用的集成,而不是一个项目。添加依赖,无需密钥即可估价,使用预付余额购买以确保私钥不接触服务,对需要实际处理的情况 match ErrorKind,并在发送前轮询到 100%。

TronSave SDK 由本博客的发布方 TronSave 发布。本文所述的版本、默认值和限制基于 crate 2.0.0,后续版本可能变化——锁定版本前请查看 crates.io 和 docs.rs。本文不构成投资建议。

TronSave
TronSave

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

相关文章

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