Synchronous Client (MetaTrader5)
Relevant source files
The following files were used as context for generating this wiki page:
The Synchronous Client (MetaTrader5) is a high-level wrapper designed to provide a Pythonic, blocking interface to the MetaTrader 5 terminal from Linux environments. It serves as a thin layer over the AsyncMetaTrader5 implementation, delegating all business logic, gRPC communication, and resilience mechanisms to the underlying asynchronous core while exposing an API that matches the official MetaTrader 5 PyPI package exactly.
This module ensures that developers can use familiar synchronous patterns while benefiting from modern features such as gRPC transport, circuit breakers, and automatic reconnection. It is primarily used in scenarios where asyncio is not required or where compatibility with legacy synchronous trading scripts is a priority.
Sources: mt5linux/client.py:1-25, README.md:10-15
Architecture and Delegation
The MetaTrader5 class implements the MT5Protocol, which defines 32 standard methods matching the official MT5 API. Internally, it initializes an instance of AsyncMetaTrader5 and manages a dedicated asyncio event loop to execute asynchronous coroutines in a blocking manner.
Structural Components
| Component | Responsibility |
|---|---|
MetaTrader5 | Public API providing synchronous methods like initialize, order_send, and copy_rates_from. |
_async_client | An internal AsyncMetaTrader5 instance that handles the actual gRPC calls and logic. |
_loop | An asyncio.AbstractEventLoop used to bridge the synchronous calls to the async implementation. |
MT5Protocol | The protocol interface ensuring strict signature compliance with the official MT5 library. |
Sources: mt5linux/client.py:46-75, tests/integration/test_protocol_compliance.py:27-56
Synchronous Execution Flow
The client uses a private _run helper method to execute async coroutines using loop.run_until_complete(). This ensures that even though the underlying transport is asynchronous, the caller experiences a blocking execution.
The diagram shows how a synchronous call is marshaled through an internal event loop to the asynchronous gRPC client.
Sources: mt5linux/client.py:90-103, tests/integration/test_sync_client_resilience.py:34-45
Core Features and Capabilities
Connection Management
The client supports explicit connection handling and context manager usage (with statement). Entering the context automatically triggers connect(), while exiting triggers disconnect().
initialize(): Establishes the connection to the MT5 terminal via the gRPC bridge.login(): Authenticates the user with specific broker credentials.shutdown(): Properly closes the terminal connection.
Sources: mt5linux/client.py:126-150, tests/integration/test_client.py:41-65
Resilience Inheritance
Because it wraps the async client, the synchronous client inherits advanced resilience features defined in the MT5Constants.Resilience namespace:
- Circuit Breaker: Prevents cascading failures by stopping requests if a failure threshold is met.
- Auto-Reconnect: Automatically attempts to restore the gRPC channel if the connection is lost during an operation.
- Event Loop Isolation: Each sync operation manages its own loop lifecycle to prevent interference in multi-threaded environments.
Sources: mt5linux/constants.py:48-65, tests/integration/test_sync_client_resilience.py:165-185
Market Data and Trading
The client provides full access to market data through NumPy-compatible structures and trading operations validated by Pydantic models.
| Method Category | Key Functions | Return Types |
|---|---|---|
| Market Data | copy_rates_from, copy_ticks_range | numpy.ndarray (structured) |
| Trading | order_send, order_check | MT5Models.OrderResult |
| Symbols | symbol_info, symbols_get | MT5Models.SymbolInfo |
| Account | account_info, terminal_info | MT5Models.AccountInfo |
Sources: mt5linux/client.py:270-350, mt5linux/models.py:145-210, tests/integration/test_client.py:105-150
Extensions Beyond Official API
The mt5linux implementation adds several extensions not found in the official MetaTrader 5 package to support the unique requirements of a bridged Linux environment.
Introspection and Testing
Methods like get_methods() and get_models() are provided for testing protocol compliance by introspecting the real MetaTrader 5 module running on the Windows/Wine server.
Sources: mt5linux/client.py:159-215
Background/Batch Orders
The sync client also exposes async-inspired extension methods for high-throughput trading:
order_send_async(): Sends an order and returns a uniquerequest_idimmediately, using a callback for completion.order_send_batch(): Executes multiple orders in parallel via the internal async queue.
Sources: mt5linux/client.py:440-505, mt5linux/constants.py:388-398
Data Consistency and Validation
The synchronous client heavily relies on MT5Models (built on Pydantic 2) to ensure that data returned from the gRPC bridge is correctly typed and structured.
The client converts raw gRPC/JSON responses into immutable Pydantic models defined in mt5linux/models.py.
Sources: mt5linux/models.py:50-100, mt5linux/client.py:250-265
Conclusion
The Synchronous Client (MetaTrader5) provides a robust and familiar entry point for Python developers working on Linux. By delegating to an asynchronous core, it achieves a balance between API simplicity and high-performance, resilient gRPC communication. It ensures that standard trading scripts can run without modification while gaining the benefits of the mt5linux bridge architecture.