Skip to content

Walkthrough

The Strategy V2 framework can be used to build strategies with or without separate Controllers. Below, we present two examples below to show you how to build both types:

Simple Strategy V2 Strategy V2 with Controller
The strategy is relatively simple You want to manage the risk and diversify your portfolio in different controllers
The logic is very standard across different trading pairs The strategy is complex and you want to isolate the decision making
The strategy only trades on one trading pair You want to try multiple configs in the same bot
You are getting started with Executors and you want a simple way to code your strategy The strategy trades on multiple trading pairs
Prototype a strategy You are familiar with the Strategy V2 and how the controllers interact with it

Simple Strategy V2

simple

In this example, we'll show you how to configure and run a simple directional trading strategy, which is defined in the v2_simple_directional_rsi.py script.

This strategy executes trades on a spot or perpetual exchange based on the RSI signals from the Market Data Provider, creating buy actions when the RSI is below a low threshold (indicating oversold conditions) and sell actions when the RSI is above a high threshold (indicating overbought conditions).

After each trade, the strategy utilizes the Position Executor component, which uses a triple barrier configuration to manage the P&L of the position or filled order.

Create script config

script config

First, let's create a script config file that defines the key strategy parameters.

Launch Hummingbot and execute the command below to generate your script configuration:

create --script-config v2_simple_directional_rsi

This command auto-completes with the subset of configurable scripts from the local /scripts directory.

You'll be prompted to specify the strategy parameters, which are then saved in a YAML file within the conf/scripts directory:

Enter markets in format exchange1.tp1,tp2:exchange2.tp1,tp2 >> binance_perpetual.JASMY-USDT,RLC-USDT
Enter the RSI period >> 14
Enter the RSI low >> 30
Enter the RSI high >> 70
Enter the interval >> 3m
Enter the amount of quote asset to be used per order >> 30
Enter the leverage >> 20
Enter the position mode (HEDGE/ONEWAY): >> HEDGE
Enter the stop loss >> 0.03
Enter the take profit >> 0.01 
Enter the time limit in seconds >> 2700
Enter a new file name for your configuration >> conf_v2_simple_directional_rsi_1.yml

Run the script

controller

Execute the command below to start the script:

start --script v2_simple_directional_rsi.py --conf conf_v2_simple_directional_rsi_1.yml

The strategy makes a series of market checks and initializes the market data provider. Afterwards, it should start placing orders for both pairs.

Run the status command to see the status (asset balances, active orders and positions) of the running strategy:

status

Strategies V2 with Controller

In a more complex example, the strategy logic is housed in a Controller, and the user generates a controller configuration that is run with a generic script, which acts as a controller loader.

This allows users to run multiple configurations, as well as multiple controllers, in a single script.

advanced

Let's say we want to create a single bot that provides liquidity to two distinct trading pairs on Binance Futures, each configured with unique buy and sell spreads, order amounts, and other pair-specific parameters. In the past, users had to run separate Hummingbot instances for each configuration, each running a separate strategy or script.

Now, this can be handled in a single strategy using the pmm_simple.py controller.

First, we will generate pair-specific configurations. Then, we can run these configurations all at once with the v2_generic_with_controllers.py generic script.

Create the controller configs

The initial step involves generating a separate controller configuration for each trading pair.

controller

Execute the command below to generate the controller config:

create --controller-config market.making.pmm_simple
Enter the name of the exchange to trade on >> binance_perpetual
Enter the name of the trading pair to trade on >> WLD-USDT
Enter the total amount in quote asset to use for trading >> 100
Enter a comma-separated list of buy spreads >> 0.01, 0.02
Enter a comma-separated list of sell spreads >> 0.01, 0.02
Enter the refresh time in seconds for executors >> 20
Set the leverage to use for trading >> 20
Enter the stop loss >> 0.03
Enter the take profit >> 0.02 
Enter the time limit in seconds >> 2700
Enter the order type for taking profit >> LIMIT
Enter the trailing stop as activation_price, trailing_delta >> 0.013, 0.003
Enter a file name for your configuration >> conf_market_making.pmm_simple_1.yml

This will create the conf_market_making.pmm_simple_1.yml controller config file under the /conf/controllers folder


Now, repeat the steps above to create a new controller config.

This time, use a different trading pair, and different buy and sell spreads. Save this modified configuration under the file name conf_market_making.pmm_simple_2.yml.

Afterwards, you should now have two controller config files under the /conf/controllers/ folder:

conf_market_making.pmm_simple_1.yml
conf_market_making.pmm_simple_2.yml

Create the generic script config

script-config

Execute the command below to generate the script config file:

create --script-config v2_generic_with_controllers

Enter the file names of your controller configs, separated by commas:

Enter controller configurations >>> conf_market_making.pmm_simple_1.yml, conf_market_making.pmm_simple_2.yml
Enter a new file name for your configuration >>> conf_v2_generic_with_controllers_1.yml

Tip

Once you create the initial generic script config, it might be easier to edit this file and replace it with new controller names rather than having to re-generate it each time.

Start the script

script-config

Execute the command below to start the script:

start --script v2_generic_with_controllers.py --conf conf_v2_generic_with_controllers_1.yml

The bot should now be running and start placing orders for both pairs. Run the status command to see the bot status.

status --live

status

Changing configs

Users often need to modify the strategy configuration as it is running. In the Strategies V2 framework, the configs are dynamic, so you just need to save changes to the config files

Let's say we want to adjust the order spreads or refresh time for the first pair above.

The controller config files are under the /conf/controllers/ folder within your instance. Browse to the Hummingbot folder then enter the command below:

nano conf/controllers/conf_market_making.pmm_simple_1.yml

This will open up Nano - a Linux text editor. You can also use Visual Studio Code or any other text editor you prefer.

id: EsRCab7Lw3CwqtBe524QvzG5i7ZDWJzoX787ZncknFoy
controller_name: pmm_simple
controller_type: market_making
candles_config: []
connector_name: binance_perpetual
trading_pair: WLD-USDT
total_amount_quote: 100.0
buy_spreads:
- 0.01
- 0.02
sell_spreads:
- 0.01
- 0.02
buy_amounts_pct: null
sell_amounts_pct: null
executor_refresh_time: 20
cooldown_time: 15
leverage: 20
position_mode: HEDGE
stop_loss: 0.03
take_profit: 0.02
time_limit: 2700
take_profit_order_type: 2
trailing_stop:
  activation_price: 0.013
  trailing_delta: 0.003

Make the necessary changes you want here then press CTRL + O to save, then CTRL + X to exit.

If you edit and save changes to the controller config file, you'll see the spreads change on the next refresh, which is set by the config_update_interval parameter (default: 60 seconds).