[Contents](https://api.fxblue.com/mytrader/scripting/markdown/000-contents.md) › [3 Functions in the framework](https://api.fxblue.com/mytrader/scripting/markdown/072-3-functions-in-the-framework.md) › [3.14 Market depth and order book](https://api.fxblue.com/mytrader/scripting/markdown/203-3.14-market-depth-and-order-book.md)

# 3.14.1 Market 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()](https://api.fxblue.com/mytrader/scripting/markdown/347-7.4-fxb-utils-generateguid.md). |
| `callback` | An optional asynchronous callback function which receives the depth. You can process market-depth messages in [OnMessage()](https://api.fxblue.com/mytrader/scripting/markdown/216-4-messages-and-event-handlers.md), 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](https://api.fxblue.com/mytrader/scripting/markdown/344-7.1-fxb-utils-dictionary.md) (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](https://api.fxblue.com/mytrader/scripting/markdown/047-2.5-fxb-instrument-object.md).

---

← [3.14 Market depth and order book](https://api.fxblue.com/mytrader/scripting/markdown/203-3.14-market-depth-and-order-book.md) | [3.14.2 Order book](https://api.fxblue.com/mytrader/scripting/markdown/205-3.14.2-order-book.md) →