用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类型代替原始请求。

什么是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%。
开始集成:运行composer require tronsave/sdk,在TronSave控制台获取key,然后在实时能量市场为你的第一笔订单询价。
TronSave SDK由本博客的发布方TronSave发布。本文所述的包版本、默认值和限制基于v2.0.0,后续版本可能变化——锁定版本前请查阅官方SDK文档。本文不构成投资建议。


