# Command Reference

Every command — including every subcommand — has its own page. Most follow the same layout (Synopsis · Description · Options · Examples · Output · Exit status · See also); pages for commands that take a positional argument add an Arguments section, and a few that need no prose drop Description. Command-group pages list and link their subcommands.

## Which commands run on which networks

wallet-cli supports two chain families, **TRON** and **EVM**, and `--network` selects one network of one family. Commands fall into these kinds:

- **Portable** — the same command on either family, with the family-specific parts named per family: `account balance` / `info` / `portfolio`, `block`, `tx send` / `broadcast` / `status` / `info` / `sign`, `token` (all five), `contract call` / `send` / `deploy`, `chain node` / `prices`, `message sign`, `typed-data sign`.
- **TRON only** — the command implements a TRON protocol feature with no EVM counterpart: `account history` / `activate` / `set`, `chain params`, `contract info` / `clear-abi` / `create2` / `set-origin-energy-limit` / `set-user-resource-percent`, `tx approvals` / `multisig`, and every command in the `stake`, `vote`, `reward`, `proposal`, `witness`, `permission`, `asset`, `exchange`, `gasfree`, `sunswap` and `sunpump` groups. Run against an EVM network they fail with **`family_mismatch`** before any node call. `sunswap` and `sunpump` narrow further: `sunpump`, `sunswap swap` and the six `sunswap` market queries run on mainnet only, while `sunswap position-info` and the three liquidity commands run on `tron` and `nile`. Elsewhere they fail with **`unsupported_network_capability`**, and the message names the network that works. Availability is per network config, not per build: the market queries need `sunswap.marketApiBaseUrl`, `swap` needs `sunswap.routerApiBaseUrl` or `sunpump.curve: true`, `sunpump buy` / `sell` need `sunpump.curve: true`, the other `sunpump` commands need `sunpump.apiBaseUrl`, and the liquidity commands and `position-info` need `sunswap.liquidity: true`. Contract addresses come from the SunSwap / SunPump SDK, not from config.
- **Service commands** — `x402` and `bai` talk to HTTP services rather than to a chain node. The ones that pay (`x402 pay` / `roundtrip`, `bai recharge`) use the selected network's family; the catalog, usage, and report commands take no network. `8004` runs on both families, but only on networks with an ERC-8004 registry — not `ethereum` or `sepolia`.
- **Local** — no network at all: `create`, `import`, `use`, `current`, `list`, `derive`, `rename`, `backup`, `delete`, `change-password`, `config`, `networks`, `contact`, `encoding`, `address`. Some of these still accept `--network` as a **display selector** (which family's address to print, which key a keystore export takes); no node is contacted either way.

Individual flags are family-scoped the same way. `--help` tags them `(TRON only)` / `(EVM only)`, and using one on the other family is a usage error — `invalid_option`, exit `2`.

The catalog is the authority on all of this: `wallet-cli --json-schema` reports a `families` array per command.

## Wallets and accounts

| Command | Page |
|---|---|
| `create` | [create.md](create.md) |
| `import` (group) | [import/index.md](import/index.md) |
| `import mnemonic` | [import/mnemonic.md](import/mnemonic.md) *(interactive-only)* |
| `import private-key` | [import/private-key.md](import/private-key.md) *(interactive-only)* |
| `import keystore` | [import/keystore.md](import/keystore.md) *(interactive-only)* |
| `import ledger` | [import/ledger.md](import/ledger.md) |
| `import watch` | [import/watch.md](import/watch.md) |
| `list` | [list.md](list.md) |
| `use` | [use.md](use.md) |
| `current` | [current.md](current.md) |
| `derive` | [derive.md](derive.md) |
| `rename` | [rename.md](rename.md) |
| `backup` | [backup.md](backup.md) |
| `delete` | [delete.md](delete.md) |
| `change-password` | [change-password.md](change-password.md) |

## Transactions

| Command | Page |
|---|---|
| `tx` (group) | [tx/index.md](tx/index.md) |
| `tx send` | [tx/send.md](tx/send.md) |
| `tx broadcast` | [tx/broadcast.md](tx/broadcast.md) |
| `tx status` | [tx/status.md](tx/status.md) |
| `tx info` | [tx/info.md](tx/info.md) |
| `tx sign` | [tx/sign.md](tx/sign.md) |
| `tx approvals` | [tx/approvals.md](tx/approvals.md) |
| `tx multisig` | [tx/multisig.md](tx/multisig.md) |

## On-chain queries

| Command | Page |
|---|---|
| `account` (group) | [account/index.md](account/index.md) |
| `account balance` | [account/balance.md](account/balance.md) |
| `account info` | [account/info.md](account/info.md) |
| `account history` | [account/history.md](account/history.md) |
| `account portfolio` | [account/portfolio.md](account/portfolio.md) |
| `account activate` | [account/activate.md](account/activate.md) |
| `account set` | [account/set.md](account/set.md) |
| `block` | [block.md](block.md) |
| `chain` (group) | [chain/index.md](chain/index.md) |
| `chain params` | [chain/params.md](chain/params.md) |
| `chain prices` | [chain/prices.md](chain/prices.md) |
| `chain node` | [chain/node.md](chain/node.md) |

## Account permissions

| Command | Page |
|---|---|
| `permission` (group) | [permission/index.md](permission/index.md) |
| `permission show` | [permission/show.md](permission/show.md) |
| `permission update` | [permission/update.md](permission/update.md) |

## Tokens and contracts

| Command | Page |
|---|---|
| `token` (group) | [token/index.md](token/index.md) |
| `token balance` | [token/balance.md](token/balance.md) |
| `token info` | [token/info.md](token/info.md) |
| `token add` | [token/add.md](token/add.md) |
| `token list` | [token/list.md](token/list.md) |
| `token remove` | [token/remove.md](token/remove.md) |
| `contact` (group) | [contact/index.md](contact/index.md) |
| `contact add` | [contact/add.md](contact/add.md) |
| `contact list` | [contact/list.md](contact/list.md) |
| `contact remove` | [contact/remove.md](contact/remove.md) |
| `contract` (group) | [contract/index.md](contract/index.md) |
| `contract call` | [contract/call.md](contract/call.md) |
| `contract send` | [contract/send.md](contract/send.md) |
| `contract deploy` | [contract/deploy.md](contract/deploy.md) |
| `contract info` | [contract/info.md](contract/info.md) |
| `contract clear-abi` | [contract/clear-abi.md](contract/clear-abi.md) |
| `contract set-origin-energy-limit` | [contract/set-origin-energy-limit.md](contract/set-origin-energy-limit.md) |
| `contract set-user-resource-percent` | [contract/set-user-resource-percent.md](contract/set-user-resource-percent.md) |
| `contract create2` | [contract/create2.md](contract/create2.md) |
| `gasfree` (group) | [gasfree/index.md](gasfree/index.md) |
| `gasfree info` | [gasfree/info.md](gasfree/info.md) |
| `gasfree transfer` | [gasfree/transfer.md](gasfree/transfer.md) |
| `gasfree trace` | [gasfree/trace.md](gasfree/trace.md) |

## Staking, voting, rewards

| Command | Page |
|---|---|
| `stake` (group) | [stake/index.md](stake/index.md) |
| `stake freeze` | [stake/freeze.md](stake/freeze.md) |
| `stake unfreeze` | [stake/unfreeze.md](stake/unfreeze.md) |
| `stake withdraw` | [stake/withdraw.md](stake/withdraw.md) |
| `stake cancel-unfreeze` | [stake/cancel-unfreeze.md](stake/cancel-unfreeze.md) |
| `stake delegate` | [stake/delegate.md](stake/delegate.md) |
| `stake undelegate` | [stake/undelegate.md](stake/undelegate.md) |
| `stake info` | [stake/info.md](stake/info.md) |
| `stake delegated` | [stake/delegated.md](stake/delegated.md) |
| `vote` (group) | [vote/index.md](vote/index.md) |
| `vote cast` | [vote/cast.md](vote/cast.md) |
| `vote list` | [vote/list.md](vote/list.md) |
| `vote status` | [vote/status.md](vote/status.md) |
| `reward` (group) | [reward/index.md](reward/index.md) |
| `reward balance` | [reward/balance.md](reward/balance.md) |
| `reward withdraw` | [reward/withdraw.md](reward/withdraw.md) |

## Governance

| Command | Page |
|---|---|
| `proposal` (group) | [proposal/index.md](proposal/index.md) |
| `proposal list` | [proposal/list.md](proposal/list.md) |
| `proposal show` | [proposal/show.md](proposal/show.md) |
| `proposal create` | [proposal/create.md](proposal/create.md) |
| `proposal approve` | [proposal/approve.md](proposal/approve.md) |
| `proposal delete` | [proposal/delete.md](proposal/delete.md) |
| `witness` (group) | [witness/index.md](witness/index.md) |
| `witness create` | [witness/create.md](witness/create.md) |
| `witness update` | [witness/update.md](witness/update.md) |
| `witness set-brokerage` | [witness/set-brokerage.md](witness/set-brokerage.md) |

## TRC10 assets and the on-chain exchange

| Command | Page |
|---|---|
| `asset` (group) | [asset/index.md](asset/index.md) |
| `asset issue` | [asset/issue.md](asset/issue.md) |
| `asset update` | [asset/update.md](asset/update.md) |
| `asset participate` | [asset/participate.md](asset/participate.md) |
| `asset unfreeze` | [asset/unfreeze.md](asset/unfreeze.md) |
| `asset info` | [asset/info.md](asset/info.md) |
| `asset list` | [asset/list.md](asset/list.md) |
| `exchange` (group) | [exchange/index.md](exchange/index.md) |
| `exchange create` | [exchange/create.md](exchange/create.md) |
| `exchange inject` | [exchange/inject.md](exchange/inject.md) |
| `exchange withdraw` | [exchange/withdraw.md](exchange/withdraw.md) |
| `exchange trade` | [exchange/trade.md](exchange/trade.md) |
| `exchange show` | [exchange/show.md](exchange/show.md) |
| `exchange list` | [exchange/list.md](exchange/list.md) |

## SunSwap and SunPump

| Command | Page |
|---|---|
| `sunswap` (group) | [sunswap/index.md](sunswap/index.md) |
| `sunswap swap` | [sunswap/swap.md](sunswap/swap.md) |
| `sunswap add-liquidity` | [sunswap/add-liquidity.md](sunswap/add-liquidity.md) |
| `sunswap remove-liquidity` | [sunswap/remove-liquidity.md](sunswap/remove-liquidity.md) |
| `sunswap collect-fees` | [sunswap/collect-fees.md](sunswap/collect-fees.md) |
| `sunswap position-list` | [sunswap/position-list.md](sunswap/position-list.md) |
| `sunswap position-info` | [sunswap/position-info.md](sunswap/position-info.md) |
| `sunswap pool-list` | [sunswap/pool-list.md](sunswap/pool-list.md) |
| `sunswap pool-search` | [sunswap/pool-search.md](sunswap/pool-search.md) |
| `sunswap token-list` | [sunswap/token-list.md](sunswap/token-list.md) |
| `sunswap token-search` | [sunswap/token-search.md](sunswap/token-search.md) |
| `sunswap price` | [sunswap/price.md](sunswap/price.md) |
| `sunpump` (group) | [sunpump/index.md](sunpump/index.md) |
| `sunpump buy` | [sunpump/buy.md](sunpump/buy.md) |
| `sunpump sell` | [sunpump/sell.md](sunpump/sell.md) |
| `sunpump launch` | [sunpump/launch.md](sunpump/launch.md) |
| `sunpump token-list` | [sunpump/token-list.md](sunpump/token-list.md) |
| `sunpump token-info` | [sunpump/token-info.md](sunpump/token-info.md) |
| `sunpump token-search` | [sunpump/token-search.md](sunpump/token-search.md) |

## Signing

| Command | Page |
|---|---|
| `message` (group) | [message/index.md](message/index.md) |
| `message sign` | [message/sign.md](message/sign.md) |
| `typed-data` (group) | [typed-data/index.md](typed-data/index.md) |
| `typed-data sign` | [typed-data/sign.md](typed-data/sign.md) |

## Payments and Agent identity

| Command | Page |
|---|---|
| `x402` (group) | [x402/index.md](x402/index.md) |
| `x402 pay` | [x402/pay.md](x402/pay.md) |
| `x402 serve` | [x402/serve.md](x402/serve.md) |
| `x402 roundtrip` | [x402/roundtrip.md](x402/roundtrip.md) |
| `x402 provider-list` | [x402/provider-list.md](x402/provider-list.md) |
| `x402 provider-show` | [x402/provider-show.md](x402/provider-show.md) |
| `x402 endpoint-list` | [x402/endpoint-list.md](x402/endpoint-list.md) |
| `x402 update-catalog` | [x402/update-catalog.md](x402/update-catalog.md) |
| `bai` (group) | [bai/index.md](bai/index.md) |
| `bai usage-summary` | [bai/usage-summary.md](bai/usage-summary.md) |
| `bai usage-records` | [bai/usage-records.md](bai/usage-records.md) |
| `bai recharge-orders` | [bai/recharge-orders.md](bai/recharge-orders.md) |
| `bai recharge` | [bai/recharge.md](bai/recharge.md) |
| `bai report-recharge` | [bai/report-recharge.md](bai/report-recharge.md) |
| `8004` (group) | [8004/index.md](8004/index.md) |
| `8004 show` | [8004/show.md](8004/show.md) |
| `8004 operator-check` | [8004/operator-check.md](8004/operator-check.md) |
| `8004 register` | [8004/register.md](8004/register.md) |
| `8004 update` | [8004/update.md](8004/update.md) |
| `8004 transfer` | [8004/transfer.md](8004/transfer.md) |
| `8004 approve` | [8004/approve.md](8004/approve.md) |
| `8004 add-operator` | [8004/add-operator.md](8004/add-operator.md) |
| `8004 remove-operator` | [8004/remove-operator.md](8004/remove-operator.md) |

## Local

| Command | Page |
|---|---|
| `encoding` (group) | [encoding/index.md](encoding/index.md) |
| `encoding convert` | [encoding/convert.md](encoding/convert.md) |
| `address` (group) | [address/index.md](address/index.md) |
| `address generate` | [address/generate.md](address/generate.md) |
| `config` | [config.md](config.md) |
| `networks` | [networks.md](networks.md) |

## Global options (every command)

```
-o, --output <text|json>   result format (default: config.defaultOutput, built-in text)
--network <string>         network id or alias, e.g. nile, sepolia, bsc, eip155:11155111
                           (falls back to config.defaultNetwork)
--account <string>         accountId, label, or address (wallet-bound commands; falls back to active)
                           an address names one chain, so use accountId or label to cross families;
                           an address matching several accounts that are not interchangeable
                           signers for the family being acted on is `ambiguous_account`
--timeout <number>         per RPC/device call timeout, ms (default: config.timeoutMs, built-in 60000)
-v, --verbose              extra diagnostic output
-h, --help / -V, --version
```

Commands whose schema allows post-broadcast polling take `--wait` / `--wait-timeout <ms>` (cap default: config `waitTimeoutMs`, built-in 60000). The early-exit modes are command-specific too: transaction-building commands may expose `--dry-run` / `--sign-only` / `--build-only`, while a submit-only command such as `tx broadcast` neither rebuilds nor signs and therefore has no `--sign-only` / `--build-only`.

Fee and multi-sig flags are **family-scoped**, so they are not global:

| Flags | Family | Where |
|---|---|---|
| Permission group and expiry — see below | TRON | TRON transaction-building commands that sign or can emit unsigned hex; not `tx broadcast`, GasFree, or the `sunswap` and `sunpump` writes |
| `--fee-limit <sun>` | TRON | the commands that spend energy: `tx send`, `contract send` / `deploy`, `sunswap swap` / `add-liquidity` / `remove-liquidity` / `collect-fees`, and `sunpump buy` / `sell` |
| `--gas-limit <n>` / `--max-fee <gwei>` / `--priority-fee <gwei>` / `--nonce <n>` | EVM | `tx send`, `contract send` / `deploy` |

`--permission-id` selects the permission group to sign under (0=owner, 1=witness, 2-9=active) and `--expiration` extends the window for collecting co-signatures. An EVM transaction carries exactly one signature, so neither has a counterpart there: on a portable command they are tagged `(TRON only)` and refused on EVM with `invalid_option`.

Where all three early-exit modes exist, they are mutually exclusive, and `--expiration` is accepted only alongside `--sign-only` or `--build-only`. Breaking either rule is a usage error at exit `2`. The code depends on where the check runs: on the `account`, `permission`, `contract`, `proposal` and `witness` writes it is `invalid_value`, and which field the message names depends on the rule. Mutual exclusion is attached to the whole object, so it reports `--input` rather than the flags you passed (`invalid --input: choose at most one of --dry-run, --sign-only, --build-only`); the `--expiration` rule is attached to its own field and names it (`invalid --expiration: only valid with --sign-only or --build-only`). Elsewhere the same conflict reports `invalid_option`. Branch on the exit code, not on the code string; see [machine interface](../machine-interface.md#error-codes).