Trading History

Relevant source files

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

• mt5linux/mt5.proto
• mt5linux/models.py
• mt5linux/constants.py
• tests/integration/test_history.py
• mt5linux/mt5_pb2_grpc.py
• tests/integration/test_async_client.py

The Trading History system in mt5linux provides a comprehensive interface for retrieving and analyzing historical trading activity from MetaTrader 5. It encompasses two primary data types: Orders, which represent the history of trade requests and their states, and Deals, which represent the actual executed transactions that impacted the account balance.

The system is built on a gRPC architecture, allowing Linux-based clients to query historical data from a Windows-based MetaTrader 5 terminal via a bridge. Data is returned in type-safe Pydantic models, ensuring consistency and ease of use in both synchronous and asynchronous trading applications.

Sources: README.md, mt5linux/mt5.proto:263-271, mt5linux/models.py:461-512

Architecture and Data Flow

Trading history requests originate from the MetaTrader5 (sync) or AsyncMetaTrader5 (async) clients. These requests are serialized into gRPC HistoryRequest messages and sent to the MT5Service. The service queries the MetaTrader 5 terminal and returns results as DictList objects, which are then parsed into Pydantic models on the client side.

gRPC Service Definition

The underlying gRPC service defines four primary endpoints for historical data:

RPC Method	Request Type	Response Type	Description
HistoryOrdersTotal	HistoryRequest	IntResponse	Total number of historical orders in range.
HistoryOrdersGet	HistoryRequest	DictList	List of historical orders with filters.
HistoryDealsTotal	HistoryRequest	IntResponse	Total number of historical deals in range.
HistoryDealsGet	HistoryRequest	DictList	List of historical deals with filters.

Sources: mt5linux/mt5.proto:264-271, mt5linux/mt5_pb2_grpc.py:127-148

Sequence of a History Query

The following diagram illustrates the flow of a historical data request from the client to the MT5 terminal.

The client utilizes HistoryRequest to apply filters such as date ranges, specific tickets, or position identifiers.
Sources: mt5linux/mt5.proto:179-185, tests/integration/test_history.py:18-50

Data Models

mt5linux uses Pydantic 2 models to represent historical records, providing immutability and validation.

Historical Orders (MT5Models.Order)

Represents trade requests that have been processed, including those that were canceled or expired.

Field	Type	Description
ticket	int	Unique order identifier.
time_setup	int	Timestamp when order was placed.
state	int	Current state (e.g., FILLED, CANCELED).
volume_initial	float	Requested volume.
price_open	float	Price at which the order was opened.

Sources: mt5linux/models.py:461-487

Historical Deals (MT5Models.Deal)

Represents the actual execution of a trade. A single order might result in multiple deals if filled partially or across different prices.

Field	Type	Description
ticket	int	Unique deal identifier.
order	int	The ticket of the order that generated this deal.
type	int	Deal type (BUY, SELL, BALANCE, etc.).
entry	int	Entry type (IN, OUT, INOUT).
profit	float	Financial result of the deal.
symbol	str	Financial instrument symbol.

Sources: mt5linux/models.py:489-512

Filtering and Query Logic

The system supports multiple ways to filter historical data using the HistoryRequest message.

Filtering Capabilities

1. Time-Based: Users can specify date_from and date_to using datetime objects.
2. Identifier-Based: Retrieval by a specific ticket or position ID.
3. Symbol-Based: The group parameter allows using patterns (e.g., *EUR*) to filter results by symbol.

Sources: mt5linux/mt5.proto:179-185, tests/integration/test_history.py:38-48, 128-138

Constants and Enumerations

The Trading History module relies on several constant namespaces within MT5Constants to define the nature of historical records.

Deal and Order Types

• DealType: Identifies the transaction nature, such as BUY (0), SELL (1), or BALANCE (2).
• DealEntry: Defines the direction relative to a position: IN (Entry), OUT (Exit), or INOUT (Reversal).
• OrderState: Represents the lifecycle status of an order, such as FILLED (4) or CANCELED (2).

Sources: mt5linux/constants.py:467-511, mt5linux/constants.py:539-556

Summary

The Trading History system provides a robust framework for auditing and analyzing past trading performance. By separating Orders (intents) from Deals (executions) and providing rich filtering options through a gRPC-backed Pydantic interface, mt5linux enables developers to build sophisticated reporting and back-testing tools on Linux.

Sources: mt5linux/models.py:461-512, tests/integration/test_history.py:202-235