Metadata-Version: 2.5
Name: pmt4api
Version: 1.0.0
Summary: Complete Python interface to the wmt4api MetaTrader 4 client library (market data, account, sizing, order entry, events).
Project-URL: Homepage, https://mtapi.one
Author: Sen Trading
License-File: LICENSE.txt
Keywords: market-data,metatrader,mt4,trading,wmt4api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: pythonnet>=3.0.3
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == 'pandas'
Provides-Extra: test
Requires-Dist: pandas>=1.5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# pmt4api — Python for wmt4api

`pmt4api` is the complete Python interface to **wmt4api**, the MetaTrader 4 client library from
[mtapi.one](https://mtapi.one). The protocol, licensing and trading logic stay in the licensed core
(`wmt4api.dll`), which this package loads in-process; every public capability of the C# library is available here
under a Pythonic name, with plain data types, a small error hierarchy, context managers, and sync, async and
callback styles.

No MetaTrader terminal is needed — the core talks to your broker directly. It is the sibling of
`pmt5api` (MT5): the two share their conventions, so a system that trades
both reads alike.

**Parity with the C# library is measured, not claimed:** `pmt4api.COVERAGE` maps every public member of the C#
`MT4API` and `OrderClient` classes to its Python counterpart (or states why it has none), and the test suite fails
if the core gains a member that is not accounted for. [`docs/FROM-CSHARP.md`](src/pmt4api/docs/FROM-CSHARP.md) is
that table; [`docs/API.md`](src/pmt4api/docs/API.md) is the reference.

## Install

The **Linux x86-64 wheel** carries everything — the core and a .NET runtime — so there is nothing else to install:

```
pip install pmt4api-<version>-py3-none-manylinux_2_28_x86_64.whl
```

On any other platform use the `py3-none-any` wheel, which carries the core and needs a .NET 8 (or later) runtime on
the machine (`dotnet --list-runtimes` should list `Microsoft.NETCore.App`).

You also need your **API key** (`wk_…`, the same key you use with wmt4api):

```
export WMT4API_KEY=wk_...         # or pass api_key=... to Client(...)
```

| | |
|---|---|
| Python | 3.9 or newer |
| Platform | **Linux x86-64 verified** (glibc 2.28 or newer). Windows and macOS are not verified yet — see *Known limitations* |
| Optional | `pip install pandas` for `to_frame` |

## Quick start

```python
from pmt4api import Client

with Client(login=12345678, password="investor-password", host="broker-access-host", port=443) as c:
    acct = c.account()
    print(acct.name, acct.balance, acct.currency, "equity", acct.equity)

    sym = c.find_symbol("EURUSD")                  # brokers add suffixes: EURUSDm, EURUSD.s ...
    print(c.quote(sym))                            # Quote(symbol='EURUSDm', bid=..., ask=..., time=...)

    for p in c.positions():
        print(p.ticket, p.symbol, p.order_type, p.lots, p.profit)
```

Use an investor (read-only) password for anything that does not trade.

## Market data

```python
from datetime import datetime
import pmt4api

c.symbols()                       # dict[str, SymbolInfo]: digits, contract size, min/max/step lots, execution ...
c.find_symbols("XAU")             # every name that starts with it: ['XAUUSDm', 'XAUEURm', ...]
c.symbol("XAUUSDm")               # one symbol's specification

h1 = c.bars("EURUSDm", "H1", count=500)                    # the latest 500 H1 bars, oldest first
d1 = c.bars("XAUUSDm", "D1", start=datetime(2026, 1, 1))   # everything since a date the server still holds
df = pmt4api.to_frame(h1)                                  # pandas DataFrame indexed by time
```

Timeframes: `M1 M5 M15 M30 H1 H4 D1 W1 MN1` — the nine the MT4 server serves; it delivers each itself. A series holds
**completed** bars: the bar that is still forming is not part of what the server sends (read the live price with
`quote()`), and `end=` reads the series up to that moment with no look-ahead. The broker limits how far back it goes
(M1 is typically a few days), so a long request returns what exists; one request carries at most 32 767 bars and
longer requests page backwards for you. `volume` is the tick volume.

### Live quotes

```python
with Client(...) as c:
    for q in c.quotes("EURUSDm", "XAUUSDm", timeout=30):   # ends after 30 s without a tick
        print(q.symbol, q.bid, q.ask, q.time)
```

```python
async with Client(...) as c:                               # connects without blocking the event loop
    async with c.aquotes("EURUSDm") as quotes:             # attached on entry, detached on exit
        async for q in quotes:
            print(q)
```

```python
remove = c.on_quote(lambda q: print(q))                    # callback style
c.subscribe("EURUSDm")
...
remove()
```

Until you subscribe to something the server streams a default set of a few hundred symbols; the moment you do it
streams only what you subscribed. The core keeps quotes honest across that change: `quote()` and the tick-value
calculations subscribe a symbol they need and wait for a tick that arrives *after* the request instead of using a
price cached from the feed that stopped (if no tick comes — a closed market — the last price is returned, and
`Quote.time` says how old it is). A position's symbol is put on the feed as soon as the position exists and stays
there, because the position's profit and the account's equity are priced from it. `account()` reports
`priced_from`, the server time of the oldest tick its figures used: minutes old while the market is open means the
feed is not delivering, and the equity should not be trusted.

Callbacks are delivered by **one dispatcher thread per client**, one at a time, in the order the core handed the
events over — you need no locks between callbacks, and a slow callback does not stall the connection. (The core
raises each event on a thread-pool thread, so two events that happen within microseconds of each other can swap;
order updates of one ticket carry `Order.profit` and times you can compare.) If a callback falls more than 20,000 events
behind, the oldest events are dropped, a warning is logged and `c.events_dropped` counts them. An exception raised
inside a callback is logged (`logging.getLogger("pmt4api")`) and swallowed. The iterators attach when you create them,
drop the oldest item when the consumer falls behind, and detach on `close()` / `async with` / garbage collection.

## Trading

```python
o = c.buy("EURUSDm", 0.10, sl=1.0950, tp=1.1100, comment="bot-1")   # market order at the ask; sell() at the bid
c.modify(o.ticket, sl=1.0970)                     # change stops; what you leave out keeps its value
c.close(o.ticket, 0.05)                           # close half; close(ticket) closes it all

p = c.place_order("EURUSDm", "buy_stop", 0.10, 1.1200, sl=1.1150,
                  expiration=timedelta(days=2))   # also buy_limit sell_limit sell_stop; a datetime works too
c.modify(p.ticket, price=1.1210)                  # a pending order's price; its expiration is kept
c.cancel(p.ticket)

c.close_by(a.ticket, b.ticket)                    # close one position against an opposite one (hedged accounts)
c.close_all_by("EURUSDm")                         # ... every opposite pair of the symbol
```

`lots` must be a multiple of 0.01 (the MT4 wire carries hundredths of a lot); a finer volume is refused before
anything is sent. `slippage` is in points. For an instant-execution symbol the order goes at `price` (default: the
current ask or bid) and a move of more than `slippage` points raises `RequoteError` with the prices the server now
offers; a market-execution symbol ignores both and fills at its own price.

**Tagging orders: use `comment`, not `magic`.** The core accepts a magic number but does not transmit it, so an
order cannot carry one. Rather than let a strategy believe its orders are tagged, `magic=` other than 0 raises
`InvalidRequestError`. A comment (ASCII, at most 31 characters) comes back on `Order.comment`; `Order.magic` is still
read from orders that carry one placed elsewhere.

**Without waiting** — a request id now, the outcome through events:

```python
c.on_order_progress(lambda p: print(p.request_id, p.stage, p.order and p.order.ticket))   # InProcess, Accepted, Opened ...
rid = c.buy_async("EURUSDm", 0.10)
for p in c.order_progress(request_id=rid, timeout=15):   # or follow one request as an iterator
    print(p.stage)
```

**In asyncio** — the synchronous calls on a worker thread: `await c.abuy(...)`, `asell`, `aplace_order`, `amodify`,
`aclose`, `acancel`, `aclose_by`, `aclose_all_by`, `aquote`, `abars`, `ahistory`. Cancelling the `await` of a trade
(a `wait_for` timeout, a cancelled task) does not recall a request that is already on its way: the order may still be
sent, so check `orders()` afterwards. Cancelling `ahistory` does abandon the download.

**Test on a demo account first.** Nothing here is ever retried or resent for you: if the server does not confirm in
time the call raises `RequestTimeout` and the order **may have been accepted** — look at `orders()` before sending
again. `NoQuoteError` is different: no price was available, so nothing was sent. A market order needs a price, so
even the `*_async` calls first wait (up to `quote_timeout`) for the symbol's first quote. After a partial close the
remainder of the position may carry a new ticket: read `positions()`.

## Sizing and risk

```python
r = c.lots_for_risk("EURUSDm", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0)
for w in r.warnings:
    print("warning:", w)                  # ok can still be True with a caveat (the broker's minimum volume risks more)
if r.ok:
    c.buy("EURUSDm", r.lots, sl=1.0950)
else:
    print("not sizing:", r.reason)
```

The value of a price unit comes from `tick_value()` (converted through the account currency's cross rates), the
broker's volume step, minimum and maximum from the account's own group; a size that cannot be justified is refused,
not guessed, and the volume is rounded **down**. Amounts are in the currency the account reports; there is no
cent-account scaling, so check the first result against your terminal. Also: `required_margin(symbol, lots)`,
`order_profit(symbol, open, close, lots)`, `tick_value(symbol, side)`, `contract_size(symbol)`.

## Account, history and curves

| Call | Returns |
|---|---|
| `account(refresh=True)` | `AccountInfo` — balance, credit, equity, floating profit, margin, free margin, margin level, leverage, currency, type |
| `balance`, `equity`, `margin`, `free_margin`, `margin_level`, `profit` | the same figures as cheap reads from the cache (no refresh; the margin may still wait for a conversion pair's first tick) |
| `orders()` / `positions()` / `pending_orders()` / `order(ticket)` | `list[Order]` working / open positions / pending / one |
| `history(start, end)` | `list[Order]` — closed orders and balance / credit entries, by close time |
| `summary(start=None, end=None)` | `AccountSummary` — realized profit, deposits, withdrawals |
| `equity_history(start, "D1")` | `list[EquityPoint]` — balance (exact) and equity (reconstructed) curve with drawdowns |

MT4 keeps one record for open positions, pending orders, closed orders and ledger entries: `Order.order_type` tells
them apart (`Buy` / `Sell`, `BuyLimit` … , `Balance` / `Credit`), and `is_market`, `is_pending`, `is_capital_flow`
say it directly. Times are naive `datetime` values in the **broker's server time**; an unset time is `None`.

`history()`, `summary()` and `equity_history()` each open their own short-lived broker connection and cost one
licence request, which the licence service rate-limits per minute: fetch once and reuse the result. `history()`
takes a `threading.Event` as `cancel=` to abandon the wait.

## Events

`on_quote`, `on_order_update`, `on_order_progress`, `on_connect`, `on_disconnect`, `on_quote_history`,
`on_symbols_update` — each returns a function that removes the callback. `quotes()`, `order_updates()` and
`order_progress()` (and the `a…` async versions) turn a stream into an iterator.

## Staying connected

Pass `auto_reconnect=True` to let the core re-establish a dropped session (exponential backoff up to 60 s, failover
across the primary server, `servers=[(host, port), ...]` and the access servers the broker published, re-subscription).
Watch `on_disconnect` (its `error` says why: `ConnectionLostError`, and `None` when you closed the client) and
`on_connect`. A session that carries nothing for `no_message_timeout` (default 30 s; the server answers a ping every
few seconds) is declared dead and closed, so a half-open link is noticed instead of lingering. A refusal retrying
cannot cure (an expired licence, a rejected login) stops the reconnecting. Do not poll `connected` and call
`connect()` in a loop — brokers rate-limit logins that hammer their access servers. `reconnect()` re-establishes by
hand and returns whether it worked. After a reconnect, re-query `account()` and `orders()`; subscriptions are
restored, cached snapshots are not. `disconnect()` is final: it also stops a reconnect that is in flight.

## Configuration

| Setting | Argument | Environment variable |
|---|---|---|
| API key | `api_key=` | `WMT4API_KEY` (then `WMTAPI_KEY`) |
| Licence service URL (leave at its default) | `token_url=` | `WMT4API_TOKEN_URL` |
| Core library (only if you do not use a wheel that carries it) | `dll_path=` | `WMT4API_DLL` |
| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server), `token_timeout`, `trade_timeout` (≥ 1), `quote_timeout` / `history_timeout` / `bars_timeout` (the defaults of `quote`, `history`, `bars`), `no_message_timeout` | — |
| Reconnect | `auto_reconnect`, `reconnect_backoff`, `reconnect_max_attempts`, `servers=` | — |
| Orders | `placed_type=` (`manual`, `expert`, `dealer` …), `comment_encoding=` (default `latin-1`) | — |
| .NET runtime location | — | `DOTNET_ROOT` |

A core path you give (argument or `WMT4API_DLL`) is used exactly as given and is an error if it does not exist. The
.NET runtime is taken from `DOTNET_ROOT` if you set it, else the runtime bundled in the wheel, else an installed one.
The bundled runtime runs in invariant-culture mode on machines without ICU. The MT4 core has no proxy support.

### Diagnostics

```python
import logging
logging.basicConfig(level=logging.DEBUG)
pmt4api.enable_core_logging()          # the core's own messages -> logging.getLogger("pmt4api.core")
```

### Offline helpers

`load_servers_ini(path_or_bytes)` / `save_servers_ini(records)` read and write a terminal's `servers.ini`.
`python -m pmt4api` prints what is installed and whether it works here (`--connect` also reads an account, using
`PMT4_LOGIN`, `PMT4_PASSWORD`, `PMT4_HOST`); the output holds no secrets.

## Errors

Everything the core raises reaches you as one of these, all subclasses of `pmt4api.WmtError`; the original
exception stays available as `__cause__`.

| Exception | Meaning |
|---|---|
| `LicenseError` | The licence service refused the key. `.reason` is one of `NoKey`, `Invalid`, `Expired`, `Revoked`, `RateLimited`, `LoginNotAllowed`, `AccountLimitReached`, `Unknown`; `.status` is its HTTP status. |
| `TokenServiceError` | The licence service could not be reached or answered unusably — retry, don't re-prompt for a key. |
| `LoginRejectedError` | The broker rejected the account number or password (`.code` is usually `INVALID_ACCOUNT`, 65). A `ServerError`. |
| `ConnectError` | No access server could be reached (or none answered within `connect_timeout`). |
| `ConnectionLostError` | An established connection dropped; with a trade in flight, whether it was applied is unknown. |
| `ServerError` | The broker refused a request. `.code` is the MT4 return code by name (`NOT_ENOUGH_MONEY`, `INVALID_STOPS`, `TRADE_DISABLED` …) and `.code_value` its number (`pmt4api.TRADE_CODES`). |
| `RequoteError` | An instant-execution price moved: `.bid` / `.ask` are the prices now offered. A `ServerError`; nothing was filled. |
| `InvestorModeError` | A read-only (investor) login tried to trade. Nothing was sent. A `ServerError`. |
| `InvalidRequestError` | The request was rejected before it was sent, e.g. an unknown symbol or a `magic` number (also a `ValueError`). |
| `BusyError` | A bar download for the same symbol and timeframe is already running. |
| `RequestTimeout` | No answer in time (also a built-in `TimeoutError`). For a trade call the request **was sent**: the order may have been accepted. |
| `NoQuoteError` | No quote arrived in time to read or to trade against. Nothing was sent. |
| `RequestCancelled` | You cancelled the wait (`history(cancel=...)`). |
| `NotConnectedError` | The call needs a connection and the client is not connected. |
| `ProtocolError` | The server sent something the core could not decode. |
| `CoreNotFoundError` / `RuntimeNotFoundError` | `wmt4api.dll` or the .NET runtime was not found; the message says where it looked. |

Calls made through `client.raw` bypass this translation and raise the core's own exceptions.

```python
from pmt4api import Client, LicenseError, LoginRejectedError, RequoteError, TokenServiceError

try:
    c = Client(...).connect()
except LicenseError as e:
    print("licence refused:", e.reason)
except LoginRejectedError as e:
    print("the broker rejected the login:", e.code)
except TokenServiceError as e:
    print("licence service unreachable:", e)
```

## What has been verified

Run against real demo accounts (not only unit-tested), through a licence authority of its own, from clean containers
with no .NET installed, on three brokers (Exness, ICMarkets, DPrime — all market-execution): connect, licensing errors
(bad key, unreachable licence service, wrong password, unreachable host); account, symbols and trading rules; quotes
and streams, including that a quote stays current after the feed is narrowed; bars on all nine timeframes (identical to
the core's own download), paging and windows; history, summary and an equity curve reconciled against the history
rows; sizing; order entry — market, pending with expiration, modify, partial close, close-by, close-all-by, cancel,
asynchronous with progress events — with the server's own rejections arriving as typed errors; failing over from a
dead primary to a backup server; dropping the connection twice mid-stream, a broker that refuses connections for a
while and a link that goes silent without closing — each recovered with subscriptions restored — a manual reconnect,
and a `disconnect()` that stays final; concurrent subscribing, quoting, bar and account reads from several threads
without an error; and every shipped example.

Two unattended runs on demo accounts: **three hours** (5 symbols, 212 333 ticks, the account read every minute,
17 bar and 17 history downloads; the connection cut three times — recovered in 3.7–4.0 s — and made silent twice —
noticed at the 20 s setting, back after 24 s) with no error, no event dropped, resident memory flat (~147 MB, −0.7 MB
between the halves), threads and file descriptors flat — on a build of the core that preceded the last review fixes;
and a **ninety-minute** run of the released wheel in a container (DPrime demo): 88 account reads, 8 bar and 8 history
downloads, 17 far-away pending orders placed and cancelled, 7 real positions opened, checked against the feed and
closed (10 more market orders were refused by the broker with `TRADE_DISABLED`, which the run counts as skipped), the
connection cut four times (recovered in about 3 s) and made silent twice (noticed at the 20 s setting, back in under
24 s), which finished with no error and no growth check tripped (resident memory 104 MB at one minute, 140 MB at half an
hour, 145 MB at the hour; threads 19–21, file descriptors 100).

## Known limitations

- **Linux x86-64 is the verified platform.** Windows, macOS, arm64 and musl-based Linux have not been verified.
- **No magic number**: the core does not transmit it (see *Trading*). Tag orders with `comment`.
- **Investor-mode refusal** (`InvestorModeError`, and `is_investor` / `can_trade` reading the account record's
  read-only flag) and **requotes** (`RequoteError`) are covered by unit tests; they have not been provoked live
  (the available demo accounts are market-execution and no investor password was at hand).
- **Comments are ASCII**, at most 31 characters: orders are read back through an ASCII parser.
- **`history()`, `summary()` and `equity_history()` use the primary server only**: each opens its own short
  connection to `host:port` and does not fail over to `servers=`.
- **The connect handshake and the first data load give up after 30 s** whatever `connect_timeout` says (that one
  bounds the TCP dial of each server); a server that stalls there is skipped and the next one tried.
- **`trade_timeout` counts whole seconds** (the core truncates it). A `ServerError` with code `TRADE_TIMEOUT` (128)
  is the server's own timeout while processing: the outcome is not known — look at `orders()` before sending again.
- **The server's UTC offset is read once per session**; a session that spans the broker's daylight-saving change has
  `server_time`, `bars(end=now)` and a relative `expiration` off by an hour until it reconnects.
- **The silence watchdog's premise** — the server answers each ping within seconds — was measured on a quiet
  session (one answer per ping); a market-closed weekend has not been observed. `no_message_timeout=0` switches it
  off.
- The server lists a default feed of its own until you subscribe; `is_subscribed()` reports your subscriptions, and
  `quote()` answers for any symbol either way.
- One `Client` is one broker connection. Its methods can be called from several threads, but a trading call is
  neither queued nor serialized for you; two threads acting on the same ticket is your responsibility.
- `TradeTimeout` below one second makes the core give up straight after sending, so `trade_timeout` must be ≥ 1.
- A folder named `wmt4api` in your working directory is handled automatically (it would otherwise hide the core's
  .NET namespace).

## Licensing and security

Your connection is authorised per session by the hosted licence service, using your API key; the core talks to your
broker directly. What is sent to the licence service and what is not, and the security notes, are in the core's own
documents, which travel with the wheel: `pmt4api/_native/docs/LICENSING.md`, `SECURITY.md` and `ERRORS.md`
(and the core's `CHANGELOG.md` next to them). `python -m pmt4api` prints where they are.

## Third-party components

The Linux wheel includes the Microsoft .NET runtime (MIT licence; its notices are in `pmt4api/_dotnet/`) and the
wmt4api core with its own notices (`pmt4api/_native/THIRD-PARTY-NOTICES.txt`).

## Trademarks

MetaTrader, MT4 and MT5 are trademarks of MetaQuotes Ltd. wmt4api/wmt5api/pmt4api/pmt5api are independent products
of Sen Trading ([mtapi.one](https://mtapi.one)); they are not affiliated with, endorsed by or sponsored by MetaQuotes
Ltd. All other names are the property of their respective owners.

## Licence and support

See `LICENSE.txt`. Use of the core library is governed by the wmt4api commercial SDK licence. For keys, support
and licence terms contact mtapi.one.
