Async Messages

Note

For a more in depth documentation, you should check the comments from the protobuf file.

AsyncQuotes

When client sends a productinfo request, we will subscribe it automatically to receive async productinfo definitions.

When it asks for definitions, it will be subscribed only to those instrument definitions found in all InstrumentDefinitionRequest send to the server that have the bool set to true.

Warning

The prices from these async quotes might not contain the price exponent. If that’s the case, the client should use the price exponent received inside the ProductInfoResponse or in the Snapshot message.

If the AsyncQuote contains the DomBookSnapshot member populated, the client should take those DomBookEntry entries from the DomBook and apply them on the current book(the one received in the snapshot, if this is the first async quote received).

Warning

Very rarely it happens that the server will send the max market depth in a DomBookSnapshot for AsyncQuotes, if that happens, the client should use it and update the previous max market depth received.

Each DomBookEntry contains a BookAction. The client should apply those actions using the following rules:

• The actions should be applied on the book in the order in which they come.

• An INSERT action, will shift down, with one level, all entries from the current book that have the level equal or greater than the level of the action received. On the level of the action, a new book entry will be inserted with the values received. If the action makes the book to grow above its maximum depth, the client should delete the last entry of the book. The maximum book depth can be found in the DomBookSnapshot message from Snapshot, field: market_depth.

• An UPDATE action, will update all fields of the book entry that is on the level of the action received.(Including the price.)

• A DELETE action, will delete the entry from the book from the level that was received in the entry. The client should shift up, by one level, all entries from the current book that have a level bigger than the level of the action received.

• An APPEND will insert a new book entry at the end of the book with received values. If the action makes the book to grow above its maximum depth, the client should delete the last entry of the book. The maximum book depth can be found in the DomBookSnapshot message from Snapshot, field: market_depth.

• A DELETE_FROM action, will delete all levels of the book starting from received level (including) to the last level.

• A DELETE_UNTIL action, will delete all levels of the book starting from the first level till the received level (including). The client should shift up, by the number of levels received, all entries from the current book that have a level bigger than the level of the action received.

• A DELETE_ALL action, will delete all levels of the book.

Warning

The client must rely on the LEVEL (instead of the price) of the entry received in an AsyncQuote, when applying the action on the book.

Examples of usage:

• Initial book with market depth equal to 5 (maximum capacity reached):

  Level	Price	Quantity	Num Orders
  1	367425	31	18
  2	367400	81	42
  3	367375	82	42
  4	367350	78	48
  5	367325	102	55

• Current book, after an INSERT (LVL: 3, price: 367380, quantity: 160, num_orders: 51) on initial book:

  Level	Price	Quantity	Num Orders
  1	367425	31	18
  2	367400	81	42
  3	367380	160	51
  4	367375	82	42
  5	367350	78	48

  Note

  On level 3, we’ve inserted a new entry, which resulted in pushing all levels that are >= 3, one level down. This also meant that previous level 5 became level 6, but the maximum capacity of the book is 5, so we’ve dropped the entry from level 6.

• Current book, after an UPDATE (LVL: 3, price: 367380, quantity: 160, num_orders: 51) on initial book:

  Level	Price	Quantity	Num Orders
  1	367425	31	18
  2	367400	81	42
  3	367380	160	51
  4	367350	78	48
  5	367325	102	55

  Note

  On level 3, we’ve updated the entry. We can update all fields, even the price. The other levels remain the same.

• Current book, after a DELETE (LVL: 3) on initial book:

  Level	Price	Quantity	Num Orders
  1	367425	31	18
  2	367400	81	42
  3	367350	78	48
  4	367325	102	55

  Note

  We’ve deleted the entry from level 3, which resulted in pushing all levels that are bigger than 3, one level up, therefore previous level 4 become level 3 and so on.

• Current book, after an APPEND (price: 367380, quantity: 160, num_orders: 51) on initial book:

  Level	Price	Quantity	Num Orders
  1	367425	31	18
  2	367400	81	42
  3	367375	82	42
  4	367350	78	48
  5	367380	160	51

  Note

  We’ve append the entry at the end of the book, but because the maximum capacity was reached, it just update the last entry with the new one.

• Current book, after a DELETE_FROM (LVL: 3) on initial book:

  Level	Price	Quantity	Num Orders
  1	367425	31	18
  2	367400	81	42

  Note

  We’ve deleted all entries starting from level 3 (including), which resulted in having just 2 levels in our book (the first 2 level from initial book).

• Current book, after a DELETE_UNTIL (LVL: 3) on initial book:

  Level	Price	Quantity	Num Orders
  1	367350	78	48
  2	367325	102	55

  Note

  We’ve deleted all entries starting from first till level 3 (including), which resulted in having just 2 levels in our book (the last 2 level from initial book). The last levels will be shifted up.

• Current book, after a DELETE_ALL on initial book:

  Level	Price	Quantity	Num Orders

  Note

  We’ve deleted all entries, the book will be empty.

---

InstrumentDefinitions

The client can receive asynchronous instrument definitions if whent it sends the InstrumentDefinitionRequest request, it sets the subscribe_to_async_def bool, to true.

So everytime a contract is updated or a new contract is added, that matches the criteria from the InstrumentDefinitionRequest requests made by the client in the current session, the client will receive that definition asynchronous.

To unsubscribe from these asynchronous definitions, the client must disconnect.

To understand this better, please check the Instrument Definitions Request.

---

BlockTrades

Asynchronous block trades.

---

ProductsInfo

Note

At the moment, we only send asynchronous messages only when a Product or ProductFamily is updated or added. In the future, we might send the other things from the ProductInfoResponse.

After sending a ProductInfoRequest request, the client will be automatically subscribed to asynchronous ProductsInfo. If the details of a Product or a ProductFamily are changed or a new Product or ProductFamily is added, the server will send that as an asynchronous message.

To understand this better, please check the Product Info Request.