The concrete strategy classes included with Hummingbot, including
DiscoveryStrategy - are all child classes of
How It Works¶
All strategy modules are child classes of
TimeIterator, which is called via
c_tick() every second.
What this means is, a running strategy module is called every second via its
c_tick() method to check on the markets and wallets, and decide whether it should perform any trades or not. One way to think about it is that a strategy module acts like it's watching a movie frame-by-frame via
c_tick(), and reacts to what it sees in real time via trading actions.
If you're reading or writing a strategy module, the
c_tick() function should be treated as the entry point of a strategy module. If you're reading a strategy module's code,
c_tick() should be where you start. If you're writing a new strategy module,
c_tick() is also going to where you start writing the important bits of your strategy.
StrategyBase object may be associated with multiple markets.
cdef c_add_markets(self, list markets)
Associates a list of
MarketBaseobjects to this
cdef c_remove_markets(self, list markets)
Disassociates a list of
MarketBaseobjects from this
MarketBaseobjects currently associated with this
Market Events Interface¶
StrategyBase class comes with a set of interfaces functions for handling market events from associated
MarketBase objects, which may be overridded by child classes to receive and process market events.
The event interface functions are as follows:
cdef c_did_create_buy_order(self, object order_created_event)
A buy order has been created. Argument is a
cdef c_did_create_sell_order(self, object order_created_event)
A sell order has been created. Argument is a
cdef c_did_fill_order(self, object order_filled_event)
An order has been filled in the market. Argument is a
cdef c_did_fail_order(self, object order_failed_event)
An order has failed in the market. Argument is a
cdef c_did_cancel_order(self, object cancelled_event)
An order has been cancelled. Argument is a
cdef c_did_expire_order(self, object expired_event)
An order has expired. Argument is a
cdef c_did_complete_buy_order(self, object order_completed_event)
A buy order has been completely filled. Argument is a
cdef c_did_complete_sell_order(self, object order_completed_event)
A sell order has been completely filled. Argument is a
Creating and Cancelling Orders¶
StrategyBase includes pre-defined logic for creating and cancelling trading orders - which are the primary ways for a strategy to interact with associated markets.
It is highly encouraged to use these functions to create and remove orders, rather than calling functions like
MarketBase objects directly - since the functions from
StrategyBase provides order tracking functionalities as well.
cdef str c_buy_with_specific_market(self, object market_trading_pair_tuple, object amount, object order_type = *, object price = *, double expiration_seconds = *)
cdef str c_sell_with_specific_market(self, object market_trading_pair_tuple, object amount, object order_type = *, object price = *, double expiration_seconds = *)
Creates a buy or a sell order in the market specified by
market_trading_pair_tuple, returns the order ID string.
MarketTradingPairTupleobject specifying the
MarketBaseobject and trading pair to create the order for.
Decimalobject, specifying the order size in terms of the base asset.
order_type: an optional
OrderTypeenum specifying the order type. Default value is
price: an optional
Decimalobject, specifying the price for a limit order. This parameter is ignored if
expiration_seconds: an optional number, which specifies how long a limit should automatically expire. This is mostly only used by decentralized exchanges like RadarRelay, where active order cancellation costs gas and thus passive order cancellation via expiration is preferred.
cdef c_cancel_order(self, object market_pair, str order_id)
Cancels an active order from a market.
MarketTradingPairTupleobject specifying the
MarketBaseobject and the trading pair to cancel order from.
order_id: Order ID string returned from a previous call to order creation functions above.
StrategyBase object comes with an internal attribute
_sb_order_tracker, which is an
OrderTracker object. The
OrderTracker object is responsible for tracking all active and in-flight orders created by the
StrategyBase object, and also all in-flight order cancels.
When writing or modifying a strategy module, you can use the built-in
OrderTracker object to query the active or in-flight orders / cancels you currently have. It's useful for preventing issuing duplicate orders or order cancels.
Below are some of the user functions or properties under
OrderTracker that you can use:
Returns a list of still active limit orders, with their market object.
Returns a dictionary mapping from market trading pair tuples to lists of active limit orders.
Returns a list of active limit bid orders, with their market object.
Returns a list of active limit ask orders, with their market object.
Returns a list of in-flight or active market orders, with their market object. This is useful for decentralized exchanges where market orders may take a minute to settle due to block delay.
Returns a dictionary of order IDs that are being cancelled.