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)[source]

Bases: _PushHandlersMixin, _AccountMixin, _MarketDataMixin, _TradingMixin, _OrderHelpersMixin

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)

property is_connected: bool

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]

Return type:: MT5WebClient

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]

Return type:: None

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]

Return type:

CommandResult

Parameters:

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

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]

Return type:

tuple[str, int]

Parameters:

login (int)
password (str)
url (str)
session (int)
otp (str)
version (int)
cid (bytes | None)
lead_cookie_id (int)
lead_affiliate_site (str)
utm_campaign (str)
utm_source (str)
auto_heartbeat (bool)

async ping()[source]

Return type:: None

async logout()[source]

Return type:: None

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]

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]

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]

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]

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]

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]

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]

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]

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]

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]

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

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]

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=<factory>)[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]

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]

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]

Protocol for collecting pymt5 operational metrics.

on_command_sent(command)[source]

Called after a command is sent to the server.

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

on_command_received(command, code)[source]

Called when a response is received for a command.

Return type:

None

Parameters:

command (int)
code (int)

on_connect()[source]

Called when the transport connects successfully.

Return type:: None

on_disconnect(reason)[source]

Called when the transport disconnects.

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

on_reconnect_attempt(attempt)[source]

Called when a reconnection attempt begins.

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

on_reconnect_success(attempt)[source]

Called when reconnection succeeds.

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.