API 参考

客户端

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)[源代码]

基类：_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.

参数:

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.

返回:: 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)[源代码]

Register a callback for disconnect events.

返回类型:: None
参数:: callback (Callable[[], None])

async connect()[源代码]

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.

返回类型:

MT5WebClient

返回:

This client instance, ready for session initialization or login.

抛出:

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)[源代码]

Official-style alias for cmd=29 session initialization.

返回类型:

CommandResult

参数:

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

async close()[源代码]

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.

返回类型:

None

返回:

None.

抛出:

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()[源代码]

Official-style alias for closing the websocket session.

返回类型:: None

last_error()[源代码]

Return the latest client-side compatibility-layer error.

返回类型:: tuple[int, str]

async health_check()[源代码]

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.

返回类型:: HealthStatus

on_health_degraded(callback, threshold_ms=5000.0)[源代码]

Register a callback that fires when ping latency exceeds threshold_ms.

The callback receives the HealthStatus snapshot.

返回类型:

None

参数:

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

async send_raw_command(command, payload=None)[源代码]

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.

返回类型:

CommandResult

参数:

command (int)
payload (bytes | None)

async send_bootstrap_command_52()[源代码]

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.

返回类型:: CommandResult

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

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.

参数:

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.

返回类型:

CommandResult

返回:

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

抛出:

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)[源代码]

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.

参数:

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.

返回类型:

tuple[str, int]

返回:

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

抛出:

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()[源代码]

Send a heartbeat command and wait for its response.

The response body and status code are not interpreted.

返回类型:

None

返回:

None.

抛出:

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

async logout()[源代码]

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.

返回类型:

None

返回:

None.

抛出:

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.

传输

class pymt5.TransportState(*values)[源代码]

基类：Enum

Connection lifecycle states for the WebSocket transport.

DISCONNECTED = 'disconnected'

CONNECTING = 'connecting'

READY = 'ready'

CLOSING = 'closing'

ERROR = 'error'

事件类

用于推送通知和健康监控的类型化事件数据类。这些冻结的数据类为现有推送处理程序回调交付的原始 dict 记录提供了类型化替代方案。

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

基类：object

A single tick update from the server.

参数:

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)[源代码]

基类：object

An order book / depth-of-market update.

参数:

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)[源代码]

基类：object

A trade result push notification.

参数:

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)[源代码]

基类：object

An account update push notification.

参数:

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)[源代码]

基类：object

Snapshot of connection health metrics.

参数:

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

异常类

所有 pymt5 异常均继承自 PyMT5Error。每个异常还继承自一个标准库异常，以便向后兼容现有的错误处理模式。

异常层级

Exception
+-- PyMT5Error                  （所有 pymt5 错误的基类）
|   +-- MT5ConnectionError      （同时继承 ConnectionError）
|   +-- AuthenticationError
|   +-- TradeError              （同时继承 ValueError）
|   +-- ProtocolError           （同时继承 ValueError）
|   +-- SymbolNotFoundError     （同时继承 KeyError）
|   +-- ValidationError         （同时继承 ValueError）
|   +-- SessionError            （同时继承 RuntimeError）
|   +-- MT5TimeoutError         （同时继承 TimeoutError）

class pymt5.PyMT5Error[源代码]

基类：Exception

Base exception for all pymt5 errors.

class pymt5.MT5ConnectionError(message='', *, server_uri='')[源代码]

基类：PyMT5Error, ConnectionError

Raised when connection to the MT5 server fails.

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

参数:

message (str)
server_uri (str)

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

class pymt5.AuthenticationError[源代码]

基类：PyMT5Error

Raised when login/authentication fails.

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

基类：PyMT5Error, ValueError

Raised when a trade operation fails.

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

参数:

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[源代码]

基类：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[源代码]

基类：PyMT5Error, KeyError

Raised when a symbol is not found in the cache.

Inherits from KeyError for backward compatibility.

class pymt5.ValidationError[源代码]

基类：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[源代码]

基类：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[源代码]

基类：PyMT5Error, TimeoutError

Raised when a command times out.

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

数据类

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)[源代码]

基类：object

Result of a trade request.

参数:

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)[源代码]

基类：object

Account summary computed from positions and deals.

参数:

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)[源代码]

基类：object

Cached symbol info for quick lookup.

参数:

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)[源代码]

基类：object

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

参数:

email (bool)
phone (bool)

email: bool = False

phone: bool = False

class pymt5.OpenAccountResult(code, login, password, investor_password)[源代码]

基类：object

Result returned by demo/real account opening commands.

参数:

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='')[源代码]

基类：object

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

参数:

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='')[源代码]

基类：AccountOpeningRequest

Demo account opening request for cmd=30.

参数:

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())[源代码]

基类：AccountOpeningRequest

Real account opening request for cmd=39.

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

参数:

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'')[源代码]

基类：object

Document upload payload for real account opening.

data_type and document_type are frontend/broker-defined enums.

参数:

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

订阅

class pymt5.SubscriptionHandle(ids, unsubscribe_fn)[源代码]

基类：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()

参数:

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()[源代码]

Explicitly unsubscribe. Idempotent.

返回类型:: None

指标

class pymt5.MetricsCollector(*args, **kwargs)[源代码]

基类：Protocol

Protocol for collecting pymt5 operational metrics.

on_command_sent(command)[源代码]

Record that a command was sent to the server.

返回类型:: None
参数:: command (int)

on_command_received(command, code)[源代码]

Record a response received for a command.

返回类型:

None

参数:

command (int)
code (int)

on_connect()[源代码]

Record a successful transport connection.

返回类型:: None

on_disconnect(reason)[源代码]

Record a transport disconnection and its reason.

返回类型:: None
参数:: reason (str)

on_reconnect_attempt(attempt)[源代码]

Record the start of a reconnection attempt.

返回类型:: None
参数:: attempt (int)

on_reconnect_success(attempt)[源代码]

Record a successful reconnection attempt.

返回类型:: None
参数:: attempt (int)

DataFrame 集成

pymt5.to_dataframe(records)[源代码]

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)

返回类型:: Any
参数:: records (list[dict[str, Any]])

配置参考

MT5WebClient 构造函数接受以下参数：

参数	类型	默认值	说明
`uri`	`str`	`"wss://web.metatrader.app/terminal"`	WebSocket 服务器 URI。
`timeout`	`float`	`30.0`	命令和初始连接的超时时间，单位为秒。
`heartbeat_interval`	`float`	`30.0`	心跳 ping 之间的间隔，单位为秒。
`tick_history_limit`	`int`	`10000`	每个交易品种的历史 deque 中保留的最大报价数量。设为 `0` 表示无限制。
`auto_reconnect`	`bool`	`False`	在意外断开连接时启用自动重连。
`max_reconnect_attempts`	`int`	`5`	放弃前的最大重连尝试次数。
`reconnect_delay`	`float`	`3.0`	重连尝试之间指数退避的基础延迟，单位为秒。
`max_reconnect_delay`	`float`	`60.0`	重连退避的最大延迟上限，单位为秒。
`rate_limit`	`float`	`0`	令牌桶速率限制（每秒命令数）。 `0` 表示禁用速率限制。
`rate_burst`	`int`	`20`	令牌桶速率限制器的最大突发容量。
`metrics`	`MetricsCollector \| None`	`None`	用于可观察性挂钩的可选指标收集器。
`symbol_cache_ttl`	`float`	`0`	交易品种缓存的生存时间，单位为秒。 `0` 表示不自动刷新。

错误处理指南

所有 pymt5 异常均继承自 PyMT5Error，因此可以用一个处理程序捕获所有库错误：

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}")

如需更细粒度的处理，请捕获特定的异常类型。双重继承设计允许使用 pymt5 异常或标准库父类：

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")

关键异常属性：

MT5ConnectionError -- server_uri ：连接失败的 URI。
TradeError -- retcode ：MT5 返回代码； symbol ：涉及的交易品种； action ：失败的交易操作。