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.
RetryPolicy
dataclass
¶
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.
ANY_MAGIC
module-attribute
¶
Pass as magic= to act on every magic number, manual trades included.