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 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 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.
  • TRON and EVM chains — one account holds an address on each; transfers, tokens, contracts, signing and chain queries work the same on both, and TRON-only protocol features are refused on EVM rather than half-working.

Table of contents

Supported chains

Networks are identified by a canonical CAIP-2 namespace:reference id, and each belongs to one of two chain families, tron or evm. --network also accepts the short alias:

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 Real funds
eip155:11155111 sepolia Ethereum test network None
eip155:56 bsc BNB Smart Chain Real funds
eip155:97 bsc-testnet BNB Smart Chain test network None
eip155:8453 base Base Real funds
eip155:84532 base-sepolia Base test network None

Balances, tokens, and transactions are isolated per network. The family decides two things: which address a command acts as — one account holds a TRON base58 address and an EVM 0x address, derived from the same seed — and which commands exist, since TRON protocol features (staking, SR voting, TRC10, the Bancor exchange, on-chain permissions, GasFree) have no EVM counterpart and are refused there with family_mismatch. Fees follow the family too: TRON's tron-resource model (bandwidth + energy) or EVM gas. See networks, accounts and energy & bandwidth.

The TRON ids used before CAIP-2 (tron:mainnet, tron:nile, tron:shasta) remain permanent aliases, so existing invocations keep working — but output now reports the CAIP-2 id, so a consumer that string-matches tron:nile must be updated.

Install

Prerequisites: Node.js 20 or later (node --version to check). Ledger signing additionally needs a supported Ledger device with the TRON or Ethereum 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)

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   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)

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)

Payments and Agent identity

Command Description
x402 Pay x402-protected HTTP endpoints, run a local paywall, and browse the provider catalog
bai B.AI credits, usage records, and stablecoin recharges
8004 Read and manage ERC-8004 Agent identities

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 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). Full spec: machine-interface.md.

Understanding the chains

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

Troubleshooting

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

All copy-pasteable examples in this documentation run against a test network — the Nile testnet (--network nile) on TRON, Sepolia (--network sepolia) on EVM. Mainnet commands move real funds; they appear only as annotated, non-copyable descriptions.

Examples pass the short alias because it reads better; the output samples beside them show the canonical id (tron:3448148188, eip155:11155111), because that is what the CLI always reports. Aliases are local config and can be re-pointed, so scripts should pass canonical ids — see machine interface.