wallet-cli —— TypeScript 实现

TypeScript 版面向脚本、CI 和 AI 智能体调用：每条命令都有稳定的 JSON 响应结构、确定的退出码和 可查询的 schema；交互式提示被限制在一份很短的白名单内——create、各个 import 子命令、backup、 change-password 和 delete——除此之外，凭据缺失一律直接报错，绝不弹出提示。关于 wallet-cli 以及 两种实现的对比，参见仓库总览；关于最早的实现，参见 Java 实现。

主要特性

• 便于自动化集成——提供稳定的 JSON 输出、确定的退出码和可查询的 schema，适合脚本、CI 和 AI 智能体调用（细节见接口约定概要）。
• 加密的本地存储——软件 keystore 在磁盘上加密保存；敏感信息绝不通过命令行参数或环境变量传递。
• 软件签名与 Ledger 签名——用软件签名，或在 Ledger 设备上签名（私钥绝不离开设备）。
• 完整的 TRON 功能支持——HD 钱包、TRX 与 TRC20/TRC10 转账、质押 / 资源代理、投票 / 奖励、 治理提案与超级代表运营、智能合约调用、部署与治理、TRC10 发行、链上 Bancor 交易所、多重签名、 GasFree 转账、消息签名，以及链上查询。
• TRON 与 EVM 双链——一个账户在两边各有一个地址；转账、token、合约、签名和链上查询在两边的用法一致，而仅限 TRON 的协议特性在 EVM 上会被直接拒绝，而不是半可用。

目录

• 支持的链
• 安装
• 快速上手
• 命令
• 钱包与账户
• 交易
• 链上查询
• Token、合约、质押、签名
• 治理、TRC10 与链上交易所
• 本地工具与配置
• 接口约定概要
• 理解这两条链
• 故障排查

支持的链

网络由规范的 CAIP-2 namespace:reference id 标识，且各自属于两个链家族之一——tron 或 evm。--network 同样接受简短别名：

网络 id	别名	说明	原生币价值
tron:728126428	tron	TRON 生产主网	真实资金
tron:3448148188	nile	主要的 TRON 测试网（水龙头在 nileex.io）	无——可自由使用
tron:2494104990	shasta	备用的 TRON 测试网	无
eip155:1	ethereum	以太坊主网	真实资金
eip155:11155111	sepolia	以太坊测试网	无
eip155:56	bsc	BNB Smart Chain	真实资金
eip155:97	bsc-testnet	BNB Smart Chain 测试网	无
eip155:8453	base	Base	真实资金
eip155:84532	base-sepolia	Base 测试网	无

余额、token 和交易按网络隔离。链家族决定两件事：以哪个地址身份执行——一个账户同时持有一个 TRON base58 地址和一个 EVM 0x 地址，两者由同一份种子派生；以及存在哪些命令——TRON 的协议特性（质押、超级代表投票、TRC10、Bancor 交易所、链上权限、GasFree）在 EVM 上没有对应物，会以 family_mismatch 被拒绝。费用同样跟随家族：TRON 的 tron-resource 模型（带宽 + 能量），或者 EVM 的 gas。参见网络、账户和能量与带宽。

CAIP-2 之前使用的那几个 TRON id（tron:mainnet、tron:nile、tron:shasta）作为永久别名保留，因此既有的调用方式仍然可用——但输出现在报告的是 CAIP-2 id，所以凡是按字符串匹配 tron:nile 的使用方都需要更新。

安装

前置条件：Node.js 20 或更高版本（用 node --version 检查）。Ledger 签名还需要一台受支持的 Ledger 设备，并安装 TRON 或 Ethereum app。参见 Ledger 指南。

npm install -g @tron-walletcli/wallet-cli

注意 scope：包名是 @tron-walletcli/wallet-cli，不是不带 scope 的 wallet-cli（那是一个无关的 第三方包）。

验证：

wallet-cli --version

<version>          # 显示已安装的版本

用 npm update -g @tron-walletcli/wallet-cli 升级；用 npm uninstall -g @tron-walletcli/wallet-cli 卸载。

从源码构建（贡献者，或要运行未发布的改动）——还需要 Git：

git clone https://github.com/tronprotocol/wallet-cli.git
cd wallet-cli/ts
npm ci && npm run build
npm link             # 把 `wallet-cli` 放到 PATH 上（或直接运行：node dist/index.js）

快速上手

创建你的第一个钱包。 create 会提示输入 master password，然后显示新账户：

wallet-cli create --label main

✅ Created wallet "main"
  Account ID    wlt_2dbv24de.0
  Type          HD
  TRON address  TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ
  EVM address   0x7B28FE10FBccE88c3967ff0Fd64f1ffB46b46C9C
  Active        yes

⚠️ Recovery phrase is encrypted locally and was not printed.
⚠️ Run `backup` soon and store the file offline.

wallet-cli list

HD  wlt_2dbv24de
└─ [0] main  TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ  (active)

完整流程——在测试网上充值、查看余额、发送第一笔 TRX——见快速上手指南。 之后可以按主题深入：发送 token · 质押与资源 · 使用 Ledger 硬件钱包 · 脚本编写。

命令

每条命令——包括每个子命令——都有自己的参考页；完整的逐命令列表见 命令索引；也可以运行 wallet-cli <command> --help 查看内置帮助。

钱包与账户

创建、导入和管理本地钱包与账户。

命令	说明
create	创建新的 HD 钱包（BIP39 种子）
import	导入钱包——mnemonic · private-key · keystore · ledger · watch（仅观察）
list	列出钱包与账户
use · current	设置 / 显示当前账户（current --qr 显示收款二维码）
derive	从种子钱包派生下一个 HD 账户
rename · backup · delete	重命名、备份或删除账户（backup 以 0600 权限导出密钥材料和元数据；--keystore 使用 Web3 keystore 格式，--records 输出导出审计日志）
change-password	更换 master password（重新加密全部软件 keystore）

交易

发送、广播、查看和联合签名交易。

命令	说明
tx send	发送原生 TRX 或 TRC20/TRC10 token
tx broadcast	广播已签名的交易
tx status · tx info	确认状态，或完整详情 + 回执
tx sign · tx approvals · tx multisig	联合签名多签交易并查看批准情况

链上查询

读取账户、区块和链的状态。

命令	说明
account balance · info · portfolio	余额、账户原始数据，或带 USD 估值的余额
account history	交易历史（需要 TronGrid）
account activate · set	激活账户，或设置其链上名称 / ID
block	获取区块（省略则取最新块）
chain params · prices · node	治理参数、资源价格，或节点状态

Token、合约、质押、签名

Token 与合约操作、资源质押、投票奖励、消息签名，以及权限管理。

命令	说明
token	Token 地址簿与查询（balance · info · add · list · remove)
contact	收款人联系簿（add · list · remove)
contract	调用、发送、部署、查看和治理合约（call · send · deploy · info · clear-abi · set-origin-energy-limit · set-user-resource-percent · create2)
stake	质押 / 代理资源（freeze · unfreeze · delegate · info, …)
vote · reward	为超级代表投票并领取投票奖励
message · typed-data	签名任意消息，或 EIP-712/TIP-712 结构化数据
permission	查看 / 更新用于多重签名的账户权限
gasfree	通过 GasFree 服务进行免 gas 的 token 转账

治理、TRC10 与链上交易所

链治理、超级代表运营，以及 TRON 协议级的 TRC10 与 Bancor 交易所机制。

命令	说明
proposal	链参数提案（list · show · create · approve · delete) ——list / show 对任何人开放，写操作命令需要已注册的见证人
witness	注册和运营超级代表（create · update · set-brokerage)
asset	发行和管理 TRC10 token（issue · update · participate · unfreeze · info · list）；TRC10 转账通过 tx send 进行
exchange	TRX 与 TRC10 之间的协议级 Bancor 交易所（create · inject · withdraw · trade · show · list)

支付与 Agent 身份

命令	说明
x402	为受 x402 保护的 HTTP 端点付费、运行本地付费墙，并浏览服务方目录
bai	B.AI 额度、用量记录与稳定币充值
8004	读取并管理 ERC-8004 Agent 身份

本地工具与配置

离线的本地命令与配置。

命令	说明
encoding convert	转换 / 校验地址和编码
address generate	生成随机密钥对（本地，不保存）
config	显示 / 读取 / 设置配置值
networks	列出已知网络

接口约定概要

每条命令都支持 -o json，并在 stdout 上输出恰好一个完整的 JSON 对象，schema 为 wallet-cli.result.v1。退出码是固定的：0 成功、 1 执行失败、2 用法错误。敏感信息（密码、助记词、私钥）绝不接受通过命令行参数传入，也不会从专用的敏感信息环境变量读取。密码可以通过 stdin 标志或交互式 TTY 提示进入；助记词/私钥导入和 change-password 只能交互执行（完全没有 stdin 路径）。完整规范：machine-interface.md。

理解这两条链

TRON 在费用、账户和密钥权限方面与 EVM 链有较大差异，建议在操作前了解以下内容：

• 网络——CAIP-2 id 与别名、两个链家族，以及两种费用模型
• 账户与 HD——助记词、派生路径、每个家族一个地址、账户激活
• 哪些命令能在哪些网络上运行——通用命令、仅限 TRON 的命令，以及本地命令
• 能量与带宽——TRON 基于资源的费用模型（取代 EVM gas）
• 安全——keystore 加密、敏感信息处理、多签权限

故障排查

命令报错或行为异常？常见问题及诊断方法见 troubleshooting.md。

本文档中所有可复制粘贴的示例都在测试网上运行——TRON 上是 Nile 测试网（--network nile），EVM 上是 Sepolia（--network sepolia）。主网命令会动用真实资金；它们只作为带注释的说明出现，不可直接复制执行。

示例中传的是简短别名，因为这样更好读；而旁边的输出样例显示的是规范 id（tron:3448148188、 eip155:11155111），因为 CLI 报告的始终是它。别名属于本地配置、可以被重新指向，所以脚本应当传规范 id ——参见机器接口。

---