Architecture Overview

MT5Linux is a high-performance bridge and client library designed to enable MetaTrader 5 (MT5) integration on Linux systems. Since the official MetaTrader 5 Python module is Windows-only, MT5Linux utilizes a gRPC-based client-server architecture. It allows Linux-based applications—often running in Docker containers—to communicate with an MT5 terminal instance running on Windows or via Wine.

The system is designed with a focus on resilience, supporting both synchronous and asynchronous communication patterns, type-safe data models using Pydantic, and robust error handling including circuit breakers and Write-Ahead Logging (WAL) for trading operations.

Sources: README.md:3-12, mt5linux/main.py:1-15

System Component Hierarchy

The project is structured into several layers, ranging from low-level network protocols to high-level trading orchestrators.

Core Components

1. gRPC Bridge Service

The MT5Service defined in mt5.proto acts as the interface between Linux and Windows. It serializes MT5's complex data structures (like NumPy structured arrays for market data) into Protobuf messages.

2. Resilience and Fault Tolerance

MT5Linux incorporates advanced architectural patterns to ensure trading reliability over unstable network connections.

• Circuit Breaker: Prevents cascading failures by stopping requests to the bridge if a failure threshold is reached.
• Write-Ahead Log (WAL): Persists trade intents to a local SQLite database BEFORE sending them to the bridge, allowing recovery if the client crashes mid-transaction.
• Request Queue: Manages parallel execution of up to 10 simultaneous operations to match server-side worker capacity.

3. Data Modeling and Validation

The system uses Pydantic v2 to provide type safety and validation for all MT5 data structures.

# Example of Model definition ensuring type safety
class OrderRequest(BaseModel):
    action: c.Order.TradeAction
    symbol: str
    volume: float = Field(gt=0, le=1000)
    type: c.Order.OrderType
    # ... other fields with defaults from MT5Settings

Sources: mt5linux/models.py:65-80

Configuration Management

Configuration is centralized in MT5Settings, which utilizes environment variables with an MT5_ prefix for seamless Docker integration.

Sources: mt5linux/settings.py:35-130

Data Flow: Market Data Retrieval

Market data flow involves reassembling chunked JSON or byte streams into NumPy arrays on the Linux client.

Transactional Integrity

For order_send operations, MT5Linux implements a unique "Idempotency Marker" using the MT5 comment field.

1. Preparation: A unique request_id (e.g., RQ1a2b3c...) is generated and prefixed to the order comment.
2. Execution: The order is sent via gRPC.
3. Ambiguous Response: If a timeout occurs, the client does not immediately retry.
4. Verification: The client searches for the request_id in the account's trade history to determine if the order was actually executed before deciding to retry or report success.

Sources: mt5linux/utilities.py:925-950, mt5linux/utilities.py:1250-1280

Conclusion

The MT5Linux architecture effectively bridges the gap between Linux-based algorithmic trading systems and the Windows-dependent MetaTrader 5 ecosystem. By layering gRPC for communication, Pydantic for data integrity, and complex resilience patterns (WAL, Circuit Breaker, and Idempotency Tracking), it provides a production-ready framework for reliable automated trading.

Sources: README.md:210-220, mt5linux/utilities.py:30-40