Creating a private test net

This guide will walk you through the process of setting up your own private network using Catapult’s technology.

To run the network, we are going to use the package Catapult Service Bootstrap. This software suite contains the necessary setup scripts to help developers to quickly build their own network.


This bootstrap setup is for learning and development purposes and it should not power any production Catapult instances.

Catapult Service Bootstrap deploys a private network with the following high-level architecture:


Bootstrap network architecture

  • peer-node (1 and 2): Peer nodes verify transactions once the API pushes them into the P2P network. They run the consensus algorithm, create new blocks, and propagate the changes through the network.
  • api-node: The API node stores data in the MongoDB database once transactions are validated. They also identify and store partial aggregate bonded transactions.
  • rest-gateway: Combines HTTP and WebSockets to perform read and write actions on the blockchain.

Hardware requirements

Catapult Service Bootstrap has been tested on computers with the following minimum requirements.

  • CPU: 2 cores or more
  • Memory: 4GB or more
  • HD: 20GB or more
  • OS: Linux or Mac


Although you might be able to run the software in less powerful instances, you might encounter some issues while installing or running the node.

Environment requirements

The setup scripts are automated using docker. To run a test net node, you will need to have installed the following docker tools:


  1. Use this link to download the latest release of the package, or clone the repository directly using Git.
git clone
  1. Open the catapult-service-bootstrap folder.
cd catapult-service-bootstrap
  1. (Optional) Customize the network’s configurable parameters before launching it.
  2. Run the network.


To run the docker containers in the background of your terminal, you can run the service in detached mode using the option --detach or -d.

  1. Verify that the node is running by opening a new browser tab with the following URL: localhost:3000/chain/height.

To stop the process, press Ctrl+C.


Command Description
./cmds/clean-data Delete all of the blockchain and cache data, keeping the configuration and generated keys.
./cmds/clean-all Clean the data and additionally will remove the generated keys and the configuration generated from these keys.
./cmds/run-api-recovery Run the API recovery service.
./cmds/setup-network Create the nemesis block and generate all the config files if they do not already exist on disk.
./cmds/start-all Create config and nemesis if it doesn’t exist and starts up all services.
./cmds/start-api-db Start the MongoDB instance and configure schema/indexes if needed.
./cmds/start-api-node Start the API node.
./cmds/start-catapult-api Start the API node and REST gateway services.
./cmds/start-catapult-api-broker Start just the API broker service.
./cmds/start-catapult-peers Start peer0 and peer1 services only.
./cmds/stop-all Stop all the services.
./cmds/stop-api-db Stop the MongoDB service.
./cmds/stop-api-node Stop the API node.
./cmds/stop-catapult-api Stop the API node and REST gateway services.
./cmds/stop-catapult-api-broker Stop just the API broker service.
./cmds/stop-catapult-peers Stop peer0 and peer1 services.
./cmds/stop-catapult-api-broker Stop just the API broker service.

Getting test currency

An account is a deposit box where you can hold mosaics (tokens) and interact with them announcing transactions. To announce a transaction, the sender should pay a fee to provide an incentive to those who validate and secure the network and run the infrastructure. This cost is paid in cat.currency mosaics, the default network token.

After running the catapult-service-bootstrap tool for the first time, the available currency supply is distributed between a generated set of accounts. To keep one of these accounts quickly retrievable, we are going to store one of them using a command-line tool to conveniently perform the most commonly used actions i.e. interact with the blockchain, setting up an account, sending funds, etc.

  1. Install NEM2-CLI.
npm install --global nem2-cli

2. Open a new terminal window. Then, go to the directory where the bootstrap tool has generated the addresses.

cd  build/generated-addresses/
  1. Display the content of the addresses.yaml file.
cat addresses.yaml

4. Under the section nemesis_addresses, you will find the key pairs which contain cat.currency. Copy the private key of the first account.

  1. Type the command nem2-cli profile import using the key obtained in the previous step.
nem2-cli profile import

Introduce network type (MIJIN_TEST, MIJIN, MAIN_NET, TEST_NET): TEST_NET
Introduce your private key: 123***456
Introduce NEM2 Node URL. (Example: http://localhost:3000): http://localhost:3000
Insert profile name: base-profile

You should see the account credentials in your terminal.

Profile stored correctly
│ Property    │ Value                                                            │
│ Address     │ SCVG35-ZSPMYP-L2POZQ-JGSVEG-RYOJ3V-BNIU3U-N2E6                   │
│ Public Key  │ 654...321                                                        │
│ Private Key │ 123...456                                                        │

As the name suggests, the private key has to be kept secret at all times. Anyone with access to the private key ultimately has control over the account. On the other hand, you can share securely the public and address of your account with other participants of the network to receive transactions from them.

Now that you have your node running an account with some cat.currency, we recommend you to surf the NEM Developer Center. In this portal, you can find everything you need to know about Catapult’s features and self-paced guides on how to use the software development kits.