# Task 1 — OrderBookTracker & Data Source¶

The UML Diagram, given above, illustrates the relations between OrderBookTracker and its subsidiary classes.

The first 2 components to begin:

• OrderBookTracker
• OrderBookTrackerDataSource

## OrderBookTracker¶

The OrderBookTracker contains subsidiary classes that help maintain the real-time order book of a market. Namely, the classes are OrderBookTrackerDataSource, OrderBook and OrderBookMessage.

Integrating a new exchange connector requires you to extend from the OrderBookTracker base class here

The following details are required functions to be implemented in OrderBookTracker:

### exchange_name¶

This function returns the appropriate exchange name

Input Parameter(s): None
Expected Output(s): str

### tracking_single_order_book¶

This function applies the snapshot/diff messages received from OrderBookDataSource into the appropriate OrderBook for any given trading pair. Notice that OrderBookTracker maintains a dictionary of OrderBook's that can be identified by the trading pair.

Input Parameter(s): trading_pair: str
Expected Output(s): None

## OrderBookTrackerDataSource¶

The OrderBookTrackerDataSource class is responsible for making API calls and/or WebSocket queries to obtain order book snapshots, order book deltas, and miscellaneous information on the order book.

Integrating your data source component requires you to extend from the OrderBookTrackerDataSource base class here.

The following details the required functions in OrderBookTrackerDataSource:

### fetch_trading_pairs¶

Performs the necessary API request(s) to get all the active trading pairs being traded on the exchange. It is also expected that the trading pairs are converted into Hummingbot's BaseAsset-QuoteAsset format (i.e. ETH-USDT)

Input Parameter(s): None
Expected Output(s): Dict[str, float]

### get_last_traded_prices¶

Performs the necessary API request(s) to get the last traded price for the given markets (trading_pairs) and return a dictionary of trading_pair its last traded price.

Input Parameter(s): trading_pairs: List[str]
Expected Output(s): Dict[str, float]

### get_snapshot¶

Fetches order book snapshot for a particular trading pair from the exchange REST API.

Note

Certain exchanges do not add a timestamp/nonce to the snapshot response. In this case, to maintain a real-time order book would require generating a timestamp for every order book snapshot and delta messages received and applying them accordingly. In the Bittrex connector, this is performed by invoking the queryExchangeState topic on the SignalR WebSocket client.

Input Parameter(s): client: aiohttp.ClientSession, trading_pair: str
Expected Output(s): Dict[str, any]

### get_new_order_book¶

Create a new OrderBook instance and populate its bids and asks by applying the order_book snapshot to the order book. This might involve calling convert_snapshot_message_to_order_book_row() from the utils script file to parse the raw API response from the exchange.

Input Parameter: trading_pair: str
Expected Output(s): OrderBook

Note

Certain exchanges do not add a timestamp/nonce to the snapshot response. In this case, to maintain a real-time order book would require generating a timestamp for every order book snapshot and delta messages received and applying them accordingly. In the Bittrex connector, this is performed by invoking the queryExchangeState topic on the SignalR WebSocket client.

### listen_for_trades¶

Subscribes to the trade channel of an exchange. Adds incoming messages(of filled orders) to the output queue, to be processed by OrderBookTracker (in _emit_trade_event_loop)

Input Parameter: ev_loop: asyncio.BaseEventLoop, output: asyncio.Queue
Expected Output(s): None

### listen_for_order_book_diffs¶

Fetches or Subscribes to the order book snapshots for each trading pair. Additionally, parses the incoming message into an OrderBookMessage and appends it into the output Queue.

Input Parameter: ev_loop: asyncio.BaseEventLoop, output: asyncio.Queue
Expected Output(s): None

### listen_for_order_book_snapshots¶

Fetches or Subscribes to the order book deltas(diffs) for each trading pair. Additionally, parses the incoming message into an OrderBookMessage and appends it into the output Queue. |

Input Parameter: ev_loop: asyncio.BaseEventLoop, output: asyncio.Queue
Expected Output(s): None

Note

In certain cases, the 3 listen_for_ coroutines could be combined into 1 single coroutine. An example could be seen in the Crypto.com connector.

## OrderBook¶

The OrderBook is an interface class that contains all the necessary functions and variables to maintain an order book of the specified trading pair. Implementing an exchange connector requires its own order book class that extends from the OrderBook.

The following details are required functions to be implemented in the new OrderBook class:

### snapshot_message_from_exchange¶

Converts json snapshot data from the exchange into standard OrderBookMessage format.

Input Parameter(s): msg: Dict[str, any], timestamp: float, metadata: Optional[Dict] = None
Expected Output(s): OrderBookMessage

### diff_message_from_exchange¶

Converts json diff data from the exchange into standard OrderBookMessage format.

Input Parameter(s): msg: Dict[str, any], timestamp: float, metadata: Optional[Dict] = None
Expected Output(s): OrderBookMessage

### trade_message_from_exchange¶

Converts json trade data from the exchange into standard OrderBookMessage format.

Input Parameter(s): msg: Dict[str, any], timestamp: float, metadata: Optional[Dict] = None
Expected Output(s): OrderBookMessage

Note

The functions mentioned above will have to be adequately adjusted based on the data provided by the exchange API. Using metadata to include additional information into content might be useful if data(i.e. timestamp) is not provided by the exchanges API.

## OrderBookMessage¶

The OrderBookMessage is an abstract class that stores the relevant order book information obtained from either the exchange or a local db. Integrating a new exchange connector will require implementing its own class that extends from OrderBookMessage.

The OrderBookMessage base class contains 3 main attributes, namely:

• type: OrderBookMessageType
Specified and differentiate the messages from SNAPSHOT, DIFF and TRADE types.

• content: Dict[str, any]
Contains the API response for snapshot, diff and trades in a JSON format.

• timestamp: float
Defines the time in which the message is received.

The following details are required functions to be implemented in the new OrderBookMessage class:

### update_id¶

Only relevant for OrderBookMessageType.DIFF and OrderBookMessageType.SNAPSHOT messages. This id is either the timestamp or the message nonce of the message.

### trade_id¶

Only relevant for OrderBookMessageType.TRADE messages. This id is either the trade id itself or the timestamp of the message.

### trading_pair¶

Specifies the trading pair in which this order book message is associated to.

### asks¶

Only relevant for OrderBookMessageType.DIFF and OrderBookMessageType.SNAPSHOT messages. List of all the order book entries on the ask side.

### bids¶

Only relevant for OrderBookMessageType.DIFF and OrderBookMessageType.SNAPSHOT messages. List of all the order book entries on the bid side.

## Utility Functions¶

It contains any miscellaneous functions that are not completely associated with the classes defined in the overall architecture but necessary for Hummingbot to perform its functions adequately. These are stored in the *_utils.py file.

Below are some examples of such functions:

Function(s) Description
convert_snapshot_message_to_order_book_row() Performs the necessary conversion from OrderBookMessage to a Tuplep[List[OrderBookRow]]
get_new_client_order_id() Generates a Hummingbot client order id from which it does its own tracking.
convert_from_exchange_trading_pair() Converts the exchange's trading pair to [Base]-[Quote] formats and return the output.
convert_to_exchange_trading_pair() Converts HB's [Base]-[Quote] trading pair format to the exchange's trading pair format and return the output.

Note

The convert_from/to_exchange_trading_pair() functions are only required if the exchange does not provide trading pairs in Base-Quote format.

For reference you can refer to Crypto.com or ProBit.

## Exchange Constants¶

It contains all the constant variables associated with an exchange.

Below are some examples of such variables

Variables(s) Type Description
EXCHANGE_NAME str Name used to identify the exchange throughout Hummingbot.
REST_URL str Base URL for the exchange's REST API.
WS_PRIVATE_CHANNELS List[str] List of all the WebSocket channels that an exchange provides.
ORDER_STATUSES List[str]` List of all the order statuses as defined by the exchange.

For reference you can refer to Crypto.com or ProBit.

## Debugging & Testing¶

As part of the QA process, for each task (Task 1 through 3), you are required to include the unit test cases for the code review process to begin. Refer to Option 1: Unit Test Cases to build your unit tests.

Last update: 2021-09-27