波场指南

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

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

用PHP购买波场能量最快的方式是TronSave官方SDK:composer require tronsave/sdk,用API key创建客户端,估算费用,下单,然后轮询订单直到100%。四次类型化调用,无需手写HTTP请求,也无需自己实现重试循环。本指南涵盖完整集成:安装、默认值、错误处理,以及订单实际如何付款。

为什么PHP后端需要它

相当大一部分商户网站运行在PHP上——WooCommerce商店、Laravel支付服务、自建计费后台。一旦其中某个系统开始在波场(TRON)上支付或接收USDT(TRC-20),就会遇到和所有人一样的算术题:每笔转账都消耗能量,而缺少的能量要按协议费率燃烧TRX来支付。因此一笔稳定币付款大约要燃烧6.43 TRX,若收款方从未持有过USDT则约为13.03 TRX(截至2026年11月)。

在批量付款前临时租赁能量,通常只需燃烧费用的一小部分。用代码来做,服务就能自动补充能量——不用有人凌晨3点盯着面板,也不会因为某个钱包余额耗尽而让整批任务卡住。如果想先了解接口层面的细节,请阅读我们的API自动化指南;本文是同一流程,只是用PHP类型代替原始请求。

PHP后端通过TronSave SDK购买波场能量时所用的能量市场
SDK下单的能量市场与网页界面使用的是同一个。来源:TronSave

什么是TronSave PHP SDK?

它是TronSave v2 API的官方PHP客户端,以tronsave/sdk发布在Packagist上(版本2.0.0,MIT许可,PHP 8.1+)。与之并列的还有TypeScript、Python、Java和Rust的官方SDK——它们封装相同的接口、行为一致,并由一套跨语言共享的一致性测试来验证,而非人工核对。

PHP客户端体积小,但为生产环境而设计:

  • 类型化结果。响应以readonly类返回——UserInfo、EstimateBuyResource、Order、OrderBookLevel——而不是需要靠猜的关联数组。
  • 真正的枚举。ResourceType、PriceTier、OrderType、OrderStatus和Network都是PHP 8.1的backed enum,拼写错误会在调用处直接报致命错误,而不是等服务器返回400。
  • PSR-18传输层。默认使用Guzzle,但可以注入任意PSR-18客户端——如果你的框架已有配置好并接入监控的HTTP栈,这一点很实用。
  • 内置重试与限流。两者默认开启,下文会分别说明。

安装与配置

composer require tronsave/sdk

然后创建客户端。构造函数的每个参数都是可选的命名参数,只需设置你需要的:

use Tronsave\TronsaveClient;
use Tronsave\Network;

$sdk = new TronsaveClient(
    apiKey: getenv('TRONSAVE_API_KEY'),
    network: Network::Testnet,   // Network::Mainnet to go live
    timeoutMs: 30000,            // default
    maxRetries: 3,               // default
);

Network自带基础URL,因此无需在代码里写死主机名:Network::Testnet指向Nile测试API,Network::Mainnet指向生产环境。先在测试网开发(不花真实TRX),再切换枚举即可。

同一个枚举还提供fundAddress(),即预付余额的充值地址。从枚举读取它,而不是把字符串粘贴进配置,是更安全的习惯——从聊天消息或搜索结果中复制的充值地址,是丢失充值款的典型原因。

完整的能量购买流程

四次调用。第一次是可选的,但值得接入健康检查。

use Tronsave\TronsaveClient;
use Tronsave\Network;

$sdk = new TronsaveClient(apiKey: getenv('TRONSAVE_API_KEY'), network: Network::Mainnet);

// 1. Who am I, and can I afford this run?
$me = $sdk->getUserInfo();
// $me->id, $me->balance, $me->representAddress, $me->depositAddress

// 2. What will it cost? (no API key required for this call)
$est = $sdk->estimateBuyResource([
    'receiver'       => 'TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM',
    'resourceType'   => 'ENERGY',
    'resourceAmount' => 65000,
    'durationSec'    => 3600,
]);
// $est->estimateTrx, $est->unitPrice, $est->durationSec, $est->availableResource

// 3. Place the order.
$order = $sdk->buyResource(
    ['receiver' => 'TFwUFWr3QV376677Z8VWXxGUAMFSrq1MbM', 'resourceAmount' => 65000, 'durationSec' => 3600],
    ['allowPartialFill' => true, 'maxPriceAccepted' => 100],
);

// 4. Poll until the energy is actually delegated.
$status = $sdk->getOrder($order->orderId);
echo $status->fulfilledPercent;   // 100 = fully delegated
echo $status->remainAmount;       // 0 when nothing is left to fill
foreach ($status->delegates as $d) {
    // $d->delegator, $d->amount, $d->txid
}

这段代码里有两个细节很有价值。estimateBuyResource无需认证——在拿到key之前就能询价,而热路径上的询价调用永远不会因认证而消耗限流额度。另外,buyResource的第二个参数是选项数组:allowPartialFill允许订单由多个供应方成交,而不必等待单个大供应方;maxPriceAccepted是你按每单位SUN计的价格上限,它决定了集成是稳健的,还是会在价格飙升时多付钱。

buyResource返回时订单并未完成——它返回的是orderId。代理会在几秒后到账。请轮询getOrder,直到fulfilledPercent达到100,再广播需要这些能量的转账。

需要了解的默认值与限制

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

64,000的最低量在客户端强制校验:数量不足的订单会在发出HTTP请求之前就抛出异常,因此有缺陷的循环不会一遍遍撞上同一个拒绝而耗尽限流额度。限流器同样在客户端运行——它主动控制你的调用节奏,而不是等服务器返回429。

经得起生产环境考验的错误处理

每种失败都是继承自Tronsave\TronsaveException的类型化异常,带有->code、->status和->raw:

异常 何时 如何处理
TronsaveAuthException 401 修正key,切勿重试。
TronsaveValidationException 400,参数错误 修正调用,切勿重试。
TronsaveBusinessException 400,因业务原因被拒 读取->code并分支处理。
TronsaveRateLimitException 429 等待->retryAfterMs后再试。
TronsaveNetworkException 传输失败 可以安全重试。
use Tronsave\{TronsaveBusinessException, TronsaveRateLimitException};

try {
    $order = $sdk->buyResource(['receiver' => $addr, 'resourceAmount' => 65000]);
} catch (TronsaveRateLimitException $e) {
    usleep($e->retryAfterMs * 1000);
} catch (TronsaveBusinessException $e) {
    $log->warning('order rejected', ['code' => $e->code, 'raw' => $e->raw]);
}

这种划分很重要,因为它无需猜测就告诉你哪些可以重试。SDK已经替你重试了临时性错误——408、425、429、500、502、503和504——采用指数退避加抖动,并在服务器发送Retry-After头时遵循它。到达你catch块的错误都已重试过,所以上面这些异常才是你的代码真正需要决策的。

订单如何付款

有两种付款方式,SDK会根据你传入的参数来选择:

  • 预付余额(推荐服务器使用)。调用buyResource时不传signedTx,订单会用你的API key认证,并从TronSave余额中结算。你的TRON私钥完全不接触集成代码——这正是Web服务器所需要的。
  • 每笔订单链上付款。传入你自己构建并签名的signedTx,订单将由该交易付款。

客户端还提供getSignedTransaction(),在服务器端签名。它自己的docblock就建议优先本地签名,你应当照做:这个调用会通过网络发送私钥。对PHP后端来说,预付余额方式更简单也更安全——用它就好。

延期而不是重新购买

如果已有的能量代理即将到期,延期比重新下单更便宜。用接收地址和extendTo Unix时间戳调用getExtendableDelegates();它会返回isAbleToExtend、totalEstimateTrx,以及可直接传给extendRequest()的extendData数据。注意第一个调用有更严格的每秒1次限制——这是SDK唯一限流更严的接口。

我们的Extend功能指南说明了何时延期比重新购买更划算。

常见问题(FAQ)

需要什么版本的PHP?

PHP 8.1或更高版本。SDK依赖backed enum、readonly属性和命名参数,这些特性都在PHP 8.0和8.1中引入。

必须使用Guzzle吗?

Guzzle是默认值,开箱即用。但传输层基于PSR-18,可以注入任何兼容的客户端——如果你的应用已经配置了带日志、代理或超时策略的客户端,这会很方便。

能否不花真实TRX进行测试?

可以。用Network::Testnet创建客户端,就会连接到Nile测试网和独立的API主机,那里不花真钱。上线时只需切换这一个枚举值。

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

收款方已持有USDT时约65,000,从未持有过时约130,000——详见一笔USDT转账需要多少能量。注意最低订单量是大于64,000,所以65,000是实际可下的最小能量订单。

PHP SDK是否落后于TypeScript版本?

不会。五个客户端都对接同一版本的v2 API,并须通过共享的一致性测试,因此各语言之间的行为不会出现偏差。如果你使用多种语言,TypeScript、Java和Rust SDK指南描述的是同一流程。

订单只部分成交会怎样?

启用allowPartialFill后,你会得到市场能提供的数量,fulfilledPercent会显示成交比例。在广播依赖这些能量的交易前先检查它——部分成交的订单可能不足以覆盖你的转账。

总结

如果你的PHP服务在波场上转移USDT,能量就是一项持续成本,最高可节省80%,而SDK让这件事变成四次调用的集成,而不是一个项目。安装SDK,无需key即可询价,用预付余额购买以免私钥接触Web服务器,并在发送前轮询到100%。

TronSave SDK由本博客的发布方TronSave发布。本文所述的包版本、默认值和限制基于v2.0.0,后续版本可能变化——锁定版本前请查阅官方SDK文档。本文不构成投资建议。

TronSave
TronSave

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

相关文章

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