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 CLI wallet.
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
wallet.key which 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 using the
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
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
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 wallet.
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
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
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:
Transfer Hotspot from 24-word Wallet
If a Hotspot is transferred to a 24-word wallet, that is ok! However, most Maker Hotspot Management Apps do not currently support 24-word wallets.
To transfer a Hotspot from a 24-word wallet to a 12-word wallet, follow the steps below.
Create a 12-word wallet to receive the Hotspot using the Helium Hotspot App and record the Public Key.
Download and install the Helium Command Line Wallet as outlined above. and navigate to the installation directory.
Import your 24-word seed phrase to the CLI Wallet.
./helium-wallet create basic --seed bip39 --output my-24-word-wallet.key
|create a wallet with a single key, as opposed to a sharded wallet|
|import with an existing seed phrase using the |
|output the wallet key file to a location of your choosing, in this case to a file called |
- Find the Gateway ID of the Hotspot to be transferred by running
./helium-wallet hotspots list
- Perform a Dry Run of the Hotspot transfer
./helium-wallet -f my-24-word-wallet.key hotspots transfer <gateway> <new-owner>
|use a file for the Hotspot wallet, in this case |
|run a Hotspot transfer|
|the gateway id you collected from Step 4 above|
|the public Wallet Address to receive the Hotspot|
The above will do a test try and have an output you should verify.
Now it's time to run it for real.
Point of No Return
--commit flag submits the transfer transaction to the blockchain.
There is no going back from this so please take your time and double-check your inputs.
./helium-wallet -f my-24-word-wallet.key hotspots transfer <gateway> <new-owner> --commit
- Once the transfer transaction is validated by the blockchain, your Hotspot will appear in the new 12-word wallet.