Skip to content

Quickstart Guides

Docker Installation Guide

Introduction

This brief guide will introduce you to the process of installing and deploying Hummingbot using Docker. You will learn step-by-step how to set up Hummingbot using Docker Compose, a tool for defining and running multi-container Docker applications, and then run your first algo trading strategy!

What You Will Learn

  1. Install Docker: Step-by-step instructions to installing Docker and Docker Compose,

  2. Hummingbot Interface: Uncover the essentials of the Hummingbot interface, including layout and navigation.

  3. Running a Script: Learn how to run an algo trading strategy as a Hummingbot script.

  4. Connecting API Keys: Master the crucial process of integrating API keys with Hummingbot, ensuring secure API-based bot trading across various exchanges.

Let's Begin!

With all the groundwork in place, it's time to unlock the full capabilities of your trading tools. Let's dive in!

1. Install Docker

Docker Installation Guide - 1 - Installation

System Prerequisites

Hummingbot runs on commodity hardware and does not require much memory or storage.

  • MacOS 10.12.6+ / Linux (Ubuntu 20.04+, Debian 10+) / Windows 10+
  • Memory: 4 GB RAM per instance
  • Storage: 5 GB HDD space per instance

Install Docker

For Windows Users

Hummingbot requires Windows Subsystem for Linux 2 (WSL2).

Install Linux on your Windows system: https://learn.microsoft.com/en-us/windows/wsl/install.

Afterwards, execute the following commands in your terminal to install Docker: 

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER

For Mac Users

The easiest and recommended way to get Docker Compose is to install Docker Desktop. Docker Desktop includes Docker Compose along with Docker Engine and Docker CLI which are Compose prerequisites.

Download and install the Docker Desktop for Mac.

For Linux Users

If you already have Docker Engine and Docker CLI installed, you can install the Compose plugin from the command line:

sudo apt-get update
sudo apt-get install docker-compose-plugin

Clone Hummingbot Repo

In your terminal, clone the Hummingbot Github repository:

git clone https://github.com/hummingbot/hummingbot
cd hummingbot

Create Container

The docker-compose.yml file contains the basic instructions to deploy Humminggbot:

Use the following command to create the Docker container:

docker compose up -d

This will start the container in the background and we'll need to attach to it to be able to send commands to it. Run the following command below:

Attach to Container

docker attach hummingbot

We should now have Hummingbot running and in the next section we'll go over the Hummingbot Interface

2. Hummingbot Interface

Docker Installation Guide - 2 - User Interface

Hummingbot operates through a Command Line Interface (CLI), a text-based system ideal for automated cryptocurrency trading. Unlike graphical interfaces, CLIs rely on text commands to function. Let's dive into how to use it effectively.

Create a Password

Alt text

If you are using Hummingbot for the first time, the system will prompt you to create a password. There are no character requirements, although we recommend using a strong password for additional security.

The password in Hummingbot encrypts sensitive data such as API keys, secret keys, and wallet private keys. For security reasons, the password is only stored locally in encrypted form, and we do not have access to it.

After you set a password you should now be in the main Hummingbot screen

User Interface Guide

Alt text

The CLI is organized into several key areas:

  • Input Pane (Lower Left): Here, you input your commands.

  • Output Pane (Upper Left): This displays the results of your commands.

  • Log Pane (Right): Here, you can view log messages.

  • Top Navigation Bar: Shows the version, current strategy, and strategy file.

  • Bottom Navigation Bar: Displays trades, CPU usage, memory, threads, and duration.

For a more in-depth look, visit User Interface

Useful shortcuts

  • CTRL + P + CTRL + Q - This exits the bot but keeps it running in the background

  • CTRL + X - Exits config

  • Double CTRL + C - Exits the bot completely

  • CTRL + V to paste in Hummingbot does not work, to paste try one of the following commands:

    • CTRL+SHIFT+V

    • SHIFT + RMB (right-mouse button)

    • SHIFT + INS

Next, let's learn about running a simple PMM script in Hummingbot

Running a Script

Docker Installation Guide - 3 - Running a Script

Simple Directional RSI Example

Let's use the v2_directional_rsi.py script. This is a configurable script that uses the Relative Strength Index (RSI) to trade cryptocurrency futures contracts. For configurable scripts, the first step is to create a config file. Here's how to create one:

create --script-config v2_directional_rsi.py

When you enter the create --script-config command and press SPACE Hummingbot will display available scripts in the scripts folder, as shown below.

Alt text

Select the v2_directional_rsi.py script and press ENTER.

Alt text

You will then be guided to configure the settings. At this stage, you may modify the options or simply hit ENTER to accept the default values.

Alt text

Give the config a name and press press ENTER to save it.

Once the config is saved we can now launch the script. Enter the command below to launch the script!

start --script v2_directional_rsi.py --conf conf_v2_directional_rsi_config_1.yml

Note that the autocomplete will popup after pressing SPACE after both the --script and --conf parameters so you can just select the correct script / config file from the list and then press ENTER

Alt text

After pressing ENTER you should be able to see activity in the log pane. Use the status command for more details or press CTRL + S. It should resemble the screen below.

status

Default Configs

Please note that the default values for the script config may not work for each and every exchange / scenario. You may need to tweak the script config in order for the bot to be able to place orders. If you encounter any issues check the log pane and the log files for more information on what the issue may be.

Alt text

To stop the script from running, type the stop command in the Hummingbot terminal

stop

Congratulations! You've successfully run your first scripts Next, we'll learn how to connect API keys for live trading.

Connecting your API Keys

Docker Installation Guide - 4 - Adding API Keys

While paper trading in Hummingbot doesn't require API keys, live trading does. This guide will help you connect your exchange API keys to Hummingbot for real-time trading.

Generate API Keys

First, you need to generate API keys from the exchange you wish to connect. Each exchange has its own setup process.

In this example, we'll connect Binance API keys. Head over to the Binance Connector Docs for instructions on how to generate API keys for Binance.

Check the Connectors list for a list of exchanges that are currently integrated with Hummingbot

Warning

Please always keep your API keys secure and do not share them.

Connect API keys to Hummingbot

In the Hummingbot run the connect command for the exchange we want to connect to. In this case for Binance use the command below - 

connect binance

Alt text

You should get a prompt to enter in your API keys - you can use the following commands below to paste them into the Hummingbot terminal. Note that CTRL + V doesn't work and you'll get a Pyperclip error in the log panel if you try to use it.

  • CTRL+SHIFT+V

  • SHIFT + RMB (right-mouse button)

  • SHIFT + INS

Alt text

After entering your API keys you should get a success message if everything went through okay. You can also confirm by running the connect command again and check that both columns next to Binance are showing Yes.

Alt text

Now your Binance API keys are connected to Hummingbot. Repeat these steps for other exchanges as needed.

What's Next?

If you're serious about delving deeper and enhancing your trading bot capabilities, consider Botcamp, a professional training program for market makers and algo traders. This comprehensive program combines new content modules and live sessions each month to help you understand the intricacies of the market. You'll learn to create and backtest market making strategies, directional trading, and other strategies using Dashboard.

Most importantly, you'll gain hands-on experience with Bot Battles, Botcamp's monthly bot trading competitions. It's a great opportunity to measure your progress and learn from others. In addition, joining the Botcamp community allows you to expand your professional network, form teams to compete together, and share insights.

Thank you once again for joining us on this journey. I hope the knowledge you've gained here serves you well in your trading endeavors. All the best with your future trading bot projects!

Using Dashboard to Deploy and Backtest Strategies

Introduction

Welcome to the Hummingbot Dashboard Quickstart Guide!

While Hummingbot started as a simple CLI-based market making bot in 2019, today it has evolved into a flexible platform that helps you create, backtest, optimize and deploy all types of algorithmic trading strategies.

This guide shows you the basics of how to use the new Hummingbot Dashboard application to create and deploy strategies at scale. Whether you're a seasoned trader or just starting out, this tutorial will provide you with the tools and knowledge to maximize your trading potential.

What You Will Learn

  1. Set up Dashboard: Understand the initial steps to get Dashboard up and running.
  2. Managing Credentials: Safeguard and manage your access credentials for optimal security.
  3. Using the Master Bot Profile: Dive deep into how to launch multiple bots and effectively orchestrate them.
  4. Managing Bots: Explore the process of executing and assessing bot strategies within the Hummingbot Dashboard for optimized trading.
  5. Analyzing Bot Performance: Grasp the fundamentals of formulating a robust trading strategy and fine-tuning it for maximum efficiency and profitability.
  6. Backtesting and Optimization: Dive into the intricacies of evaluating the effectiveness of your strategies using historical data, ensuring they align with your trading objectives.
  7. Deploying Strategies: Gain comprehensive insights into the process of testing strategies against past market data (backtesting), and optimizing them based on the results to achieve optimal trading outcomes.
  8. Conclusion and Next Steps: Familiarize yourself with the steps to roll out multiple trading configurations seamlessly, ensuring a smooth transition from testing to live trading environments.

Let's Begin!

With the foundation set, it's time to harness the full potential of the Dashboard. Let's dive in!

Set up Dashboard

Creating a Custom Market Making Strategy

Introduction

Welcome to the new Hummingbot Quickstart Guide! This will teach you how to build and customize market making strategy using Hummingbot over 5 exercises.

Whether you're a beginner or an experienced trader, this guide should help you get started with creating your own custom trading strategies using Hummingbot. So, let's dive in and start building!

Note

Introduced in version 1.4.0, Scripts enable users to build customized strategies and access the full power of Hummingbot exchange connectors without creating a full-blown strategy. Scripts are light Python files that can be run and modified without re-compilation, which let users can stop a script, adjust the code, and start it without leaving the Hummingbot client interface. See Examples for a list of the current sample scripts in the Hummingbot codebase.

Getting Started

First, check out the Installation section to install Hummingbot. You may install it using Docker (easiest for new users) or from source (best for developers).

If you have questions or need help, join the official Hummingbot Discord and ask for help on the #support channel from our community.

If you have installed Hummingbot successfully, you should see a welcome screen like the one below:

The Hummingbot CLI helps you manage, configure, and run your bots. Familiarize yourself with the basic features in Hummingbot, especially the User Interface.

Exercises

We will start with a simple "Hello World" example of a Hummingbot script and gradually add more functionality to it with each exercise. By the end, you should gain a basic understanding of how to create a market making strategy and use market data to customize its behavior.

Exercise 1: Create Hello World Script

  • How a basic script works
  • Fetching real-time prices (best bid, best ask, mid-price, last traded price)
  • Emitting custom log messages

Exercise 2: Create Market Making Script

  • Building the Pure Market Making strategy as a simple script
  • Placing orders using exchange API
  • Cancelling orders using exchange API
  • Handle an order fill event

Exercise 3: Customize Status Command

  • Overriding the default status command with custom output

Exercise 4: Add Basic Price Ceiling/Floor

  • Motivation for adding this type of logic to a market making strategy
  • Adding a price ceiling/floor feature to your script

Exercise 5: Add Dynamic Price Ceiling/Floor

  • Creating custom OHLCV candles and technical indicators from order book data
  • Making the price ceiling/floor feature dynamic with Bollinger Bands

Additional Resources

Liquidity Mining with Hummingbot

In this guide, you'll learn how to set up a market making bot using Hummingbot that earns liquidity rewards on Miner, a liquidity mining platform that provides a decentralized, community-powered approach to market making across various exchanges.

First, you'll create API keys and add them to Miner. Next, you will install the open source Hummingbot algorithmic trading software and run the liquidity_mining strategy in Hummingbot, which we recommend for new users. Finally, we'll show you how to collect your rewards and assess your bot's performance in the Miner app.

Disclaimer

Miner is not maintained by nor affiliated with Hummingbot Foundation. Neither this nor any other Hummingbot documentation constitutes financial advice. Hummingbot does not guarantee rewards, but provides the general public access to the same market making and liquidity mining roles previously reserved for large hedge funds.

Sections

  1. Create API Keys
  2. Configure Miner
  3. Install Hummingbot
  4. Create Bot
  5. Earn Rewards