The Helium CLI Wallet – Not For The Faint Of Heart

There’s almost no good reason to use the CLI (Command Line Interface) wallet for a normal person, but…not everyone who gets into Helium is normal. If, like me, you’re faced with having to use it, this series of instructions might help.

This is NOT written for experts who know what they’re doing; they’ll laugh at this. This is NOT written for most of the Helium community. Trust me, you don’t need to use the CLI wallet for regular tasks. This IS written for someone like me; slightly curious, driven by the usual HNT incentives, and willing to futz around with things they don’t understand. If that’s you, enjoy!

It started off with a friend of mine creating a 24 word wallet. Yes, you can create those, just not on the Helium app.

We were testing a hotspot I’d sent him and wanted it to “live” in its own wallet during testing. Once testing wrapped up, I wanted to move the hotspot from the wallet where it was to another wallet where I have other hotspots. This was in part just to keep all HNT earnings in one place, and in part to have (MUCH) easier control over it for me, as a “generally-non-code-using” member of the Helium community.

Now, my friend is a security wizard and fluent in about a million coding languages, so for him managing anything via CLI is just standard stuff. For me, it was more like being thrown in the middle of a Russian street fair knowing I had to buy a very specific item; say a 17mm hex head bolt with a thread pitch of 1.6.

I don’t speak Russian, but damn, I really wanted that hex head bolt!

This particular hotspot serves as one of my tracking units, so I re-assert the location every time I go to track an event, and then when I bring it back. Being able to easily move it (dragging a pin on the app) is important to me.

So, there I was, with an open Terminal window on my Mac and no real idea what to do. My friend had just taken a very time-demanding job, so he was mostly unavailable. We’d grab a few minutes here and there, but at the end of the day what you need for this kind of thing is about 3 hours of solid “Let me walk you through this”. The reason you need 3 hours for an expert to help you is they have to deal with you making about 2 hours and 59 minutes worth of mistakes along the way. In this case, despite being extraordinarily generous, my friend just didn’t have that time to give at this moment. So…

In 40+ years of zinging around the sun on this spaceship we call Earth, I’ve found that if you ask enough people for help, read as much as you can on Google, and just keep going, you figure things out.

The following is a condensation of the process, leaving out all the mistakes I made over the course of a few days, including missing key formats, entering the wrong information, entering information incorrectly, using the wrong commands, forgetting a vital letter, relaying what I was seeing incorrectly to experts, and yep, even missing a single syntax hiccup.

Working with code can be VERY frustrating. If you get just one tiny thing wrong, the computer, the program, and in general, the world, doesn’t give a single shit. Still, when you get it right, it is extraordinarily satisfying.

Ok, here we go!

Step 1: Get the Helium Wallet onto your computer.

Start here and load Helium’s CLI wallet onto your local computer. Look for the “Releases” link, click that, then download the appropriate tar.gz file. You’ll need to unzip that, then you can run the full PATH or just use ./helium-wallet in front of your commands.

I like to start out by ls-ing, just so I have a record of what is where. I’m new at this, so the old hands may laugh at my constant ls habit, but it’s very useful for me.

nik@my-computer downloads % ls
helium-wallet-v1.6.8-x86-64-macos		helium-wallet-v1.6.8-x86-64-macos.tar.gz

Now that you’ve made sure you have what you need on your computer, the next step is to use it!

Before you go on, if you get stuck on any of these steps or want to know more, just type -h or –help at the end of your command. That’ll give you the help menu for that particular command or subcommand, which *can* be useful. It does NOT always tell you what you’re missing. Ask me how I know. 🙂

nik@my-computer Downloads % /Users/nik/Downloads/helium-wallet-v1.6.8-x86-64-macos/helium-wallet --help                                           
helium-wallet 1.6.8
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
    commit        Commit a transaction to the blockchain
    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
    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

Step 2: Load the selling wallet

This is the one with 24 words, so I needed to use “bip39” after the –seed command.

nik@my-computer ~ % /Users/nik/Downloads/helium-wallet-v1.6.8-x86-64-macos/helium-wallet create basic --seed bip39 --output adw-wallet.key
Space separated seed words:[this is where you enter your 24 word seed phrase]
Password: [enter the password you want to use for this wallet on this computer]

That will give you an output confirming you’ve loaded the correct wallet (it’d be hard to load the incorrect wallet, but it’s nice to see confirmation). I’ll show you what that looks like in the next step.

Step 3: Load the buying wallet

This is the 12 word “normal” wallet, so I used the “mobile” after the –seed command.

nik@my-computer downloads % /Users/nik/Downloads/helium-wallet-v1.6.8-x86-64-macos/helium-wallet create basic --seed mobile --output gki-wallet.key
Space separated seed words: [this is where you enter your 12 word seed phrase]
Password: [enter the password you want to use for this wallet on this computer]

That should give you an output that looks like this (you will have seen something similar when you loaded your selling wallet).

+---------+-----------------------------------------------------+
| Key     | Value                                               |
+---------+-----------------------------------------------------+
| Address | 14sT3TpAqxahjy6aGFvTHB4zqCX1mx31a1aYwNJ56TtzkM1DzQC |
+---------+-----------------------------------------------------+
| Sharded | false                                               |
+---------+-----------------------------------------------------+
| Verify  | true                                                |
+---------+-----------------------------------------------------+
| PwHash  | Argon2id13                                          |
+---------+-----------------------------------------------------+

The address in that table should match your buying wallet’s address.

Step 4: Use the CLI “sell” command

This tells the blockchain what your selling wallet is doing (“transferring” a hotspot.)

nik@my-computer Downloads % /Users/nik/Downloads/helium-wallet-v1.6.8-x86-64-macos/helium-wallet -f adw-wallet.key hotspots transfer sell 11oXZSoRW7pLQppvbQfbipzPpe4DbuUzssKHvKHkvWjvvJ5FmyW 14sT3TpAqxahjy6aGFvTHB4zqCX1mx31a1aYwNJ56TtzkM1DzQC  
Password: [the password to the selling wallet's key file]

Funnily enough, you don’t need to use the “commit” subcommand when you sell, only when you buy. Weird. Anyhoo…that Sell command will give you an output like this:

2gGvAQohAGmlHdiIljDi7IOvWS2+Cx8fVYwRumnnfw3rrz/cnCdWEiEBcUAYhbrCcB2pYOhl3osDLN9SSPP1WOmzB21uDUKLDB8aIQH9o5Dm6AUfxvGboCq4knzehnEZGWs4NN2MGNuPu1zMmCJAxsNIL0AHvrbUcYgXcRryKIYCTTR7wY0hBSqn50E9dhz9jwjCtH621HDFVNpCghnb/AonxlOWxE8GPsTVYpsFCEDYrQM=

You’ll need that in the next step.

Step 5: Use the CLI “buy” command to receive the sold hotspot.

nik@my-computer Downloads % /Users/nik/Downloads/helium-wallet-v1.6.8-x86-64-macos/helium-wallet -f gki-wallet.key hotspots transfer buy --commit 2gGvAQohAGmlHdiIljDi7IOvWS2+Cx8fVYwRumnnfw3rrz/cnCdWEiEBcUAYhbrCcB2pYOhl3osDLN9SSPP1WOmzB21uDUKLDB8aIQH9o5Dm6AUfxvGboCq4knzehnEZGWs4NN2MGNuPu1zMmCJAxsNIL0AHvrbUcYgXcRryKIYCTTR7wY0hBSqn50E9dhz9jwjCtH621HDFVNpCghnb/AonxlOWxE8GPsTVYpsFCEDYrQM=
Password: [the password to the selling wallet's key file]

Hit “enter” after your password, and you should see something like this:

{
    "hash": "AfPo-ulQVWAMQVNT8z309XvBVQGEDM5qxoo9a1wJ8kA",
    "txn": "2gHxAQohAGmlHdiIljDi7IOvWS2+Cx8fVYwRumnnfw3rrz/cnCdWEiEBcUAYhbrCcB2pYOhl3osDLN9SSPP1WOmzB21uDUKLDB8aIQH9o5Dm6AUfxvGboCq4knzehnEZGWs4NN2MGNuPu1zMmCJAxsNIL0AHvrbUcYgXcRryKIYCTTR7wY0hBSqn50E9dhz9jwjCtH621HDFVNpCghnb/AonxlOWxE8GPsTVYpsFCCpARz7hD7AUaswLWe0H+99OtesPqKCyLuToqpTvlR6QezVx0I4bRtOdrGB7NoGtQXRFWVeOKS3Y2g6RB31gTEUGAUDYrQM="
}

Step 6: Check your work using the Helium API.

Copy and paste that “hash” from above into the Pending Transactions URL on the Helium API, like this:

https://api.helium.io/v1/pending_transactions/AfPo-ulQVWAMQVNT8z309XvBVQGEDM5qxoo9a1wJ8kA

At first it’ll return something that says “pending”, but after a few tense minutes of wondering whether you got it all right, something like this should come up. The key thing you’re looking for is that the “status” changes to “cleared”.

{"data":[{"updated_at":"2021-09-15T14:49:03.471321Z","type":"transfer_hotspot_v1","txn":{"type":"transfer_hotspot_v1","seller":"13od1JZtPrqJY8dAQoDVwGmDWYcPUGXqfXMyGsDGznPXDBUREd4","hash":"AfPo-ulQVWAMQVNT8z309XvBVQGEDM5qxoo9a1wJ8kA","gateway":"11oXZSoRW7pLQppvbQfbipzPpe4DbuUzssKHvKHkvWjvvJ5FmyW","fee":55000,"buyer_nonce":0,"buyer":"14sT3TpAqxahjy6aGFvTHB4zqCX1mx31a1aYwNJ56TtzkM1DzQC","amount_to_seller":0},"status":"cleared","hash":"AfPo-ulQVWAMQVNT8z309XvBVQGEDM5qxoo9a1wJ8kA","failed_reason":"","created_at":"2021-09-15T14:48:30.013020Z"}]}

Step 7: Relax. You’re done.

My great hope is that this saves at least one person the few days it took me to bumble through this. An enormous thanks to @madninja, @tteague and @jerm at Helium for shining a light or holding my hand through the worst parts, and a generous thanks to the many anonymous or unnamed folks who left clues throughout the internet for me.

Rock on, Heliites!