wallet-cli derive¶

Derive the next HD account from a seed wallet.

Synopsis¶

wallet-cli derive [--seed-id <wlt_…>] [--account <account>] [--index <n>] [--label <l>] [options]

Options¶

Option	Description
`--seed-id <string>`	seed id of the HD wallet to derive from — the HD group header in `list`. Wins over `--account` when both are given
`--account <string>`	accountId, label, or address of any account in the HD wallet; defaults to the active account
`--index <number>`	explicit HD account index; omit to use the next free index. An index that already exists is not re-derived — that account is made active, `status` comes back `"existing"`, and text output is headed `Selected existing account` instead of `Derived sub-account`
`--label <string>`	label for the new account, 1-64 chars; omit to auto-generate
`--password-stdin`	read the master password from stdin (fd 0)

Plus global options.

Notes¶

With no --seed-id or --account, derive uses the seed of the active account. Any account of the wallet selects it, not only index 0.

Each new account gets m/44'/195'/0'/0/<index> for TRON and m/44'/60'/0'/0/<index> for EVM.

Private-key, Ledger, and watch-only accounts have no seed and cannot derive; selecting one fails with seed_not_found (exit 2). See Accounts & HD.

A wallet created before 4.13.1 may hold TRON accounts at the old path. Deriving a new account from it fails with legacy_derivation. Naming one of those accounts with --index still works — it is made active with a warning. See Recover addresses after legacy_derivation.

If a stored address does not match the seed, derive fails with derivation_mismatch.

Examples¶

In the examples, $PW is your master password (from an environment variable, password manager, etc.), fed on stdin via --password-stdin.

Derive the next account of the active account's wallet:

printf '%s' "$PW" | wallet-cli derive --password-stdin

✅ Derived sub-account "main-1"
  Account ID    wlt_kwyjcwdh.1
  Index         1
  TRON address  TVz38F2QmQf53g7QVATBbsZ6JkHKccJFAQ
  EVM address   0xEA4A61822322c695F5A9eB7920b843054CbDaA83
  Active        yes
  Note          shares the wallet's recovery phrase

printf '%s' "$PW" | wallet-cli derive --password-stdin -o json

{"schema":"wallet-cli.result.v1","success":true,"command":"derive","data":{"status":"created","accountId":"wlt_kwyjcwdh.1","label":"main-1","type":"seed","index":1,"active":true,"addresses":{"tron":"TVz38F2QmQf53g7QVATBbsZ6JkHKccJFAQ","evm":"0xEA4A61822322c695F5A9eB7920b843054CbDaA83"},"seedId":"wlt_kwyjcwdh","derivationPath":{"tron":"m/44'/195'/0'/0/1","evm":"m/44'/60'/0'/0/1"}},"meta":{"durationMs":1784,"warnings":[]}}

To derive from another wallet, name any of its accounts with --account, or its seed with --seed-id.

Output¶

data is the derived account (always an HD seed account). Local command — no chain block.

Field	Type	Meaning
`status`	string	`"created"` for a newly derived index, `"existing"` when `--index` names an index this wallet already holds — that account is simply made active again, and no new key is derived
`accountId`	string	Stable id `<seedId>.<index>`
`label`	string	Account label (default `<wallet-name>-<index>`, e.g. `main-1`)
`type`	string	Always `"seed"`
`index`	number	HD derivation index
`active`	boolean	Always `true` (the account is made active)
`addresses`	object	One address per family the account can produce: `tron` (base58) and `evm` (`0x`, EIP-55 checksummed)
`derivationPath`	object	The verified path of each address. A new account gets `{"tron":"m/44'/195'/0'/0/<index>","evm":"m/44'/60'/0'/0/<index>"}`; an `"existing"` account reports the path it actually uses, which can be the old TRON path
`seedId`	string	Owning seed wallet id

Exit status¶

0 success · 1 execution failure, including legacy_derivation and derivation_mismatch · 2 usage error, including seed_not_found. See machine-interface.