MLThon API package

Submodules

mlthon.api.istrat_env module

class IStratEnv

Bases: object

add_cmd_hook(cmd_name_str, callback_func)

Dynamically hook a command (by name) to a callback function. Every time the environment receives that command name, the corresponding callback function will be invoked, and parameters (if any) are provided to that callback as a List of strings TODO:(review capitalization effect on cmd_name_str)

fetch_account_info(exchange)

Obtain account related information for that exchange.

fetch_funding_info(exchange, instrument_id)

Obtain the funding rate for the provided derivative pair.

fetch_order_status(exchange, instrument_id, client_ord_id)

Obtain order status information about the order with matching instrument and client order ID.

fetch_orders_info(exchange, instrument_id=None)

Obtain a list of all the open orders for the provided exchange. If the instrument ID is also provided, only the orders for that instrument ID will be listed

fetch_position_info(exchange, instrument_id)

Obtain the position for the provided derivative pair.

fetch_wallet_info(exchange, coin)

Obtain the wallet balance for the provided coin.

login(strat_name)

log into the framework

publish_telegram(msg)

Publish a msg to the strategy telegram channel

send_cancel_all(exchange, instrument_id)

Cancel all the orders on the provided Exchange, for the given instrument ID.

send_cancel_order(exchange, instrument_id, client_ord_id)

Cancel the order with the provided client order ID.

send_modify_order(exchange, client_ord_id, new_price, new_qty)

Modify the order with the provided client order ID, allowing users to modify only the price or only the quantity.

send_new_order(client_id, exchange, instrument_id, side, price, qty, exec_instr, ord_type, time_in_force, close_position)

Create a new Order. Return the client order ID as an int. Note that price and qty parameters are strings and that the user is responsible for providing valid values.

send_stop_ack()

When the strategy has received an on_stop() callback from the infra, it needs to let the infra know when it is done “stopping”. After having sent that, the api should no longer send requests, until it received another on_start() callback

setup_daily_callback(hh_mm_ss, callback_func)

Setup a daily callback triggering the invocation of callback_func. The daily callback is recurrent IFF it returns True, and cancelled in any other case. The format of hh_mm_ss is ‘HH:mm:ss’, for instance ‘16:30:00’ is 4PM. The timezone of the system is assumed.

setup_timer(duration_ms, callback_func)

Setup a timer which will trigger the invocation of the provided callback function every duration_ms milliseconds. If the callback returns True, the timer is renewed. Any other return value (including no return value) will cause the timer to be cancelled.

class MDSub(value)

Bases: mlthon.basics.mlt_enum.MltEnum

An enumeration.

BBO = (3,)

LevelBook = (1,)

OrderBook = (0,)

PriceLevelBook = (2,)

PublicTrades = 4

mlthon.api.istrategy module

ML Tech, Inc. Strategy API docstrings

Note: The trading environment is an IStratEnv class instance, which provides key functionalities for order entry, market data update, etc.

A trading strategy runnable in our framework is actually a class implementing the IStrategy interface below. It’s nothing more than an API, providing multiple callback functions, which would be invoke by the trading environment when the corresponding information comes into the system.

Inside these callback, researchers can use the functionalities of the trading environment to send orders, get information, etc.(Check the documentation of the trading environment istrat_env for more details). Check the docstrings of callback functions/methods below to see their usage and arguments.

See demo_strat for the example of a trading strategy.

Q&A

Are the callbacks async?

Yes. Callbacks are async. We don’t need to wait for the response once a request is sent to the trading environment. The response is delivered through different callback by the trading environment (Eg: Response for NewOrder is delivered through NewOrderAck or NewOrderReject callback).

Could we perform a blocking operation for the callbacks?

No. Blocking operations in any of the callbacks will hinder the trading environment to deliver the response of any previous requests. So blocking operations should not be performed in any of the callbacks.

What’s the typical ordering of initialization-related callbacks?

(__init__(), => on_framework_connected(), => on_start(), => on_instruments(), => on_strat_params_update(), => on_gateway_status(), => on_feed_handler_status())

In a live trading environment, here’s a typical process:

a) the constructor (__init__()) of the strategy would be called at first in order to run it.

b) python side will be connected to trading system and then on_framework_connected(env) is invoked. A REQUIRED practice in on_framework_connected(env) is logging into the trading system:

def  on_framework_connected(env: IStratEnv):
     ...
     env.login(<strategy_name>)
     ...

c) if researchers login into the trading system, the trading system side will be able to confirm that it’s good to send msg back and forward. Then the following things would happen:

c.1) a “start” execution command would be sent back from the trading system (just like a hook command, but triggered by the system itself automatically). Then on_start() method would be called.

c.2) all instrument information would be sent from trading system at once, on_instruments() method would be invoked.

c.3) all strat params would be sent from trading system, on_strat_params_update() would be invoked.

d) on_gateway_status() and on_feed_handler_status() won’t be invoked when gtw and feed handler are still ready to trade (gtw and feed handler are ready even before the connection between python side and trading system is established). These two methods would be invoked only when gtw and fee handler change from ready to other states (or later on, change from other states back to ready). So these two methods are not initialized-related callbacks indeed

class IStrategy

Bases: object

The interface of a strategy runnable on the trading environment.

abstract on_account_info(exchange, user_id)

In this callback method, researchers should define the behavior of the strategy when receiving account info. For now, this message (and thus, this method) is not very useful.

Parameters

• exchange (Exchange) – exchange the account info comes from.

• user_id (str) – account information - user ID of this account.

Return type

None

abstract on_add_level(exchange, instrument_id, side, level_id, price, qty, recv_ts)

In this callback method, researchers should define the behavior of the strategy when receiving a add-level market data. This method would be invoked by the trading environment, with information of this market data record.

Parameters

• exchange (Exchange) – exchange with market data update (add level).

• instrument_id (int) – instrument ID with market data update.

• side (Side) – side of the add-level update.

• level_id (int) – level ID of the update.

• price (Price) – price for this level.

• qty (Qty) – quantity for this level.

• recv_ts (int) – timestamp when receiving this record. Trading environment will pass current timestamp to it if unspecified.

Return type

None

Example

For example, when the feed handler receive an add-level buy order update from exchange Bybit, for instrument ID 30000000000 (BTC-USD inverse perpetual in Bybit), with level ID 92265000, price 9226.5 and qty 13952, the trading environment will invoke this callback method with exchange Exchange.Bybit, instrument ID 30000000000, side Side.Buy, level_id 92265000, price Price(‘9226.50000000’) and qty Qty(‘13952.00000000’).

abstract on_add_price_level(exchange, instrument_id, side, price, qty, recv_ts)

In this callback method, researchers should define the behavior of the strategy when receiving a add-price-level market data. This method would be invoked by the trading environment, with information of this market data record.

Parameters

• exchange (Exchange) – exchange with market data update (add price level).

• instrument_id (int) – instrument ID with market data update.

• side (Side) – side of the add-price-level update, Side.Sell or Side.Buy.

• price (Price) – price for this level.

• qty (Qty) – quantity for this level.

• recv_ts (int) – timestamp when receiving this record. Trading environment will pass current timestamp to it if unspecified.

Return type

None

Example

For example, when the feed handler receive an add-price-level buy order update from exchange Bybit, for instrument ID 30000000000 (BTC-USD Inverse Perpetual in Bybit) BTC-USD, with price 9297 and qty 13952, the trading environment will invoke this callback method with exchange Exchange.Bybit, instrument ID 30000000000, side Side.Buy, price Price(‘9226.50000000’) and qty Qty( ‘13952.00000000’).

abstract on_best_ask_level_update(exchange, instrument_id, price, qty, recv_ts)

In this callback method, researchers should define the behavior of the strategy when best ask level is updated. This method would be invoked by the trading environment, with information of the new best ask level.

Parameters

• exchange (Exchange) – the exchange where one of the product has best ask level update.

• instrument_id (int) – the product with best ask level update.

• price (Price) – price level for the new best ask.

• qty (Qty) – quantity for the new best ask.

• recv_ts (int) – timestamp when receiving this update. Trading environment will pass current timestamp to it if unspecified.

Return type

None

abstract on_best_bid_level_update(exchange, instrument_id, price, qty, recv_ts)

In this callback method, researchers should define the behavior of the strategy when best bid level is updated. This method would be invoked by the trading environment, with information of the new best bid level.

Parameters

• exchange (Exchange) – the exchange where one of the product has best bid level update.

• instrument_id (int) – the product with best bid level update.

• price (Price) – price level for the new best bid.

• qty (Qty) – quantity for the new best bid.

• recv_ts (int) – timestamp when receiving this update. Trading environment will pass current timestamp to it if unspecified.

Return type

None

abstract on_cancel_all_ack(exchange, instrument_id)

When sending a cancel-all request and get acknowledgement from the exchange, exchange will send a cancel all ack message back to the trading environment. Then the environment will invoke this method with all the necessary information of a cancel order ack message. So in this callback method, researchers should define the behavior of the strategy (the api) when the cancel-all requested is acknowledged.

Parameters

• exchange (Exchange) – exchange of the cancel-all request.

• instrument_id (int) – instrument (product) of this cancel-all request, represented by ID. This DOES NOT correspond the the actual cancellation of the corresponding order(s), which is signaled by the on_order_cancelled callback.

Return type

None

abstract on_cancel_all_reject(exchange, instrument_id, reject_code, reject_reason)

In this callback method, researchers should define the behavior of the strategy (the api) when the cancel-all requested is rejected. Trading environment would invoke it with all the necessary information when the request is rejected by the exchange.

Parameters

• exchange (Exchange) – exchange of this request.

• instrument_id (int) – instrument/product of this request, represented as ID

• reject_code (GtwRejectCode) – reject code from Gateway. Code represents the reason of rejection, e.g. 1000 = GtwNotReady (gateway is not ready for requests).

• reject_reason (str) – attached reason for the rejection.

• Note that ‘reject_reason’ may be empty. Strategy developers should familiarize themselves with

• the meaning of GtwRejectCode, as it may help them react differently to different types of rejection.

Return type

None

abstract on_cancel_order_ack(exchange, client_id)

When sending a cancel order and get acknowledgement from the exchange, exchange will send a cancel order ack message back to the trading environment. Then the environment will invoke this method with all the necessary information of a cancel order ack message. So in this callback method, researchers should define the behavior of the strategy (the api) when the cancel order requested is acknowledged.

Parameters

• exchange (Exchange) – exchange of this cancel order.

• client_id (str) – client ID (generated and kept in the internal system) for this cancel order. This DOES NOT correspond the the actual cancellation of the corresponding order, which is signaled by the on_order_cancelled callback.

Return type

None

abstract on_cancel_order_reject(exchange, nullable_client_id, reject_code, reject_reason)

In this callback method, researchers should define the behavior of the strategy (the api) when the cancel order requested is rejected. Trading environment would invoke it with all the necessary information when the request is rejected by the exchange.

Parameters

• exchange (Exchange) – exchange of this order.

• nullable_client_id (str) – internal client ID. client_id is optional here. If it’s None, the corresponding request would be cancel-all.

• reject_code (GtwRejectCode) – reject code from Gateway. Code represents the reason of rejection, e.g. 1000 = GtwNotReady (gateway is not ready for requests).

• reject_reason (str) – attached reason for the rejection.

• Note that ‘reject_reason’ may be empty. Strategy developers should familiarize themselves with

• the meaning of GtwRejectCode, as it may help them react differently to different types of rejection.

Return type

None

abstract on_delete_level(exchange, instrument_id, side, level_id, recv_ts)

In this callback method, researchers should define the behavior of the strategy when receiving a delete-level market data. This method would be invoked by the trading environment, with information of this market data record.

Parameters

• exchange (Exchange) – exchange with market data update (delete level).

• instrument_id (int) – instrument ID with market data update.

• side (Side) – side of the delete-level update.

• level_id (int) – level ID of the update.

• recv_ts (int) – timestamp when receiving this record. Trading environment will pass current timestamp to it if unspecified.

Return type

None

Example

For example, when the feed handler receive a delete-level buy order update from exchange Bybit, for instrument ID 30000000000 (BTC-USD inverse perpetual in Bybit), with level ID 92375000, the trading environment will invoke this callback method with exchange Exchange.Bybit, instrument ID 30000000000, side Side.Buy and level_id 92375000.

abstract on_delete_price_level(exchange, instrument_id, side, price, recv_ts)

In this callback method, researchers should define the behavior of the strategy when receiving a delete-price-level market data update. This method would be invoked by the trading environment, with information of this market data record.

Parameters

• exchange (Exchange) – exchange with market data update (delete price level).

• instrument_id (int) – instrument ID with market data update.

• side (Side) – side of the delete-price-level update.

• price (Price) – price level of this update

• recv_ts (int) – timestamp when receiving this record. Trading environment will pass current timestamp to it if unspecified.

Return type

None

Example

For example, when the feed handler receive a delete-price-level buy order update from exchange Bybit, for instrument ID 30000000000 (BTC-USD inverse perpetual in Bybit), with price 9226.5, the trading environment will invoke this callback method with exchange Exchange.Bybit, instrument ID 30000000000, side Side.Buy and price Price(‘9226.50000000’).

abstract on_feed_handler_status(exchange, status, detail)

This callback method should define the behaviors of the strategy (the api) when receiving Feed Handler status transition. Possible status values are: ‘SnapshotStart’, ‘SnapshotEnd’, ‘Disconnected’:

SnapshotStart - the feed is connected and the following events are a snapshot of the feed

SnapshotEnd - all the events between SnaphotStart and SnapshotEnd constitute the initial snapshot of the feed. subsequent events are incremental updates (AKA delta updates)

Disconnected - The feed got disconnected, and is attempting to reconnect, once connected a new snapshot will be observed

The api (this callback method) should clear the orders books when receiving a Connecting status. Between SnapshotStart and End, the api should build the order book. After receiving SnapshotEnd, the api should continue building its order book, knowing that the updates it receives are now live incremental updates.

Parameters

• exchange (Exchange) – exchange with Feed Handler status transition.

• status (FeedHandlerStatus) – new Feed Handler status, ‘SnapshotStart’, ‘SnapshotEnd’ or ‘Disconnected’.

• detail (str) – attached details for the status transition.

Return type

None

abstract on_framework_connected(env)

In this callback method, researchers should define the behavior of the strategy (the api) when it’s connected to the trading framework. When the trading framework (gateway, feed handler, etc.) is connected, the environment will invoke this method. Note that login via trading environment is REQUIRED in this method so that the strategy could be registered into the system and start sending msg back and forward. An example is provided below.

Parameters

env (IStratEnv) – this callback may provide trading env as a parameter

Return type

None

Example

# A simple implementation for this method (need to initiate the internal states in the constructor, in order to keep them) :

class ExampleStrat(IStrategy):
    def __init__(self, cfg):  # or no cfg
        ...
        self._env_ = None  # keep the internal state for trading env object
    ......
    def  on_framework_connected(env: IStratEnv):
        self._env_ = env
        ...
        self._env_.login("example strat")
        ...
    ......

abstract on_framework_disconnected()

In this callback method, researchers should define the behavior of the strategy (the api) when losing connection to the framework itself. When losing connections, the environment will invoke this method.

Return type

None

abstract on_funding_info(exchange, instrument_id, funding_rate, next_funding_ts)

In this callback method, researchers should define the behavior of the strategy when receiving funding info. Some exchanges reward users for being long or short certain derivative products. This method will be invoked by the trading environment, with information about the rate of such rewards.

Parameters

• exchange (Exchange) – exchange this info comes from.

• instrument_id (int) – instrument ID of this funding info.

• funding_rate (float) – funding rate of this funding info.

• next_funding_ts (int) – timestamp of next funding event.

Return type

None

abstract on_gateway_status(exchange, status, detail)

This callback method should define the behaviors of the strategy (the api) when receiving Gateway status transition. Possible status values are ‘ReadyToTrade’, ‘Connecting’ and ‘Maintenance’:

ReadyToTrade - connected to trading system and ready to trade (get/send orders etc..) Connecting - The gateway is connecting and trying to get ready Maintenance - The gateway of some exchanges would report this status when it’s in maintenance

The api should only try and send order on an gateway if it is in ReadyToTrade status. Not doing so will result in a reject.

Parameters

• exchange (Exchange) – exchange with gateway status transition. In the example above, it’s Exchange.Blade.

• status (GtwStatus) – new gateway status. In the example above, it’s GtwStatus.ReadyToTrade.

• detail (str) – attached details for this record.

Return type

None

Example

For example, when the gateway for Bybit is connected and ready to trade, the trading environment would invoke this callback method, with exchange Exchange.Bybit, status ReadyToTrade, and detail ‘null’. Then in this callback method, researchers can set up some internal states to tell the strategy (the api) that it’s able to send orders now.

on_instruments(instruments)

This method is invoked when all instruments used by this strategy have been loaded. It would include all the information necessary for trading purposes, e.g. min quantity for an instrument, etc. It is the burden of the strategy to save the information it requires in order to trade. An example implementation of this method is provided below.

Parameters

instruments (typing.Iterable[Instrument]) – an iterable (set or list) of Instrument objects, containing the necessary info for product/instruments. Check Instrument class for more details. Note that this method is only called once, providing all the instruments needed by this strategy.

Return type

None

Example

# A simple implementation for this method (need to initiate the internal states in the constructor, in order to keep them) :

class ExampleStrat(IStrategy):
    def __init__(self, cfg):  # or no cfg
        ...
        self._instruments_by_name_ = {}
        # if using instrument id to find instrument, researchers can also keep self._instruments_by_id_
    ......
    def on_instrument(self, instruments: typing.Iterable[Instrument]):
        self._instruments_by_name_ = {instrument.get_instrument_name(): instrument for instrument in instruments}
        # self._instruments_by_id_ = {instrument.get_instrument_id(): instrument for instrument in instruments}
    ......

abstract on_modify_level(exchange, instrument_id, side, level_id, new_qty, recv_ts)

In this callback method, researchers should define the behavior of the strategy when receiving a modify-level market data. This method would be invoked by the trading environment, with information of this market data record.

Parameters

• exchange (Exchange) – exchange with market data update (modify level).

• instrument_id (int) – instrument ID with market data update.

• side (Side) – side of the modify-level update.

• level_id (int) – level ID of the update.

• new_qty (Qty) – new quantity for this level.

• recv_ts (int) – timestamp when receiving this record. Trading environment will pass current timestamp to it if unspecified.

Return type

None

Example

For example, when the feed handler receive a modify-level buy order update from exchange Bybit, for instrument ID 30000000000 (BTC-USD inverse perpetual in Bybit), with level ID 92360000 and qty 64628, the trading environment will invoke this callback method with exchange Exchange.Bybit, instrument ID 30000000000, side Side.Buy, level_id 92360000 and new_qty Qty(‘64628.00000000’).

abstract on_modify_order_ack(exchange, client_id, new_price, new_qty, leaves_qty)

When sending a modify order and get acknowledgement from the exchange, exchange will send a modify order ack message back to the trading environment. Then the environment will invoke this method with all the necessary information of a modify order ack message. So in this callback method, researchers should define the behavior of the strategy (the api) when the modify order requested is acknowledged.

Parameters

• exchange (Exchange) – exchange of this order, e.g. Exchange.Bybit.

• client_id (str) – client ID is an identification in the internal system.

• new_price (Price) – new price of this modified order.

• new_qty (Qty) – new quantity of this modified order.

• leaves_qty (Qty) – remaining quantity of this order.

• Note that new_price and new_qty are optional, but at least one of them must be present.

Return type

None

abstract on_modify_order_reject(exchange, client_id, reject_code, reject_reason)

In this callback method, researchers should define the behavior of the strategy (the api) when the modify order requested is rejected. Trading environment would invoke it with all the necessary information when the request is rejected by the exchange.

Parameters

• exchange (Exchange) – exchange of this order.

• client_id (str) – internal client ID.

• reject_code (GtwRejectCode) – reject code from Gateway. Code represents the reason of rejection, e.g. 1000 = GtwNotReady (gateway is not ready for requests).

• reject_reason (str) – attached reason for the rejection.

• Note that ‘reject_reason’ may be empty. Strategy developers should familiarize themselves with

• the meaning of GtwRejectCode, as it may help them react differently to different types of rejection.

Return type

None

abstract on_modify_price_level(exchange, instrument_id, side, price, new_qty, recv_ts)

In this callback method, researchers should define the behavior of the strategy when receiving a modify-price-level market data. This method would be invoked by the trading environment, with information of this market data record.

Parameters

exchange (Exchange) – exchange with market data update (modify price level).

instrument_id: int

instrumen id with market data update.

side: Side

side of the modify-price-level update.

price: Price

price level ID of the update.

new_qty: Qty

new quantity for this level.

recv_ts: int

timestamp when receiving this record. Trading environment will pass it as current timestamp if unspecified.

Return type

None

Example

For example, when the feed handler receive a modify-price-level buy order update from exchange Bybit, for instrument ID 30000000000 (BTC-USD inverse perpetual in Bybit), with price 9226.5 and new qty 64628, the trading environment will invoke this callback method with exchange Exchange.Bybit, instrument ID 30000000000, side Side.Buy, price Price(‘9226.50000000’).

abstract on_new_order_ack(exchange, client_id, exchange_id, instrument_id, side, price, qty, leaves_qty, order_type, tif, exec_instr)

When sending a new order and get acknowledgement from the exchange, exchange will send a new order ack message back to the trading environment. Then the environment will invoke this method with all the necessary information of a new order ack message. So in this callback method, researchers should define the behavior of the strategy (the api) when the new order requested is acknowledged.

Parameters

• exchange (Exchange) – exchange of this order, e.g. Exchange.Bybit.

• client_id (str) – client ID is an identification in the internal system.

• exchange_id (str) – ID in external exchange.

• instrument_id (int) – product of this order, represented via its ID, e.g. 30000000000 represents BTC-USD inverse perpetual in Bybit.

• side (Side) – side of this order, Side.Buy or Side.Sell.

• price (Price) – price of this order.

• qty (Qty) – quantity of this order.

• leaves_qty (Qty) – leave quantity (number of shares still open for execution) in this order.

• order_type (OrderType) – type of this order, OrderType.Unset or OrderType.Limit (limit order)

• tif (TIF) – time in force, TIF.Unset, TIF.GTC (Good to Cancel), TIF.IOC (Execute immediately, even partially, the rest is cancelled)

• exec_instr (ExecInstructions) – execution instruction, ExecInstructions.Unset or ExecInstructions.PostOnly

Return type

None

abstract on_new_order_reject(exchange, client_id, reject_code, reject_reason)

In this callback method, researchers should define the behavior of the strategy (the api) when the new order requested is rejected. Trading environment would invoke it with all the necessary information when the request is rejected by the exchange.

Parameters

• exchange (Exchange) – exchange of this order.

• client_id (str) – internal client ID.

• reject_code (GtwRejectCode) – reject code from Gateway. Code represents the reason of rejection, e.g. 1000 = GtwNotReady (gateway is not ready for requests).

• reject_reason (str) – attached reason for the rejection.

• Note that ‘reject_reason’ may be empty. Strategy developers should familiarize themselves with

• the meaning of GtwRejectCode, as it may help them react differently to different types of rejection.

Return type

None

abstract on_order_cancelled(exchange, client_id, unsolicited, engine_ts, recv_ts, cancel_code, cancel_reason)

In this callback method, researchers should define the behavior of the strategy (the api) when the order is cancelled. Trading environment would invoke it, with all the necessary information, on the cancellation of an order, regardless of whether it was requested by the user or not.

Parameters

• exchange (Exchange) – exchange of this order.

• client_id (str) – internal client ID.

• unsolicited (bool) – True means that the cancel was not requested by the user.

• engine_ts (int) – timestamp at which the cancellation occurred. 0 if unknown.

• recv_ts (int) – record reception timestamp. Trading environment will pass current timestamp to it if unspecified.

• cancel_code (CancelCode) – cancel code, ‘Unset’, ‘CanceledByUser’ or ‘SelfTradePrevention’ (cancellation not requested by user)

• cancel_reason (str) – reason for cancellation

Return type

None

abstract on_order_execution(exchange, client_id, side, price, fill_qty, leaves_qty, exec_ts, recv_ts)

In this callback method, researchers should define the behavior of the strategy (the api) when the order is executed (filled). Trading environment would invoke it on the execution (or fill) of an order, with all the necessary information.

Parameters

• exchange (Exchange) – exchange of this order.

• client_id (str) – internal client ID.

• side (Side) – side of this order.

• price (Price) – price level of this order.

• fill_qty (Qty) – filled quantity of this order.

• leaves_qty (Qty) – leave quantity (number of shares still open for execution) of this order.

• exec_ts (int) – execution timestamp.

• recv_ts (int) – record reception timestamp. Trading environment will pass current timestamp to it if unspecified.

Return type

None

abstract on_order_status(exchange, instrument_id, client_ord_id, exch_ord_id, side, price, leaves_qty, status, order_type, tif, exec_instr)

In this callback method, define behaviors of the strategy when receiving the order information for a single order as requested by a call to fetch_order_status().

Parameters

• exchange (Exchange) – exchange of this order.

• client_ord_id (str) – client ID is an identification in our internal system.

• exch_ord_id (str) – ID in external exchange.

• instrument_id (int) – instrument ID of this single order info.

• side (Side) – side of this order, Side.Buy or Side.Sell.

• price (Price) – price of this order.

• leaves_qty (Qty) – leave quantity (number of shares still open for execution) in this order.

• status (OrderStatus) – status of the order, e.g. filled

• order_type (OrderType) – type of this order, OrderType.Unset or OrderType.Limit (limit order)

• tif (TIF) – time in force, TIF.Unset, TIF.GTC (Good to Cancel), TIF.IOC (Execute immediately, even partially, the rest is cancelled)

• exec_instr (ExecInstructions) – execution instruction, ExecInstructions.Unset or ExecInstructions.PostOnly

Return type

None

abstract on_orders_info(exchange, orders)

In this callback method, researchers should define the behavior of the strategy when receiving orders info. The trading environment would invoke this method with exchange and orders containing a list of open orders matching the filtering criteria passed when making the request.

Parameters

• exchange (Exchange) – exchange of this orders info

• orders (typing.List[Order]) – a list of open orders matching the filtering criteria passed when making the request

Return type

None

abstract on_position_info(exchange, instrument_id, position)

In this callback method, researchers should define the behavior of the strategy when receiving position info. For derivative products, this callback method would be invoked by the trading environment with the current position. For non derivative products, cf. on_wallet_info.

Parameters

• exchange (Exchange) – exchange this info comes from.

• instrument_id (int) – instrument ID of this position info.

• position (Qty) – current position for this instrument.

Return type

None

abstract on_public_trade(exchange, instrument_id, side, price, qty, exec_ts, recv_ts)

This method invoked when a public trade is observed in the market data. So in this callback method, researchers should define the behavior of the strategy when receiving a public trade market data record.

Parameters

• exchange (Exchange) – exchange with market data update (public trade).

• instrument_id (int) – instrument ID with market data update.

• side (Side) – taker side of this public trade.

• price (Price) – price of this public trade.

• qty (Qty) – quantity of this trade.

• exec_ts (int) – trade execution timestamp.

• recv_ts (int) – timestamp when receiving this record. Trading environment will pass current timestamp to it if unspecified.

Return type

None

Example

For example, when the feed handler receive a public trade from exchange Bybit, for instrument ID 30000000000 (BTC-USD inverse perpetual in Bybit), with sell taker side, price 9297 and qty 50, executed at 1594097430153 in exchange and received to us at 1594097430427, trading environment will invoke this method with exchange Exchange.Bybit, instrument ID 30000000000, side Side.Sell, price Price(‘9297.0’), qty Qty(‘50.0’), exec_ts 1594097430153 and recv_ts 1594097430427.

abstract on_rate_limit_info(exchange, rate_limit, rate_remaining, reset_ts)

Exchanges restrict the rate at which users may send requests. This callback would be invoked by the trading environment to informs the api of its rate usage. The gtw arbitrarily invokes this callback when 50% has been used, 90% and 100% has been used. When in the danger zone (90%+) the api (this callback) should take actions to reduce its exposure so as to not end up being locked out. Repetitive violation of these limits may result in a ban.

Parameters

• exchange (Exchange) – exchange reaching this rate limit.

• rate_limit (int) – overall rate limit of this exchange. In the example above, it’s 100, i.e. 100% is the limit of Bybit.

• rate_remaining (int) – rate limit remaining. In the example above, it’s 10, i.e. have 10% rate left.

• reset_ts (int) – timestamp when the usage of the rate limit is expected to be reset to zero.

Return type

None

Example

For example, when reaching a 90% rate limit for requests in Bybit exchange, and the timestamp of rate limit reset is 1594159619, the trading environment would invoke this method, with exchange Exchange.Bybit, rate_limit 100, rate_remaining 10 and reset_ts 1594159619. Since that it has already been in the danger zone, researchers should take actions, e.g. reduce the rate of the requests, etc., in this callback method.

abstract on_request_reject(exchange, reject_code, detail, rejected_rqst_type)

In this callback method, researchers should define the behavior of the strategy when the request is rejected. This method would be invoked by the trading environment when a request sent by the strategy got rejection in gateway.

Parameters

• exchange (Exchange) – exchange rejecting the request.

• reject_code (GtwRejectCode) – reject code from Gateway. Code represents the reason of rejection, e.g. 1000 = GtwNotReady (gateway is not ready for requests).

• detail (str) – attached details for the rejection.

• rejected_rqst_type (str) – type of the rejected request.

Return type

None

abstract on_start(params)

This method is called by the environment when running ‘start’ command hook to start the strategy manually. During and after this call, the strat may request market data and/or gateway connections (if no manual start, do these in on_framework_connected).

Parameters

params (str) – params for ‘start’ command book. If manually starting the strat with some parameter setups via command hook, the parameters entered for the command hook would be passed here, as one string

Return type

None

abstract on_stop(params)

This method is called by the environment when the strategy should be stopped (running a ‘stop’ command hook manually). the strategy (the api) may take usual actions as long after this call, but it is expected to exit its trading logic.

Return type

None

on_strat_params_update(strat_params)

This method is invoked when strategy parameters used by this strategy have been loaded. It would include all the parameters necessary for trading purposes, e.g. any custom strategy parameters required for strategy. It is up to strategy to save these parameters and used them as required. An example implementation of this method is provided below.

Parameters

strat_params (typing.Dict) – Dictionary of strategy parameters expected by strategy. Note that this method is also called when strategy parameters are updated.

Return type

None

Example

# A simple implementation for this method (need to initiate the internal states in the constructor, in order to keep them) :

class ExampleStrat(IStrategy):
    def __init__(self, cfg):  # or no cfg
        self._strat_params = None
        self._prev_bid_price = 0
        ...
    ......
    def on_strat_params_update(self, strat_params: typing.Dict):
        self._strat_params = strat_params
        ...
    ......
    def on_best_bid_level_update(self, exchange: Exchange, instrument_id: int, price: Price, qty: Qty, recv_ts: int):
        | ._prev_bid_price = price
        ...
    ......

abstract on_unsupported_op(exchange, unsupported_msg_type)

Some operations may only be supported by certain exchanges. If an exchange does not support a request sent

by the api, this callback method is invoked by the trading environment.

Parameters

• exchange (Exchange) – exchange not supporting this operation.

• unsupported_msg_type (str) – a string indicating the message type of this unsupported operation.

Return type

None

Example

For example, when sending a Modify Order request but not supported by Blockchain.com exchange, the trading environment would invoke this method, with exchange Exchange.Blockchain and unsupported_msg_type ‘ModifyOrder’.

abstract on_wallet_info(exchange, coin, total_balance, available_balance)

In this callback method, researchers should define the behavior of the strategy when receiving wallet info. Trading environment would invoke this method with the balance of the wallet for the listed coin. Note that for non spot products, this is what the strategy (the api) may use to derive positional changes.

Parameters

• exchange (Exchange) – exchange this info comes from.

• coin (str) – coin of this wallet info.

• total_balance (Qty) – total balance of the listed coin in this wallet.

• available_balance (Qty) – available balance of the listed coin in this wallet.

Return type

None