Market Depth (DOM)
Relevant source files
The following files were used as context for generating this wiki page:
Market Depth, also known as the Depth of Market (DOM) or Order Book, provides a real-time visualization of the buy and sell orders waiting to be executed at different price levels for a specific financial instrument. Within the mt5linux project, this feature allows Linux-based clients to access professional-grade market transparency by bridging MetaTrader 5 (MT5) data through a gRPC service layer.
The system enables users to subscribe to specific symbols, retrieve the current state of the order book, and manage subscriptions to optimize data throughput. This is particularly critical for high-frequency trading or strategies requiring insight into liquidity levels beyond the top-of-book bid and ask prices.
Sources: tests/integration/test_market_depth.py:1-10, mt5linux/mt5.proto:263-267, README.md:104-106
Architecture and Data Flow
The Market Depth feature follows a request-response pattern over gRPC. The client must first explicitly subscribe to a symbol's market depth before data can be reliably retrieved, although some brokers may provide cached data automatically.
System Interaction Flow
The following sequence diagram illustrates the typical lifecycle of a Market Depth session:
The client initiates a subscription which the bridge server translates into MT5 terminal commands. Data is subsequently pulled by the client and eventually the subscription is released to save resources.
Sources: mt5linux/mt5_pb2_grpc.py:182-205, tests/integration/test_market_depth.py:91-114
Data Structures and Models
The project uses Pydantic models and Protobuf messages to ensure type safety and consistent serialization across the gRPC boundary.
BookEntry Model
The BookEntry structure represents a single price level in the order book.
| Field | Type | Description |
|---|---|---|
price | float | The price level for the order(s). |
type | int | The type of entry (Buy, Sell, etc.). Required field. |
volume | float | The volume at this price level. |
volume_dbl | float | High-precision volume representation. |
Sources: mt5linux/models.py:489-498, tests/unit/test_model_schema_validation.py:80-84
Market Depth Enums
Specific order types within the DOM are categorized using the BookType enumeration.
| Enum Constant | Value | Description |
|---|---|---|
SELL | 1 | Sell order level (Ask). |
BUY | 2 | Buy order level (Bid). |
SELL_MARKET | 3 | Market sell order level. |
BUY_MARKET | 4 | Market buy order level. |
Sources: mt5linux/constants.py:461-466
API Implementation
The Market Depth functionality is exposed via three primary RPC methods in the MT5Service definition.
Service Methods
| RPC Method | Request Type | Response Type | Description |
|---|---|---|---|
MarketBookAdd | SymbolRequest | BoolResponse | Subscribes the terminal to the DOM for a symbol. |
MarketBookGet | SymbolRequest | DictList | Retrieves the current list of book entries for a symbol. |
MarketBookRelease | SymbolRequest | BoolResponse | Unsubscribes from the DOM for a symbol. |
Sources: mt5linux/mt5.proto:263-267, mt5linux/mt5_pb2_grpc.py:182-205
Implementation Details
- Symbol Selection: Before calling
market_book_add, the symbol must be selected in the terminal usingsymbol_select(symbol, enable=True). - Data Format: The
MarketBookGetmethod returns aDictListcontaining JSON-serialized strings of the book entries, which are then parsed intoBookEntryobjects or tuples by the client library. - Criticality: Market depth operations are classified as
LOWcriticality, meaning they are read-only operations that do not have financial side effects likeorder_send.
Sources: tests/integration/test_market_depth.py:18-20, mt5linux/constants.py:276-278, mt5linux/mt5.proto:106-108
Usage Example
The following snippet demonstrates the standard lifecycle of interacting with the DOM using the sync client.
from mt5linux import MetaTrader5
with MetaTrader5(host="localhost", port=50051) as mt5:
symbol = "EURUSD"
mt5.symbol_select(symbol, enable=True)
# Subscribe to DOM
if mt5.market_book_add(symbol):
# Retrieve order book data
book = mt5.market_book_get(symbol)
if book:
for entry in book:
print(f"Price: {entry.price}, Vol: {entry.volume}, Type: {entry.type}")
# Release subscription
mt5.market_book_release(symbol)
Sources: tests/integration/test_market_depth.py:91-114, README.md:104-106
Summary
The Market Depth (DOM) module provides essential transparency for advanced trading strategies. By utilizing a gRPC bridge, mt5linux enables Linux-based applications to subscribe to and query the MT5 order book with low overhead. The use of Pydantic models and strictly defined gRPC services ensures that the high-volume data characteristic of order books is handled reliably and with clear structure.