Quickstart
The new Hummingbot Dashboard¶
In this tutorial, we'll guide you through installing Hummingbot 2.0, which provide an easy-to-use Dashboard app that helps you connect exchange credentials, create/backtest a strategy configuration, and deploy a fleet of bots!
Watch this video for an overview and walkthrough of the features in Hummingbot 2.0:
Prerequisites: Docker¶
Hummingbot 2.0 uses Docker Compose to install and manage dependencies. We recommend installing Docker Desktop as it includes Docker Compose
, Docker Engine
, and Docker CLI
, all of which are needed for the Dashboard to work.
Installation¶
Clone the Deploy repository, which contains the Docker Compose configuration file and a bash script that automatically pulls the latest images and starts the necessary services.
Open a Terminal window and run the following commands:
The setup script will pull the Docker images defined in repo's docker-compose.yml
file and start them as new containers. It might take a while to pull the images for the first time.
[+] Running 7/7
✔ Network deploy_emqx-bridge Created
✔ Volume "deploy_emqx-data" Created
✔ Volume "deploy_emqx-log" Created
✔ Volume "deploy_emqx-etc" Created
✔ Container dashboard Started
✔ Container backend-api Started
✔ Container hummingbot-broker Started
After all containers have started, access the Dashboard at http://localhost:8501 in your browser.
Cloud Servers
If you are using a cloud server or VPS, replace localhost
with the IP of your server. You may need to edit the firewall rules to allow inbound connections to the necessary ports.
Adding Credentials¶
Credentials are your API keys needed for Hummingbot to trade on an exchange. The Dashboard allows you to create and manage API keys under multiple accounts, which is useful if you use multiple sub-accounts on a single exchange.
Let's say you have three Kucoin accounts and want the ability to switch between them when creating bots. The Credentials page will allow you to do this since you can select which account to use when deploying bots.
On the menu on the left click Credentials
to get to the Credentials page:
Let's go over the different sections below:
In this section, we will see the list of accounts
and any API keys already registered to that account. In the screenshot above, we only have one master_account
created with one exchange API connected for Kucoin
.
To create a new account
, just enter the name of the account and then click Create Account
.
If you want to delete an account
(this includes all API keys associated with it), select the account from the drop-down list and then click Delete Account
.
If you want to delete a specific API key connected to an existing account, select the account from the list and then select the API credential and then click Delete Credential
To add API keys to our account, use this section. Select the account you want the API keys to be associated with, select the Connector
or Exchange
, enter the corresponding API keys, and then click Submit Credentials
.
If the API keys are valid, you should see them appear in the list under the Available Accounts and Credentials
section at the top. For example, if you added API keys for Binance Perpetual under the master account you should see binance_perpetual
listed under master_account
Viewing Your Portfolio¶
Once API keys are added, you can view the tokens available and their allocation under the Portfolio page. You can filter by account, exchange, or token to get more details.
The table above shows the list of available tokens for the Kucoin
exchange. The graphs below will show your Portfoliio Evolution over Time
as well as Token Value Evolution over time
Configuring Strategies¶
Before we can deploy bots, we'll have to configure a Controller, which defines an algo trading strategy. Under the Config Generator section we have the following available controllers:
- PMM Simple
- PMM Dynamic
- D-Man Maker V2
- Bollinger V1
- MACD BB V1
- SuperTrend V1
- XEMM Controller
Let's use the PMM Simple
controller for now and go through the different sections below:
Under Configurations
, if we uncheck the "Use Default Configs" box, this will display a drop down list of configs that we've previously configured. Since we don't have any previous configs, there won't be any in the list.
For General Settings
, we can select the Connector
or exchange we want to trade on, the Trading Pair
and Leverage
. For trading on spot markets we recommend setting Leverage
to 1
.
We can also set the Total amount of quote
which is how much we want to trade with (in USDT), Position Mode
(ONE-WAY / HEDGE), as well as Stop Loss Cooldown Time
which is the cool down time in minutes after stop loss is triggered and Executor Refresh Time
which is your order refresh time.
Under Executors Configuration
, we can set the the spread and amount for both buy and sell orders manually or we can choose from the following distributions:
- GeoCustom
- Geometric
- Fibonacci
- Logarithmic
- Arithmetic
- Linear
For Risk Management
, you can set your Stop Loss
, Take Profit
, Time Limit
, Trailing Stop Activation Price
, Trailing Stop Delta
as well as the Take Profit Order Type
(LIMIT / MARKET)
In this section, Executor Distribution
shows a graphical visualization of the order amount vs spread order distribution for both the buy and sell orders configured under the Executors Configuration
section.
Backtesting Strategies¶
After making changes to the configuration above you can run a backtest to test your strategy configuration. Just set the start
and end
date as well as the Backtesting Resolution
(candles) and Trade Cost
(fees) and then click the Run Backtesting
button to see the results like the one below.
From here, you can still make changes to the configuration above and continue to run backtesting until you get the results you want.
Once you are done making the necessary changes to your strategy and are satisfied with the backtesting results you can give the config a name (or just use the defaults) and then click Upload
to upload your config and make it available in the Deploy
page.
If you make changes later, the Config Tag
will be incremented to a higher version, so any new changes will always be saved to a config with a newer config tag version. However, if you change the Config Tag
to a previous version, any new changes you made will overwrite the config for that previous version.
Deploying Instances¶
After uploading your config, it will become available in the Deploy V2
page and from here we can deploy bots based on those configs.
Select the config you want to use from the list of Available Configurations
and then give the instance a name, select the available Docker image from the drop down list (note you can use your own Docker image) and select the account that contains the API keys you want to use.
Once ready, click the Launch Bot
button and this will create your instance with the selected config. You can view the running instance under the Instances
page.
If you want to delete an existing config, you can do this by selecting the config then click the Delete
button to remove the config from the list.
Managing Instances¶
The Instances
page will show all running instances (active or stopped). This page shows information like Net PNL
, Volume Traded
, Liquidity Placed
etc for each instance. It will also show the current active controllers as well as the current config.
From here you can also view the Error Logs
as well as General Logs
so you can easily monitor the bot status without needing to attach to the instance manually.
To stop a running instance, check the box of the active controller and then click the Stop
button. This is the recommended way to stop the instance as this will create orders to close the active positions if there are any.
If you click the stop
icon in the top right hand corner this will send a stop command to the bot which will then cancel all active orders.
Dashboard appends hummingbot
+ the current date & time
to the instance name that you specified. You can check the complete name of the bot in the top left hand corner right under Local Instances
. If you need to manually attach to the Docker container in the terminal this would be the complete name.
In the above screenshot, the complete instance name is hummingbot-new-bot-2024.06.20_03.55
so if we need to attach to this container using Docker we would open a terminal and do docker attach hummingbot-new-bot-2024.06.20_03.55
Congratulations, you just created your first instance using the Hummingbot Dashboard!
Authentication¶
Authentication is disabled by default. To enable Dashboard Authentication please follow the steps below:
Set Credentials (Optional):
The dashboard uses admin
and abc
as the default username and password respectively. It's strongly recommended to change these credentials for enhanced security.:
- For Docker, navigate to the
deploy
folder ordashboard
folder if using Source and open thecredentials.yml
file. - Add or modify the current username / password and save the changes afterward
credentials:
usernames:
admin:
email: [email protected]
name: John Doe
logged_in: False
password: abc
cookie:
expiry_days: 0
key: some_signature_key # Must be string
name: some_cookie_name
pre-authorized:
emails:
- [email protected]
Docker¶
- Ensure the dashboard container is not running.
- Open the
docker-compose.yml
file within thedeploy
folder using a text editor. - Locate the environment variable
AUTH_SYSTEM_ENABLED
under the dashboard service configuration.
services:
dashboard:
container_name: dashboard
image: hummingbot/dashboard:latest
ports:
- "8501:8501"
environment:
- AUTH_SYSTEM_ENABLED=True
- BACKEND_API_HOST=backend-api
- BACKEND_API_PORT=8000
AUTH_SYSTEM_ENABLED
from False
to True
.
- Save the changes to the docker-compose.yml
file.
- Relaunch Dashboard by running bash setup.sh
Source¶
- Open the
CONFIG.py
file located in the dashboard root folder - Locate the line
AUTH_SYSTEM_ENABLED = os.getenv("AUTH_SYSTEM_ENABLED", "False").lower() in ("true", "1", "t")
.
CERTIFIED_EXCHANGES = ["ascendex", "binance", "bybit", "gate.io", "hitbtc", "huobi", "kucoin", "okx", "gateway"]
CERTIFIED_STRATEGIES = ["xemm", "cross exchange market making", "pmm", "pure market making"]
AUTH_SYSTEM_ENABLED = os.getenv("AUTH_SYSTEM_ENABLED", "False").lower() in ("true", "1", "t")
BACKEND_API_HOST = os.getenv("BACKEND_API_HOST", "127.0.0.1")
False
to True
to enable dashboard authentication.
- Save the CONFIG.py file.
- Relaunch dashboard by running make run
Known Issues¶
- Refreshing the browser window may log you out and display the login screen again. This is a known issue that might be addressed in future updates.