Hummingbot Academy

Quickstart Guide for amm_arb

This guide shows you how to show how to install and run the new amm_arb strategy. The amm_arb strategy, which we describe in this blog post, lets you arbitrage price differences between AMM protocols like Balancer and order book exchanges.

You'll learn how to:

  1. Install Hummingbot (Docker)
  2. Set up Hummingbot
  3. Install and configure Hummingbot Gateway
  4. Run the amm_arb strategy

Let's get started!

1. Install Hummingbot (Docker)

Note: If you have already installed Hummingbot v0.33 or higher using Docker or from source, you can skip this step.

Since amm_arb requires Hummingbot Gateway, a separate repository, you have to install Hummingbot either using Docker or from source to run it. This strategy will not work if you install Hummingbot with the Windows or macOS installers.

First, let's install the Docker version of Hummingbot. We have guides for each OS:

If installation is successful, you should see the Hummingbot client interface:

Hummingbot command line interface

2. Set up Hummingbot

Next, we need to add our credentials to the Hummingbot client so that it can trade on both the AMM protocol and an order book exchange.

We'll also configure Hummingbot to work with Hummingbot Gateway, a separate module that facilitates communication with blockchain protocols. Since Gateway is a separate web server that resides in the same local machine as Hummingbot, we need to make sure that all communications between the two are securely encrypted.

Create a secure password

If you are using Hummingbot for the first time on this machine, the system will prompt you to create a password. This password will be used to encrypt sensitive configuration settings e.g. API keys, secret keys and wallet private keys.

Enter exchange API keys

Since amm_arb arbitrages price differences between an AMM protocol and a centralized exchange, you have to enter in your credentials for both before you can start trading. Let's enter the exchange API keys first.

Hummingbot requires trade enabled API keys to access your exchange account. For exchange-specific information on how to find your API keys, please see the See all connectors page in the Hummingbot docs.

Enter the command connect to see what exchanges are available. Afterwards, enter connect [exchange] to connect your exchange account to Hummingbot by adding API keys, where [exchange]is one of the exchanges supported by Hummingbot.

>>> connect binance
Enter your Binance API key
>>> ****************************

Enter your Binance API secret
>>> ****************************

You are now connected to binance.

See See all connectors for a list of available exchanges.

Set up Ethereum wallet and node

Next, we will add our Ethereum wallet and connect to an Ethereum node, which are needed to submit transactions on the Ethereum blockchain.

Note: If you are running amm_arb on an non-Ethereum protocol, the instructions below may not apply.

Enter the command connect ethereum and add the private key associated with your Ethereum wallet. Hummingbot stores both your private key and exchange API keys in encrypted form.

>>> connect ethereum
Enter your wallet private key
>>> ****************************

Wallet 0x...xxxx connected to hummingbot.

Next, enter config ethereum_rpc_url and enter the URL of your Infura node.

>>> config ethereum_rpc_url
Which Ethereum node would you like your client to connect to?

Note that we'll need this URL again later when we set up Hummingbot Gateway.

Note: To see how to set up your own Ethereum node or other providers besides Infura, please see Advanced Configuration - Ethereum Nodes.

Add ETH Gas Station API key

ETH Gas Station is a free site that tracks real-time Ethereum gas prices. Since Ethereum gas prices are highly volatile, we recommend adding an API key so that the client can incorporate live gas prices when a running a bot.

To get a free API key for ETH Gas Station, visit DefiPulse Data and create an account. Afterwards, save the API key for use in Hummingbot:

Getting a ETH Gas Station API key from DeFiPulse

Next, run the following commands to input your ETH Gas Station API key and tell Hummingbot to use it for gas price lookups:

>>> config ethgasstation_gas_enabled
Do you want to enable Ethereum gas station price lookup?
>>> Yes

>>> config ethgasstation_api_key
Enter API key for gas station API
>>> **************

>>> config ethgasstation_gas_level
Enter gas level you want to use for Ethereum transactions (fast, fastest, safeLow, average)
>>> fast (or another option)

Note: You can also manually set the gas price by running config manual_gas_price

Create SSL Cert in Hummingbot

Finally, we will generate an SSL certificate that secures communications between the Hummingbot client and Hummingbot Gateway.

Enter generate_certs to create the SSL cert:

>>>  generate_certs
Enter passphrase to generate Gateway SSL certification
>>> [your secret passphrase]

Gateway SSL certification files are created in /Users/[USERNAME]/hummingbot/certs

Write down your passphrase and the certification path, since we'll need it shortly.

Getting the Certs Path: If you need to fetch the certification path later on, go to the directory where your Hummingbot files are stored. If you accepted the default options when installing the Docker version of Hummingbot, there will be a /hummingbot_files directory on your machine. Go to it and run cd certs to enter the certs folder. Then, you can run pwd from inside the certs directory to get the absolute path.

3. Install and configure Hummingbot Gateway

Hummingbot Gateway is a light web server with connectors to various blockchain. It allows the Python-based Hummingbot client to interact with protocols like Balancer that utilize Javascript modules.

Install Gateway

From Terminal or Bash, run the following commands to download and execute the installation script:

# Download Hummingbot Gateway install
curl -o
curl -o

# Enable script permissions
chmod a+x

# Create a gateway instance

Configure Gateway

The script asks you some questions to complete the installation process:

===============  CREATE A NEW GATEWAY INSTANCE ===============

ℹ️  Press [ENTER] for default values:

For the first 3 questions, you can press ENTER to accept the default values:

Enter Gateway version you want to use [latest/development] (default = "latest") >>>
Enter a name for your new Gateway instance (default = "gateway-instance") >>>
Enter Balancer network you want to use [mainnet/kovan] (default = "mainnet") >>>

Enter the absolute path to the certs folder that you wrote down in Step 2:

Enter the full location path where your Hummingbot cert files are located
>>> /Users/[USERNAME]/hummingbot/certs

Enter your Infura node URL that you added in Step 2:

Enter the Ethereum RPC URL set in your Hummingbot instance

Enter the passphrase that you used to generate the SSL certificate in Step 2:

Enter your Gateway cert passphrase configured in Hummingbot
>>> [your secret passphrase]

Afterwards, review the information and enter Yes to complete the Gateway configuration:

Changing Ports: By default, Gateway will install on port 5000 that Hummingbot uses to connect to . If port 5000 is not available, Gateway will increment the port number and use port 5001. If the port is 5001, run config gateway_api_port in Hummingbot to set the correct port.

4. Run an amm_arb bot

Now, we can finally configure an amm_arb bot that arbitrages between AMM protocols and order book exchanges!

Configure the bot

Use the create command to build a strategy configuration file:

What is your market making strategy?
>>> amm_arb

Enter your first connector (exchange/AMM)?
>>> balancer

Enter the token trading pair you would like to trade on balancer (e.g. WETH-DAI)

Enter your second connector (exchange/AMM)?
>>> binance

Enter the token trading pair you would like to trade on binance (e.g. ZRX-ETH)

What is the amount of WETH per order?
>>> [order_amount]

What is the minimum profitability for you to make a trade (Enter 1 to indicate 1%)?
>>> 1

# Buffer added to the price to account for price movement before trade execution
How much buffer do you want to add to the price to account for slippage for orders on the first market (Enter 1 for 1%)?
>>> 0.1

How much buffer do you want to add to the price to account for slippage for orders on the second market (Enter 1 for 1%)?
>>> 0.1

# If true the bot submits both arbitrage taker orders (buy and sell) simultaneously.
# If false, the bot will wait for first exchange order filled before submitting the other order.
Do you want to submit both arb order concurrently (Yes/No)?
>>> Yes

For details on each parameter above, see Strategies - AMM Arb.

Adding Ethereum tokens: To add token addresses to the the list of Ethereum tokens maintained by Hummingbot, edit the following file in the Hummingbot directory (if you installed from source): /hummingbot/hummingbot/wallet/ethereum/erc20_tokens.json. We intend to simplify this process in future versions of Hummingbot.

Run the bot

Enter start to run the bot.

The perform will perform checks to ensure that it can connect to both the protocol and the exchange. Afterwards, the bot will automatically call the approve function on any tokens that need approval.

Then, the bot will continually scan for arbitrage opportunities and execute trades to capture them.

Enter status to see the current profitability of each arbitrage leg.

Enter history to see what trades your bot has made in the current session.

Checking Transaction Status: To check the status of submitted transactions, go to Etherscan to check if any pending transaction gets stuck for too long (> 5 min). If any transactions are stuck, consider changing the config ethgasstation_gas_level to fast or fastest.

DISCLAIMER: The websites located at,, (collectively, the "Site") are copyrighted works belonging to CoinAlpha, Inc. ("Company", "us", "our", and "we"). Certain features of the Site may be subject to additional guidelines, terms, or rules, which will be posted on the Site in connection with such features. All such additional terms, guidelines, and rules are incorporated by reference into these Terms. These terms of use (these "Terms") set forth the legally binding terms and conditions that govern your use of the Site. By accessing or using the Site, you are accepting these Terms (on behalf of yourself or the entity that you represent), and you represent and warrant that you have the right, authority, and capacity to enter into these terms (on behalf of yourself or the entity that you represent). You may not access or use the Site or accept the terms if you are not at least 18 years old. If you do not agree with all of the provisions of these terms, do not access and/or use the Site.