pmt4api 1.0.0__py3-none-any.whl

pmt4api/docs/API.md

@@ -0,0 +1,702 @@
+# pmt4api — API reference
+
+Generated from the code (`tools/gen_docs.py`); do not edit by hand. Times are naive `datetime` values in the broker's server time. Every call that needs a connection raises `NotConnectedError` when there is none, and every error is a subclass of `pmt4api.WmtError`.
+
+## Constructing a client
+
+```python
+Client(login, password, host, port=443, *, api_key=None, token_url=None, dll_path=None, connect_timeout=None, token_timeout=None, trade_timeout=None, quote_timeout=None, history_timeout=None, bars_timeout=None, no_message_timeout=None, auto_reconnect=False, reconnect_backoff=None, reconnect_max_attempts=None, servers=None, comment_encoding='latin-1', placed_type=None)
+```
+
+A connection to one MetaTrader 4 account through the licensed core.
+
+>>> with Client(login, password, host, port, api_key="wk_...") as c:
+...     print(c.quote("EURUSDm"))
+
+Credentials and library: `api_key` falls back to the `WMT4API_KEY` environment variable (then `WMTAPI_KEY`)
+and `token_url` to `WMT4API_TOKEN_URL` (the core reads these itself); `dll_path` falls back to
+`WMT4API_DLL`, then to the core bundled in the wheel.
+
+Timeouts are in seconds: `connect_timeout` (one connect attempt on one server), `token_timeout` (each licence
+request), `trade_timeout` (a trade confirmation; at least 1 s), `quote_timeout` (waiting for a quote),
+`history_timeout` / `bars_timeout` (downloads), `no_message_timeout` (silence after which the session is
+declared dead and closed: default 30 s, at least 10 s, `0` switches it off; the server answers a ping every few
+seconds, so a longer silence means the link stopped carrying traffic). Every other timeout must be positive; the
+quote, history and bars timeouts are the defaults of `quote`, `history` and `bars`. The
+handshake with the broker has its own fixed 30 s limit, whatever `connect_timeout` says (that one bounds the
+TCP dial of each server).
+
+Reconnecting: `auto_reconnect=True` turns on the core's watchdog (exponential backoff, failover across the
+primary server, `servers` and the broker's published list, re-subscription); tune it with `reconnect_backoff`
+(seconds) and `reconnect_max_attempts` (0 = until reconnected or `disconnect()`). Do not poll `connected`
+and call `connect()` in a loop. `servers` are extra `(host, port)` access servers to fall back to.
+
+`comment_encoding` is the codepage order comments are written in (default `latin-1`); `placed_type`
+records how orders are placed (`"manual"`, `"expert"`, `"dealer"`; a per-call `placed_type` overrides it).
+
+Callbacks run on a dispatcher thread of this client, not on the thread that created it.
+
+## Connection and session
+
+#### `async aconnect()`
+
+Awaitable `connect`; the blocking connect runs on a worker thread.
+
+#### `add_server(host, port=443)`
+
+Add a backup access server, tried (in order) when the primary one cannot be dialled. Credential
+rejections do not fail over. Takes effect at the next connect.
+
+#### `async adisconnect()`
+
+Awaitable `disconnect`.
+
+#### `can_trade` *(property)*
+
+Connected with a trading (not investor) password. The broker may still refuse a particular symbol or
+time; this only says the session is allowed to try. See `is_investor`.
+
+#### `company` *(property)*
+
+The broker's company name, as the server reports it (empty before the first connect).
+
+#### `connect()`
+
+Connect, authorise through the licence service and load the account. Returns `self`. Calling it on a
+client that is already connected does nothing (it never opens a second session).
+
+Raises `LicenseError` / `TokenServiceError` when the licence is refused or unreachable,
+`LoginRejectedError` when the broker rejects the account or password, and `ConnectError` when
+no access server could be reached within `connect_timeout`.
+
+#### `connected` *(property)*
+
+Live: false when the socket died (the core notices a closed or reset connection at once and a silent one
+within `no_message_timeout`).
+
+#### `core_version` *(property)*
+
+The version of the licensed core library in use.
+
+#### `disconnect()`
+
+Close the session and stop the core's reconnect watchdog for good — also when the link is down and the
+watchdog is mid-way through reconnecting. Harmless when never connected.
+
+#### `host` *(property)*
+
+The access server this client was created for (it may fail over to another of `server_list`).
+
+#### `is_investor` *(property)*
+
+The login is the read-only investor password, as the account record reports it (the field the C# client
+reads): every trading call then raises `InvestorModeError` before anything is sent. (Verified on
+trading logins only: no investor password was available to exercise the true case.)
+
+#### `login` *(property)*
+
+The account login number.
+
+#### `port` *(property)*
+
+The access-server port.
+
+#### `raw` *(property)*
+
+The underlying core object, for anything this layer does not wrap. Calls made on it raise the core's own
+exceptions, not pmt4api's.
+
+#### `reconnect()`
+
+Re-establish a dropped session over the primary server, `servers` and the list the broker published, and
+restore the quote subscriptions. `True` when connected afterwards (also when it already was), `False` when
+every server failed — try again later. A refusal retrying cannot cure (an expired licence, a rejected login)
+also returns `False`: call `connect` to see the reason.
+
+#### `server_list` *(property)*
+
+The access servers the broker published at the last connect, as `(host, port)`: the pool a reconnect
+fails over across (empty before the first connect).
+
+#### `server_time` *(property)*
+
+The server's clock (server time, naive): the local UTC clock moved by the server's offset. `None` before
+the first connect.
+
+#### `server_utc_offset` *(property)*
+
+The server's offset from UTC, in whole hours as the broker configures it; `None` before the first
+connect.
+
+#### `servers` *(property)*
+
+The extra access servers given with `servers=` / `add_server`, tried after the primary one.
+
+#### `trade_build` *(property)*
+
+The server's build number for this session.
+
+## Symbols, quotes and bars
+
+#### `async abars(*args, **kwargs)`
+
+Awaitable `bars` (runs on a worker thread; never blocks the event loop).
+
+#### `async aquote(symbol, timeout=None)`
+
+Awaitable `quote` (runs on a worker thread; never blocks the event loop).
+
+#### `bars(symbol, timeframe='H1', *, count=None, start=None, end=None, timeout=None)`
+
+OHLC bars, oldest first, in the broker's server time.
+
+Give `count` for the latest N bars, or `start` for everything from that time; with neither, the latest
+500. `end` (default: now) is the moment the series is read up to: only bars that had completed by then are
+returned (a bar that opens exactly at `end` is still forming and is not in it), so there is no look-ahead.
+`timeframe` is one of `M1 M5 M15 M30 H1 H4 D1 W1 MN1` (or its length in minutes): the server serves each
+itself. The server limits how far back it goes (about a few days of M1), so a long request may return fewer
+bars than asked for; that is the end of the broker's history. `timeout` (seconds, default: the client's
+`bars_timeout`) bounds the whole call.
+
+#### `contract_size(symbol)`
+
+The contract size of a symbol (units of the instrument per 1.0 lot).
+
+#### `find_symbol(prefix)`
+
+The symbol `prefix` names: the exact name if the broker has it, else the only symbol that starts with
+it. `None` when there is none; an `InvalidRequestError` listing the candidates when several do
+(use `find_symbols` and choose).
+
+#### `find_symbols(prefix)`
+
+Every symbol whose name starts with `prefix` (case-insensitive; brokers add suffixes such as `m` or
+`.s`), exact match first, then shortest name.
+
+#### `has_symbol(name)`
+
+Whether the broker offers `name` (case-insensitive).
+
+#### `is_subscribed(symbol)`
+
+Whether `symbol` was subscribed (by `subscribe`, a quote request that had to wait, or the core
+itself for the symbols of open positions). Before the first subscription the server streams a default set
+of symbols, so `quote` also answers for symbols this reports as not subscribed.
+
+#### `quote(symbol, timeout=None)`
+
+The current quote of one symbol, waiting up to `timeout` seconds (default: the client's `quote_timeout`)
+for the first tick; `NoQuoteError` if none arrives. The price is current: a symbol that is not
+subscribed (while others are) is subscribed first and the call waits for its next tick, so it is never a price
+cached before the feed was narrowed. `time` is the tick's server time.
+
+#### `subscribe(*symbols)`
+
+Start the live quote feed for the given symbols (names, or lists of names). A name the broker does not
+offer raises `InvalidRequestError` before anything is subscribed.
+
+#### `symbol(name)`
+
+One symbol's specification. Names carry the broker's suffix (`EURUSDm`, `XAUUSD.s`): find yours with
+`find_symbols`. The lookup ignores case.
+
+#### `symbol_groups()`
+
+The broker's configured symbol groups (name and description). The core does not say which group a symbol
+belongs to; `SymbolInfo.security_index` is the key of its volume rules.
+
+#### `symbols()`
+
+Every symbol the broker offers on this account, by name, with its specification.
+
+#### `tick_value(symbol, side='ask', timeout=None)`
+
+The value, in account currency, of one full price unit per 1.0 lot (as the terminal computes it,
+converting through the account currency's cross rates).
+
+This is an *input* to position sizing, not a recipe: see `lots_for_risk`. `side` is `"ask"` (what a
+long position is priced against) or `"bid"` (a short). Waits up to `timeout` seconds (default:
+`quote_timeout`) for a live quote. Raises `InvalidRequestError` when the value cannot be computed (a
+symbol whose profit currency has no conversion rate), never a NaN.
+
+#### `unsubscribe(*symbols)`
+
+Stop the live quote feed for the given symbols (names, or lists of names). A symbol with an open position
+stays on the feed (its profit and the account's equity are priced from it); with nothing left subscribed the
+server goes back to streaming its default set.
+
+## Account, orders and history
+
+#### `account(refresh=True)`
+
+Account details. With `refresh` (the default) every open position's symbol is quoted once first, so
+`equity`, `profit`, `margin`, `free_margin` and `margin_level` are priced from current ticks. They are
+derived on the client (the server does not push them), as the terminal does; see `equity` for the cheap
+read of one figure.
+
+#### `async ahistory(start=None, end=None, timeout=None)`
+
+Awaitable `history`. Cancelling the awaiting task abandons the download (the broker connection it
+opened is closed), so `asyncio.wait_for(c.ahistory(...), 10)` does not leave a request running.
+
+#### `balance` *(property)*
+
+The account balance (closed-trade funds, floating P/L excluded); a cheap read.
+
+#### `credit` *(property)*
+
+The credit the broker granted; a cheap read.
+
+#### `equity` *(property)*
+
+Balance + floating P/L + credit, priced from the quotes already cached (it does not subscribe or wait: a
+position whose symbol has not ticked yet counts 0 floating). Use `live_equity` to wait for fresh
+quotes.
+
+#### `equity_history(start, timeframe='D1', exclude_same_bars=True)`
+
+The balance and equity curve since `start` (`timeframe` is `H1`, `H4` or `D1`).
+
+`balance` is exact; the historical `equity` is a reconstruction priced from the symbols' bars. With
+`exclude_same_bars` (the default, as in the C# library) consecutive points with an unchanged balance and
+equity are dropped. Downloads the history and per-symbol bars, so it blocks and costs a licence request.
+
+#### `free_margin` *(property)*
+
+Equity − margin.
+
+#### `history(start=None, end=None, timeout=None, cancel=None)`
+
+Closed orders and balance / credit entries between `start` and `end` (default: the last 30 days up to
+now), sorted by close time. Blocks until the server has sent everything, up to `timeout` seconds (default:
+the client's `history_timeout`); set the `cancel` event to abandon the wait early
+(`RequestCancelled`).
+
+Naive datetimes are used exactly as given, in the broker's server time; timezone-aware ones are converted to
+it. The default window is computed on the server's clock.
+
+Each call opens its own short-lived broker connection and costs one licence request, which the licence
+service rate-limits per minute: fetch once and reuse the result rather than polling.
+
+#### `leverage` *(property)*
+
+The account leverage (the N in 1:N).
+
+#### `live_equity()`
+
+Equity priced from FRESH quotes: it subscribes each open position's symbol and waits (up to the client's
+`quote_timeout` per symbol) for a tick. Blocks; the cached read is `equity`.
+
+#### `margin` *(property)*
+
+The margin the open positions hold, derived on the client like the terminal (Forex by leverage, CFD by
+the symbol's margin divider; a Futures position counts 0 until its formula is verified). May wait for a
+conversion quote.
+
+#### `margin_level` *(property)*
+
+Equity / margin × 100, as the terminal shows it; 0 when no margin is used.
+
+#### `order(ticket)`
+
+One open order or position by ticket, or `None` when it is not open.
+
+#### `orders()`
+
+Everything currently working: open positions and pending orders. Each position's `profit` is re-priced
+from the live quote on every read.
+
+#### `pending_orders()`
+
+Pending orders only (limits and stops).
+
+#### `positions()`
+
+Open market positions only (`Buy` / `Sell`).
+
+#### `profit` *(property)*
+
+The floating P/L of the open positions (equity − balance − credit), from cached quotes.
+
+#### `summary(start=None, end=None)`
+
+Realized trading result, deposits and withdrawals, from the closed-order ledger (all time by default).
+
+Downloads the history, so it blocks and costs one licence request; call it off your UI thread (or use
+`asyncio.to_thread`).
+
+#### `update_margin()`
+
+Warm the quotes the margin figure is priced from (every open position's symbol).
+
+#### `update_profits(symbol=None)`
+
+Warm the quotes the equity figures are priced from: every open position's symbol, or just `symbol`.
+Blocks up to `quote_timeout` per symbol.
+
+## Sizing and risk
+
+#### `lots_for_risk(symbol, entry_price, stop_price, risk_amount, *, lot_step=None, min_lot=None, max_ratio=None, max_equity_share=None, max_lot=None)`
+
+The volume that loses `risk_amount` (account currency) if `stop_price` is hit, with the evidence.
+
+The value of a price unit comes from `tick_value` and the broker's step / minimum / maximum volume from
+the account's own group (pass one to override it); a size that cannot be justified is refused, not guessed.
+The volume is rounded **down** to the step. Check `ok`: when false, `lots` is 0 and `reason` says which
+check failed. Amounts are in the currency the account reports (no cent-account scaling is applied: check the
+first result against your terminal).
+
+#### `order_profit(symbol, open_price, close_price, lots, buy=True)`
+
+The P/L, in account currency, of `lots` moving from `open_price` to `close_price`. For reporting a
+completed or hypothetical move; use `lots_for_risk` to size. Raises `InvalidRequestError` when the
+value cannot be computed (no conversion rate yet).
+
+#### `required_margin(symbol, lots, side='buy', price=0.0)`
+
+The margin needed to open `lots` of `symbol`, computed as the terminal does (`price` 0 = the live
+quote; Forex uses the account leverage, CFD the symbol's margin divider). Raises `InvalidRequestError`
+when it cannot be computed (a Futures symbol, whose formula is not verified, or no conversion rate yet).
+
+## Order entry
+
+#### `async abuy(*args, **kwargs)`
+
+Awaitable `buy`.
+
+#### `async acancel(*args, **kwargs)`
+
+Awaitable `cancel`.
+
+#### `async aclose(*args, **kwargs)`
+
+Awaitable `close`.
+
+#### `async aclose_all_by(*args, **kwargs)`
+
+Awaitable `close_all_by`.
+
+#### `async aclose_by(*args, **kwargs)`
+
+Awaitable `close_by`.
+
+#### `async amodify(*args, **kwargs)`
+
+Awaitable `modify`.
+
+#### `async aplace_order(*args, **kwargs)`
+
+Awaitable `place_order`.
+
+#### `async asell(*args, **kwargs)`
+
+Awaitable `sell`.
+
+#### `buy(symbol, lots, *, price=None, slippage=0, sl=0.0, tp=0.0, comment=None, magic=0, placed_type=None)`
+
+Buy at market. `price` defaults to the current ask (an instant-execution symbol fills at it within
+`slippage` points; a market-execution symbol ignores it). `sl` / `tp` are prices (0 = none); `lots` is
+a multiple of 0.01. `comment` (at most 31 characters) is how to tag an order: the core does not transmit a
+magic number, so `magic` other than 0 raises `InvalidRequestError` rather than being ignored.
+`placed_type` is `manual`, `expert`, `dealer` ... (default: the client's).
+
+#### `buy_async(symbol, lots, *, price=None, slippage=0, sl=0.0, tp=0.0, comment=None, magic=0, placed_type=None)`
+
+Send a market buy and return its request id as soon as the request is on the wire; the outcome arrives
+through `on_order_progress` (and `on_order_update`).
+
+#### `cancel(ticket)`
+
+Delete a pending order.
+
+#### `cancel_async(ticket)`
+
+Delete a pending order and return its request id at once; see `cancel`.
+
+#### `close(ticket, lots=None, *, price=None, slippage=0)`
+
+Close a position at market, completely or (with `lots`) in part; `price` defaults to the current
+bid (buy) / ask (sell). Returns the closing record. After a partial close the remainder may carry a new
+ticket: read `positions`.
+
+#### `close_all_by(symbol)`
+
+Close every pair of opposite positions of `symbol` against each other (hedged accounts).
+
+#### `close_all_by_async(symbol)`
+
+`close_all_by`, returning its request id at once.
+
+#### `close_async(ticket, lots=None, *, price=None, slippage=0)`
+
+Close a position (or part of it) at market and return its request id at once; see `close`.
+
+#### `close_by(ticket, opposite_ticket)`
+
+Close a position against an opposite position of the same symbol (hedged accounts); the result arrives as
+order updates. Both must be open positions of the same symbol and opposite sides.
+
+#### `close_by_async(ticket, opposite_ticket)`
+
+`close_by`, returning its request id at once.
+
+#### `modify(ticket, *, sl=None, tp=None, price=None, expiration=None)`
+
+Change a position's stop-loss / take-profit, or a pending order's price / stops / expiration. Anything
+left as `None` keeps its current value (a pending order's expiration included; `expiration="gtc"` clears
+it). Returns the order as the server now holds it.
+
+#### `modify_async(ticket, *, sl=None, tp=None, price=None, expiration=None)`
+
+Modify a position or pending order and return its request id at once; see `modify`.
+
+#### `place_order(symbol, kind, lots, price, *, sl=0.0, tp=0.0, expiration=None, slippage=0, comment=None, magic=0, placed_type=None)`
+
+Place a pending order. `kind` is one of `buy_limit sell_limit buy_stop sell_stop`. `expiration` is
+`None` or `"gtc"` (good till cancelled), a `datetime` (server time, or timezone-aware) or a
+`timedelta` from now.
+
+#### `place_order_async(symbol, kind, lots, price, *, sl=0.0, tp=0.0, expiration=None, slippage=0, comment=None, magic=0, placed_type=None)`
+
+Place a pending order and return its request id at once; see `place_order`.
+
+#### `sell(symbol, lots, *, price=None, slippage=0, sl=0.0, tp=0.0, comment=None, magic=0, placed_type=None)`
+
+Sell at market (`price` defaults to the current bid); see `buy`.
+
+#### `sell_async(symbol, lots, *, price=None, slippage=0, sl=0.0, tp=0.0, comment=None, magic=0, placed_type=None)`
+
+Send a market sell and return its request id at once; see `buy_async`.
+
+## Events and streams
+
+#### `aorder_progress(*, request_id=None, maxsize=1000)`
+
+Async version of `order_progress`.
+
+#### `aorder_updates(*, maxsize=1000)`
+
+Async version of `order_updates`.
+
+#### `aquotes(*symbols, maxsize=10000)`
+
+Async version of `quotes` (no timeout; `aclose()` or cancel the task to stop). Call it inside a
+running event loop.
+
+#### `events_dropped` *(property)*
+
+How many events were dropped because callbacks fell too far behind (see `pmt4api._streams`).
+
+#### `on_connect(callback)`
+
+Call `callback(event)` after every successful connect: the first one and each automatic or manual
+reconnect (`event.connected` is true).
+
+#### `on_disconnect(callback)`
+
+Call `callback(event)` once when a session ends. `event.error` is why a link dropped, and `None` when
+you called `disconnect`. With `auto_reconnect` the client then reconnects by itself and
+`on_connect` fires again.
+
+#### `on_order_progress(callback)`
+
+Call `callback(progress)` as a trade request advances (see `buy_async`). Synchronous calls raise
+their outcome instead, but they also report here under an id this client does not return.
+
+#### `on_order_update(callback)`
+
+Call `callback(update)` when the server pushes a change to an order or position (opened, modified,
+closed, a pending order placed, filled or deleted, a balance entry).
+
+#### `on_quote(callback)`
+
+Call `callback(quote)` for every tick of every subscribed symbol. Returns a function that removes it.
+
+#### `on_quote_history(callback)`
+
+Call `callback(event)` as each chunk of bars of a `bars` download arrives.
+
+#### `on_symbols_update(callback)`
+
+Call `callback()` when the server pushes a change to the symbol list; read `symbol` again (the
+core keeps the table it loaded at connect, so a changed specification is seen at the next reconnect).
+
+#### `order_progress(*, request_id=None, timeout=None, maxsize=1000)`
+
+Iterate trade-request progress (attached when called), optionally only that of `request_id`. Ends when
+`timeout` seconds pass without an item.
+
+#### `order_updates(*, timeout=None, maxsize=1000)`
+
+Iterate order updates (attached when called). Ends when `timeout` seconds pass without one.
+
+#### `quotes(*symbols, timeout=None, maxsize=10000)`
+
+Iterate live quotes of `symbols` (subscribing them first; with none given, every subscribed symbol).
+Ends when `timeout` seconds pass without a tick. The feed is attached when this is called, not at the first
+`next()`. If the consumer falls behind by more than `maxsize` quotes the oldest are dropped.
+
+## Module functions
+
+#### `load_servers_ini(source)`
+
+The brokers in a terminal's `servers.ini`: each with its name, company, demo flag, main host and
+`(host, port)` access servers. Offline: reads only the file (a path, or the file's bytes).
+
+#### `save_servers_ini(records)`
+
+The bytes of a `servers.ini` file holding `records` (the inverse of `load_servers_ini`).
+
+#### `enable_core_logging(logger_name='pmt4api.core')`
+
+Forward the core's log messages (`Logger.OnMsgEx`) and internal diagnostics (`Diag.Sink`) to the Python
+logger `logger_name`. Returns a function that switches it off again. Nothing is forwarded unless this is called,
+and the core is silent by default.
+
+#### `to_frame(items)`
+
+A `pandas.DataFrame` from a list of the package's value objects (`Bar`, `Order`, `Quote`, ...).
+
+A list of bars is indexed by its `time`; anything else keeps a plain integer index.
+
+## Data types
+
+#### `Quote`
+
+A price. `time` is the server time of the tick (use it to judge how old the price is); `high` and `low`
+are the session's range once the server has sent it, and `None` before that.
+
+Fields: `symbol`, `bid`, `ask`, `time`, `high`, `low`
+
+#### `SymbolInfo`
+
+A symbol's specification and trading rules, as the server publishes them.
+
+Fields: `name`, `digits`, `point`, `currency`, `profit_mode`, `contract_size`, `margin_divider`, `tick_size`, `execution`, `security_index`, `min_lots`, `max_lots`, `lots_step`, `code`, `raw_tick_value`, `raw_bid_tick_value`, `raw_ask_tick_value`
+
+#### `SymbolGroup`
+
+One of the broker's configured symbol groups (its name and description).
+
+Fields: `name`, `description`
+
+#### `AccountInfo`
+
+The account at the moment it was read. `equity`, `profit`, `margin`, `free_margin` and `margin_level`
+are derived on the client from the live quotes (the server does not push them), exactly as the terminal does.
+`priced_from` is the server time of the oldest tick those figures were priced from (`None` with no open
+position): minutes old while the market is open means the feed is not delivering — do not trust the equity.
+
+Fields: `login`, `name`, `company`, `group`, `currency`, `leverage`, `balance`, `credit`, `equity`, `profit`, `margin`, `free_margin`, `margin_level`, `account_type`, `is_investor`, `priced_from`
+
+#### `AccountSummary`
+
+Realized totals over a history range (from the closed-order ledger, not the floating P/L of open positions).
+
+Fields: `balance`, `credit`, `realized_profit`, `deposit`, `withdrawal`
+
+#### `EquityPoint`
+
+One sample of the balance and equity curve. `balance_change` is the change of balance since the first point
+(deposits and withdrawals included, so it is not a trading result: use `AccountSummary`).
+
+Fields: `time`, `balance`, `equity`, `balance_change`, `unrealized_pl`, `balance_drawdown_raw`, `balance_drawdown_relative`, `equity_drawdown_raw`, `equity_drawdown_relative`
+
+#### `LotSizing`
+
+The answer of `Client.lots_for_risk`. If `ok` is false, `lots` is 0 and `reason` says why: do not
+trade it. `warnings` can accompany a true `ok` (most often that the broker's minimum volume risks more than
+was asked).
+
+Fields: `ok`, `lots`, `expected_loss_at_stop`, `risk_requested`, `minimum_trade_cost`, `ratio`, `reason`, `warnings`
+
+#### `Order`
+
+One MT4 order: an open position, a pending order, a closed order of the history, or a balance / credit entry.
+
+Fields: `ticket`, `symbol`, `order_type`, `lots`, `open_time`, `open_price`, `stop_loss`, `take_profit`, `close_time`, `close_price`, `expiration`, `magic`, `swap`, `commission`, `comment`, `profit`, `rate_open`, `rate_close`, `rate_margin`
+
+#### `Bar`
+
+Bar(time: 'datetime', open: 'float', high: 'float', low: 'float', close: 'float', volume: 'float')
+
+Fields: `time`, `open`, `high`, `low`, `close`, `volume`
+
+#### `OrderUpdate`
+
+A change the server pushed: `action` is one of `PositionOpen`, `PositionClose`, `PositionModify`,
+`PendingOpen`, `PendingClose`, `PendingModify`, `PendingFill`, `Balance`, `Credit` (a pending order that
+fills arrives as `PositionOpen`).
+
+Fields: `action`, `order`
+
+#### `OrderProgress`
+
+Progress of a trade request, as the request id (the integer `Client.buy_async` and friends return)
+advances through the server: `stage` is `InProcess`, `Accepted`, `Opened`, `Closed`, `Modified`,
+`PendingDeleted`, `ClosedBy`, `MultipleClosedBy`, `Price` or `Exception` (`Rejected` and `Timeout` are
+defined by the core but never raised by it). `order` is set where the server returned one, `error` for an
+`Exception` stage (a pmt4api error such as `ServerError`).
+
+Fields: `request_id`, `stage`, `order`, `error`
+
+#### `ConnectEvent`
+
+A session started (`connected` true: the first connect and every reconnect) or ended (`connected` false;
+`error` is the reason for a drop and `None` when you closed the client yourself).
+
+Fields: `connected`, `error`
+
+#### `QuoteHistoryEvent`
+
+A chunk of bars the server delivered for a bar download (see `Client.on_quote_history`).
+
+Fields: `symbol`, `timeframe`, `bars`
+
+#### `ServerRecord`
+
+A broker of a `servers.ini` file: its name, company, demo flag, main host and (host, port) access servers.
+
+Fields: `name`, `company`, `is_demo`, `main_host`, `access`
+
+## Errors
+
+```
+WmtError
+  BusyError
+  ConnectError
+  ConnectionLostError
+  CoreNotFoundError
+  InvalidRequestError
+  LicenseError
+  NoQuoteError
+  NotConnectedError
+  ProtocolError
+  RequestCancelled
+  RequestTimeout
+  RuntimeNotFoundError
+  ServerError
+    InvestorModeError
+    LoginRejectedError
+    RequoteError
+  TokenServiceError
+```
+
+- `BusyError` — The core allows one request of this kind at a time and one is still running; wait for it and retry.
+- `ConnectError` — No access server could be reached (or none answered within `connect_timeout`).
+- `ConnectionLostError` — An established connection was lost, possibly with a request in flight: whether it was applied is unknown; reconnect and look at `Client.orders` before sending again.
+- `CoreNotFoundError` — The licensed core library (wmt4api.dll) could not be located.
+- `InvalidRequestError` — The request was rejected before it was sent (for example, a symbol the server does not know).
+- `InvestorModeError` — The account was opened with an investor (read-only) password and the request needs trading rights. Nothing was sent.
+- `LicenseError` — The licence service refused the request. `reason` is one of: NoKey, Invalid, Expired, Revoked, RateLimited, LoginNotAllowed, AccountLimitReached, Unknown. `status` is the service's HTTP status and `detail` its own message, for support.
+- `LoginRejectedError` — The broker rejected the login: a wrong account number or password (typically code 65), a disabled or expired login, or an authorisation refusal. Fix the credentials; this is not an SDK fault and is not retried across servers.
+- `NoQuoteError` — No quote was available in time to read or to trade against. Nothing was sent.
+- `NotConnectedError` — The call needs a connection and the client is not connected.
+- `ProtocolError` — The server sent something the core could not decode.
+- `RequestCancelled` — The wait was cancelled by the caller (the `cancel` event of a download was set).
+- `RequestTimeout` — The server did not answer within the requested time. For a trade call this means the request WAS sent and was not confirmed in time: the order may have been accepted; look at `orders()` before sending again. (When nothing was sent, `NoQuoteError` is raised instead.)
+- `RequoteError` — An instant-execution price moved before the fill. `bid` / `ask` are the prices the server now offers: decide again and resend (nothing was filled).
+- `RuntimeNotFoundError` — The .NET runtime needed to host the core could not be started.
+- `ServerError` — The broker's server refused the request (a rejected login or a rejected order). `code_value` is the MT4 return code and `code` its name (`"REQUOTE"`, `"NOT_ENOUGH_MONEY"`, `"INVALID_STOPS"`, ...); both are `None` when the refusal carried no code.
+- `TokenServiceError` — The licence service could not be reached or answered with something unusable (not a licence decision).
+- `WmtError` — Base class of every pmt4api error.