The Helium Command Line Interface (CLI) wallet is the most flexible of the wallet options but it also requires more technical knowledge. As such, it is suitable for all types of transactions, but requires more caution on behalf of its users.
Once you've covered the basics here, you can explore more specific use-cases for the wallet:
Installing CLI Wallet
Releases of the CLI wallet are tagged and hosted on Github. Click on "Downloads" for the most recent release and select the appropriate package for your operating system.
Unpack the zip file and place the helium-wallet binary in your $PATH somewhere. This operation differs depending on your operating system, but is a common task and easily searchable.
At any time, use
--help to see the most recent documentation and help for the
At time of this writing, version 1.6.0 looks like this:
$ helium-wallet --help helium-wallet 1.6.0 Common options for most wallet commands USAGE: helium-wallet [OPTIONS] <SUBCOMMAND> FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: -f, --file <files>... File(s) to use [default: wallet.key] --format <format> Output format to use [default: table] [possible values: table, json] SUBCOMMANDS: balance Get the balance for a wallet. The balance is given in HNT and has a precision of 8 decimals burn Burn HNT to Data Credits (DC) from this wallet to given payees wallet create Create a new wallet help Prints this message or the help of the given subcommand(s) hotspots Display list of hotspots associated with wallet or transfer a hotspot to another wallet htlc Create or Redeem from an HTLC address info Get wallet information multisig Commands multi signature transactions oracle Report an oracle price to the blockchain oui Create or update an OUI pay Send one (or more) payments to given addresses. If an input file is specified for multiple payments, the payee, amount and memo arguments are ignored request Construct various request (like payment) in a QR code securities Work with security tokens upgrade Upgrade a wallet to the latest supported version of the given format. The same password is used to decrypt the old and encrypt the new wallet validators Commands for validators vars Commands for chain variables verify Verify an encypted wallet
Exploring the help menu is always a good way to orient yourself. To learn more
about a certain transaction (or subcommand), simply append
helium-wallet pay --help
This documentation will not cover every single command, but we will provide some basic examples to help you get familiar.
helium-wallet create basic
This command will create a wallet as a single key, stored in
gets output in whatever directory you ran this command.
Upon creation, the CLI will prompt you for a password which encrypts the file. A strong password will make it difficult for someone to brute force the file should the file be compromised.
Displaying information for one or more wallets without needing its password can be done using;
To display a QR code for the public key of the given wallet use:
helium-wallet info --qr
This is useful for sending tokens to the wallet from the mobile wallet.
Wallet Creation Features
Creating a wallet above is easy, but there's a lot more flexibility you might not know about. It's always recommended to explore the help menu to learn more:
$ helium-wallet create basic --help helium-wallet-create-basic 1.6.0 Create a new basic wallet USAGE: helium-wallet create basic [FLAGS] [OPTIONS] FLAGS: --force Overwrite an existing file -h, --help Prints help information -V, --version Prints version information OPTIONS: --key-type <key-type> The type of key to generate (ecc_compact/ed25519) [default: ed25519] --network <network> The network to generate the wallet (testnet/mainnet) [default: mainnet] -o, --output <output> Output file to store the key in [default: wallet.key] --seed <seed> Use a BIP39 or mobile app seed phrase to generate the wallet keys [possible values: bip39, mobile]
We'll go through a few examples next.
Managing Multiple Wallets
You can specify a more precise location or filename when creating a wallet by
--output flag. eg:
helium-wallet create basic --output ~/my-wallets/wallet-5.key
When using a wallet, you can specify a file other than the default
./wallet.key by using the the global option
helium-wallet -f ~/my-wallets/wallet-5.key pay <AMOUNT> <ADDRESS>
Sharding wallet keys is supported via Shamir's Secret Sharing. A key can be broken into N shards such that recovering the original key needs K distinct shards. This can be done by passing options to create:
helium-wallet create sharded -n 5 -k 3
This will create wallet.key.1 through wallet.key.5 (the base name of the wallet
file can be supplied with the
When keys are sharded using verify will require at least K distinct keys.
--seed option described above can also be used to construct a sharded
A ed25519 key is generated via libsodium. The provided password is run through PBKDF2, with a configurable number of iterations and a random salt, and the resulting value is used as an AES key. When sharding is enabled, an additional AES key is randomly generated and the 2 keys are combined using a sha256 HMAC into the final AES key.
The private key is then encrypted with AES256-GCM and stored in the file along with the sharding information, the key share (if applicable), the AES initialization vector, the PBKDF2 salt and iteration count and the AES-GCM authentication tag.
--seed flag enables you to import a wallet generated elsewhere. For
example, you may want to import you key from the mobile wallet, so that you can
submit transactions that may not be supported in the mobile wallet.
Enter the command:
$ helium-wallet create basic --seed mobile
After you press enter, you will be prompted for your seed words.
Remember, your seed is your private key. Keep it safe and private. When you import the seed as a CLI wallet, you do not "log yourself out" of your mobile wallet; you've only copied the private key from your mobile wallet into the CLI. Mobile wallet and CLI wallet both have a local copies of the key and can submit transactions to the blockchain API.
Pay Transaction Example
If you explore the pay command, you will see the following:
$ helium-wallet pay --help helium-wallet-pay 1.6.0 Send one (or more) payments to given addresses. The payment is not submitted to the system unless the '--commit' option is given. USAGE: helium-wallet pay [FLAGS] [OPTIONS] <SUBCOMMAND> FLAGS: --commit Commit the payment to the API -h, --help Prints help information -V, --version Prints version information [..] SUBCOMMANDS: help Prints this message or the help of the given subcommand(s) multi Multiple payees (requires file input). Check "helium-wallet pay multi --help" for details one Single payee
Let's explore the
one subcommand to figure out usage for a single payment:
$ helium-wallet pay one --help helium-wallet-pay-one 1.6.0 Single payee USAGE: helium-wallet pay one [OPTIONS] <address> <amount> FLAGS: -h, --help Prints help information -V, --version Prints version information OPTIONS: --memo <memo> Memo field to include. Provide as a base64 encoded string [default: AAAAAAAAAAA=] ARGS: <address> Address to send the tokens to <amount> Amount of HNT to send
USAGE section is is very helpful:
helium-wallet pay one [OPTIONS] <address> <amount>.
For example, if I want to send 5.0 HNT to
14GWyFj9FjLHzoN3aX7Tq7PL6fEg4dfWPY8CrK8b9S5ZrcKDz5S, it would look like this:
helium-wallet pay one 14GWyFj9FjLHzoN3aX7Tq7PL6fEg4dfWPY8CrK8b9S5ZrcKDz5S 5 --commit
--commit FLAG is a global option to the
pay command - you'll recall it
was documented at the scope of
helium-wallet pay --help. It's critical for
all transactions to confirm that you want the transaction to be submitted to
the blockchain API.
When you commit a transaction to the API, you will be provided with a transaction hash. This is a unique identifier for your transaction on the blockchain and you can track your transcation status using the API endpoint: