Setting up Gateway
Below, we show you how to install and use Gateway from a non-technical trader's perspective. You'll run a command from the Hummingbot client that installs, configures, and uses the Gateway Docker image to connect to DEXs.
Alternatively, you can run a standalone Gateway server and connect the Hummingbot client to it manually, which offers more customizability. We recommend this path for developers adding DEX connectors or otherwise modifying Gateway. See Setting up Gateway for Developers for instructions on this workflow.
Installing Gateway from the Hummingbot client requires Docker to be installed on the host system. You can find instructions on how to install Docker from Docker's website:
Setting up Gateway¶
Inside the main Hummingbot console, issue the command:
This initializes Gateway as a Docker container in your system. Once Gateway has been initialized, it will be automatically started whenever you start Hummingbot.
Once you see the message "Loaded new configs into Gateway container", and the "Gateway" status flips to "ON" in the status bar, your Gateway installation is ready to use.
Connecting to a DEX¶
Once Gateway is up and running, you can then use
gateway connect to add connections to decentralized exchanges.
Let's say you want to connect to Uniswap:
gateway connect uniswap
You will then be asked about which instance of Uniswap you want to connect. You'll be asked to specify a Layer 1 blockchain (i.e.
polygon) and network (i.e.
optimism, etc), and then the private key of your wallet. See the Uniswap documentation page for which chains and network it support.
Once your wallet has been connected to the gateway, you can the test the connection by running
And you should see your wallet balance on the native blockchain asset (i.e. ETH for Uniswap / Ethereum, AVAX for Pangolin / Avalanche) for your connected networks related to the decentralized exchanges. Other ERC20 token assets on your wallet will only be displayed once you have loaded an amm_arb strategy.
Changing Gateway configuration¶
Gateway supports a robust configuration management system for each supported chain, network and exchange. You can see all the current configuration by running:
Afterwards, change a setting by running:
gateway config <chain>.networks.<network>.<setting>
For example, to change the
nodeURL for Ethereum mainnet, you can run
gateway config ethereum.networks.mainnet.nodeURL. To change the
nodeURL for the Ethereum testnets, run
gateway config ethereum.networks.kovan.nodeURL and
gateway config ethereum.networks.ropsten.nodeURL.
Why does Gateway continually emit disconnection messages?
Any time you change a Gateway config, it restarts in order to propagate that setting across other related settings. Therefore, you may see log messages about Gateway losing and re-establishing connection. If Gateway doesn't restart, you can force it to start by running
Click here to see the different gateway commands.
Connecting to a node provider¶
Connecting to a node provider is necessary for Hummingbot to receive and send data to a blockchain network. Alternatively, you can also run your own node client and connect to its RPC URL. This is set by the
nodeURL configuration parameter for each network.
To help new users use Gateway, Hummingbot assumes a default
nodeURL for each supported chain/network and automatically connects to it when users connect to a DEX. The default
nodeURL for each chain/network uses Ankr RPC endpoints where available, since they do not require users to sign up for an account.
For certain testnet or other networks that Ankr doesn't support, the default
nodeURL may be an alternate public endpoint, or in certain cases, an Infura endpoint, which users need to configure with their Infura key to use (see Changing Gateway configuration).
For a list of the default parameters including
nodeURL for each chain/network, see Ethereum and EVM-Based Chains.
Working with Token Lists¶
When trading across different blockchains, it's very important to understand how symbols map to addresses for each chain/network. In Hummingbot, each chain/network defines a
tokenListSource (path to the designated file or URL), which uses the Token Lists standard to define a token dictionary for each network.
You can edit the
tokenListSource parameters for each network by running
gateway config (see Changing Gateway configuration)
For a list of the default parameters including
tokenListSource for each chain/network, see Ethereum and EVM-Based Chains.
Adding tokens to
To have the
balance command report balances for a specific token symbol, use the
gateway connector-tokens command.
For instance, you can run the following command from the Hummingbot client:
# format: gateway connector-tokens [connector_chain_network] [symbol] >>> gateway connector-tokens uniswap_ethereum_mainnet UNI The 'balance' command will now report token balances UNI for 'uniswap_ethereum_mainnet'.
Certain DEXs like Uniswap and TraderJoe automatically wrap native tokens that are not ERC-20, so that users can trade tokens such as
AVAX through the interface. Behind the scenes, these exchanges automatically wrap these tokens into ERC-20 compliant
Gateway does not auto-wrap tokens by default, so users need to wrap native tokens into ERC-20 tokens before using them with Gateway. As of the
v1.4.0 release, there is no error message that lets you know if the token can't be used when it's not wrapped and instead will just display
"Markets are not ready" but we are working on adding more informative messages within the next few releases.
On Ethereum and EVM-compatible chains, wallets need to approve other addresses such as DEXs before they can send tokens to them, creating an allowance.
When you start a strategy that interacts with a DEX connector, Hummingbot will automatically send an
approve transaction for the DEX from your wallet, if your wallet does not have an existing allowance with the DEX contract. Hummingbot will wait for the
allowance to be created before starting the strategy.