Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 12 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<h1 align="center">wallet-cli</h1>

<h4 align="center">
A command-line wallet for the <a href="https://tron.network">TRON network</a> — interactive in Java, agent-first in TypeScript
A command-line wallet for <a href="https://tron.network">TRON</a> and selected EVM networks — dual-mode in Java, agent-first in TypeScript
</h4>

<p align="center">
Expand All @@ -14,36 +14,37 @@

This repository holds **two independent implementations** that share the same purpose but target different users:

- **[Java](java/README.md)** — the original, full-featured reference CLI. An interactive prompt (REPL) you drive by hand.
- **[Java](java/README.md)** — the original, full-featured reference CLI. Run one-shot standard commands or start the interactive prompt (REPL).
- **[TypeScript](ts/README.md)** — an agent-first rewrite for automation. Standard subcommands with a stable JSON envelope, built for scripts, CI, and AI agents.

Both manage the same kind of wallet on the same networks — your address is identical regardless of which you use. They cover the same TRON feature surface and differ in how you install and drive them. Pick one and read its own README for depth; this page gives you the basics of each so you can choose.
Both manage TRON wallets, but they are independent implementations rather than interchangeable account stores. Do not assume every derived account has the same address across implementations: check the recorded BIP44 path when migrating. The TypeScript implementation additionally supports selected EVM networks.

## At a glance

| | [**Java**](java/README.md) — the original | [**TypeScript**](ts/README.md) — agent-first rewrite |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **What it is** | The mature, full-feature reference CLI. | A newer rewrite focused on programmatic integration. |
| **Runtime** | JVM — built with Gradle, run as a `.jar`. Uses the [Trident](https://github.com/tronprotocol/trident) SDK. | [Node.js](https://nodejs.org) **20+**. |
| **Install** | `git clone` + `./gradlew build` (see [Setup](java/README.md#setup)) | `npm install -g @tron-walletcli/wallet-cli` |
| **How you drive it** | An **interactive prompt only** — start it, then type commands at `>`. | **One-shot subcommands** — `wallet-cli <command>` from your shell. Interactive prompts only for secret input. |
| **Command style** | PascalCase verbs: `RegisterWallet`, `SendCoin`, `GetBalance`. Amounts in **SUN** (1 TRX = 1,000,000 SUN). | Noun-verb subcommands: `create`, `tx send`, `account balance`, with `--flags`. |
| **Output for scripts** | Human-readable text. | Stable JSON via `-o json` ([`wallet-cli.result.v1`](ts/docs/machine-interface.md)) + fixed exit codes (`0`/`1`/`2`). |
| **Config / networks** | `config.conf` (net type + full node), or `SwitchNetwork` at runtime. Mainnet · Nile · Shasta · custom. | `--network` flag / `config` command. `tron:mainnet` · `tron:nile` · `tron:shasta`. |
| **Install** | `git clone` + `cd wallet-cli/java && ./gradlew build` (see [Setup](java/README.md#setup)) | `npm install -g @tron-walletcli/wallet-cli` |
| **How you drive it** | One-shot standard commands, or an interactive prompt when run without a command / with `--interactive`. | **One-shot subcommands** — `wallet-cli <command>` from your shell. Interactive prompts only for secret input. |
| **Command style** | Kebab-case one-shot commands (`send-coin`) or PascalCase REPL verbs (`SendCoin`). Amounts in **SUN**. | Noun-verb subcommands: `create`, `tx send`, `account balance`, with `--flags`. |
| **Output for scripts** | Text by default; standard mode supports `--output json` and structured success/error envelopes. | Stable JSON via `-o json` ([`wallet-cli.result.v1`](ts/docs/machine-interface.md)) + fixed exit codes (`0`/`1`/`2`). |
| **Config / networks** | `config.conf` endpoints, or `SwitchNetwork` at runtime. Mainnet · Nile · Shasta · custom. | `--network` flag / `config` command. Three TRON networks plus Ethereum, Sepolia, BNB Smart Chain, and its testnet. |
| **Signing** | Software keystore · Ledger. | Encrypted local keystore · Ledger. Secrets enter via stdin/TTY, never argv or dedicated secret env vars. |
| **Feature scope** | **The full surface** — wallets and transfers, staking, voting and rewards, governance, contracts, TRC10, and the on-chain exchange. | **The full surface** — HD wallets, TRX/TRC20/TRC10 transfers, staking & delegation, voting & rewards, governance proposals & super-representative operation, contract call/deploy/governance, TRC10 issuance, the on-chain Bancor exchange, multi-sig, GasFree transfers, message signing, and on-chain queries. |
| **Best for** | People at a terminal who want every TRON capability. | Scripting, CI pipelines, and AI agents. |
| **Full docs** | [java/README.md](java/README.md) | [ts/README.md](ts/README.md) |

## Java — get a taste

Interactive only. Build it, start the prompt, then type commands:
Build it, then either run a standard command or start the prompt:

```console
$ git clone https://github.com/tronprotocol/wallet-cli.git
$ cd wallet-cli && ./gradlew build && cd build/libs
$ cd wallet-cli/java && ./gradlew build && cd build/libs
$ java -jar wallet-cli.jar --output json --network nile get-balance --address T...
$ java -jar wallet-cli.jar # opens the interactive prompt
> RegisterWallet 123456 # create a keystore (password 123456)
> RegisterWallet # prompts twice for the password, then for mnemonic length
> Login # unlock it
> GetAddress # your TRON address
> GetBalance # TRX balance
Expand Down
27 changes: 17 additions & 10 deletions java/README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# wallet-cli — Java implementation

The original, full-featured implementation of wallet-cli: an interactive prompt (REPL) covering the complete TRON feature surface — managing accounts and keystores, TRX / TRC10 / TRC20 transfers, staking resources, voting for super representatives, deploying and calling smart contracts, Ledger hardware signing, and [GasFree](https://gasfree.io) gas-less transfers. All gRPC calls run on the [Trident SDK](https://github.com/tronprotocol/trident).
The original, full-featured implementation of wallet-cli. It supports both one-shot standard commands for scripts and an interactive prompt (REPL), covering the complete TRON feature surface — managing accounts and keystores, TRX / TRC10 / TRC20 transfers, staking resources, voting for super representatives, deploying and calling smart contracts, Ledger hardware signing, and [GasFree](https://gasfree.io) gas-less transfers. All gRPC calls run on the [Trident SDK](https://github.com/tronprotocol/trident).

> For what wallet-cli is and how this compares to the scriptable, JSON-first [TypeScript implementation](../ts/README.md), see the [repository overview](../README.md).

**Quick links:** [Setup](#setup) · [Quickstart](#quickstart) · [Commands](#commands) · [Understanding TRON mechanics](#understanding-tron-mechanics) · [Configuration](docs/reference/config.md)
**Quick links:** [Setup](#setup) · [Quickstart](#quickstart) · [Commands](#commands) · [Standard CLI](docs/commands/standard-cli.md) · [Understanding TRON mechanics](#understanding-tron-mechanics) · [Configuration](docs/reference/config.md)

Need help? Join the [Telegram developer group](https://t.me/TronOfficialDevelopersGroupEn).

Expand All @@ -18,7 +18,7 @@ git clone https://github.com/tronprotocol/wallet-cli.git

### Configuration

A minimal `config.conf` only needs a network type and a full node to talk to:
A minimal `config.conf` needs a full-node endpoint. `net.type` does not select the network; it only controls whether `grpc.mainnet.apiKey` is applied. The startup network is inferred from the configured node endpoints.

```
net {
Expand All @@ -40,28 +40,35 @@ You can also switch networks at runtime with the [`SwitchNetwork`](docs/commands
- **Compile and run**:

```console
$ cd wallet-cli
$ cd wallet-cli/java
$ ./gradlew build
$ cd build/libs
$ java -jar wallet-cli.jar
$ java -jar wallet-cli.jar --help
```

wallet-cli connects to java-tron via the gRPC protocol, which can be deployed locally or remotely. Configure the java-tron node IP and port in `src/main/resources/config.conf`, or use `SwitchNetwork` to switch among mainnet, testnets (Nile and Shasta), and custom networks.
With no arguments, wallet-cli opens the legacy interactive prompt. Any command selects the standard CLI; `--interactive` selects the prompt explicitly. Global options without a command, except supported modes such as `--help` and `--version`, are a usage error. Standard mode accepts options such as `--network <main|nile|shasta|custom>`, `--wallet`, `--grpc-endpoint`, and `--output <text|json>`:

```console
$ java -jar wallet-cli.jar --output json --network nile get-balance --address T...
$ java -jar wallet-cli.jar --interactive
```

wallet-cli connects to java-tron via gRPC. At startup it first looks for `config.conf` in the current working directory, then falls back to the bundled classpath resource. Use `SwitchNetwork` to switch among mainnet, testnets (Nile and Shasta), and custom networks.

## Quickstart

Build, create an account, and send your first transfer — all from the interactive prompt:
This quickstart uses the interactive prompt. For automation, pass a standard command to the jar and add `--output json`; see the [standard CLI contract](docs/standard-cli-contract-spec.md).

```console
# 1. Build
$ git clone https://github.com/tronprotocol/wallet-cli.git
$ cd wallet-cli && ./gradlew build && cd build/libs
$ cd wallet-cli/java && ./gradlew build && cd build/libs

# 2. Start the interactive wallet
$ java -jar wallet-cli.jar

# 3. In the wallet prompt: create an account (or ImportWallet), unlock, and inspect it
> RegisterWallet 123456 # create a keystore with password 123456
> RegisterWallet # prompts twice for the password, then for mnemonic length
> Login # unlock the account
> GetAddress # show your address
> GetBalance # TRX balance
Expand All @@ -76,7 +83,7 @@ The full first-run walkthrough is in the [getting-started guide](docs/guide/gett

## Commands

Every command is documented on a family page under [docs/commands/](docs/commands/index.md). The **[command index](docs/commands/index.md)** has the full A–Z list linking each command to its section; in the wallet, typing any command shows its built-in usage tips.
Legacy interactive commands are documented on family pages under [docs/commands/](docs/commands/index.md). The **[interactive command index](docs/commands/index.md)** links each PascalCase command to its section. The separate **[standard CLI catalog](docs/commands/standard-cli.md)** lists the 107 one-shot commands and their global invocation contract.

### Wallets & accounts

Expand Down
8 changes: 5 additions & 3 deletions java/docs/commands/contract.md
Original file line number Diff line number Diff line change
Expand Up @@ -111,18 +111,20 @@ Example:
## TriggerConstantContract

```console
> TriggerConstantContract [ownerAddress] contractAddress method args isHex fee_limit value token_value token_id
> TriggerConstantContract ownerAddress contractAddress method args isHex [value token_value token_id]
```

- `OwnerAddress` — the address of the account that initiated the transaction, optional, default is the address of the login account.
- `ownerAddress` — required. Pass a base58 address, or `#` to use the logged-in account.
- `contractAddress` — smart contract address.
- `method` — the name of the function and parameters; refer to the example.
- `args` — parameter value; if you want to call `receive`, pass `#` instead.
- `isHex` — the format of the parameters `method` and `args`; hex string or not.
- `fee_limit` — the most TRX allowed for consumption.
- `value` — optional call value in SUN; when supplied, `token_value` and `token_id` are required too.
- `token_value` — number of TRC10.
- `token_id` — TRC10 id; if not, use `#` instead.

The command accepts exactly five parameters without value/token fields, or eight parameters with all three optional fields. It does not take `fee_limit`.

Example:

```console
Expand Down
3 changes: 2 additions & 1 deletion java/docs/commands/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,13 @@

Commands are grouped into family pages below; the A–Z index links each command to its owning page. Every family page is populated. Links point to the owning page (open it and jump to the command's section).

Type any command in the interactive wallet to see its built-in usage tips.
This page indexes legacy interactive commands. For one-shot kebab-case commands, global flags, and JSON output, use the [standard CLI reference](standard-cli.md). Type any command in the interactive wallet to see its built-in usage tips.

## By family

| Family | Page |
|---|---|
| Standard one-shot CLI | [standard-cli.md](standard-cli.md) |
| Wallet management | [wallet.md](wallet.md) |
| Account commands | [account.md](account.md) |
| Network | [network.md](network.md) |
Expand Down
2 changes: 2 additions & 0 deletions java/docs/commands/multisig.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

Configure account permissions, co-sign transactions, inspect signature weight, and use TronLink multi-sign. For the underlying permission model, see [concepts/multisig](../concepts/multisig.md).

Many legacy REPL write commands accept `-m` only as their final token. That switch routes the operation through the interactive multi-sign flow instead of the normal single-signer broadcast. Support is command-specific; use the command's built-in usage text before appending it. The one-shot standard CLI uses command options documented by `<command> --help` and does not inherit this trailing-token convention.

## How to use the multi-signature feature of wallet-cli

Multi-signature allows other users to access the account in order to better manage it. There are three types of access:
Expand Down
7 changes: 4 additions & 3 deletions java/docs/commands/stake-v1-legacy.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,12 +11,13 @@ After the funds are frozen, the corresponding number of shares and bandwidth wil
**Freeze operation is as follows:**

```console
> freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY] [receiverAddress]
> freezeBalance [OwnerAddress] frozen_balance frozen_duration [ResourceCode:0 BANDWIDTH, 1 ENERGY, 2 TRON_POWER] [receiverAddress]
```

- `OwnerAddress` — the address of the account that initiated the transaction, optional, default is the address of the login account.
- `frozen_balance` — the amount of frozen funds, the unit is Sun. The minimum value is **1000000 Sun (1 TRX)**.
- `frozen_duration` — freeze time, this value is currently only allowed for **3 days**.
- `ResourceCode` — `0` BANDWIDTH; `1` ENERGY; `2` TRON_POWER only when `getAllowNewResourceModel` is enabled. TRON_POWER cannot be delegated, so omit `receiverAddress` when using `2`.

For example:

Expand All @@ -33,7 +34,7 @@ After the freezing time expires, funds can be unfrozen.
**Unfreeze operation is as follows:**

```console
> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 CPU) [receiverAddress]
> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 ENERGY, 2 TRON_POWER) [receiverAddress]
```

## How to delegate resource
Expand All @@ -55,7 +56,7 @@ The latter two parameters are optional. If not set, the TRX is frozen to obtain
### UnfreezeBalance (undelegate)

```console
> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 CPU) [receiverAddress]
> unfreezeBalance [OwnerAddress] ResourceCode(0 BANDWIDTH, 1 ENERGY) [receiverAddress]
```

The latter two parameters are optional. If they are not set, the BANDWIDTH resource is unfrozen by default; when the `receiverAddress` is set, the delegated resources are unfrozen.
Expand Down
Loading