Trading Constants & Enums
Relevant source files
The following files were used as context for generating this wiki page:
The mt5linux project utilizes a centralized system for managing trading constants, magic numbers, and enumerations. This architecture ensures strict parity between the Linux-based gRPC client and the native MetaTrader 5 (MT5) library running within a Wine/Docker environment. Constants are organized into business domain namespaces to provide a structured API for developers, separating shared production constants from test-specific values.
Sources: mt5linux/constants.py:7-14, tests/constants.py:1-25
Constant Organization & Architecture
The project follows a strict separation of concerns between source constants and test constants. Shared constants reside in mt5linux.constants.py and are used to mirror the actual MT5 API or core logic. Test-only constants are maintained in tests.constants.py and include magic numbers for mock data, specific test timeouts, and property generation bounds.
Namespace Structure
Constants are grouped into nested classes representing specific business domains:
| Namespace | Responsibility |
|---|---|
| Network | Ports (gRPC, VNC, Health), timeouts, and message size limits. |
| Resilience | Circuit breaker states, retryable gRPC codes, and MT5 retcode classifications. |
| Order | Trade actions, order types (BUY/SELL), filling modes, and execution results. |
| Trading | Position types, deal entries, and execution reasons. |
| MarketData | Timeframe definitions (M1 to MN1), tick flags, and market depth types. |
| Symbol | Calculation modes, trade restrictions, and swap calculation modes. |
Sources: mt5linux/constants.py:17-50, mt5linux/constants.py:168-185, mt5linux/constants.py:270-300
Parity Validation Logic
To ensure the Linux bridge remains accurate, the project includes an automated validation suite that compares local Python enums against the live values retrieved from the MT5 terminal via gRPC.
The diagram shows the workflow for validating that the Linux client's constants match the actual values in the MetaTrader 5 terminal.
Sources: tests/integration/test_constants_validation.py:38-100
Trade Execution & Return Codes
A critical component of the constants module is the classification of TradeRetcode values. These codes determine the outcome of a transaction and dictate how the TransactionOrchestrator handles retries or state verification.
Classification Categories
MT5 return codes are classified into seven distinct internal categories, which are then mapped to five public-facing TransactionOutcome states.
| Category | Description | Examples (Codes) |
|---|---|---|
| SUCCESS | Operation completed successfully. | 10009 (DONE), 10008 (PLACED) |
| RETRYABLE | Transient error, safe to retry immediately. | 10004 (REQUOTE), 10024 (TOO_MANY_REQUESTS) |
| VERIFY_REQUIRED | Ambiguous state; order might have executed. | 10012 (TIMEOUT), 10031 (CONNECTION), 0 (EMPTY) |
| PERMANENT | Terminal error; do not retry. | 10019 (NO_MONEY), 10014 (INVALID_VOLUME) |
| PARTIAL | Order partially filled. | 10010 (DONE_PARTIAL) |
Sources: mt5linux/constants.py:86-165, mt5linux/utilities.py:734-775
Outcome Mapping Logic
The sequence shows how a return code is processed through the classifier to determine if state verification is necessary before a retry.
Sources: mt5linux/utilities.py:1017-1055, mt5linux/constants.py:126-135
Market Data & Timeframes
Timeframes are defined as integer constants representing minutes, with specific values for higher-level periods like Hours and Days.
Timeframe Definitions
The MarketData.TimeFrame enum provides the following mappings used in copy_rates and copy_ticks operations:
- Minutes:
M1(1),M5(5),M15(15),M30(30) - Hours:
H1(16385),H4(16388) - Days/Weeks:
D1(16408),W1(32769),MN1(49153)
Sources: mt5linux/constants.py:375-403, tests/integration/test_parametrized.py:840-855
Request Tracking & Identifiers
For transaction safety, the project uses request identifiers embedded in the order comment field to ensure idempotency.
| Parameter | Value | Description |
|---|---|---|
REQUEST_ID_PREFIX | "RQ" | Prefix for unique transaction tracking strings. |
REQUEST_ID_HEX_LENGTH | 16 | Length of the hex portion (64-bit entropy). |
MAX_COMMENT_LENGTH | 31 | The maximum characters allowed in an MT5 order comment. |
Sources: mt5linux/constants.py:530-535, mt5linux/utilities.py:910-925
# From mt5linux/utilities.py:927-938
@staticmethod
def mark_comment(comment: str | None, request_id: str) -> str:
"""Add request_id marker to comment field."""
if comment:
# Leave room for request_id + separator + some original
max_original = 31 - len(request_id) - 1
return f"{request_id}|{comment[:max_original]}"
return request_id
Summary
The Trading Constants and Enums system provides the backbone for the mt5linux bridge, ensuring that all data passed between the Linux client and the Windows-based MT5 server is interpreted correctly. By categorizing return codes and providing validated namespaces for market data, the system enables the TransactionOrchestrator to maintain high levels of execution safety and fault tolerance.
Sources: mt5linux/constants.py:650-685, mt5linux/utilities.py:1140-1160