API Reference

Client

class pymt5.MT5WebClient(uri='wss://web.metatrader.app/terminal', timeout=30.0, heartbeat_interval=30.0, tick_history_limit=10000, max_tick_symbols=0, auto_reconnect=False, max_reconnect_attempts=5, reconnect_delay=3.0, max_reconnect_delay=60.0, rate_limit=0, rate_burst=20, metrics=None, symbol_cache_ttl=0, trade_protocol='legacy', rate_bar_format='auto', tick_price_mode='auto', tick_price_modes=None)[source]

Bases: _PushHandlersMixin, _AccountMixin, _MarketDataMixin, _TradingMixin, _OrderHelpersMixin

Provide an asynchronous MetaTrader 5 Web Terminal client.

The client owns its transport, authentication state, heartbeat, caches, and push subscriptions. Using it as an asynchronous context manager connects on entry and closes on exit; authentication still requires an explicit call to login().

If automatic reconnection is enabled, an unexpected disconnect after a successful login triggers exponential backoff with jitter, reauthentication, and restoration of tick and order-book subscriptions. Pending commands are not replayed. Calling close() cancels reconnection, clears stored credentials, and prevents new sessions until cleanup is quiescent.

Parameters:

uri (str)
timeout (float)
heartbeat_interval (float)
tick_history_limit (int)
max_tick_symbols (int)
auto_reconnect (bool)
max_reconnect_attempts (int)
reconnect_delay (float)
max_reconnect_delay (float)
rate_limit (float)
rate_burst (int)
metrics (MetricsCollector | None)
symbol_cache_ttl (float)
trade_protocol (str)
rate_bar_format (str)
tick_price_mode (Literal['auto', 'scaled', 'normalized'])
tick_price_modes (Mapping[str, Literal['auto', 'scaled', 'normalized']] | None)

property is_connected: bool

Whether the transport is ready and the client is authenticated.

Returns:: True only when the encrypted transport is ready and login has completed successfully; otherwise False.

property server_build: int: Server build number extracted from the bootstrap handshake.

on_disconnect(callback)[source]

Register a callback for disconnect events.

Return type:: None
Parameters:: callback (Callable[[], None])

async connect()[source]

Open the WebSocket and complete the encrypted bootstrap exchange.

Connecting does not authenticate the account. Call login() after this method succeeds. A concurrent close invalidates the attempt rather than allowing it to establish a replacement session.

Return type:

MT5WebClient

Returns:

This client instance, ready for session initialization or login.

Raises:

SessionError – If the client is already logged in, cleanup from a previous session is still running, or close invalidates the connection attempt.
MT5ConnectionError – If the bootstrap exchange fails or returns a malformed response.
TimeoutError – If opening the socket or exchanging bootstrap data exceeds the configured timeout.
asyncio.CancelledError – If the caller cancels the attempt. Partial transport resources are still cleaned up.

async initialize(*, version=0, password='', otp='', cid=None)[source]

Official-style alias for cmd=29 session initialization.

Return type:

CommandResult

Parameters:

version (int)
password (str)
otp (str)
cid (bytes | None)

async close()[source]

Log out if necessary and close the client session.

Heartbeat and reconnection work are stopped, the transport is closed, and local login state and stored credentials are cleared. Cleanup is coordinated with in-flight login and logout operations and is bounded by the configured timeout plus a short cancellation grace period. Non-cooperative cleanup may continue in a detached task after that deadline, while new sessions remain protected by generation checks.

The first cleanup error is re-raised after best-effort cleanup. Caller cancellation is preserved, and authentication state is reset even when logout or transport closure fails.

Return type:

None

Returns:

None.

Raises:

SessionError – If another close or incompatible reconnect cleanup is still preventing a new close from starting.
TimeoutError – If session cleanup exceeds its configured deadline.
asyncio.CancelledError – If caller cancellation is the first error recorded during shutdown.
Exception – If logout, receive-task cleanup, or transport closure fails; the first such error is propagated.

async shutdown()[source]

Official-style alias for closing the websocket session.

Return type:: None

last_error()[source]

Return the latest client-side compatibility-layer error.

Return type:: tuple[int, str]

async health_check()[source]

Return a snapshot of the current connection health.

If the transport is ready, a ping is sent and the round-trip latency is measured. Otherwise ping_latency_ms will be None.

Return type:: HealthStatus

on_health_degraded(callback, threshold_ms=5000.0)[source]

Register a callback that fires when ping latency exceeds threshold_ms.

The callback receives the HealthStatus snapshot.

Return type:

None

Parameters:

callback (Callable[[HealthStatus], None])
threshold_ms (float)

async send_raw_command(command, payload=None)[source]

Send a raw MT5 command.

This is the escape hatch for reserved or reverse-engineered commands that do not have a first-class helper yet.

Return type:

CommandResult

Parameters:

command (int)
payload (bytes | None)

async send_bootstrap_command_52()[source]

Send the reserved bootstrap-only cmd=52 helper.

Observed against the official Web Terminal build 5687 (built on 2026-03-15):

on a fresh bootstrap-only connection, cmd=52 returns code=0 with an empty body
after cmd=29 or cmd=28, the same command causes the server to drop the socket

The numeric ID is kept in the public name intentionally because the business meaning is still unknown.

Return type:: CommandResult

async init_session(version=0, password='', otp='', cid=None)[source]

Send the MT5 session-initialization command on an open transport.

Unlike initialize(), this method does not connect automatically. The raw result is returned without interpreting its status code.

Parameters:

version (int) – Terminal protocol version to send, or zero for the default.
password (str) – Optional session-initialization password.
otp (str) – Optional one-time password.
cid (bytes | None) – Optional 16-byte client identifier. A client identifier is generated when omitted.

Return type:

CommandResult

Returns:

The decoded command result, including its server status code and unparsed response body.

Raises:

ValidationError – If cid is not exactly 16 bytes.
SessionError – If the transport is not ready or the connection is invalidated while waiting.
MT5TimeoutError – If sending or receiving exceeds the configured command timeout.

async login(login, password, url='', session=0, otp='', version=0, cid=None, lead_cookie_id=0, lead_affiliate_site='', utm_campaign='', utm_source='', auto_heartbeat=True)[source]

Authenticate the current transport and start an MT5 session.

Call connect() before logging in. Successful authentication stores the login arguments for optional reconnection; logout and close clear them. Session-changing operations are serialized so that close cannot silently invalidate a successful login.

Parameters:

login (int) – Numeric MT5 account login.
password (str) – Account password used to construct the login payload.
url (str) – Optional URL string forwarded in the login payload.
session (int) – Session identifier to include, or zero for a new session.
otp (str) – Optional one-time password.
version (int) – Terminal protocol version to send, or zero for the default.
cid (bytes | None) – Optional 16-byte client identifier. A client identifier is generated when omitted.
lead_cookie_id (int) – Optional lead-cookie identifier for attribution.
lead_affiliate_site (str) – Optional affiliate-site attribution string.
utm_campaign (str) – Optional campaign attribution string.
utm_source (str) – Optional source attribution string.
auto_heartbeat (bool) – Whether to start periodic heartbeat pings after successful authentication.

Return type:

tuple[str, int]

Returns:

A tuple containing the authentication token as a hexadecimal string and the numeric MT5 session identifier.

Raises:

ValidationError – If cid is not exactly 16 bytes.
AuthenticationError – If the server rejects the login.
SessionError – If cleanup is pending, the client is already logged in, the transport is not ready, or close invalidates the login.
MT5TimeoutError – If sending or receiving exceeds the configured command timeout. Once transmission has begun, authentication may have completed remotely even though no result was received.

async ping()[source]

Send a heartbeat command and wait for its response.

The response body and status code are not interpreted.

Return type:

None

Returns:

None.

Raises:

SessionError – If the transport is not ready or is invalidated.
MT5TimeoutError – If sending or receiving exceeds the configured command timeout.

async logout()[source]

End the authenticated session and clear local login state.

Active reconnection is cancelled first. If that cancellation leaves no ready transport, local authentication state is cleared without sending another command. Otherwise, a successful logout response stops the heartbeat and clears stored credentials. A server rejection leaves the login state unchanged; transport failures may independently mark the client disconnected and trigger configured reconnection handling.

Return type:

None

Returns:

None.

Raises:

SessionError – If cleanup is pending, the transport is not ready, the server rejects logout, or close invalidates the operation.
MT5TimeoutError – If sending or receiving exceeds the configured command timeout. Once transmission has begun, the server may have processed the logout even though no result was received.

Transport

class pymt5.TransportState(*values)[source]

Bases: Enum

Connection lifecycle states for the WebSocket transport.

DISCONNECTED = 'disconnected'

CONNECTING = 'connecting'

READY = 'ready'

CLOSING = 'closing'

ERROR = 'error'

Event Classes

Typed event dataclasses for push notifications and health monitoring. These frozen dataclasses provide a typed alternative to the raw dict records delivered by the existing push handler callbacks.

class pymt5.TickEvent(symbol_id, symbol, bid, ask, last, volume, timestamp, raw)[source]

Bases: object

A single tick update from the server.

Parameters:

symbol_id (int)
symbol (str)
bid (float)
ask (float)
last (float)
volume (float)
timestamp (float)
raw (dict[str, Any])

symbol_id: int

symbol: str

bid: float

ask: float

last: float

volume: float

timestamp: float

raw: dict[str, Any]

class pymt5.BookEvent(symbol_id, symbol, entries, raw)[source]

Bases: object

An order book / depth-of-market update.

Parameters:

symbol_id (int)
symbol (str)
entries (list[dict[str, Any]])
raw (dict[str, Any])

symbol_id: int

symbol: str

entries: list[dict[str, Any]]

raw: dict[str, Any]

class pymt5.TradeResultEvent(retcode, order, deal, volume, price, comment, raw)[source]

Bases: object

A trade result push notification.

Parameters:

retcode (int)
order (int)
deal (int)
volume (float)
price (float)
comment (str)
raw (dict[str, Any])

retcode: int

order: int

deal: int

volume: float

price: float

comment: str

raw: dict[str, Any]

class pymt5.AccountEvent(balance, equity, margin, margin_free, raw)[source]

Bases: object

An account update push notification.

Parameters:

balance (float)
equity (float)
margin (float)
margin_free (float)
raw (dict[str, Any])

balance: float

equity: float

margin: float

margin_free: float

raw: dict[str, Any]

class pymt5.HealthStatus(state, ping_latency_ms, last_message_at, uptime_seconds, reconnect_count)[source]

Bases: object

Snapshot of connection health metrics.

Parameters:

state (TransportState)
ping_latency_ms (float | None)
last_message_at (float | None)
uptime_seconds (float)
reconnect_count (int)

state: TransportState

ping_latency_ms: float | None

last_message_at: float | None

uptime_seconds: float

reconnect_count: int

Exception Classes

All pymt5 exceptions inherit from PyMT5Error. Each exception also inherits from a standard library exception for backward compatibility with existing error-handling patterns.

Exception Hierarchy

Exception
+-- PyMT5Error                  (base for all pymt5 errors)
|   +-- MT5ConnectionError      (also inherits ConnectionError)
|   +-- AuthenticationError
|   +-- TradeError              (also inherits ValueError)
|   +-- ProtocolError           (also inherits ValueError)
|   +-- SymbolNotFoundError     (also inherits KeyError)
|   +-- ValidationError         (also inherits ValueError)
|   +-- SessionError            (also inherits RuntimeError)
|   +-- MT5TimeoutError         (also inherits TimeoutError)

class pymt5.PyMT5Error[source]

Bases: Exception

Base exception for all pymt5 errors.

class pymt5.MT5ConnectionError(message='', *, server_uri='')[source]

Bases: PyMT5Error, ConnectionError

Raised when connection to the MT5 server fails.

Inherits from ConnectionError for compatibility with stdlib connection error handling patterns.

Parameters:

message (str)
server_uri (str)

server_uri: The URI of the server that was being connected to.

class pymt5.AuthenticationError[source]

Bases: PyMT5Error

Raised when login/authentication fails.

class pymt5.TradeError(message='', *, retcode=0, symbol='', action=0)[source]

Bases: PyMT5Error, ValueError

Raised when a trade operation fails.

Inherits from ValueError for backward compatibility with existing code that catches ValueError from trade validation.

Parameters:

message (str)
retcode (int)
symbol (str)
action (int)

retcode: MT5 return code.

symbol: Symbol involved in the trade.

action: Trade action that failed.

class pymt5.ProtocolError[source]

Bases: PyMT5Error, ValueError

Raised when the binary protocol parsing fails.

Inherits from ValueError for backward compatibility with existing code that catches ValueError from protocol parsing.

class pymt5.SymbolNotFoundError[source]

Bases: PyMT5Error, KeyError

Raised when a symbol is not found in the cache.

Inherits from KeyError for backward compatibility.

class pymt5.ValidationError[source]

Bases: PyMT5Error, ValueError

Raised when input validation fails.

Inherits from ValueError for backward compatibility with existing code that catches ValueError from input validation.

class pymt5.SessionError[source]

Bases: PyMT5Error, RuntimeError

Raised when an operation requires a different session state.

Inherits from RuntimeError for backward compatibility with existing code that catches RuntimeError from session state checks.

class pymt5.MT5TimeoutError[source]

Bases: PyMT5Error, TimeoutError

Raised when a command times out.

Inherits from TimeoutError for compatibility with stdlib timeout handling patterns (e.g., asyncio.wait_for).

Data Classes

class pymt5.TradeResult(retcode, description, success, deal=0, order=0, volume=0, price=0.0, bid=0.0, ask=0.0, comment='', request_id=0)[source]

Bases: object

Result of a trade request.

Parameters:

retcode (int)
description (str)
success (bool)
deal (int)
order (int)
volume (int)
price (float)
bid (float)
ask (float)
comment (str)
request_id (int)

retcode: int

description: str

success: bool

deal: int = 0

order: int = 0

volume: int = 0

price: float = 0.0

bid: float = 0.0

ask: float = 0.0

comment: str = ''

request_id: int = 0

class pymt5.AccountInfo(balance=0.0, equity=0.0, margin=0.0, margin_free=0.0, margin_level=0.0, profit=0.0, credit=0.0, leverage=0, currency='', server='', positions_count=0, orders_count=0)[source]

Bases: object

Account summary computed from positions and deals.

Parameters:

balance (float)
equity (float)
margin (float)
margin_free (float)
margin_level (float)
profit (float)
credit (float)
leverage (int)
currency (str)
server (str)
positions_count (int)
orders_count (int)

balance: float = 0.0

equity: float = 0.0

margin: float = 0.0

margin_free: float = 0.0

margin_level: float = 0.0

profit: float = 0.0

credit: float = 0.0

leverage: int = 0

currency: str = ''

server: str = ''

positions_count: int = 0

orders_count: int = 0

class pymt5.SymbolInfo(name, symbol_id, digits, description='', path='', trade_calc_mode=0, basis='', sector=0)[source]

Bases: object

Cached symbol info for quick lookup.

Parameters:

name (str)
symbol_id (int)
digits (int)
description (str)
path (str)
trade_calc_mode (int)
basis (str)
sector (int)

name: str

symbol_id: int

digits: int

description: str = ''

path: str = ''

trade_calc_mode: int = 0

basis: str = ''

sector: int = 0

class pymt5.VerificationStatus(email=False, phone=False)[source]

Bases: object

Two-channel verification state used by account-opening flows.

Parameters:

email (bool)
phone (bool)

email: bool = False

phone: bool = False

class pymt5.OpenAccountResult(code, login, password, investor_password)[source]

Bases: object

Result returned by demo/real account opening commands.

Parameters:

code (int)
login (int)
password (str)
investor_password (str)

code: int

login: int

password: str

investor_password: str

property success: bool: Whether the account-opening response has a zero success code.

class pymt5.AccountOpeningRequest(first_name, second_name, email='', phone='', group='', deposit=100000.0, leverage=100, agreements=0, country='', city='', state='', zipcode='', address='', domain='', phone_password='', email_confirm_code=0, phone_confirm_code=0, language='', utm_campaign='', utm_source='')[source]

Bases: object

Shared fields used by the Web Terminal’s account opening payloads.

Parameters:

first_name (str)
second_name (str)
email (str)
phone (str)
group (str)
deposit (float)
leverage (int)
agreements (int)
country (str)
city (str)
state (str)
zipcode (str)
address (str)
domain (str)
phone_password (str)
email_confirm_code (int)
phone_confirm_code (int)
language (str)
utm_campaign (str)
utm_source (str)

first_name: str

second_name: str

email: str = ''

phone: str = ''

group: str = ''

deposit: float = 100000.0

leverage: int = 100

agreements: int = 0

country: str = ''

city: str = ''

state: str = ''

zipcode: str = ''

address: str = ''

domain: str = ''

phone_password: str = ''

email_confirm_code: int = 0

phone_confirm_code: int = 0

language: str = ''

utm_campaign: str = ''

utm_source: str = ''

class pymt5.DemoAccountRequest(first_name, second_name, email='', phone='', group='', deposit=100000.0, leverage=100, agreements=0, country='', city='', state='', zipcode='', address='', domain='', phone_password='', email_confirm_code=0, phone_confirm_code=0, language='', utm_campaign='', utm_source='')[source]

Bases: AccountOpeningRequest

Demo account opening request for cmd=30.

Parameters:

first_name (str)
second_name (str)
email (str)
phone (str)
group (str)
deposit (float)
leverage (int)
agreements (int)
country (str)
city (str)
state (str)
zipcode (str)
address (str)
domain (str)
phone_password (str)
email_confirm_code (int)
phone_confirm_code (int)
language (str)
utm_campaign (str)
utm_source (str)

class pymt5.RealAccountRequest(first_name, second_name, email='', phone='', group='', deposit=100000.0, leverage=100, agreements=0, country='', city='', state='', zipcode='', address='', domain='', phone_password='', email_confirm_code=0, phone_confirm_code=0, language='', utm_campaign='', utm_source='', middle_name='', birth_date_ms=0, gender=0, citizenship='', tax_id='', employment=0, industry=0, education=0, wealth=0, annual_income=0, net_worth=0, annual_deposit=0, experience_fx=0, experience_cfd=0, experience_futures=0, experience_stocks=0, documents=list())[source]

Bases: AccountOpeningRequest

Real account opening request for cmd=39.

birth_date_ms uses Unix milliseconds, matching the frontend’s propType=9 date encoding.

Parameters:

first_name (str)
second_name (str)
email (str)
phone (str)
group (str)
deposit (float)
leverage (int)
agreements (int)
country (str)
city (str)
state (str)
zipcode (str)
address (str)
domain (str)
phone_password (str)
email_confirm_code (int)
phone_confirm_code (int)
language (str)
utm_campaign (str)
utm_source (str)
middle_name (str)
birth_date_ms (int)
gender (int)
citizenship (str)
tax_id (str)
employment (int)
industry (int)
education (int)
wealth (int)
annual_income (int)
net_worth (int)
annual_deposit (int)
experience_fx (int)
experience_cfd (int)
experience_futures (int)
experience_stocks (int)
documents (list[AccountDocument])

middle_name: str = ''

birth_date_ms: int = 0

gender: int = 0

citizenship: str = ''

tax_id: str = ''

employment: int = 0

industry: int = 0

education: int = 0

wealth: int = 0

annual_income: int = 0

net_worth: int = 0

annual_deposit: int = 0

experience_fx: int = 0

experience_cfd: int = 0

experience_futures: int = 0

experience_stocks: int = 0

documents: list[AccountDocument]

class pymt5.AccountDocument(data_type, document_type, front_name, front_buffer, back_name='', back_buffer=b'')[source]

Bases: object

Document upload payload for real account opening.

data_type and document_type are frontend/broker-defined enums.

Parameters:

data_type (int)
document_type (int)
front_name (str)
front_buffer (bytes)
back_name (str)
back_buffer (bytes)

data_type: int

document_type: int

front_name: str

front_buffer: bytes

back_name: str = ''

back_buffer: bytes = b''

Subscriptions

class pymt5.SubscriptionHandle(ids, unsubscribe_fn)[source]

Bases: object

Manages the lifecycle of a tick or book subscription.

Usage:

async with client.subscribe_ticks_managed([symbol_id]) as handle:
    # subscribed here
    ...
# automatically unsubscribed here

Or without a context manager:

handle = await client.subscribe_ticks_managed([symbol_id])
# ... later ...
await handle.unsubscribe()

Parameters:

ids (list[int])
unsubscribe_fn (Callable[[list[int]], Coroutine[Any, Any, None]])

property ids: list[int]: Symbol IDs covered by this subscription.

property active: bool: Whether the subscription is still active.

async unsubscribe()[source]

Explicitly unsubscribe. Idempotent.

Return type:: None

Metrics

class pymt5.MetricsCollector(*args, **kwargs)[source]

Bases: Protocol

Protocol for collecting pymt5 operational metrics.

on_command_sent(command)[source]

Record that a command was sent to the server.

Return type:: None
Parameters:: command (int)

on_command_received(command, code)[source]

Record a response received for a command.

Return type:

None

Parameters:

command (int)
code (int)

on_connect()[source]

Record a successful transport connection.

Return type:: None

on_disconnect(reason)[source]

Record a transport disconnection and its reason.

Return type:: None
Parameters:: reason (str)

on_reconnect_attempt(attempt)[source]

Record the start of a reconnection attempt.

Return type:: None
Parameters:: attempt (int)

on_reconnect_success(attempt)[source]

Record a successful reconnection attempt.

Return type:: None
Parameters:: attempt (int)

DataFrame Integration

pymt5.to_dataframe(records)[source]

Convert a list of record dicts to a pandas DataFrame.

Raises ImportError if pandas is not installed.

Example:

rates = await client.get_rates("EURUSD", 60, from_ts, to_ts)
df = to_dataframe(rates)

Return type:: Any
Parameters:: records (list[dict[str, Any]])

Configuration Reference

The MT5WebClient constructor accepts the following parameters:

Parameter	Type	Default	Description
`uri`	`str`	`"wss://web.metatrader.app/terminal"`	WebSocket server URI.
`timeout`	`float`	`30.0`	Timeout in seconds for commands and the initial connection.
`heartbeat_interval`	`float`	`30.0`	Interval in seconds between heartbeat pings.
`tick_history_limit`	`int`	`10000`	Maximum number of ticks retained in the per-symbol history deque. Set to `0` for unlimited.
`auto_reconnect`	`bool`	`False`	Enable automatic reconnection on unexpected disconnect.
`max_reconnect_attempts`	`int`	`5`	Maximum number of reconnection attempts before giving up.
`reconnect_delay`	`float`	`3.0`	Base delay in seconds for exponential backoff between reconnect attempts.
`max_reconnect_delay`	`float`	`60.0`	Maximum delay cap in seconds for the reconnect backoff.
`rate_limit`	`float`	`0`	Token bucket rate limit (commands per second). `0` disables rate limiting.
`rate_burst`	`int`	`20`	Maximum burst size for the token bucket rate limiter.
`metrics`	`MetricsCollector \| None`	`None`	Optional metrics collector for observability hooks.
`symbol_cache_ttl`	`float`	`0`	Time-to-live in seconds for the symbol cache. `0` means no automatic refresh.

Error Handling Guide

All pymt5 exceptions inherit from PyMT5Error, so you can catch all library errors with a single handler:

from pymt5 import MT5WebClient, PyMT5Error

async with MT5WebClient() as client:
    try:
        await client.login(12345, "password")
    except PyMT5Error as exc:
        print(f"pymt5 error: {exc}")

For more granular handling, catch specific exception types. The dual-inheritance design allows you to use either the pymt5 exception or the standard library parent:

from pymt5 import (
    MT5WebClient,
    MT5ConnectionError,
    AuthenticationError,
    TradeError,
    MT5TimeoutError,
    SessionError,
)

async with MT5WebClient(auto_reconnect=True) as client:
    try:
        await client.login(12345, "password")
    except MT5ConnectionError as exc:
        # Also catchable as ConnectionError
        print(f"Connection failed to {exc.server_uri}: {exc}")
    except AuthenticationError:
        print("Invalid credentials")

    try:
        result = await client.buy_market("EURUSD", 0.1)
    except TradeError as exc:
        # Also catchable as ValueError
        print(f"Trade failed: retcode={exc.retcode}, symbol={exc.symbol}")
    except MT5TimeoutError:
        # Also catchable as TimeoutError
        print("Trade request timed out")
    except SessionError:
        # Also catchable as RuntimeError
        print("Not connected or session invalid")

Key exception attributes:

MT5ConnectionError – server_uri: the URI that failed.
TradeError – retcode: MT5 return code; symbol: involved symbol; action: trade action that failed.