Skip to main content
gen wallet manages the local wallet store used to sign Grid activations. Wallets live under ~/.gen/wallets/: keystore.json holds the wallet records and config.toml tracks the active wallet. New wallets are encrypted with a password by default; leaving the password blank, or passing --plaintext, stores secret material unencrypted. This page covers wallet identity and key management only. For balance queries, transfers, and faucet bootstrap, see gen wallet transfers. For RPC connection settings (--rpc-url, headers), see CLI configuration.

​
Options

Only the global flags work on every gen wallet subcommand:
  • --json, -j: emit a single JSON envelope ({ ok, command, timestamp, result | error }) instead of human output. Required for scripting. See CLI configuration for the other global flags (--rpc-url, --header, and so on).
The rest are command-specific and are rejected on subcommands that do not define them:
  • --plaintext: only on the commands that store new secret material (create, import seed, import mnemonic, import private-key), skips password encryption and writes the wallet in plaintext. Unsafe; use only for disposable local automation.
  • --wallet <NAME>: only on commands that take an optional positional NAME, the named-flag form of the same argument.
Wallet selection precedence for commands that need an active wallet:
  1. explicit NAME argument or --wallet <NAME>
  2. active wallet recorded in ~/.gen/wallets/config.toml
  3. error if neither is set
Hex output (public keys, private keys, seeds) is always 0x-prefixed.

​
gen wallet init

Interactive onboarding flow. Walks through choosing seed create/import, mnemonic create/import, or private-key import; prompts for an optional name; prompts for an encryption password; and sets the resulting wallet as active.
Output: prompts to stdin/stdout, then a confirmation that the wallet was created and set active. Use this when you do not yet have a wallet and want a guided setup.

​
gen wallet create

Create a new wallet from fresh CSPRNG entropy. Defaults to a 32-byte seed; pass --mnemonic to generate a BIP-39 phrase instead.
Key flags:
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --plaintext: Store the private key without encryption (unsafe).
  • --mnemonic: Generate a BIP-39 recovery phrase instead of the default seed.
  • --12-word: Generate a 12-word recovery phrase instead of the default 24-word phrase.
Example:
Output: prints the wallet name, the Address: (grd@... 1-part account locator), the public key, and the recovery material (seed or mnemonic) once. Record the recovery material immediately; the store does not retain it.

​
gen wallet import

Import a wallet from existing key material. Each flavor is its own subcommand.

​
gen wallet import seed

Import from a 32-byte seed (64 hex characters, optionally 0x-prefixed).
Key flags:
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --plaintext: Store the private key without encryption (unsafe).
  • --seed-file <PATH>: Read the seed hex from a file instead of prompting.
  • --derivation-path <PATH>: Use a custom BIP-44 derivation path instead of the default Gen path (for example: m/44’/218’/0’/0/7; only purpose, coin type, and account are hardened).
Example:
Output: confirms the imported wallet name, address, and public key.

​
gen wallet import mnemonic

Import from a BIP-39 recovery phrase.
Key flags:
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --plaintext: Store the private key without encryption (unsafe).
  • --mnemonic-file <PATH>: Read the recovery phrase from a file instead of prompting.
  • --derivation-path <PATH>: Use a custom BIP-44 derivation path instead of the default Gen path (for example: m/44’/218’/0’/0/7; only purpose, coin type, and account are hardened).
Example:
Output: confirms the imported wallet name, address, and public key.

​
gen wallet import private-key

Import from a raw private key (hex, optionally 0x-prefixed).
Key flags:
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --plaintext: Store the private key without encryption (unsafe).
  • --private-key-file <PATH>: Read the private key from a file instead of prompting.
Example:
Output: confirms the imported wallet name, address, and public key.

​
gen wallet import encrypted

Import a portable encrypted wallet bundle previously produced by gen wallet export encrypted.
Prompts for the bundle password, validates the decrypted key against the bundle metadata, prompts for a destination wallet name if not supplied, then prompts for a local storage password. Sets the imported wallet active. Example:
Output: confirms the destination wallet name and address.

​
gen wallet list

Show all stored wallets as a table.
Columns: NAME, ACTIVE, STORAGE, SOURCE, ADDRESS. With --json, returns an array of records with the same fields.

​
gen wallet show

Show metadata for one wallet. With no argument, shows the active wallet.
Key flags:
  • [NAME] (positional): Wallet to act on; defaults to the active wallet.
  • --wallet <NAME>: Wallet to act on, as a flag instead of the positional NAME; defaults to the active wallet.
  • --account-address-only: Print only the selected wallet account address.
  • --public-key-only: Print only the selected wallet public key.
Example:
Output: human-readable metadata block with Address and Public key, or just the requested field. JSON mode returns a result object with name, account, public_key_hex, storage, and source.

​
gen wallet set-active

Set which wallet is used by default for wallet-backed commands.
Output: confirmation that the active wallet has changed. Persisted to ~/.gen/wallets/config.toml.

​
gen wallet rename

Rename a stored wallet. If the renamed wallet was active, it stays active under the new name.
Output: confirmation of the rename.

​
gen wallet remove

Delete a wallet from the local store. If the removed wallet was active, the active wallet is cleared.
Output: confirmation of the removal. There is no recovery; make sure recovery material is backed up first.

​
gen wallet export

Export wallet material. Two flavors: raw private key, or a portable encrypted bundle.

​
gen wallet export private-key

Print the wallet’s private key to stdout as 0x-prefixed hex. Requires explicit --unsafe acknowledgement.
Example:
Output: a single 0x-prefixed hex string on stdout. This is the only command in the wallet surface that prints the private key; treat the output as a secret.

​
gen wallet export encrypted

Write a portable encrypted wallet bundle to a file. Secret material never touches stdout.
If the wallet is already encrypted, the bundle inherits the wallet’s existing password. If the wallet is plaintext, the command prompts for a new bundle password. Example:
Output: confirmation that the bundle was written. Restore on another machine with gen wallet import encrypted.

​
See also