Open source guides and documentation for the IoTeX network


Using the testnet

IoTeX testnet via MacOS/Linux

If you don't already have Docker installed on your machine, you can download it here

First, download the testnet software from the official IoTeX github. You can achieve this by opening cmd and running:

git clone

Or if you don't have Git installed, you can simply download the .zip and extract it.

Configuring your node

Open the config.yaml file and add your external IP address next to the externalHost parameter. You can find your external IP address by simply searching the words "IP address" in Google.

The first 6 lines of the config file should look something like this:

externalPort: 4689
- '/dns4/'
- '/dns4/'
Using the config

We can now use that edited config file to tell our docker container how to run and where to store blockchain data. In your terminal, do the following:

cd iotex-testnet
mkdir -p $IOTEX_HOME/data
mkdir -p $IOTEX_HOME/log
mkdir -p $IOTEX_HOME/etc
cp config.yaml $IOTEX_HOME/etc/
cp genesis.yaml $IOTEX_HOME/etc/

We're already ready to run our testnet node! Open your terminal and run:

docker run -d --name iotxplorer-testnet-tutorial \
-p 4689:4689 \
-p 14014:14014 \
-p 8080:8080 \
-v=$IOTEX_HOME/data:/var/data:rw \
-v=$IOTEX_HOME/log:/var/log:rw \
-v=$IOTEX_HOME/etc/config.yaml:/etc/iotex/config_override.yaml:ro \
-v=$IOTEX_HOME/etc/genesis.yaml:/etc/iotex/genesis.yaml:ro \
iotex/iotex-core:v0.5.0-rc5-hotfix1 \
iotex-server \
-config-path=/etc/iotex/config_override.yaml \
-genesis-path=/etc/iotex/genesis.yaml \
NOTE: You have to replace v0.5.0-rc5-hotfix1 in the above block to be the correct name of the current testnet version. At the time of writing this guide, the version is v0.5.0-rc5-hotfix1.
Is it working?

To check that it's all working correctly let's ask docker. In your terminal, type docker container ls. This will bring up a list of all running containers. You should see a container id, image name, and iotxplorer-testnet-tutorial in the entry.

Now that we've confirmed the container is running, lets check the logs. Logs tell us everything going on in the blockchain. First open terminal. You have two choices, you can run

docker logs -f iotxplorer-testnet-tutorial

but that will get you some unformatted/hard to follow logs. For a prettier logging experience, we use

docker logs -f --tail 20 IoTeX-Node | sed 's/,"errorVerbose":"[^"]*"//g' | jq

which puts the responses in a readable JSON format.

Ok, so I started a node. What now?
Read the next section on 'Interacting with the IoTeX network' to find out.

Interacting with the IoTeX blockchain


ioctl is a command-line interface for interacting with IoTeX blockchains. With it, we can do things like check our delegate status, claim rewards, make accounts, wallets, post smart contracts, etc.


ioctl can actually be used outside of the container we just ran! You can use it anywhere on your computer after installing it. To install, open terminal and run:

curl | sh

Then make sure ioctl is pointing to the testnet to get its data:

ioctl config set endpoint

After it has finished downloading, simply type ioctl. You should then see some welcoming introductory text:

ioctl is a command-line interface for interacting with IoTeX blockchain.

ioctl [command]

Available Commands:
account Deal with accounts of IoTeX blockchain
action Deal with actions of IoTeX blockchain
bc Deal with block chain of IoTeX blockchain
config Set or get configuration for ioctl
help Help about any command
version Print the version number of ioctl
wallet Manage accounts

-h, --help help for ioctl
Use "ioctl [command] --help" for more information about a command.

This is help text for ioctl, it is fairly self explanatory, but lets do one test for clarity.

Making an iotex account

One use of ioctl is making accounts. To see how this works, type ioctl account create and bam! Like magic, you will get a response object containing a public and private key which you can use to do whatever you wish.

The other commands all work in a similar fashion, be encouraged to try out all the commands and explore the different things you can do alone. The next section will be all about how to get elected and use the testnet as a delegate.