Offers dynamic bot controls by running a user defined script alongside a strategy.
Currently, Scripts can only be used when running Hummingbot from source or with Docker. Using this feature in the Mac or Windows installers will crash the bot.
As with Hummingbot source code, the script is fully compatible with Python 3.7.
How it works¶
After configured, the script will start automatically once a strategy starts and it stops when the strategy stops. The script is run on a new dedicated process, in case where the script fails or has a bug, your main Hummingbot application can still function.
Create your own script¶
- Create a new script file, you can see examples in the Examples section below, and save it into
- Configure your Hummingbot
- Inside Hummingbot run command
conf_global.ymlfile using a text editor.
script_enabled: true script_file_path: spreads_adjusted_on_volatility_script.py
- Start running a strategy
This is the base class (
hummingbot/script/script_base.py) for your script, it provides data, events and functions
At every tick, the script gets current market price (
mid_price), strategy configuration (
total balances (
mid_price is stored in a list (
mid_prices) where a new
is added to the end of the list, whereas strategy configuration and total balances are replaced every time.
Note: The current script feature supports only pure market making strategy configuration.
To set a pure market making strategy parameter to a new value, simply assign a new value to it.
self.pmm_parameters.bid_spread = Decimal("0.03") - to update bid spread to 3%
These below are configurable parameters:
- buy_levels (a number of buy orders to place, initially set to
order_levels when the strategy starts)
- sell_levels (a number of sell orders to place, initially set to
order_levels when the strategy starts)
The code here will be executed on every tick which is every second on a default Hummingbot configuration.
The script will be notified every time a buy order of yours is fully filled. Put in your code logic here to handle such situation if needed.
The script will be notified every time a sell order of yours is fully filled. Put in your code logic here to handle such situation if needed.
This is called upon
status command issued on the Hummingbot application. You can provide your custom status message
Notifies the user, the message will appear on top left panel of HB application. If Telegram integration enabled, the message will also be sent to the telegram user.
Logs message to the strategy log file and display it on Running Logs section of HB.
Calculates average (mean) of the stored mid prices.
avg_value = self.avg_mid_price(60, 30) - to calculate average mid price at a minute interval for the
last 30 minutes
Calculates average (mean) price volatility, volatility is a price change compared to the previous cycle regardless of its direction, e.g. if price changes -3% (or 3%), the volatility is 3%.
avg_value = self.avg_price_volatility(60, 30) - to calculate average price volatility at a minute
interval for the last 30 minutes
Calculates median (middle value) price volatility.
median_value = self.median_price_volatility(60, 30) - to calculate median price volatility at
a minute interval for the last 30 minutes
Calculates central located price volatility based on a given mean function. The mean function can be one
that is supported by
statistics library e.g. mean, median, geometric_mean and many more.
median_value = self.locate_central_price_volatility(60, 30, median) - to calculate median price
volatility at a minute interval for the last 30 minutes
Rounds a given number down by a given step size.
rounded_value = self.round_by_step(1.8, 0.25) will give you 1.75
Takes samples out of a given list where the last item is the most recent.
a_list = [1, 2, 3, 4, 5, 6, 7]
samples = self.take_samples(a_list, 3, 2) will give you
All below examples can be found in
The most basic example only a few lines of code.
Replicates our current ping pong strategy using script.
Replicates our current price band strategy using script.
Demonstrates how to set the band around mid price moving average, the band moves as the average moves.
Demonstrates how to adjust bid and ask spreads dynamically based on price volatility.