Skip to content

derive.md

Latest commit

 

History

History
87 lines (60 loc) · 4.76 KB

derive.md

File metadata and controls

87 lines (60 loc) · 4.76 KB
Raw

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. With an existing index, --label must be omitted or match the account's label (ignoring case); a different label is refused with invalid_value and nothing is written — change a label with rename
--label <string> label for the new account, 1-64 chars; omit to auto-generate. A duplicate label is refused before an account is written
--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 seed wallet may hold TRON accounts at m/44'/195'/<index>'/0/0 with index greater than zero. 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; the base name is truncated so the complete label fits 64 characters)
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 and invalid_value — a --label already used by another account, or a different --label for an existing --index. See machine-interface.

See also

create · list · Accounts & HD