Skip to content

README.md

Latest commit

 

History

History
180 lines (129 loc) · 10.4 KB

README.md

File metadata and controls

180 lines (129 loc) · 10.4 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, multi-sig, GasFree transfers, message signing, and on-chain queries.

Table of contents

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)

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
  TRON address  TTVdGTBXY5mmY3nJFGUp7Vo898kUJ6gtFQ
  Active        yes
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 · 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)
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 contracts (call · send · deploy · info)
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

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; for calling from an AI agent, see the Agent skill.

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 three networks and the family:chain id
  • 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.

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.