Skip to main content

Install headless wallet from source code

Goal​

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

tip

Installing from source code is recommended only for the development of Hathor headless wallet or derived wallet applications. For production environments or for developing and testing other components, it is recommended to install the headless wallet via Docker or together with the full node using Docker Compose.

Requirements​

Requirements for operating Hathor headless wallet.

Hardware​

For production environment:

  • CPU: 2 vCPU
  • Memory: 0.5 GB
  • Bandwidth: 5 Gbps

Reference machine: AWS EC2 type t3.nano

Software​

  • Platform: Linux, macOS, or WSL
  • Node.js ≥\ge v22.12.0

Environment​

This article was created using the following environment:

  • Ubuntu 24.04.1 LTS
  • Node.js v22.12.0

Different environments may require different steps, or may not work at all.

Step-by-step​

  1. Download the latest release of Hathor headless wallet.
  2. Install dependencies.
  3. Set up configurations.
  4. Start 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 https://github.com/HathorNetwork/hathor-wallet-headless.git

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.

danger

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 of the seed phrase (either digital, physical, or both) and ensuring that both the backup and the chosen installation directory are protected against unauthorized access.

  1. Open the file src/config.js.
  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:
hathor-wallet-headless/src/config.js
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.