Positions¶

Open position models and retrieval services.

Models¶

Position¶

Position ¶

Bases: BaseModel

An open trading position in MetaTrader 5.

Wraps the raw TradePosition struct returned by mt5.positions_get(). In addition to the raw fields, computed properties expose pip-based profit metrics that are commonly needed for position management.

digits and point are not part of the MT5 position struct — they are fetched from mt5.symbol_info() by PositionService and attached here so that pip calculations are self-contained.

ATTRIBUTE	DESCRIPTION
`ticket`	Unique position identifier. TYPE: `int`
`time`	Position open time as a Unix timestamp (seconds). TYPE: `int`
`time_msc`	Position open time in milliseconds. TYPE: `int`
`time_update`	Last modification time as a Unix timestamp (seconds). TYPE: `int`
`time_update_msc`	Last modification time in milliseconds. TYPE: `int`
`type`	Direction of the position (BUY or SELL). TYPE: `PositionType`
`magic`	Expert Advisor identifier; 0 for manual trades. TYPE: `int`
`identifier`	Position identifier matching the opening order ticket. TYPE: `int`
`reason`	How the position was opened (terminal, EA, etc.). TYPE: `PositionReason`
`volume`	Current position size in lots. TYPE: `float`
`price_open`	Price at which the position was opened. TYPE: `float`
`sl`	Stop loss price; 0.0 if not set. TYPE: `float`
`tp`	Take profit price; 0.0 if not set. TYPE: `float`
`price_current`	Current market price for the position's symbol. TYPE: `float`
`swap`	Accumulated swap charges. TYPE: `float`
`profit`	Floating profit/loss in account currency. TYPE: `float`
`symbol`	Trading instrument name (e.g. `"EURUSD"`). TYPE: `str`
`comment`	Arbitrary comment attached to the position. TYPE: `str`
`external_id`	Position identifier in an external system. TYPE: `str`
`digits`	Number of decimal places for the symbol's price. TYPE: `int`
`point`	Smallest price increment for the symbol. TYPE: `float`

is_buy `property` ¶

is_buy: bool

Whether this is a long (buy) position.

is_sell `property` ¶

is_sell: bool

Whether this is a short (sell) position.

pip_size `property` ¶

pip_size: float

Pip size in price units for this symbol.

Delegates to calculate_pip_size which accounts for the fractional-pip convention used by 3- and 5-digit symbols.

pips_profit `property` ¶

pips_profit: float

Current floating profit expressed in pips.

Positive values indicate profit; negative values indicate loss. Direction is taken from type so the sign is always correct for both long and short positions.

RETURNS	DESCRIPTION
`float`	Profit in pips relative to the open price.

pips_to_tp `property` ¶

pips_to_tp: float

Distance from the current price to the take profit level in pips.

Returns 0.0 when no take profit is set (tp == 0). A positive value means the TP has not yet been reached; a negative value means the price has already passed the TP level.

RETURNS	DESCRIPTION
`float`	Distance to take profit in pips, or 0.0 if TP is not set.

Service¶

PositionService¶

PositionService ¶

PositionService()

Retrieves open positions from the MT5 terminal.

Maintains an internal cache of (digits, point) pairs per symbol so that symbol_info() is only called once per unique symbol across repeated positions() calls within the same service instance.

positions ¶

positions(
    symbol: str | None = None,
) -> Result[list[Position]]

Retrieve all open positions, optionally filtered by symbol.

Fetches (digits, point) from mt5.symbol_info() for each unique symbol in the result set (using the cache to avoid redundant calls) and attaches them to each Position for pip calculations.

PARAMETER	DESCRIPTION
`symbol`	If provided, only positions for this symbol are returned. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Result[list[Position]]`	`Result[list[Position]]`: The list of open positions on success
`Result[list[Position]]`	(may be empty), or a failure result if the MT5 call fails or the
`Result[list[Position]]`	payload cannot be parsed.

positions_total ¶

positions_total() -> Result[int]

Return the total number of open positions.

RETURNS	DESCRIPTION
`Result[int]`	`Result[int]`: The count of open positions on success, or a
`Result[int]`	failure result if the MT5 call fails.

Usage¶

# Get all positions
res = mt5.positions()
if res.success:
    for p in res.data:
        print(f"{p.symbol}: {p.pips_profit:+.1f} pips")

# Filter by symbol
res = mt5.positions(symbol="EURUSD")

# Count only
res = mt5.positions_total()