Skip to content

Setting up Gateway V2

Hummingbot Gateway is middleware that allows Hummingbot to connect to decentralized exchanges like Uniswap. You can setup the gateway V2 by following these steps.

The steps to set up Hummingbot to run with Gateway V2 are the same as setting up Hummingbot from source. The only additional thing to do is to check out the development branch.

Follow the instructions from Source. The only additional step is to do:

git checkout development


There are small changes made in the Hummingbot client for it to work with gateway-v2 so it's very important to have both the client and the gateway running from the same branch.



Run the following commands to install node and other dependencies. The example illustrates a Debian-based Linux Distro.

# Installing curl
sudo apt install curl

# Installing jq
sudo apt install jq

# Installs nodejs v14.x
curl -sL | sudo bash -
sudo apt-get install -y nodejs

# Installs Yarn
curl -sL | sudo apt-key add -
echo "deb stable main" | sudo tee /etc/apt/sources.list.d/yarn.list
sudo apt update && sudo apt install yarn


If you’re using homebrew execute the following command to install node and other dependencies.

# Using Homebrew installs node and yarn
brew install node
brew install yarn

# Installing curl
brew install curl

# Installing jq. Note: jq is like `sed` for JSON data
brew install jq

# Installing envsubst
brew install gettext
brew link --force gettext

Generating Configurations and SSL Certificates

There are bash scripts in $PROJECT_HOME/gateway/setup folder that can be used to generate the necessary configurations and certificates that will be used by both the Gateway Server and the Hummingbot Client.

  • Generate Certificates using Hummingbot Client
    • Run the Hummingbot client.
    • Run the gateway generate-certs command
    • The passphrase must be the same as the hummingbot client password
    • Take note of the directory in which the certs are being created. It will be used to configure ssl certifacte. Generate Certs
  • Generating the configuration Execute the following commands:

    cd $PROJECT_HOME/gateway/setup
    # Generates and configures the ethereum.yml conf to use the right Infura Eth node
    # $GATEWAY_CONF_FOLDER - Directory the ssl.yml file is located in
    # $CA_CERT_FILE_PATH - Intended value for the caCertificatePath configuration.
    # $CERT_FILE_PATH - Intended value for the certificatePath configuration.
    # KEY_FILE_PATH - Intended value for the keyPath configuration.


    1. $GATEWAY_CONF_FOLDER should be the $PROJECT_HOME/gateway/conf folder.

    2. For INFURA_PROJECT_ID, you can register for a free infura account and create your own Ethereum node for testing.

    3. The files passed to GATEWAY_CA_FILE, GATEWAY_SERVER_CERT_FILE, and GATEWAY_SERVER_KEY_FILE are generated by and should be under $PROJECT_HOME/gateway/certs.

  • List of Environment Variables

    Below is an example of environment variables that are used by the aforementioned scripts and within the Hummingbot Client

    # Used within Hummingbot client to initialize GatewayHttpClient
    export GATEWAY_CONF_FOLDER="/Users/<username>/hummingbot/gateway/conf"
    export CERT_FOLDER="/Users/<username>/.hummingbot-gateway/hummingbot-gateway-36191c46/certs"
    export GATEWAY_LOGS_FOLDER="/Users/<username>/.hummingbot-gateway/hummingbot-gateway-36191c46/logs"
    # Used to populate the Gateway conf accordingly
    export GATEWAY_CA_FILE="/Users/<username>/.hummingbot-gateway/hummingbot-gateway-36191c46/certs/ca_cert.pem"
    export GATEWAY_SERVER_CERT_FILE="/Users/<username>/.hummingbot-gateway/hummingbot-gateway-36191c46/certs/server_cert.pem"
    export GATEWAY_SERVER_KEY_FILE="/Users/<username>/.hummingbot-gateway/hummingbot-gateway-36191c46/certs/server_key.pem"
    # Used in curl commands for manual-testing
    export GATEWAY_CERT="/Users/<username>/.hummingbot-gateway/hummingbot-gateway-36191c46/certs/client_cert.pem"
    export GATEWAY_KEY="/Users/<username>/.hummingbot-gateway/hummingbot-gateway-36191c46/certs/client_key.pem"

Starting Server

Execute the following commands

# $PROJECT_HOME should be the root directory of the hummingbot project
cd $PROJECT_HOME/gateway

# Installs all dependencies defined

# Builds project
yarn build

# Starts the Gateway Server
yarn start --passphrase=$GATEWAY_PASSPHRASE


$GATEWAY_PASSPHRASE is the passphrase you set for the certificates when generating the ssl certificate. It should be the same as the hummingbot client password

Additional Configurations/Troubleshooting

  1. Changing Gateway Port

    In certain cases, the default port, 5000, might already be in use. As such you might need to change the port number accordingly. To do so modify the following yaml files accordingly:

    • $PROJECT_HOME/hummingbot/gateway/conf/server.yml

      port: <NEW_PORT_NUMBER>
      ipWhitelist: []
      unsafeDevModeWithHTTP: false
      GMTOffset: 800
      id: <ID>
    • $PROJECT_HOME/hummingbot/conf/conf_global.yml

      # Gateway API Configurations
      # default host to only use localhost
      # Port need to match the final installation port for Gateway
      gateway_api_host: localhost
      gateway_api_port: '<NEW_PORT_NUMBER>'

      NOTE: The NEW_PORT_NUMBER in conf_global.yml should be in single-quotations

  2. Getting a Error: could not detect network error Ensure that the nodeAPIKey of ethereum.yml and/or avalanche.yml is entered correctly.

    • If using Infura Node, the nodeAPIKey refers to your PROJECT ID

Testing using curl

Certain manual tests are defined in $PROJECT_HOME/gateway/manual-tests/ file. To run them, ensure that you have curl installed in your system.

Copy and paste individual commands into your terminal to execute the tests accordingly i.e.

curl -s -X GET -k --key $GATEWAY_KEY --cert $GATEWAY_CERT [https://localhost:5000/](https://localhost:500/) | jq

Expected Output:

  "status": "ok"

Last update: 2022-05-31