3.14.1Market depth

The framework always responds to market depth requests, even if no depth data is available from the back-end system. What it will then send is simply changes in the current bid and ask, with no trading volume.

Where market depth is available, the back-end system may send either of the following:

Multiple quotes at each price (from different liquidity providers)

A single quote at each price

You request market depth using Framework.RequestMarketDepth(). This has one compulsory parameter and two optional parameters:

Parameter	Description
instrumentId	instrumentId of the market for which you want depth. Obviously compulsory.
requestId	An optional ID for your request, used in termination (see below). If you do not provide one, the framework will automatically allocate an ID, and report it in all responses. If you allocate your own ID, you are recommended to use FXB.utils.GenerateGuid().
callback	An optional asynchronous callback function which receives the depth. You can process market-depth messages in OnMessage(), or optionally choose to receive them in a specific asynchronous callback as well.

For example:

// Allow the framework to allocate an ID for the request, reported as the requestId in messages

Framework.RequestMarketDepth("EUR/USD", null, function (Msg) {

// Response containing market depth, also received in/via OnMessage()

// ID of the request, for use in termination, will be in Msg.requestId

});

You should terminate market depth requests when you no longer need them, using Framework.TerminateMarketDepth(). The function takes two parameters: the instrument ID, and the request ID allocated either by you or the framework.

Each market-depth update message has the following properties:

Property	Description
instrumentId	instrumentId of the market
requestId	The ID of the market-depth request, either provided by you in your call to RequestMarketDepth() or allocated automatically by the framework. Can be used to terminate requests.
initial	Boolean value indicating whether this the first message, or a subsequent update to the depth
changes	An array of changes to the market depth. For the first message, initial:true, this will list all the entries in the market depth. For subsequent messages, initial:false, it will list changes: the addition of new quotes, removal of quotes, modification of existing quotes.
depth	Object describing the full market depth, incorporating the latest changes. In other words, the framework gives you both the individual changes and also the resulting full book. You don't need to calculate the book yourself from the changes.

The changes object contains two arrays of changed quotes: asks[] and bids[]. Each item in these arrays can have the following properties:

asks[]/bids[] change	Description
id	An ID for the quote which is being added/removed/modified
state	The type of change to the quote: one of "new", "deleted", "changed". In the first message, initial:true, all the state values will be "new". After that, new quotes can be added, and existing quotes can be removed or modified. If a quote is being changed, then either or both of the price and volume may be different.
price	The price of the quote (e.g. 1.23456)
volume	The volume of the quote (e.g. 10000000)

The depth object contains the current full book following the changes; you don't need to calculate this yourself.

As noted above, the back-end system may have multiple quotes at each price (from different liquidity providers). The depth summary calculates both individual current quotes and also the aggregated volume at each price (which will be the same thing if the back-end system only issues aggregated quotes).

The depth object contains the following properties:

depth properties	Description
aggregated	Object containing asks[] and bids[] arrays containing total volume at each price. These are always sorted, by proximity to the best price - bids[] in descending order, asks[] in ascending order. Therefore, asks[0] and bids[0] are the best bid and offer. Each entry in the asks[] and bids[] arrays has a price and a volume. It also has a cumulative value: the total volume of this and all previous/better quotes in the array.
book	Object containing Dictionaries (not arrays) of the individual current bid and ask quotes. Each quote consists of an id, price, and volume. The key of each quote in its dictionary is the id.
bestAsk	Best ask price (same as aggregated.asks[0].price), or zero - see below
bestBid	Bid bed price (same as aggregated.bids[0].price) , or zero - see below
askVolume	Total volume of all ask quotes
bidVolume	Total volume of all bid quotes

A couple of final notes:

You need to be a little careful with this data. During unusual market conditions, or just very briefly during updates, it is possible for there to be no quotes on the bid side or ask side (or even both). Therefore, you cannot safely assume that aggregated.asks.length or aggregated.bids.length is greater than zero.

Internally within the broker's back-end system, it is possible for there to be different routes for market depth versus "trading" prices. It is not absolutely guaranteed that the bestBid and bestAsk in the market depth will match the current bid and ask of the FXB.Instrument.