Market Depth (Level II)

Market depth data, also known as level II, represents an instrument's order book. Via the TWS API it is possible to obtain this information with the IBApi.EClient.reqMarketDepth function (Note: it is named reqMktDepth in Java, C++, and Python). Unlike Top Market Data (Level I), market depth data is sent without sampling nor filtering, however we cannot guarantee that every price quoted for a particular security will be displayed when you invoke IBApi.EClient.reqMarketDepth. In particular, odd lot orders are not included. Beginning in API v974 and TWS v974 it is possible to Smart-route a IBApi.EClient.reqMarketDepth request to receive aggregated data from all available exchanges, similar to the TWS BookTrader display.

Requesting

The IBApi.EClient.reqMarketDepth method receives a request identifier (or ticker Id) with which to identify the incoming data, the IBApi.Contract for which we want to pull this information and the number of rows or depth level that is required. In case the market depth is smaller than the requested number of rows, the TWS will simply return the available entries.

•             client.reqMarketDepth(2001, ContractSamples.EurGbpFx(), 5, false, null);

•         client.reqMktDepth(2001, ContractSamples.EurGbpFx(), 5, false, null);

•         client.reqMarketDepth(2001, ContractSamples.EurGbpFx(), 5, False, Nothing)

•     m_pClient->reqMktDepth(2001, ContractSamples::EurGbpFx(), 5, false, TagValueListSPtr());

•         self.reqMktDepth(2001, ContractSamples.EurGbpFx(), 5, False, [])

Market Maker or Exchange

Market depth will be returned via the IBApi.EWrapper.updateMktDepth or the IBApi.EWrapper.updateMktDepthL2 callback. The two functions differ in that when there is a market maker or exchange identifier to be returned market depth data will be relayed back through IBApi.EWrapper.updateMktDepthL2. Otherwise it is returned to IBApi.EWrapper.updateMktDepth. For example, ARCA only has ARCA itself as a Market Maker. Therefore when requesting market depth data from ARCA, the data will be relayed back via IBApi.EWrapper.updateMktDepth. On the other hand, with NASDAQ market maker information is provided, so the market maker MPID will be relayed back via IBApi.EWrapper.updateMktDepthL2. The market maker MPID is reported in the 'marketMaker' string argument of the callback function. If the isSmartDepth boolean (available with API v974+) is True, the marketMaker field will indicate the exchange from which the quote originates. Otherwise it indicates the MPID of a market maker.

To check which exchanges offer deep book data, the function IBApi::EClient::reqMktDepthExchanges can be invoked. It will return a list of exchanges from where market depth is available if the user has the appropriate market data subscription.

•             client.reqMktDepthExchanges();

•         client.reqMktDepthExchanges();

•         client.reqMktDepthExchanges()

•     m_pClient->reqMktDepthExchanges();

•         self.reqMktDepthExchanges()

API 'Exchange' fields for which a market depth request would return market maker information and result in a callback to IBApi::EWrapper::updateMktDepthL2 will be indicated in the results from the IBApi::EWrapper::mktDepthExchanges field by a 'True' value in the 'isL2' field:

•         public void mktDepthExchanges(DepthMktDataDescription[] depthMktDataDescriptions)
          {
              Console.WriteLine("Market Depth Exchanges:");
  
              foreach (var depthMktDataDescription in depthMktDataDescriptions)
              {
                  Console.WriteLine("Depth Market Data Description: Exchange: {0}, Security Type: {1}, Listing Exch: {2}, Service Data Type: {3}, Agg Group: {4}", 
                      depthMktDataDescription.Exchange, depthMktDataDescription.SecType, 
                      depthMktDataDescription.ListingExch, depthMktDataDescription.ServiceDataType,
                      Util.IntMaxString(depthMktDataDescription.AggGroup));
              }
          }

•     @Override
      public void mktDepthExchanges(DepthMktDataDescription[] depthMktDataDescriptions) {
          System.out.println(EWrapperMsgGenerator.mktDepthExchanges(depthMktDataDescriptions));
      }

•         Public Sub mktDepthExchanges(depthMktDataDescriptions As DepthMktDataDescription()) Implements EWrapper.mktDepthExchanges
              Console.WriteLine("Market Depth Exchanges:")
  
              For Each depthMktDataDescription In depthMktDataDescriptions
                  Console.WriteLine("Depth Market Data Descriprion. Exchange: " & depthMktDataDescription.Exchange &
                                    " Security Type: " & depthMktDataDescription.SecType &
                                    " Listing Exch: " & depthMktDataDescription.ListingExch &
                                    " Service Data Type: " & depthMktDataDescription.ServiceDataType &
                                    "  Agg Group: " & Util.IntMaxString(depthMktDataDescription.AggGroup))
              Next
          End Sub

• void TestCppClient::mktDepthExchanges(const std::vector<DepthMktDataDescription> &depthMktDataDescriptions) {
      printf("Mkt Depth Exchanges (%lu):\n", depthMktDataDescriptions.size());
  
      for (unsigned int i = 0; i < depthMktDataDescriptions.size(); i++) {
          printf("Depth Mkt Data Description [%d] - exchange: %s secType: %s listingExch: %s serviceDataType: %s aggGroup: %s\n", i,
              depthMktDataDescriptions[i].exchange.c_str(),
              depthMktDataDescriptions[i].secType.c_str(),
              depthMktDataDescriptions[i].listingExch.c_str(),
              depthMktDataDescriptions[i].serviceDataType.c_str(),
              Utils::intMaxString(depthMktDataDescriptions[i].aggGroup).c_str());
      }
  }

•     def mktDepthExchanges(self, depthMktDataDescriptions:ListOfDepthExchanges):
          super().mktDepthExchanges(depthMktDataDescriptions)
          print("MktDepthExchanges:")
          for desc in depthMktDataDescriptions:
              print("DepthMktDataDescription.", desc)

Receiving

Initially, all requested/available rows will be delivered to the client application. As market moves however these rows will inevitably change. To keep the client's order book consistent, the TWS will send updates not only informing which row is to be updated but also the operation to perform in the row: insert (0), update (1) or remove (2).

•     public class EWrapperImpl : EWrapper 
      {

  ...

          public virtual void updateMktDepth(int tickerId, int position, int operation, int side, double price, decimal size)
          {
              Console.WriteLine("UpdateMarketDepth. " + tickerId + " - Position: " + position + ", Operation: " + operation + ", Side: " + side + ", Price: " + Util.DoubleMaxString(price) + ", Size: " + Util.DecimalMaxString(size));
          }

  ...

          public virtual void updateMktDepthL2(int tickerId, int position, string marketMaker, int operation, int side, double price, decimal size, bool isSmartDepth)
          {
              Console.WriteLine("UpdateMarketDepthL2. " + tickerId + " - Position: " + position + ", Operation: " + operation + ", Side: " + side + ", Price: " + Util.DoubleMaxString(price) + ", Size: " + Util.DecimalMaxString(size) + ", isSmartDepth: " + isSmartDepth);
          }

• public class EWrapperImpl implements EWrapper {

  ...

      @Override
      public void updateMktDepth(int tickerId, int position, int operation, int side, double price, Decimal size) {
          System.out.println(EWrapperMsgGenerator.updateMktDepth(tickerId, position, operation, side, price, size));
      }

  ...

      @Override
      public void updateMktDepthL2(int tickerId, int position, String marketMaker, int operation, int side, double price, Decimal size, boolean isSmartDepth) {
          System.out.println(EWrapperMsgGenerator.updateMktDepthL2( tickerId, position, marketMaker, operation, side, price, size, isSmartDepth));
      }

•     Public Class EWrapperImpl
          Implements EWrapper

  ...

          Public Sub updateMktDepth(tickerId As Integer, position As Integer, operation As Integer, side As Integer, price As Double, size As Decimal) Implements IBApi.EWrapper.updateMktDepth
              Console.WriteLine("UpdateMarketDepth. " & CStr(tickerId) & " - Position: " & CStr(position) & ", Operation: " & CStr(operation) & ", Side: " & CStr(side) &
                            ", Price: " & Util.DoubleMaxString(price) & ", Size: " & Util.DecimalMaxString(size))
          End Sub

  ...

          Public Sub updateMktDepthL2(tickerId As Integer, position As Integer, marketMaker As String, operation As Integer, side As Integer, price As Double, size As Decimal, isSmartDepth As Boolean) Implements IBApi.EWrapper.updateMktDepthL2
              Console.WriteLine("UpdateMarketDepthL2. " & CStr(tickerId) & " MarketMaker: " & marketMaker & ", Position: " & CStr(position) & ", Operation: " & CStr(operation) & ", Side: " & CStr(side) &
                            ", Price: " & Util.DoubleMaxString(price) & ", Size: " & Util.DecimalMaxString(size) & ", isSmartDepth: " & CStr(isSmartDepth))
          End Sub

• class TestCppClient : public EWrapper
  {

  ...

  void TestCppClient::updateMktDepth(TickerId id, int position, int operation, int side,
                                     double price, Decimal size) {
      printf( "UpdateMarketDepth. %ld - Position: %s, Operation: %d, Side: %d, Price: %s, Size: %s\n", id, Utils::intMaxString(position).c_str(), operation, side, 
          Utils::doubleMaxString(price).c_str(), DecimalFunctions::decimalStringToDisplay(size).c_str());
  }

  ...

  void TestCppClient::updateMktDepthL2(TickerId id, int position, const std::string& marketMaker, int operation,
                                       int side, double price, Decimal size, bool isSmartDepth) {
      printf( "UpdateMarketDepthL2. %ld - Position: %s, Operation: %d, Side: %d, Price: %s, Size: %s, isSmartDepth: %d\n", id, Utils::intMaxString(position).c_str(), operation, side, 
          Utils::doubleMaxString(price).c_str(), DecimalFunctions::decimalStringToDisplay(size).c_str(), isSmartDepth);
  }

• class TestWrapper(wrapper.EWrapper):

  ...

      def updateMktDepth(self, reqId: TickerId, position: int, operation: int,
                         side: int, price: float, size: Decimal):
          super().updateMktDepth(reqId, position, operation, side, price, size)
          print("UpdateMarketDepth. ReqId:", reqId, "Position:", position, "Operation:",
                operation, "Side:", side, "Price:", floatMaxString(price), "Size:", decimalMaxString(size))

  ...

      def updateMktDepthL2(self, reqId: TickerId, position: int, marketMaker: str,
                           operation: int, side: int, price: float, size: Decimal, isSmartDepth: bool):
          super().updateMktDepthL2(reqId, position, marketMaker, operation, side,
                                   price, size, isSmartDepth)
          print("UpdateMarketDepthL2. ReqId:", reqId, "Position:", position, "MarketMaker:", marketMaker, "Operation:",
                operation, "Side:", side, "Price:", floatMaxString(price), "Size:", decimalMaxString(size), "isSmartDepth:", isSmartDepth)
  

Canceling

To cancel an active market depth request simply invoke the IBApi.EClient.cancelMktDepth passing in the request's identifier.

•             client.cancelMktDepth(2001, false);

•         client.cancelMktDepth(2001, false);

•         client.cancelMktDepth(2001, False)

•     m_pClient->cancelMktDepth(2001, false);

•         self.cancelMktDepth(2001, False)
          self.cancelMktDepth(2002, True)

Limitations

Given the potentially high amount of data being sent, market depth request's are much more limited. Just as with historical data requests, the amount of active depth requests is related to the amount of market data lines, with a minimum of three and maximum of 60:

Number of lines	Max. Requests
0 - 399	3
400 - 499	4
500 - 599	5
600 - 699	6
etc...

Please note that there is a limit of only 10 quote boosters packs per account and rest of the market data lines are allocated using equity and commissions. Also note that each quote booster pack provides 100 market data lines.