Position Tracking
Relevant source files
The following files were used as context for generating this wiki page:
Position Tracking in mt5linux refers to the system's ability to monitor, retrieve, and validate open trading positions within a MetaTrader 5 terminal. It provides a bridge between the Linux-based client and the Windows/Wine-based MT5 terminal via gRPC, allowing developers to query the state of active market commitments, including their volume, profit, and associated tickets.
This module is critical for risk management and trade execution logic, ensuring that the current state of the account is accurately reflected in the client application. It works in conjunction with Order Management to provide a complete view of the trading lifecycle from pending orders to historical deals.
Architecture and Data Flow
The tracking of positions follows a gRPC-based request-response pattern. The client initiates a request to the MT5Service which interacts with the underlying terminal logic to fetch live position data.
The diagram shows the flow of position data from the MT5 terminal through the gRPC service to the client, where it is validated using Pydantic models.
Sources: mt5.proto:246-247, mt5linux/models.py:270-289
Key Components
| Component | Description |
|---|---|
PositionsGet | gRPC RPC call that retrieves a list of open positions based on symbol, group, or ticket. |
MT5Models.Position | Pydantic model providing type-safe validation for position data fields like profit, swap, and volume. |
PositionsRequest | Message structure containing filters for position retrieval. |
PositionsTotal | RPC call returning the integer count of currently open positions. |
Sources: mt5.proto:246-247, mt5linux/models.py:270-289, mt5linux/constants.py:320-330
Data Models
Position tracking relies on the MT5Models.Position class, which maps raw terminal data to a structured format. This model inherits from a Base class that facilitates conversion from MT5 objects, namedtuples, or dictionaries.
Position Field Specifications
| Field | Type | Description |
|---|---|---|
ticket | int | Unique identifier for the position (Required). |
symbol | str | Financial instrument symbol. |
volume | float | Current volume of the position. |
price_open | float | Entry price of the position. |
price_current | float | Current market price. |
profit | float | Floating profit/loss in account currency. |
type | int | Position type (0 for BUY, 1 for SELL). |
magic | int | Expert Advisor ID associated with the position. |
Sources: mt5linux/models.py:270-289, mt5linux/constants.py:448-451
Implementation Details
Retrieving Positions
Retrieval can be filtered by specific criteria using the PositionsRequest. If no parameters are provided, the system returns all open positions for the account.
# Example of position retrieval in tests
positions = mt5.positions_get(symbol="EURUSD")
for pos in positions:
if pos.magic == tc.TEST_ORDER_MAGIC:
print(f"Position found: {pos.ticket}")
Sources: tests/integration/test_trading.py:202-210, mt5.proto:168-172
Life Cycle State Flow
The tracking system monitors positions through various reasons for creation or modification, such as client intervention, Expert Advisor logic, or Stop Loss (SL) / Take Profit (TP) triggers.
The state diagram illustrates the lifecycle of a tracked position from execution to closure.
Sources: mt5linux/constants.py:421-432, tests/integration/test_trading.py:212-230
Resilience and Criticality
Position tracking operations are classified by their criticality level, which determines the retry strategy and circuit breaker behavior.
- HIGH Criticality:
positions_getis considered high criticality because it provides data that directly affects trading decisions. - LOW Criticality:
positions_totalis classified as low criticality as it is a read-only count of current state.
Sources: mt5linux/constants.py:320-330
Transaction Classification
The system uses ErrorClassification to handle various MT5 return codes during position modifications (like closing a position). For example, 10036 (POSITION_CLOSED) is a permanent error indicating the position no longer exists for tracking.
Sources: mt5linux/constants.py:192-210
Conclusion
Position Tracking in mt5linux provides a robust, type-safe mechanism for monitoring live market exposure. By leveraging gRPC for communication and Pydantic for data validation, it ensures that developers have accurate, real-time access to position data, which is essential for building sophisticated automated trading strategies on Linux environments.