Skip to main content

Install headless wallet from source code


This article will guide you to install Hathor headless wallet from source code.



Ubuntu \ge v20.04; or macOS \ge 11; or Windows (WSL) \ge v10.


Node.js \ge v20.0.0


  1. Download the latest release of Hathor headless wallet.
  2. Install dependencies.
  3. Set up configurations.
  4. Launch the application.

Step 1: download the latest release of Hathor headless wallet

  1. Start a shell session.
  2. Change the working directory to where you want to store the application — namely, source code and database.
  3. Download the latest release of Hathor headless wallet:
git clone -b release

Step 2: install dependencies

  1. Change the working directory (the one you chose to store the application) to its child hathor-wallet-headless:
cd hathor-wallet-headless
  1. Install dependencies:
npm install

Step 3: set up configurations

  1. Copy the config.js.template file to src/, renaming it to config.js:
cp config.js.template src/config.js

Once you have Hathor headless wallet running, there will be three alternatives to start a wallet in the application: (1) by its seed phrase; (2) by its seed key; or (3) by its extended public key (in case of a read-only wallet). To start a wallet by its seed key, you must had previously added such seed key with an associated seed phrase into the config.js file.

If you already have a previously generated seed phrase (i.e., wallet), you may use it. Otherwise, you must generate a new seed phrase.

  1. (Optional) If you don't have a wallet seed phrase, generate a new one:
make words

The output will be a string of 24 random words.


Anyone with access to a seed phrase can manage the funds of the associated wallet. Also, you cannot manage your wallet without access to the seed phrase or the private keys generated from it. Thus, we strongly recommend storing a backup file (either digital or physical or both) of the seed phrase and keeping the backup and the chosen installation directory secure against unauthorized access.

  1. Open the config.js file.
  2. (Optional) Change the default configuration values of the application.
  3. (Optional) To be able to start a wallet by its seed key, add a key/value pair my_seed_nr_1: <24_words_seed_phrase_string> into the seeds object, replacing the my_seed_nr_1 with the desired key and the <24_words_seed_phrase_string> placeholder with its associated seed phrase:
module.exports = {


seeds: {
my_seed_nr_1: '<24_words_seed_phrase_string>',


  1. (Optional) You may repeat the last step as many times you want. In other words, you may define multiple seed keys in the seeds object, in order to start multiple wallets using them.

Step 4: launch the application

Start the wallet application:

npm start

By default, the application starts listening to port 8000 and connects to a public full node of the Hathor Network mainnet.

Task completed

You now have a running instance of Hathor headless wallet. To know how to operate and use this application, see Hathor headless wallet pathway.