gRPC Protocol Buffers

Relevant source files

The following files were used as context for generating this wiki page:

• mt5linux/mt5.proto
• mt5linux/mt5_pb2.py
• mt5linux/mt5_pb2_grpc.py
• mt5linux/generated_pb2.py
• mt5linux/generated_aio_grpc.py
• tests/integration/test_proto_validation.py
• pyproject.toml

The mt5linux project utilizes gRPC Protocol Buffers (protobuf) as the foundational communication layer between Linux-based clients and the MetaTrader 5 (MT5) terminal, which typically requires a Windows/Wine environment. By replacing older RPyC implementations with gRPC, the system achieves better asynchronous performance and a strictly typed boundary for cross-platform data exchange. Sources: mt5linux/mt5.proto:3-5, mt5linux/generated_pb2.py:1

The protocol defines a centralized service, MT5Service, which encapsulates terminal operations, market data retrieval, trading execution, and account provisioning. Data is exchanged using highly efficient binary serialization, while complex Python objects (like dictionaries and namedtuples) are handled through JSON-serialized strings or raw bytes for NumPy arrays to ensure compatibility across different environment versions. Sources: mt5linux/mt5.proto:186-258, pyproject.toml:23-27

Service Architecture and Lifecycle

The communication is structured around a Unary RPC model where the client sends a request message and receives a response. The MT5Service handles the bridge between the high-level Python API and the underlying gRPC transport.

Core Service Definition

The MT5Service is divided into logical operation groups to maintain the MetaTrader 5 PyPI interface parity:

Category	Key RPC Methods	Purpose
Terminal	HealthCheck, Initialize, Login, Shutdown	Manages terminal connectivity and lifecycle.
Introspection	GetMethods, GetModels	Validates protocol compliance against the real MT5 module.
Market Data	CopyRatesFrom, CopyTicksRange	Transfers large datasets as raw NumPy bytes.
Trading	OrderSend, OrderCheck, OrderCalcMargin	Executes and validates trade requests via JSON payloads.
Provisioning	GetProvisionedAccount, CreateDemoAccount	Automates container-based account management.

Sources: mt5linux/mt5.proto:189-257, mt5linux/mt5_pb2_grpc.py:46-193

Communication Flow

The following diagram illustrates the interaction between the Linux Client and the MT5 gRPC Bridge:

This flow ensures that the Linux environment remains decoupled from the Windows-specific MetaTrader 5 binaries. Sources: mt5linux/mt5_pb2_grpc.py:46-52, tests/integration/test_proto_validation.py:192-205

Data Serialization Strategies

Due to the dynamic nature of MetaTrader 5 data structures, the protobuf definition employs three distinct strategies for data transfer:

1. JSON Serialization (DictData, DictList)

For dictionaries and lists of dictionaries (like account info or positions), the protocol uses JSON strings. This allows the bridge to pass complex, varying structures without requiring constant proto definition updates.

• Message: DictData contains a json_data string.
• Message: DictList contains repeated string json_items.
  Sources: mt5linux/mt5.proto:81-89, tests/integration/test_proto_validation.py:99-105

2. NumPy Raw Bytes (NumpyArray)

To optimize the transfer of high-volume market data (rates and ticks), arrays are moved as raw bytes. This avoids the overhead of iterating over thousands of individual protobuf messages.

• Fields: bytes data, string dtype, repeated int32 shape.
  Sources: mt5linux/mt5.proto:92-97, pyproject.toml:23-27

3. Strictly Typed Introspection (MethodInfo, ModelInfo)

To ensure the bridge accurately reflects the target MT5 version, the protocol includes introspection types that describe the real MT5 module's structure.

Infrastructure and Validation

Requirements and Dependencies

The system relies on specific versions of the gRPC and Protobuf libraries to ensure runtime stability. The protobuf library must be kept in lockstep with the generated code versions to avoid VersionError at import.

Dependency	Version Range	Rationale
grpcio	>=1.60.0	Core transport and async support.
protobuf	>=6.31.1, <7	Matches gencode version in mt5_pb2.py.
numpy	>=2.1, <3	Host-side array handling for Python 3.13.

Sources: pyproject.toml:20-33, mt5linux/mt5_pb2.py:10-14

Protocol Validation Tests

The project includes comprehensive integration tests in test_proto_validation.py to ensure that the generated stubs match the expected service interface. These tests verify the existence of all 38 RPC methods defined in the .proto file and validate the structure of request/response messages. Sources: tests/integration/test_proto_validation.py:192-230

# Example of Request Validation from tests
def test_init_request_exists() -> None:
    request = mt5_pb2.InitRequest(
        path="/path/to/mt5",
        login=12345,
        password="pass",
        server="server",
        timeout=60000,
        portable=False
    )
    assert request.path == "/path/to/mt5"
    assert request.login == 12345

Sources: tests/integration/test_proto_validation.py:146-156, mt5linux/mt5.proto:113-120

Conclusion

The gRPC Protocol Buffer implementation in mt5linux provides a robust, high-performance, and type-safe bridge for MetaTrader 5 operations on Linux. By leveraging JSON for flexibility and raw bytes for performance, it maintains full compatibility with the MT5 ecosystem while enabling modern asynchronous Python workflows. Sources: mt5linux/mt5.proto:3-5, mt5linux/generated_aio_grpc.py:11-12