the helium CLI wallet

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!

6 thoughts on “The Helium CLI Wallet – Not For The Faint Of Heart”

  1. I learned to used the CLI wallet a few weeks back, because I wanted to store my HNT with my Ledger wallet. Now I do not have to worry about “not my keys not my coin”, I feel much better more secure keeping it stored there.

  2. Nic,
    Thanks for writing this blog post. Can you shoot a screen capture video showing us how to do this on Windows 10.
    It’s seems like 90% of the videos talking about creating a CLI wallet are made by people run Mac OS or Linux. All of the
    videos made by Helium, are by or are for developers. People like me and you, don’t seem to exist. Or maybe there is an infinitesimal number of us that don’t know how to do this. That video would be perfect for your YouTube Channel.

    @Brandon- Once I get one set up, I want to do the same thing.

  3. Hi Gary, I’m actually on a Mac with no Windows around, sorry mate! I get your frustration though. Just keep going and looking into it, you’ll get it!

  4. Hi Nik! I did this quite a few times in October without much problem. Now, however, it seems as if they have changed the commands and the workflow. It seems to me that I should do

    helium-wallet.exe -f wallet.key hotspots transfer –commit

    I get some output and a hash, but no base64 string. Do you know how to transfer hotspots now? Really happy for some help.

  5. Hi Hampus, the best place to get help is over in the Discord in the official Helium Server, look for #cli-wallet-development

  6. Thank you.
    I just figured this out today with a Ledger. It took we a couple weeks of frustration before realizing that I could drag and drop the cli file to create a new directory…..
    Years of working with Adobe has shown me that the answer to every annoying issue is a couple simple key strokes away from success. It’ just figuring it out.

Leave a Comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Scroll to Top