Operation Commands
Info and usage about Basic Operation Commands
Commands Overview
Below are the available commands in the current Hummingbot release.
| Command | Function |
|---|---|
| connect | List available exchanges and add API keys to them |
| create | Create a new bot |
| Import | Import an existing bot by loading the configuration file |
| help | List available commands |
| balance | Display your asset balances across all connected exchanges |
| config | Display the current bot's configuration |
| start | Start the current bot |
| stop | Stop the current bot |
| status | Get the market status of the current bot |
| history | See the past performance of the current bot |
| exit | Exit and cancel all outstanding orders |
| paper_trade | Toggle paper trading mode |
| export | Export your bot's trades or private keys |
| order_book | Displays the top 5 bid/ask prices and volume |
| kill switch | Automatically stops the bot |
connect
List available exchanges and check whether API keys have been added correctly.
>>> connect
Testing connections, please wait...
Exchange Keys Added Keys Confirmed Connector Status
binance Yes Yes GREEN
bittrex Yes Yes GREEN
coinbase_pro No No RED
eterbase No No RED
ethereum Yes Yes YELLOW
huobi No No YELLOW
kraken No No UNKNOWN
kucoin No No GREEN
liquid No No UNKNOWNconnect [ exchange ]
Connect to an exchange by adding API keys.
>>> connect binance
Enter your Binance API key >>>
Enter your Binance secret >>>
You are now connected to binance.Replace existing API keys to an exchange connection.
>>> connect binance
Would you like to replace your existing binance API key ...abc1 (Yes/No)? >>>
Enter your Binance API key >>>
Enter your Binance secret >>>Connect to an Ethereum wallet and Ethereum node.
>>> connect ethereum
Enter your wallet private key >>>
Which Ethereum node would you like your client to connect to? >>>
Enter the Websocket Address of your Ethereum Node >>>
Wallet 0x8D10...def2 connected to hummingbot.Replace existing Ethereum wallet.
>>> connect ethereum
Would you like to replace your existing Ethereum wallet [address] (Yes/No)? >>>
Enter your wallet private key >>>
Which Ethereum node would you like your client to connect to? >>>
Enter the Websocket Address of your Ethereum Node >>>
Wallet 0xC20...8bFa connected to hummingbot.create
Create a new bot and walk through the strategy configuration.
>>> create
What is your market making strategy? >>>create [ file_name ]
Specify first the name of the file before going though the strategy configuration.
>>> create conf_pure_mm_1.yml
What is your market making strategy? >>>import
Import an existing bot by loading the configuration file.
>>> import
Enter path to your strategy file (e.g. "conf_pure_mm_1.yml") >>>
Configuration from conf_pure_mm_1.yml file is imported.
Preliminary checks:
- Exchange check: All connections confirmed.
- Strategy check: All required parameters confirmed.
- All checks: Confirmed.
Enter "start" to start market making.import [ file_name ]
Specify the file name to import and skip the prompt.
>>> import conf_pure_mm_1.yml
Configuration from conf_pure_mm_1.yml file is imported.
Preliminary checks:
- Exchange check: All connections confirmed.
- Strategy check: All required parameters confirmed.
- All checks: Confirmed.
Enter "start" to start market making.help
List available commands.
>>> help
usage: {connect,create,import,help,balance,config,start,stop,status,history,exit,paper_trade,export}
..
positional arguments:
{connect,create,import,help,balance,config,start,stop,status,history,exit,paper_trade,export}
connect List available exchanges and add API keys to them
create Create a new bot
import Import an existing bot by loading the configuration file
help List available commands
balance Display your asset balances across all connected exchanges
config Display the current bot's configuration
start Start the current bot
stop Stop the current bot
status Get the market status of the current bot
history See the past performance of the current bot
exit Exit and cancel all outstanding orders
paper_trade Toggle paper trade mode on and off
export Export secure information
order_book Display current order book
help [ command_name ]
Displays command usage and function.
>>> help connect
usage: connect [-h] [{liquid,coinbase_pro,binance,kraken,bittrex,huobi,ethereum,kucoin}]
positional arguments:
{liquid,coinbase_pro,binance,kraken,bittrex,huobi,ethereum,kucoin}
Name of the exchange that you want to connectbalance
Display your asset balances across all connected exchanges.
>>> balance
Updating balances, please wait...
binance:
Asset Amount Limit
BNB 0.0000 -
BTC 0.0000 -
ETH 0.0000 -
TFUEL 0.0187 -
THETA 0.5880 -
USDC 0.0090 -
USDT 158.8197 -
XRP 0.8440 -
XZC 0.0076 -
bittrex:
Asset Amount Limit
BTC 0.0020 -
BTXCRD 1025.2352 -
XZC 5.1501 -
coinbase_pro:
Asset Amount Limit
BAT 10.0000 -
ETH 0.2059 -
LINK 15.0500 -
USDC 0.0033 -
ethereum:
asset amount
ETH 0.0453balance limit [ exchange ][ asset ] [ amount ]
Set the amount limit on how much assets Hummingbot can use in an exchange or wallet. This can be useful when running multiple bots on different trading pairs with same tokens e.g. running a BTC-USDT pair and another bot on ETH-USDT using the same account.
>>> balance limit binance USDT 100
Limit for USDT on binance exchange set to 100.0Run the balance command again to confirm the limit has been applied.
>>> balance
Updating balances, please wait...
binance:
Asset Amount Limit
BNB 0.0000 -
BTC 0.0000 -
ETH 0.0000 -
TFUEL 0.0187 -
THETA 0.5880 -
USDC 0.0090 -
USDT 158.8197 100.0000
XRP 0.8440 -
XZC 0.0076 -Example Scenario
Create pure market making strategy, run config to view the whole configuration.
Run balance limit binance ETH 0.0513 to set the balance limit to 0.0513 ETH. Run balance limit binance USDT 30 to set the balance limit to 30 USDT. Both ETH and USDT value is equivalent to $30.
Each order is 0.0188 equivalent to $11.20
Sell order gets filled. USDT available balance is now 30.1657
Another sell order gets filled, the available balance now shows 41.2069. Plus the open buy order, the "usable" balance on USDT is now at around $52.
After the two sell orders gets filled the remaining available balance in ETH is 0.0137 equivalent to $8.17. It means that after the next order_refresh_time it won't create sell order because the minimum order amount is $11.
Same process as the scenario above. After the two buy orders gets filled the remaining available balance in USDT is 7.5317 equivalent to $7.53. It means that after the next order_refresh_time it won't create buy order because the minimum order amount is $11.
balance paper
Show existing paper account balance setting.
>>> balance paper
Paper account balances:
Asset Balance
DAI 1000.0000
ETH 10.0000
ONE 1000.0000
TUSD 1000.0000
USDC 1000.0000
USDQ 1000.0000
USDT 1000.0000
WETH 10.0000
ZRX 1000.0000balance paper [ asset ][ amount ]
Set the amount of asset balance for paper trading mode. For example, we want to add 0.5 BTC to our paper account balance.
>>> balance paper BTC 0.5
Paper balance for BTC token set to 0.5
>>> balance paper
Paper account balances:
Asset Balance
BTC 0.5000
DAI 1000.0000
ETH 10.0000
ONE 1000.0000
TUSD 1000.0000
USDC 1000.0000
USDQ 1000.0000
USDT 1000.0000
WETH 10.0000
ZRX 1000.0000config
Display the current bot's configuration.
>>> config
Global Configurations:
Key Value
kill_switch_enabled False
kill_switch_rate -100
telegram_enabled False
telegram_token None
telegram_chat_id None
send_error_logs True
0x_active_cancels False
script_enabled False
script_file_path None
Strategy Configurations:
Key Value
strategy pure_market_making
exchange binance
market ETH-BTC
bid_spread 1
ask_spread 1
minimum_spread -100
order_refresh_time 30
order_refresh_tolerance_pct 0
order_amount 1
price_ceiling -1
price_floor -1
ping_pong_enabled True
order_levels 1
order_level_amount 0
order_level_spread 1
inventory_skew_enabled False
inventory_target_base_pct 50
inventory_range_multiplier 1
filled_order_delay 60
hanging_orders_enabled False
hanging_orders_cancel_pct 10
order_optimization_enabled False
ask_order_optimization_depth 0
bid_order_optimization_depth 0
add_transaction_costs False
price_source_enabled False
price_source_type None
price_source_exchange None
price_source_market None
price_source_custom None
take_if_crossed Noneconfig [ key ]
Reconfigure a parameter value.
>>> config order_refresh_time
How often do you want to cancel and replace bids and asks (in seconds)? >>>config [ key ][ value ]
Reconfigure a parameter value without going through the prompts. These can be reconfigured without stopping the bot however, it will only take effect after restarting the strategy.
>>> config order_refresh_time 30
New configuration saved:
order_refresh_time: 30.0Configure parameters on the fly
Currently, only the following parameters can be reconfigured without stopping the bot. The changes will take effect in the next order refresh.
- bid_spread
- ask_spread
- order_amount
- order_levels
- order_level_spread
- inventory_target_base_pct
- inventory_range_multiplier
- filled_order_delay
Take note the reconfiguring of inventory_target_base_pct for DEX connectors are not working at the moment
start
Start the current bot.
>>> start
Preliminary checks:
- All checks: Confirmed.
Status check complete. Starting 'pure_market_making' strategy...
'pure_market_making' strategy started.
Run `status` command to query the progress.stop
Stops the current bot. This cancels all active and hanging orders.
>>> stop
Winding down...
Cancelling outstanding orders...
All outstanding orders cancelled.status
Get the market status of the current bot.
>>> status
Markets:
Exchange Market Best Bid Price Best Ask Price Mid Price
binance ETHBTC 0.025521 0.025527 0.025524
Assets:
ETH BTC
Total Balance 4.3725 0.1274
Available Balance 3.3725 0.1021
Current Value (BTC) 0.1116 0.1274
Current % 46.7% 53.3%
Orders:
Level Type Price Spread Amount (Orig) Amount (Adj) Age Hang
1 sell 0.0257747 0.98% 1 1 00:00:02 no
1 buy 0.02526431 1.02% 1 1 00:00:02 noOptional arguments
--live- Displays status in real time.
history
See the past performance of the current bot.
>>> history
Start Time: 2020-11-11 00:56:37
Current Time: 2020-11-11 12:57:22
Duration: 0 days 12:00:45
binance / MFT-BNB
Trades:
buy sell total
Number of trades 113 97 209
Total trade volume (BTC) 2181335 -2133912 47423
Total trade volume (USDT) -217,67 210.76 -6.91
Avg price 0.0000998 0.0000988 0.0001457
Assets:
Start Current Change
MFT 155248 202671 47423
BNB 23.331 16.419 -6.912
MFT/BNB price 0.0001076 0.0000809 -0.0000267
Base asset % 41.7% 50.0% 8.2%
Performance:
Hold portfolio value 35.890 BNB
Current portfolio value 32.815 BNB
Trade P&L -3.075 BNB
Fees paid -0.428 BNB
Total P&L -3.504 BNB
Return %: -9.76%How It Works
The history command in Hummingbot displays the current duration of total past trades, assets inventory and value, and market trading pair performance.
The following displays the formula for key calculations:
Note: For more details on all the indidvual item formula, see google sheetfor the formulas in the cells.
Avg Price
Avg Price = Total trade volume of quote/Total trade volume of base asset
From the above example, for the total avg price is 6.91/47423 = 0.0001457
This value means the average price of total MFT/BNB trades is 0.0001457
Hold portfolio value
The asset value from the start to the end with no trades.
Hold portfolio value = (base start asset*quote current value)+ quote start asset
From the above example, for the Hold portfolio value is (155248*0.0000809)+23.33=35.89
Current portfolio value
Current portfolio value = (quote current asset*quote current value)+ quote current asset
From the above example, for the Hold portfolio value is (202671*0.0000809)+16.419=32.815
Trade P&L
Trade P&L = Current portfolio value - Hold Portfolio value
From the above example, for the Trade P&L value is 32.815-35.89=-3.075
Tota P&L
Total P&L = Trade P&L + Fees paid
From the above example, for the Total P&L is -3.075 + -0.428 = -3.504
Return Percentage
Return% = Total P&L/Hold portfolio value
From the above example, for the Return% is -3.075/-35.89 = -9.76%
Note: The Return% (bottom navbar) matches the calculated return on history after the last trade, see following screenshot:
If the trading pair price moves, the History changes but Return% retains the calculated return based on the last price, see following screenshot:
Optional arguments
| Command Argument | Description |
|---|---|
--verbose | Displays a list of past trades |
--config file | You can select different strategy file.By default, displays the current strategy file. |
--duration | You can select the duration in minutes, days and hours. For example, 7d for 7 days or 12h for 12 hours. By default, displays in hour if no value is defined. |
exit
Exit and cancel all outstanding orders. This cancels all active and hanging orders.
>>> exit
Winding down...
Cancelling outstanding orders...
All outstanding orders cancelled.exit -f
Force exit and cancel all outstanding orders.
>>> exit -fpaper_trade
Toggle paper trade mode on and off. When paper trade mode is enabled, all orders are simulated and no real orders are placed.
This feature allows users to test Hummingbot and simulate trading strategies without risking any actual assets. Enter the command paper_trade to enable this feature.
Enabling and Disabling
Paper trading mode can be enabled/disabled inside Hummingbot by doing paper_trade or config paper_trade_enabled.
Alternatively, you can edit the conf_global.yml file using a text editor and set paper_trade_enabled: value to true or false.
- Locating your global configuration:
- Installed from source:
hummingbot/conf - Installed via Docker:
hummingbot_files/hummingbot_confhummingbot_filesis the default name of the parent directory. This can be different depending on the setup when the instance was created. - Installed via Binary (Windows):
%localappdata%\hummingbot.io\Hummingbot\conf - Installed via Binary (MacOS):
~/Library/Application\ Support/Hummingbot/Conf
- Installed from source:
The top bar shows the status to indicate if paper trading mode is on or off.
Also shows a reminder that paper trade was enabled when doing a status or history command.
Account Balance
By default, the paper trade account has the following tokens and balances:
paper_trade_account_balance:
BTC: 1
USDT: 1000
ONE: 1000
USDQ: 1000
TUSD: 1000
ETH: 10
WETH: 10
USDC: 1000
DAI: 1000Paper trade assets can be added in two ways:
- Run
balance paper [asset] [amount]. See more information in balance command. - Edit
conf_global.ymlin the/conforhummingbot_conffolder using a text editor. Strictly follow the same format above.
Note:
- When making changes to the global config file, make sure to exit and restart Hummingbot to take effect.
- For a list of supported connectors, see Connectors
export
Exports secure information.
export keys
Displays API keys, secret keys and wallet private key in the command output pane.
>>> export keys
Enter your password >>> *****
Warning: Never disclose API keys or private keys. Anyone with your keys can steal any assets held in your account.
API keys:
binance_api_key:
binance_api_secret:
Ethereum wallets:
Public address:
Private key:export trades
Exports all trades in the current session to a .csv file.
>>> export trades
Enter a new csv file name >>> trade_list
Successfully exported trades to logs/trade_list.csvorder_book
Displays the top 5 bid/ask prices and volume of the current market, similar to how they're displayed in the exchange's order book.
>>> order_book
market: binance ETHUSDT
bid_price bid_volume ask_price ask_volume
395.87 0.73244 395.89 34.37802
395.86 7 395.9 10.786
395.85 71.36763 395.91 0.19
395.84 12.786 395.92 2.02141
395.83 16.5706 395.93 3.29861Note: This command will only work while a strategy is running.
Run order_book --lines [value] to specify the number of lines displayed or you can use arguments --live to displays the orderbook of the market in real time . For example, run `order_book --live. The order book displays the top 5 bid/ask prices and volume of the current market in real time.
Run order_book --lines [value] to specify the number of lines displayed.
>>> order_book --lines 15
market: binance ETHUSDT
bid_price bid_volume ask_price ask_volume
395.91 6 395.93 30
395.9 0.02764 395.94 10.786
395.89 8.292 395.95 0.11719
395.87 25.13292 395.96 8.53205
395.86 61.26264 395.97 0.0007
395.84 12.40548 395.98 7.52538
395.83 20.7474 395.99 8.61834
395.82 11 396 13.53414
395.81 8.61536 396.02 12.92161
395.8 60.38759 396.03 6.26138
395.79 25.5767 396.04 21.61688
395.78 31.94231 396.05 44.45931
395.77 41.51229 396.06 0.19829
395.76 24.17199 396.07 12.26197
395.75 2.9788 396.08 1.21638By default, the order_book command shows only the maker market in cross-exchange strategy or primary market when using arbitrage.
You can use arguments --live to displays the orderbook of the market in real time . For example, run order_book --lines 20 --live.
The order book displays the top 20 bid/ask prices and volume of the current market in real time.
Optional arguments
arguments --exchange and --market allows you to check the order book of the taker market or secondary market.
Sample usage:
>>> order_book --exchange kucoin --market ETH-USDT
market: kucoin ETH-USDT
bid_price bid_volume ask_price ask_volume
395.8 1.07 395.81 2.02
395.79 22.95406 395.82 0.0505293
395.77 7.668467 395.84 0.554996
395.75 0.05 395.85 3.644207
395.7 1 395.86 1.825kill switch
Automatically stops the bot when it reaches a certain performance threshold, which can be either positive or negative. This feature uses the same performance calculation methodology as the history command.
Would you like to enable the kill switch? (Yes/No) >>>
At what profit/loss rate would you like the bot to stop? (e.g. -5 equals 5 percent loss) >>>You can always reconfigure this feature in two ways:
- Inside Hummingbot run command
config kill_switch_enabledand/orconfig kill_switch_rate. - Edit
conf_global.ymlfile using a text editor.
Note that when the market prices changes, so does the bot's performance and may trigger the kill switch. For example, we executed 13 trades and our performance are shown below.
- kill_switch_enabled: True
- kill_switch_rate: -0.3Inventory:
Market Asset Starting Current Net Delta Trade Delta
0 binance ETH 10.0000 11.0000 1.0000 3.0000
1 binance USDT 500.0000 297.1580 -202.8420 -610.6340
Markets:
Market Pair Start Price End Price Trades Trade Value Delta
0 binance ETHUSDT 203.913 202.7150000000 13 -2.48900000 USDT
Performance:
Started: 2020-05-26 10:28:03
Duration: 0 days 00:07:06
Total Trade Value Delta: -2.489 USDT
Return %: -0.0985 %After a while, the end price changed from 202.715 to 200.54 and so did our bot's performance even without making more trades. Since kill_switch_rate is set to -0.3 this will stop the strategy.
Inventory:
Market Asset Starting Current Net Delta Trade Delta
0 binance ETH 10.0000 11.0000 1.0000 3.0000
1 binance USDT 500.0000 297.1580 -202.8420 -610.6340
Markets:
Market Pair Start Price End Price Trades Trade Value Delta
0 binance ETHUSDT 203.913 200.5400000000 13 -9.01400000 USDT
Performance:
Started: 2020-05-26 10:28:03
Duration: 0 days 02:09:13
Total Trade Value Delta: -9.014 USDT
Return %: -0.3598 %[Kill switch triggered]
Current profitability is -0.003550034854458. Stopping the bot...
kill_switch - Kill switch threshold reached. Stopping the bot...ticker
Displays market ticker prices such as best bid, best ask, mid price and last trade price.
When optional arguments are not used i.e. running ticker alone displays the output from the maker market of a cross-exchange strategy or primary market when using arbitrage.
Note: This command will only work while a strategy is running.
Optional arguments
| Command Argument | Description |
|---|---|
--exchange | The specific exchange of the market |
--market | The market trading pair of the order book |
--live | Displays the ticker in real time |
You can use arguments --live to displays market ticker prices such as best bid, best ask, mid price and last trade price in real time. For example, run ticker --live.
Sample usage
When running a cross-exchange or arbitrage strategy, you can specify which exchange and market you can display.
>>> ticker --exchange binance --market ETH-USDT
Best Bid Best Ask Mid Price Last Trade
351.41 351.42 351.415 351.42