Node API Check

Any syntax in <> brackets is a user’s unique variable/version. Exchange with a corresponding name without the <> brackets.

Operating a nym-node is not a “set and forget” endeavor, it takes some work. To diagnose node performance querying APIs is a good knowledge to have. There are two main places to look for API endpoints regarding nym-node:

Besides that, Gateway operators can check out their node performance, connectivity and much more on

Basic API usage

For information about available endpoints and their status, you can refer to:

# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
# for http
# or

# for reversed proxy/WSS

For example to determine which mode your node is running, you can check :8080/api/v1/roles endpoint:

# sustitude <NODE_IP_ADDRESS> or <NODE_DOMAIN> with a real one
# for http
# or

# for reversed proxy/WSS

To make this a bit easier, we made a CLI tool querying all available API endpoints based on node Identity Key (further denoted as <ID_KEY>) called To diagnose your node performance, whether by yourself or by sharing an output in our operator channel, this tool provides you with a quick overview of live data. We recommend to run this checker alongside nym_gateway_probe to triage both performance and an actual routing.

Besides querying any bonded node APIs, nym_api_check has a function counting all existing nodes in provided version.




  1. Start with installing Python3:
sudo apt install python3
  1. Make sure Python3 is your default Python version:
update-alternatives --install  /usr/bin/python python /usr/bin/python3 1

# controll
python --version

# should return higher than 3
  1. Install Python modules tabulate, pandas and argparse:
  • either using pip and then running:
pip install tabulate pandas argparse
  • or if you installed Python3 system-wide you can install modules directly:
sudo apt install python3-tabulate python3-pandas python3-argparse


  1. Get and api_endpoints.json. If you compiled from source, you already have both of these files. If you prefer to download them individually, do it by opening terminal in your desired location and running:

  1. Make executable:
chmod u+x

Now you are ready to check your node.


Run with --help flag to see the available commands:

./ –help

usage: Nym-node API check [-h] [-V]
                          {query_stats,q,query,version_count,v,version} ...

Run through all endpoints and print results.

positional arguments:
    query_stats (q, query)
                        Get all nodes API endpoints
    version_count (v, version)
                        Sum of nodes in given version(s)

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit


When you want to see all the options connected to a command, add a --help flag after the command of your choice, like in this example:

./ query_stats –help

usage: Nym-node API check query_stats [-h] [-n] [-m] [-o [OUTPUT]] id

positional arguments:
  id                    supply nym-node identity key

optional arguments:
  -h, --help            show this help message and exit
  -n, --no_routing_history
                        Display node stats without routing history
  -m, --markdown        Display results in markdown format
  -o [OUTPUT], --output [OUTPUT]
                        Save results to file (in current dir or supply with
                        path without filename)

The most common usage may be ./ query_stats <ID_KEY> where <ID_KEY> is required, substitute it with node Identity Key.

Optional arguments

--markdown-mreturns output in markdown format
--no_routing_history-nreturns output without routing history which can be lengthy
--output-oexports output to a file, possible to add a target path


Another command is version_count where at least one nym-node version is required. In case of multiple version count, separate the versions with space. We recommend to run this command with --markdown flag for a nicer output. This is an example where we want to look up how many registered nodes are on versions 1.1.0, 1.1.1, 1.1.2 and 1.1.3:

./node_api_check version_count 1.1.0 1.1.1 1.1.2 1.1.3 --markdown