Connection¶

Connection lifecycle and credential management.

Models¶

LoginCredential¶

LoginCredential ¶

Bases: BaseModel

Credentials required to connect to a MetaTrader 5 terminal.

The password field uses Pydantic's SecretStr type so the value is never accidentally logged or serialised in plain text.

ATTRIBUTE	DESCRIPTION
`login`	MT5 account number. TYPE: `int`
`password`	Account password (stored as a secret). TYPE: `SecretStr`
`server`	Broker server name (e.g. `"ICMarkets-Demo"`). TYPE: `str`
`path`	Optional path to the `terminal64.exe` executable. When `None`, MT5 uses the default installation path. TYPE: `str \| None`

Service¶

ConnectionService¶

ConnectionService ¶

ConnectionService()

Manages the MT5 terminal connection lifecycle.

Wraps mt5.initialize(), mt5.login(), mt5.shutdown(), and mt5.version(). Tracks initialisation state internally so that calling initialize() a second time is a no-op rather than an error.

Typical usage follows the sequence: initialize → login → (operations) → shutdown.

initialize ¶

initialize(
    credentials: LoginCredential | None = None,
) -> Result[None]

Connect to the MetaTrader 5 terminal.

If the terminal is already initialised, returns success immediately without making another MT5 call. Optionally accepts a path to the terminal executable via credentials.path.

PARAMETER	DESCRIPTION
`credentials`	Optional credentials whose `path` field is used to locate the terminal executable. All other fields are ignored here — call `login()` separately to authenticate. TYPE: `LoginCredential \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`Result[None]`	`Result[None]`: Success if the terminal connected; failure with
`Result[None]`	the MT5 error code and message otherwise.

login ¶

login(credentials: LoginCredential) -> Result[None]

Authenticate with the broker using the provided credentials.

Must be called after a successful initialize(). The password is extracted from the SecretStr field and never logged.

PARAMETER	DESCRIPTION
`credentials`	Account number, password, and server name. TYPE: `LoginCredential`

RETURNS	DESCRIPTION
`Result[None]`	`Result[None]`: Success if authentication succeeded; failure
`Result[None]`	with the MT5 error code otherwise.

shutdown ¶

shutdown() -> Result[None]

Disconnect from the MetaTrader 5 terminal.

Resets the internal initialisation flag regardless of whether the MT5 call succeeds, so subsequent calls to initialize() will attempt a fresh connection.

RETURNS	DESCRIPTION
`Result[None]`	`Result[None]`: Success in almost all cases; failure only if
`Result[None]`	MT5 explicitly returns `False` from `shutdown()`.

version ¶

version() -> Result[tuple[int, int, str]]

Retrieve the MetaTrader 5 terminal version.

RETURNS	DESCRIPTION
`Result[tuple[int, int, str]]`	`Result[tuple[int, int, str]]`: A 3-tuple of
`Result[tuple[int, int, str]]`	`(build_number, build_date, version_string)` on success, or
`Result[tuple[int, int, str]]`	a failure result if the terminal is not connected or returns an
`Result[tuple[int, int, str]]`	unexpected payload.

Usage¶

from pydantic import SecretStr
from syntiq_mt5 import LoginCredential, MetaTrader5Client

creds = LoginCredential(
    login=12345678,
    password=SecretStr("your-password"),  # Never logged or serialized
    server="Broker-Demo",
    path=None,  # Optional: path to terminal64.exe
)

with MetaTrader5Client() as mt5:
    # Initialize connects to the terminal
    init = mt5.initialize(creds)
    if not init.success:
        print(f"Initialize failed: {init.error_message}")
        raise SystemExit(1)

    # Login authenticates with the broker
    login = mt5.login(creds)
    if not login.success:
        print(f"Login failed: {login.error_message}")
        raise SystemExit(1)