Home
Relevant source files
The following files were used as context for generating this wiki page:
mt5linux is a Python client/server library designed to bridge the gap between Linux systems and the MetaTrader 5 (MT5) trading platform. Since MetaTrader 5 lacks a native Linux client, this project utilizes gRPC to facilitate communication between a Linux host and an MT5 instance running in a Windows environment or within a Docker container using Wine.
The system provides both synchronous and asynchronous clients, type-safe Pydantic models for trading data, and a high-performance gRPC bridge. This architecture allows developers to build trading algorithms and analysis tools on Linux while leveraging the full capabilities of the MetaTrader 5 API.
Sources: README.md:1-10, mt5linux/main.py:5-15
System Architecture
The project is structured as a distributed system where a Linux client communicates with a Windows-based server (or container) via gRPC.
High-Level Component Flow
The following diagram illustrates the flow of a trading request from a Linux application to the MetaTrader 5 terminal.
The client can be either the traditional blocking MetaTrader5 or the non-blocking AsyncMetaTrader5.
Sources: README.md:3-15, mt5linux/mt5.proto:218-225
Core Components
1. gRPC Protocol (mt5.proto)
The communication backbone is defined in mt5.proto. It replaces older protocols (like RPyC) with gRPC for improved asynchronous performance. It defines services for terminal operations, market data retrieval, and trading execution.
Key services defined in the protocol include:
- Terminal Operations:
Initialize,Login,Shutdown,Version. - Market Data:
CopyRatesFrom,CopyTicksFrom,SymbolInfo. - Trading:
OrderSend,OrderCheck,OrderCalcMargin,OrderCalcProfit.
Sources: mt5linux/mt5.proto:1-10, mt5linux/mt5.proto:228-285
2. Data Models (models.py)
mt5linux uses Pydantic 2 models to ensure type safety for MetaTrader 5 data structures. These models provide validation and convenient factory methods like from_mt5() to parse raw responses.
| Model | Description |
|---|---|
OrderRequest | Validated order parameters for sending or checking trades. |
OrderResult | Encapsulates execution results, including retcode and deal IDs. |
AccountInfo | Contains 28 fields of account-specific data (balance, equity, etc.). |
SymbolInfo | Comprehensive metadata for financial instruments (96 fields). |
Position | Represents an active, open trading position. |
Sources: mt5linux/models.py:20-45, mt5linux/models.py:155-165, mt5linux/models.py:320-330
3. Centralized Constants (constants.py)
The MT5Constants class (aliased as c) provides a central authority for all magic numbers, enums, and configuration values used in the MetaTrader 5 domain.
Infrastructure & Deployment
Docker Integration
The project supports containerized deployment through docker-compose.yaml. This setup packages the Wine environment and MetaTrader 5 terminal into a manageable service.
| Variable | Default | Description |
|---|---|---|
MT5_GRPC_PORT | 28812 (Test) | The port where the gRPC server listens. |
MT5_VNC_PORT | 23000 (Test) | VNC port for GUI access to the Wine environment. |
MT5_LOGIN | 0 | Default account login ID. |
Sources: DOCKER_COMPOSE_USAGE.md:15-30, README.md:120-135
Bridge Server
The server component can also run as a standalone Python process on Windows. It is launched using the command: python -m mt5linux --server. This starts a gRPC server that binds to the local MT5 installation.
Sources: mt5linux/main.py:45-55, README.md:105-115
Error Classification & Resilience
The system includes a sophisticated error classification mechanism to handle the various return codes (retcode) from MT5.
- SUCCESS: Operation completed (e.g., code 10009).
- RETRYABLE: Transient errors like
REQUOTEorTOO_MANY_REQUESTS. - VERIFY_REQUIRED: Critical states like
TIMEOUTorCONNECTIONwhere the order might have been sent but no response was received. - PERMANENT: Critical failures like
NO_MONEYorTRADE_DISABLED.
Sources: mt5linux/constants.py:115-150, mt5linux/constants.py:215-240
Conclusion
mt5linux provides a robust, type-safe, and high-performance framework for Linux-based algorithmic trading with MetaTrader 5. By abstracting the complexities of Wine and gRPC, it allows developers to interact with financial markets using modern Python patterns while maintaining compatibility with the official MetaTrader 5 API.