The Helium CLI Wallet — Not For The Faint Of Heart

There’s almost no good rea­son to use the CLI (Com­mand Line Inter­face) wal­let for a nor­mal per­son, but…not every­one who gets into Heli­um is nor­mal. If, like me, you’re faced with hav­ing to use it, this series of instruc­tions might help. 

This is NOT writ­ten for experts who know what they’re doing; they’ll laugh at this. This is NOT writ­ten for most of the Heli­um com­mu­ni­ty. Trust me, you don’t need to use the CLI wal­let for reg­u­lar tasks. This IS writ­ten for some­one like me; slight­ly curi­ous, dri­ven by the usu­al HNT incen­tives, and will­ing to futz around with things they don’t under­stand. If that’s you, enjoy!

It start­ed off with a friend of mine cre­at­ing a 24 word wal­let. Yes, you can cre­ate those, just not on the Heli­um app. 

We were test­ing a hotspot I’d sent him and want­ed it to “live” in its own wal­let dur­ing test­ing. Once test­ing wrapped up, I want­ed to move the hotspot from the wal­let where it was to anoth­er wal­let where I have oth­er hotspots. This was in part just to keep all HNT earn­ings in one place, and in part to have (MUCH) eas­i­er con­trol over it for me, as a “gen­er­al­ly-non-code-using” mem­ber of the Heli­um community.

Now, my friend is a secu­ri­ty wiz­ard and flu­ent in about a mil­lion cod­ing lan­guages, so for him man­ag­ing any­thing via CLI is just stan­dard stuff. For me, it was more like being thrown in the mid­dle of a Russ­ian street fair know­ing I had to buy a very spe­cif­ic item; say a 17mm hex head bolt with a thread pitch of 1.6.

I don’t speak Russ­ian, but damn, I real­ly want­ed that hex head bolt! 

This par­tic­u­lar hotspot serves as one of my track­ing units, so I re-assert the loca­tion every time I go to track an event, and then when I bring it back. Being able to eas­i­ly move it (drag­ging a pin on the app) is impor­tant to me. 

So, there I was, with an open Ter­mi­nal win­dow on my Mac and no real idea what to do. My friend had just tak­en a very time-demand­ing job, so he was most­ly unavail­able. We’d grab a few min­utes here and there, but at the end of the day what you need for this kind of thing is about 3 hours of sol­id “Let me walk you through this”. The rea­son you need 3 hours for an expert to help you is they have to deal with you mak­ing about 2 hours and 59 min­utes worth of mis­takes along the way. In this case, despite being extra­or­di­nar­i­ly gen­er­ous, my friend just did­n’t have that time to give at this moment. So…

In 40+ years of zing­ing around the sun on this space­ship we call Earth, I’ve found that if you ask enough peo­ple for help, read as much as you can on Google, and just keep going, you fig­ure things out. 

The fol­low­ing is a con­den­sa­tion of the process, leav­ing out all the mis­takes I made over the course of a few days, includ­ing miss­ing key for­mats, enter­ing the wrong infor­ma­tion, enter­ing infor­ma­tion incor­rect­ly, using the wrong com­mands, for­get­ting a vital let­ter, relay­ing what I was see­ing incor­rect­ly to experts, and yep, even miss­ing a sin­gle syn­tax hiccup. 

Work­ing with code can be VERY frus­trat­ing. If you get just one tiny thing wrong, the com­put­er, the pro­gram, and in gen­er­al, the world, does­n’t give a sin­gle shit. Still, when you get it right, it is extra­or­di­nar­i­ly satisfying.

Ok, here we go!

Step 1: Get the Helium Wallet onto your computer.

Start here and load Heli­um’s CLI wal­let onto your local com­put­er. Look for the “Releas­es” link, click that, then down­load the appro­pri­ate 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 con­stant ls habit, but it’s very use­ful 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 com­put­er, 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 com­mand. That’ll give you the help menu for that par­tic­u­lar com­mand or sub­com­mand, which *can* be use­ful. It does NOT always tell you what you’re miss­ing. 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 need­ed 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 out­put con­firm­ing you’ve loaded the cor­rect wal­let (it’d be hard to load the incor­rect wal­let, but it’s nice to see con­fir­ma­tion). I’ll show you what that looks like in the next step.

Step 3: Load the buying wallet 

This is the 12 word “nor­mal” wal­let, 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 out­put that looks like this (you will have seen some­thing sim­i­lar when you loaded your sell­ing wallet).

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

The address in that table should match your buy­ing wal­let’s address.

Step 4: Use the CLI “sell” command

This tells the blockchain what your sell­ing wal­let is doing (“trans­fer­ring” 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]

Fun­ni­ly enough, you don’t need to use the “com­mit” sub­com­mand when you sell, only when you buy. Weird. Anyhoo…that Sell com­mand will give you an out­put 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 pass­word, and you should see some­thing 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 Pend­ing Trans­ac­tions URL on the Heli­um API, like this:

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

At first it’ll return some­thing that says “pend­ing”, but after a few tense min­utes of won­der­ing whether you got it all right, some­thing like this should come up. The key thing you’re look­ing for is that the “sta­tus” 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 per­son the few days it took me to bum­ble through this. An enor­mous thanks to @madninja, @tteague and @jerm at Heli­um for shin­ing a light or hold­ing my hand through the worst parts, and a gen­er­ous thanks to the many anony­mous or unnamed folks who left clues through­out the inter­net for me. 

Rock on, Heliites!