Skip to content

wallet-cli — TypeScript implementation

The agent-first implementation of wallet-cli, built for automation: every command has a stable JSON envelope, deterministic exit codes, and discoverable schemas; interactive prompts are kept to a short allowlist — create, the import variants, backup, change-password and delete — and everywhere else a missing credential is an error, never a prompt. For what wallet-cli is and how the two implementations compare, see the repository overview; for the original, see the Java implementation.

Key features

  • Agent-first — stable JSON output, deterministic exit codes, and discoverable schemas, built for scripts, CI, and AI agents (details in The contract, in one paragraph).
  • Encrypted local storage — software keystores are encrypted on disk; secrets enter via stdin/TTY, never argv or dedicated secret environment variables.
  • Software and Ledger signing — sign in software, or on a Ledger device (the private key never leaves the device).
  • Covers the full TRON feature surface — HD wallets, TRX and TRC20/TRC10 transfers, staking / resource delegation, voting / rewards, governance proposals and super-representative operation, smart-contract calls, deployment and governance, TRC10 issuance, the on-chain Bancor exchange, multi-sig, GasFree transfers, message signing, and on-chain queries.
  • EVM chains too — transfers, tokens, contracts, and signing also run on Ethereum and BNB Smart Chain. TRON-protocol-only commands refuse an EVM network with family_mismatch; see which commands run on which networks.

Table of contents

Supported chains

Seven built-in networks are supported. Networks use a canonical CAIP-2 namespace:reference id. The namespace is not the family: eip155 is CAIP-2's namespace for EVM chains, while the family this CLI branches on is evm. An alias is a short name you may type instead; it resolves at selection and never appears in output:

Network id Alias What it is Native coin value
tron:728126428 tron Production TRON Real funds
tron:3448148188 nile Primary TRON testnet (faucet at nileex.io) None — use freely
tron:2494104990 shasta Alternate TRON testnet None
eip155:1 ethereum Ethereum mainnet (ETH) Real funds
eip155:11155111 sepolia Ethereum test network (ETH) None
eip155:56 bsc BNB Smart Chain (BNB) Real funds
eip155:97 bsc-testnet BNB Smart Chain test network (BNB) None

Within a family your address is the same on every network (base58 T… on TRON, 0x… on EVM — the two families derive different addresses from the same seed), while balances, tokens, and transactions stay isolated per network. Fees follow the family: TRON's tron-resource model (bandwidth + energy) or EVM gas — see networks and energy & bandwidth.

Install

Prerequisites: Node.js 20 or later (node --version to check). Ledger signing additionally needs a supported Ledger device with the app for the selected family installed — TRON for TRON accounts, Ethereum for EVM accounts. See the Ledger guide.

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

Note the scope: the package is @tron-walletcli/wallet-cli, not the bare wallet-cli name (which is an unrelated third-party package).

Verify:

wallet-cli --version

<version>          # shows the installed version

Upgrade with npm update -g @tron-walletcli/wallet-cli; uninstall with npm uninstall -g @tron-walletcli/wallet-cli.

From source (contributors, or to run unreleased changes) — additionally requires Git:

git clone https://github.com/tronprotocol/wallet-cli.git
cd wallet-cli/ts
npm ci && npm run build
npm link             # puts `wallet-cli` on your PATH (or run: node dist/index.js)

Quickstart

Create your first wallet. create prompts for a master password, then shows the new account:

wallet-cli create --label main

✅ Created wallet "main"
  Account ID    wlt_2dbv24de.0
  Type          HD
  TRON address  TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ
  EVM address   0x5c8e1b04A7f39d62C0B3e85A1d47F9028b6ce713
  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)

The full flow — fund it on a testnet, check the balance, send your first TRX — is in the getting-started guide. From there, go deeper by topic: sending tokens · staking & resources · using a Ledger hardware wallet · scripting.

Commands

Every command — including every subcommand — has its own reference page; the full per-command list is in the command index, and wallet-cli <command> --help is the built-in equivalent.

Wallets and accounts

Create, import, and manage local wallets and accounts.

Command Description
create Create a new HD wallet (BIP39 seed)
import Import a wallet — mnemonic · private-key · keystore · ledger · watch-only
list List wallets and accounts
use · current Set / show the active account (current --qr for a receive QR)
derive Derive the next HD account from a seed wallet
rename · backup · delete Rename, back up, or delete an account (backup writes secret + metadata, mode 0600; --keystore for Web3 keystore format, --records for the export audit log)
change-password Change the master password (re-encrypt all software keystores)

Transactions

Send, broadcast, inspect, and co-sign transactions.

Command Description
tx send Send native TRX or TRC20/TRC10 tokens
tx broadcast Broadcast a presigned transaction
tx status · tx info Confirmation status, or full detail + receipt
tx sign · tx approvals · tx multisig Co-sign multi-sig transactions and inspect approvals

On-chain queries

Read account, block, and chain state.

Command Description
account balance · info · portfolio Balance, raw account data, or balances with USD estimate
account history Transaction history (requires TronGrid)
account activate · set Activate an account, or set its on-chain name / ID
block Get a block (latest if omitted)
chain params · prices · node Governance params, resource prices, or node status

Tokens, contracts, staking, signing

Token and contract operations, resource staking, voting rewards, message signing, and permissions.

Command Description
token Token address book and queries (balance · info · add · list · remove)
contact Recipient contact book (add · list · remove)
contract Call, send, deploy, inspect, and govern contracts (call · send · deploy · info · clear-abi · set-origin-energy-limit · set-user-resource-percent · create2)
stake Stake / delegate resources (freeze · unfreeze · delegate · info, …)
vote · reward Vote for super representatives and claim voting rewards
message · typed-data Sign arbitrary messages, or EIP-712/TIP-712 structured data
permission View / update account permissions for multi-sig
gasfree Gas-free token transfers via the GasFree service

Governance, TRC10, and the on-chain exchange

Chain governance, super-representative operation, and TRON's protocol-level TRC10 and Bancor exchange mechanics.

Command Description
proposal Chain-parameter proposals (list · show · create · approve · delete) — list / show are open to anyone, the write commands require a registered witness
witness Register and operate a super representative (create · update · set-brokerage)
asset Issue and manage TRC10 tokens (issue · update · participate · unfreeze · info · list); TRC10 transfers go through tx send
exchange The protocol-level Bancor exchange between TRX and TRC10 (create · inject · withdraw · trade · show · list)

Local tools and configuration

Offline local commands and configuration.

Command Description
encoding convert Convert / validate addresses and encodings
address generate Generate a random keypair (local, not stored)
config Show / get / set configuration values
networks List known networks

The contract, in one paragraph

Every command supports -o json and then prints exactly one terminal JSON frame on stdout, schema wallet-cli.result.v1. Exit codes are fixed: 0 success, 1 execution failure, 2 usage error. Secrets (passwords, mnemonics, private keys) are never accepted via argv and are not read from dedicated secret environment variables. Passwords can enter through stdin flags or interactive TTY prompts; mnemonic/private-key import and change-password are interactive-only (no stdin path at all). Full spec: machine-interface.md.

Understanding TRON mechanics

TRON differs a lot from EVM chains in fees, accounts, and key permissions — these are worth understanding up front to avoid surprises:

  • Networks — the seven built-in networks, CAIP-2 ids, and the two chain families
  • Accounts & HD — mnemonics, derivation paths, account activation
  • Energy & bandwidth — TRON's resource-based fee model (in place of EVM gas)
  • Security — keystore encryption, secret handling, multi-sig permissions

Troubleshooting

A command errored or behaved unexpectedly? Common issues and how to diagnose them are in troubleshooting.md.

Copy-pasteable examples that spend anything target a testnet — Nile (--network tron:3448148188) on TRON, Sepolia (--network eip155:11155111) on EVM. Mainnet ids (tron:728126428, eip155:1) also appear: in read-only examples such as token-book listings and config paths, and in a few illustrations of mainnet token contracts. Those last ones carry placeholder recipients (T... / 0x...) and are not runnable as written.