Skip to content

README.md

Latest commit

 

History

History
160 lines (118 loc) · 9.63 KB

README.md

File metadata and controls

160 lines (118 loc) · 9.63 KB
Raw

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 only for secret input (import / backup / delete). 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 are never passed via argv or environment variables.
  • Software and Ledger signing — sign in software, or on a Ledger device (the private key never leaves the device).
  • Covers the main TRON capabilities — HD wallets, TRX and TRC20/TRC10 transfers, staking / resource delegation, voting / rewards, smart-contract calls and deployment, message signing, and on-chain queries.

Supported chains

Three TRON networks are supported today. Networks are identified by a canonical family:chain id (all tron today):

Network id What it is TRX value
tron:mainnet Production mainnet Real funds
tron:nile Primary testnet (faucet at nileex.io) None — use freely
tron:shasta Alternate testnet None

Your address is the same on every network, but balances, tokens, and transactions are isolated per network. Fees use TRON's tron-resource model (bandwidth + energy) rather than 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 TRON app installed — 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)

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
  TRON address  TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ
  Active        yes
wallet-cli list
HD  wlt_2dbv24de
└─ [0] main  TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ  (active)

Next: fund it on a testnet, check the balance, and send TRX → Getting started.

Start here

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 or environment variables — only via stdin flags or interactive TTY prompts; mnemonic/private-key import and change-password are interactive-only (no stdin path at all). Details: machine-interface.md.

Commands

Every command — including every subcommand — has a reference page; run wallet-cli <command> --help for the built-in equivalent.

Wallets and accounts

Command Description
create Create a new HD wallet (BIP39 seed)
import mnemonic Import a BIP39 mnemonic phrase (interactive-only)
import private-key Import a raw private key (interactive-only)
import ledger Register a Ledger account (watch-only; signs on device)
import watch Register a watch-only address (no secret)
list List wallets / accounts
use / current Set / show the active account
derive Derive the next HD account from a seed wallet
rename / backup / delete Manage accounts (backup writes secret + metadata, mode 0600)
change-password Change the master password (re-encrypt all software keystores)

Transactions

Command Description
tx send Send native TRX or TRC20/TRC10 tokens
tx broadcast Broadcast a presigned transaction
tx status Show confirmation status (confirmed / failed / pending / not_found)
tx info Show full transaction detail + receipt

On-chain queries

Command Description
account balance Show the native TRX balance
account info Show raw account data incl. resources
account history Show transaction history (requires TronGrid)
account portfolio Native + token balances with best-effort USD value
block Get a block (latest if omitted)
chain params On-chain governance parameters
chain prices Energy/bandwidth unit price and memo fee
chain node Connected node status (version / sync / peers)

Tokens, contracts, staking, signing

Command Description
token Manage the token address book and query tokens (balance · info · add · list · remove)
contract Call, send, deploy, and inspect smart contracts (call · send · deploy · info)
stake Stake / delegate resources & query state (freeze · unfreeze · withdraw · cancel-unfreeze · delegate · undelegate · info · delegated)
vote Vote for super representatives (cast · list · status)
reward Query / withdraw voting rewards (balance · withdraw)
message Sign arbitrary messages (sign)

Local configuration

Command Description
config Show / get / set configuration values
networks List known networks (tron:mainnet, tron:nile, tron:shasta)

Documentation map

You want to… Read
Learn by doing guide/ — getting started · sending tokens · staking · Ledger · scripting
Look up a command commands/
Integrate programmatically machine-interface.md
Understand TRON mechanics concepts/ — networks · accounts & HD · energy & bandwidth · security
Fix an error troubleshooting.md

All copy-pasteable examples in this documentation run against the Nile testnet (--network tron:nile). Mainnet commands move real funds; they appear only as annotated, non-copyable descriptions.