PHPackages zhifu/tron-api - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [API Development](/categories/api) 4. / 5. zhifu/tron-api ActiveLibrary[API Development](/categories/api) zhifu/tron-api ============== 增强版波场（TRON）API接口库，提供更完善的功能和更稳定的表现，简化TRON区块链应用开发 v1.2.3(1y ago)5542[2 issues](https://github.com/PandaTwo/tron-api/issues)MITPHPPHP >=7.4 Since Mar 14Pushed 1y ago1 watchersCompare [ Source](https://github.com/PandaTwo/tron-api)[ Packagist](https://packagist.org/packages/zhifu/tron-api)[ RSS](/packages/zhifu-tron-api/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (6)Versions (12)Used By (0) Zhifu Tron API ============== [](#zhifu-tron-api) 基于 iexbase/tron-api 二次开发的增强版波场（TRON）API接口库。提供更完善的功能和更稳定的表现，简化TRON区块链应用开发。 功能特性 ---- [](#功能特性) - **完整的波场API支持** - 支持波场网络上的所有主要操作 - **增强的代币支持** - 全面支持TRC10和TRC20代币操作 - **能量和带宽管理** - 质押TRX获取能量和带宽的完整解决方案 - **高级交易功能** - 支持批量转账、能量估算等高级功能 - **钱包管理工具** - 提供完整的钱包创建、导入和验证功能 - **交易监控机制** - 实现自动充值检测和通知 - **完善的错误处理** - 提供更详细的错误信息和异常处理 - **丰富的示例代码** - 提供多种场景的实际应用示例 - **内存优化管理** - 自动清理缓存，适合高频调用和长时间运行的应用 - **底层库优化** - 自动修补底层库的内存泄漏问题 安装 -- [](#安装) ``` # 标准安装 composer require zhifu/tron-api # 如果安装过程中遇到扩展或PHP版本兼容性问题，可以使用以下命令忽略平台要求 composer require zhifu/tron-api --ignore-platform-reqs ``` ### 底层库内存优化 [](#底层库内存优化) 从v1.0.6版本开始，我们添加了自动修补脚本来解决底层`iexbase/tron-api`库的内存泄漏问题： 1. 安装或更新时会自动修补底层库 2. 如果没有自动修补，可以手动运行修补脚本： ``` php vendor/zhifu/tron-api/scripts/patch-vendor.php ``` 3. 如果仍然遇到内存问题，可以尝试增加PHP内存限制： ``` ini_set('memory_limit', '2G'); ``` 如果遇到依赖问题，有以下几种解决方案： ### GMP扩展问题 [](#gmp扩展问题) #### 方案1：安装GMP扩展（推荐） [](#方案1安装gmp扩展推荐) 这是最佳方案，可以使用所有功能： ``` # Ubuntu/Debian sudo apt-get install php7.4-gmp sudo service apache2 restart # CentOS/RHEL sudo yum install php-gmp sudo systemctl restart httpd # macOS (使用Homebrew) brew install php@7.4-gmp ``` #### 方案2：在项目中绕过GMP扩展检查 [](#方案2在项目中绕过gmp扩展检查) 如果无法安装GMP扩展，可以在项目的`composer.json`中添加如下配置： ``` { "config": { "platform": { "ext-gmp": "1.0.0" } } } ``` ### PHP版本兼容性问题 [](#php版本兼容性问题) 本库支持PHP 7.4及以上版本。对于底层依赖`iexbase/tron-api`，我们兼容3.x, 4.x和5.x版本： - 使用PHP 7.4：会自动选择兼容的3.x或4.x版本 - 使用PHP 8.0+：会优先使用最新的5.x版本 如果安装时遇到PHP版本兼容性问题，可以尝试以下方案： ``` # 方案1：在安装时忽略平台要求（不推荐） composer require zhifu/tron-api --ignore-platform-reqs # 方案2：在项目的composer.json中设置platform配置（推荐） # 在composer.json中添加： { "config": { "platform": { "php": "7.4.33" } } } ``` 注意：方案2会影响所有依赖的安装，确保这符合您的项目需求。 要求 -- [](#要求) 支持以下PHP版本： - PHP 7.4 及以上 - 必须安装BCMath扩展（用于高精度计算） - 使用钱包功能时需要安装GMP扩展（用于私钥生成和地址验证） ### 安装GMP扩展（可选，仅用于钱包功能） [](#安装gmp扩展可选仅用于钱包功能) 如果您需要使用钱包创建、导入和验证功能，则需要安装GMP扩展： 对于Ubuntu/Debian： ``` sudo apt-get install php7.4-gmp sudo service apache2 restart # 或 php-fpm ``` 对于CentOS/RHEL： ``` sudo yum install php-gmp sudo systemctl restart httpd # 或 php-fpm ``` 对于macOS (使用Homebrew)： ``` brew install php@7.4-gmp ``` ### 跳过GMP扩展检查（不推荐） [](#跳过gmp扩展检查不推荐) 如果您确定不会使用钱包功能，可以在composer.json中添加以下配置来绕过GMP扩展检查： ``` { "config": { "platform": { "ext-gmp": "1.0.0" } } } ``` 内存优化和性能管理 --------- [](#内存优化和性能管理) 本库针对高频调用和长时间运行的场景进行了内存优化，特别是TRC20合约操作。 ### 自动缓存清理 [](#自动缓存清理) 从v1.0.5版本开始，TRC20合约转账操作会自动清理不需要的缓存数据： ``` // 无需手动管理缓存，转账后会自动清理 $contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'); $result = $contract->transfer('接收方地址', 10.5); // 此时已自动清理缓存，释放内存 ``` ### 禁用自动清理 [](#禁用自动清理) 在某些特殊场景下，您可能希望禁用自动清理功能： ``` // 禁用自动清理功能 \Zhifu\TronAPI\TRC20Contract::setAutoCleaning(false); // 执行多次操作... // 操作完成后手动清理 \Zhifu\TronAPI\TRC20Contract::clearCache(); ``` ### 分批处理大批量操作 [](#分批处理大批量操作) 对于大批量转账或查询，库已内置分批处理机制： ``` // 批量转账时可以控制每批大小，默认为5 $contract = $tron->contract($usdtContract); $results = $contract->batchTransfer($transfers, 3); // 每批处理3个转账 // 批量查询余额时也可以控制每批大小，默认为20 $balances = $contract->batchBalanceOf($addresses, true, 10); // 每批处理10个地址 ``` ### 长时间运行的应用 [](#长时间运行的应用) 对于长时间运行的脚本或应用（如充值监控服务），建议定期手动清理： ``` // 每处理100个区块后清理一次 if ($blockCount % 100 === 0) { \Zhifu\TronAPI\TRC20Contract::clearCache(); } ``` 基本用法 ---- [](#基本用法) ``` use Zhifu\TronAPI\Tron; // 初始化节点提供者 $fullNode = 'https://api.trongrid.io'; $solidityNode = 'https://api.trongrid.io'; $eventServer = 'https://api.trongrid.io'; try { $tron = new Tron($fullNode, $solidityNode, $eventServer); // 设置地址 $tron->setAddress('您的钱包地址'); // 查询余额（以TRX为单位） $balance = $tron->getBalance(null, true); echo "余额: " . $balance . " TRX\n"; // 查询USDT余额 $usdtBalance = $tron->getUsdtBalance(); echo "USDT余额: " . $usdtBalance . " USDT\n"; } catch (Exception $e) { echo "错误: " . $e->getMessage(); } ``` API密钥支持 ------- [](#api密钥支持) 当使用公共节点进行大量请求时，您可能需要使用API密钥来避免请求限制。 ### 获取API密钥 [](#获取api密钥) 在 [TRON Grid 官网](https://www.trongrid.io/dashboard) 注册账户并获取API密钥。 ### 设置API密钥 [](#设置api密钥) ``` // 在创建Tron实例时设置API密钥 $apiKey = '您的TRON API密钥'; $tron = new Tron($fullNode, $solidityNode, $eventServer, null, $apiKey); // 或者在实例创建后设置 $tron->setApiKey('您的TRON API密钥'); ``` 详细示例请参考 `examples/api_key_demo.php`。 钱包管理 ---- [](#钱包管理) ### 创建新钱包 [](#创建新钱包) ``` // 生成新钱包 $wallet = $tron->generateWallet(); echo "私钥: " . $wallet['privateKey'] . "\n"; echo "地址: " . $wallet['address'] . "\n"; ``` ### 从私钥导入钱包 [](#从私钥导入钱包) ``` // 从私钥获取地址 $privateKey = "您的私钥"; $addressInfo = $tron->getAddressFromPrivateKey($privateKey); echo "地址: " . $addressInfo['address'] . "\n"; ``` ### 验证私钥与地址 [](#验证私钥与地址) ``` // 验证私钥与地址是否匹配 $isValid = $tron->validatePrivateKey($privateKey, '地址'); echo "验证结果: " . ($isValid ? '匹配' : '不匹配') . "\n"; ``` 详细示例请参考 `examples/wallet_demo.php`。 TRC20代币操作 --------- [](#trc20代币操作) ### 查询代币余额 [](#查询代币余额) ``` // 查询USDT余额 $usdtBalance = $tron->getUsdtBalance('钱包地址'); echo "USDT余额: " . $usdtBalance . " USDT\n"; // 查询其他TRC20代币 $tokenContract = '代币合约地址'; $tokenBalance = $tron->getTokenBalance($tokenContract, '钱包地址'); echo "代币余额: " . $tokenBalance . "\n"; ``` ### 转账TRC20代币 [](#转账trc20代币) ``` // 设置发送方地址和私钥 $tron->setAddress('发送方地址'); $tron->setPrivateKey('私钥'); // 获取合约对象 $contract = $tron->contract('代币合约地址'); // 转账 - 自动设置安全的费用限制 $result = $contract->transfer('接收方地址', '金额'); // 检查结果 if (isset($result['result']) && $result['result'] === true) { echo "转账成功，交易ID: " . $result['txid'] . "\n"; } else { echo "转账失败\n"; } ``` 详细转账示例请参考 `examples/transfer_demo.php`。 ### 查询TRC20代币交易历史 [](#查询trc20代币交易历史) ``` // 设置API版本 $tron->setApiVersion('v1'); // 查询USDT交易记录 $usdtContract = 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'; // USDT合约地址 $transactions = $tron->getTrc20TransactionsByAccount( '钱包地址', $usdtContract, 20 // 查询条数 ); // 显示交易记录 foreach ($transactions['data'] as $tx) { echo "交易ID: " . $tx['transaction_id'] . "\n"; echo "金额: " . $tx['value'] . "\n"; } ``` 详细示例请参考 `examples/trc20_transactions_demo.php`。 自动充值检测 ------ [](#自动充值检测) ``` // 已处理的交易ID列表 $processedTxIds = [ // 从数据库中获取已处理的交易ID ]; // 检查是否收到指定金额的USDT付款 $payment = $tron->checkTrc20Payment( '接收地址', 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT合约地址 100.00, // 预期金额 3600000, // 检查最近1小时内的交易 $processedTxIds ); if ($payment) { echo "收到匹配的充值，金额: " . $payment['amount'] . " USDT\n"; } ``` 质押TRX获取资源 --------- [](#质押trx获取资源) 波场网络上的交易需要消耗能量和带宽资源，可以通过质押TRX获取这些资源。 ### 质押获取能量 [](#质押获取能量) ``` // 设置钱包地址和私钥 $tron->setAddress('钱包地址'); $tron->setPrivateKey('私钥'); // 质押10个TRX获取能量 $result = $tron->freezeBalanceForEnergyV2(10); if (isset($result['result']) && $result['result'] === true) { echo "质押成功，交易ID: " . $result['txid'] . "\n"; } else { echo "质押失败\n"; } ``` ### 质押获取带宽 [](#质押获取带宽) ``` // 质押5个TRX获取带宽 $result = $tron->freezeBalanceForBandwidthV2(5); ``` ### 解除质押 [](#解除质押) ``` // 解除质押 (10 TRX, 能量) $result = $tron->unfreezeBalanceV2(10, 1); ``` 详细质押示例请参考 `examples/stake_energy_demo.php`。 能量估算 ---- [](#能量估算) 在转账前，可以估算交易所需的能量，避免因能量不足导致交易失败。 ``` // 估算TRC20转账所需能量 $energyEstimate = $tron->estimateTrc20TransferEnergy( 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t', // USDT合约地址 '接收方地址', 10.5, // 转账金额 '发送方地址' ); echo "预估所需能量: " . $energyEstimate['energy_used'] . "\n"; echo "建议费用限制: " . $energyEstimate['suggested_fee_limit_trx'] . " TRX\n"; ``` 查询账户资源 ------ [](#查询账户资源) ``` // 查询账户的资源情况 $resources = $tron->getAccountResources('钱包地址'); echo "能量上限: " . ($resources['EnergyLimit'] ?? 0) . "\n"; echo "已使用能量: " . ($resources['EnergyUsed'] ?? 0) . "\n"; echo "带宽上限: " . ($resources['NetLimit'] ?? 0) . "\n"; echo "已使用带宽: " . ($resources['NetUsed'] ?? 0) . "\n"; ``` 批量操作 ---- [](#批量操作) ### 批量查询余额 [](#批量查询余额) ``` // 批量查询USDT余额 $contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'); $balances = $contract->batchBalanceOf([ 'TJoq53NiXhrgC9G2KNvpKv2s6UkcdNRgFP', 'TFpS9NJ4Djm29RTmax3VonXL8HumgrC4zW' ]); foreach ($balances as $address => $balance) { echo $address . ": " . $balance . " USDT\n"; } ``` ### 批量转账TRC20代币 [](#批量转账trc20代币) ``` // 设置发送方地址和私钥 $tron->setAddress('发送方地址'); $tron->setPrivateKey('私钥'); // 获取合约对象 $contract = $tron->contract('TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t'); // 批量转账 $transfers = [ ['to' => '接收方地址1', 'amount' => 1.5], ['to' => '接收方地址2', 'amount' => 2.3] ]; $results = $contract->batchTransfer($transfers); foreach ($results as $result) { echo ($result['success'] ? "成功" : "失败") . "\n"; } ``` 详细的批量转账示例请参考 `examples/batch_transfer_usdt_demo.php`。 示例文件说明 ------ [](#示例文件说明) 本库提供了多个示例文件，位于 `examples/` 目录下： - **basic\_usage.php** - 基本用法示例 - **wallet\_demo.php** - 钱包管理示例 - **balance\_demo.php** - 余额查询示例 - **transfer\_demo.php** - TRC20代币转账示例 - **batch\_transfer\_usdt\_demo.php** - TRC20代币批量转账示例 - **trc20\_transactions\_demo.php** - TRC20交易记录查询示例 - **api\_key\_demo.php** - API密钥使用示例 - **stake\_energy\_demo.php** - 质押TRX获取能量示例 - **energy\_guide.php** - 能量使用指南 - **staking\_guide.md** - 质押指南文档 - **check\_balance.php** - 余额检查工具 - **trx\_balance.php** - TRX余额查询工具 - **production\_balance.php** - 生产环境余额查询示例 错误处理 ---- [](#错误处理) 本库提供了详细的错误信息和异常处理，使用 try-catch 捕获异常： ``` try { $result = $tron->send('接收方地址', 100); } catch (TronException $e) { echo "Tron错误: " . $e->getMessage() . "\n"; echo "错误代码: " . $e->getCode() . "\n"; } catch (Exception $e) { echo "一般错误: " . $e->getMessage() . "\n"; } ``` 注意事项 ---- [](#注意事项) 1. **节点选择** - 建议使用私有节点或付费API服务，公共节点可能会有请求限制和稳定性问题 2. **费用设置** - TRC20转账时，确保设置适当的费用限制，避免因能量不足导致交易失败 3. **API密钥** - 在生产环境中，强烈建议使用API密钥 4. **质押操作** - 质押和解除质押操作在某些公共节点上可能受限，建议使用私有节点 5. **能量管理** - 在进行TRC20交易前，确保账户有足够的能量或TRX余额 赞助 -- [](#赞助) 如果您觉得这个项目有帮助，可以给予赞助： **Tron(TRX)**: TJoq53NiXhrgC9G2KNvpKv2s6UkcdNRgFP 许可证 --- [](#许可证) 本项目采用 MIT 许可证 ### Health Score 29 — LowBetter than 59% of packages Maintenance37 Infrequent updates — may be unmaintained Popularity16 Limited adoption so far Community9 Small or concentrated contributor base Maturity44 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 11 Last Release 430d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/9e7066da1f63a8f338175726b4c8b411ef8569837779a932e3ace993a093b919?d=identicon)[PandaTwo](/maintainers/PandaTwo) --- Top Contributors [![18551385538](https://avatars.githubusercontent.com/u/75899148?v=4)](https://github.com/18551385538 "18551385538 (16 commits)") --- Tags blockchaintrontron-libtron-phptron-apitrc20USDTenergyzhifustaking ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/zhifu-tron-api/health.svg) ``` [![Health](https://phpackages.com/badges/zhifu-tron-api/health.svg)](https://phpackages.com/packages/zhifu-tron-api) ``` ### Alternatives [iexbase/tron-api A PHP API for interacting with Tron (Trx) 437136.9k8](/packages/iexbase-tron-api)[fenguoz/tron-api A PHP API for interacting with Tron (Trx) 1146.8k3](/packages/fenguoz-tron-api) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)