Skip to content

Connecting and trading

connect

connect(login: int | str, password: str, server: str, *, path: str | None = None, timeout_ms: int = 60000, magic: int = 0, deviation: int = 10, retry: RetryPolicy | None = None) -> Result[Trader, TradeError]

Start (or attach to) the MT5 terminal, log in, and return a ready Trader.

Trader

Trader(terminal: Terminal, clock: Clock, *, magic: int = 0, deviation: int = 10, retry: RetryPolicy | None = None)

Trading calls on one logged-in account; get one from connect.

Every trading call and query returns a Result. Orders carry the trader's magic, and close-all / cancel-all act only on it unless told otherwise. A context manager: with trader: shuts the connection down on exit. Tests build one directly from fakes of the Terminal and Clock ports.

open_position

open_position(symbol: str, side: Side | str, volume: float, *, sl: StopInput = None, tp: StopInput = None, price: float | None = None, comment: str | None = None) -> Result[TradeReceipt, TradeError]

Open a market position; sl/tp floats are prices, Stop.points distances.

Without price the current quote is used and requotes are retried with a fresh quote. An explicit price is sent once: re-sending the same price after a requote cannot succeed.

place_limit_order

place_limit_order(symbol: str, side: Side | str, volume: float, price: float, *, sl: StopInput = None, tp: StopInput = None, comment: str | None = None) -> Result[TradeReceipt, TradeError]

Place a BUY/SELL LIMIT at price; point stops are measured from that level.

A limit on the wrong side of the market is refused by the server (INVALID_PRICE) rather than converted into a market order.

close_positions

close_positions(symbol: str | None = None, *, ticket: int | None = None, magic: int | AnyMagic | None = None, comment: str | None = None) -> Result[list[TradeReceipt], BatchFailure]

Close matching positions; ticket takes precedence over symbol.

Only the trader's own magic unless another magic is given; magic=ANY_MAGIC closes every position, manual ones included. A ticket is closed whatever its magic.

cancel_pending_orders

cancel_pending_orders(symbol: str | None = None, *, magic: int | AnyMagic | None = None, kind: PendingKind | None = None) -> Result[list[TradeReceipt], BatchFailure]

Cancel matching pending orders of the trader's own magic by default.

magic=ANY_MAGIC cancels every order on the account, manual ones included.

positions

positions(symbol: str | None = None, *, ticket: int | None = None, magic: int | AnyMagic | None = None) -> Result[list[Position], TradeError]

Every position by default: a read never needs the own-magic guard.

pending_orders

pending_orders(symbol: str | None = None, *, magic: int | AnyMagic | None = None, kind: PendingKind | None = None) -> Result[list[PendingOrder], TradeError]

Every pending order by default, optionally only one kind.

shutdown

shutdown() -> None

Close the connection to the terminal.

RetryPolicy dataclass

RetryPolicy(attempts: int = 3, delay_seconds: float = 0.5)

How often a request the server provably did not execute is retried.

That is a requote, a price change, no quotes or too many requests, each answered with a fresh quote, and a missing quote before sending.

Raises ValueError for fewer than one attempt or a negative delay. Timeouts and lost connections are never retried, whatever the policy.

attempts class-attribute instance-attribute

attempts: int = 3

delay_seconds class-attribute instance-attribute

delay_seconds: float = 0.5

ANY_MAGIC module-attribute

ANY_MAGIC: Final = AnyMagic.ANY

Pass as magic= to act on every magic number, manual trades included.

AnyMagic

Bases: Enum

The type of ANY_MAGIC.

ANY class-attribute instance-attribute

ANY = 'any'