Handshake logo
 \/\::/  /
   /:/  / 

HSD Configuration

By default, the mainnet hsd config files will reside in ~/.hsd/hsd.conf (node) and ~/.hsd/hsw.conf (wallet). Any parameter passed to hsd at startup will have precedence over the config file. Even if you are just running hs-client without hsd installed (to access a remote server, for example) the configuration files would still reside in ~/.hsd/

For example:

hsd --network=regtest --api-key=menace

will read the config file at ~/.hsd/regtest/hsd.conf and ignore any network or api-key parameters listed in that file.

All hsd configuration options work in the config file, CLI arguments, process environment, and in the constructor parameters when instantiating new node objects in JavaScript. Each method has slightly different formatting. Note specifically the usage of hyphens and capital letters. See the examples below:

config file CLI parameter environment variable JS object constructor
network: testnet --network=testnet export HSD_NETWORK=testnet {network: 'testnet'}
log-level: debug --log-level=debug export HSD_LOG_LEVEL=debug {logLevel: 'debug'}
max-outbound: 8 --max-outbound=8 export HSD_MAX_OUTBOUND=8 {maxOutbound: 8}
cors: true --cors export HSD_CORS=true {cors: true}

Keep in mind, that setting bash environment variable which will be passed to the hsd or hs-client subprocesses requires export command: export HSD_NETWORK=testnet.


The hsd datadir is determined by the prefix option. The following example wiil create a datadir of ~/.hsd_test, containing a chain database, wallet database and log file.

$ hsd --prefix ~/.hsd_test

Preprocessor Options

The following configuration settings are only available for the command line when hsd is launched. They WILL NOT be read from a hsd.conf file or pulled from the shell environment. This is because they are processed directly by the $PATH command which executes scripts in the repository at bin/hsd and bin/node.

Common Options

Node Options

Logger Options

Chain Options

Note that certain chain options affect the format and indexing of the chain database and must be passed in consistently each time.

Mempool Options

Pool Options

Miner Options


Note: For security cors should not be used with no-auth.
If enabled you should also enable wallet-auth and set api-key.

DNS Resolver options

Wallet options

These options must be saved in hsw.conf. They can also be passed as environment variables or command-line variables if they are preceded with a wallet- prefix (WALLET_ for env vars).

For example, to run a hsd and wallet node on a remote server that you can access from a local machine, you would could use the following examples:

Example using hsw.conf:

network: testnet
wallet-auth: true
api-key: hunter2

Example using CLI options:

$ ./bin/hsd --network=testnet --http-host= --wallet-http-host= --wallet-api-key=hunter2 --wallet-wallet-auth=true

Example using ENV:


hsd client:

Wallet database:

Wallet http server:

Default ports

main testnet regtest simnet
clearnet p2p 12038 13038 14038 15038
brontide p2p 44806 45806 46806 47806
node http 12037 13037 14037 15037
wallet http 12039 13039 14039 15039
root authoritative resolver 5349 15349 25349 35349
recursive resolver 5350 15350 25350 35350

Example Configurations

NOTE: unless otherwise specified in Preprocessor Options, only one set of options is needed to run with the example configuration. For example if you choose to use a hsd.conf file, you will not need to use the command line options.

Full Node with wallet

This may require up to 200 MB of disk space per day. It is the most private and secure way to use Handshake for transactions and auctions.

Command ~/.hsd/hsd.conf
hsd (none, default parameters are OK)

SPV Node with wallet

This may require up to 60 kB of disk space per day. SPV leaks some privacy and relies on being connecting to at least one “honest” full node, which may weaken overall security assumptions.

Command ~/.hsd/hsd.conf
hsd --spv (none, must use command line argument)

Pruned full node with wallet

This will never require more than 400 MB total. Only the last 288 blocks are saved to disk. Wallet rescans are impossible in this mode. This node will not relay historical blocks to new bootstrapping nodes but otherwise is fully validating and just as private and secure as any full node.

Command ~/.hsd/hsd.conf
hsd --prune prune: true

Full Node with wallet as separate process on same machine

Both of these commands must be executed to run full node and wallet separately.

Command ~/.hsd/hsd.conf
hsd --no-wallet (none, must use command line argument)
Command ~/.hsd/hsw.conf
hs-wallet (none, default parameters are OK)

Full Node with wallet as separate process on DIFFERENT machine

Both of these commands must be executed to run full node and wallet separately. To run wallet and node remotely, you MUST use a strong <API key> and enforce SSL on the full node. <https://URL> MUST be a resolvable domain name secured by legacy certificate authority SSL.

Command ~/.hsd/hsd.conf
hsd --no-wallet \
--api-key=<API KEY> \
--http-host=<https://URL> \
--ssl=true \
--ssl-cert=<path> \

api-key:<API key>
http-host: <https://URL>
ssl: true
ssl-cert: <path>
ssl-key: <path>
Command ~/.hsd/hsw.conf
hs-wallet \
--node-host=<https://URL> \
--node-ssl: true \
--node-api-key: <API key>

node-host: <https://URL>
node-ssl: true
node-api-key: <API key>

Full Node that allows inbound connections from other full and light clients like hnsd

<IP address> MUST be your external IP address, publicly accessible by the internet.

Command ~/.hsd/hsd.conf
hsd \
--bip37=true \
--listen=true \
--public-host=<IP address> \

public-host: <IP address>
max-inbound: 100

Full Node with public HNS recursive resolver

Note: if you configure this way it is strongly recommended to enable a firewall on your system to mitigate amplification attacks. This is not a recommended configuration for a fully public server. If your hsd node is running locally (on your home network or LAN) that should be OK. <IP address> MUST be publicly accessible by the internet (or just your local network if applicable). You could use for this but that may disrupt other DNS services using port 53 on the same machine.

Command ~/.hsd/hsd.conf
hsd \
--rs-host=<IP address> \

rs-host: <IP address>
rs-port: 53

Full Node in “nerd mode”

Useful if you are running a block explorer service or otherwise need access to all the data hsd could possibly provide.

Command ~/.hsd/hsd.conf
hsd \
--index-tx=true \
--index-address=true \

index-tx: true
index-address: true
log-level: spam

See a mistake? Open a pull request.