pmt5api 1.0.0__tar.gz

pmt5api-1.0.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog — pmt5api
+
+## [1.0.0] — 2026-10-12
+
+First release. `pmt5api` exposes every public capability of the wmt5api 3.x C# library to Python.
+
+### Capabilities
+- Connection and session: licensing, failover, `auto_reconnect`, proxies (SOCKS4/SOCKS5/HTTPS), client certificate,
+  all timeouts, connect-progress events, server time and account mode.
+- Market data: symbols with trading rules and sessions, commissions, quotes and subscriptions (callbacks, iterators,
+  asyncio), bars M1–D1 with tick volume, tick value and contract size.
+- Account: balances and margins (with and without swap/commission), orders, positions, closed orders, history and
+  deal history (blocking and event-driven), realized summary, balance/equity curve.
+- Sizing and risk: money-scale calibration, lots-for-risk with evidence, required margin, order profit.
+- Order entry: market, pending (limit, stop, stop-limit), expiration, fill policy, modify, partial close, close-by,
+  cancel — synchronous, with request ids and progress events, and awaitable; magic number on orders and deals.
+- Offline helpers and administration: `servers.dat` read and write, demo account request, password change.
+- Diagnostics: the core's log into Python `logging`.
+- Parity manifest `pmt5api.COVERAGE`, checked against the DLL by the test suite; generated API reference and a
+  C#-to-Python table.
+
+### Packaging
+- Linux x86-64 wheel carrying the core and the .NET 9 runtime (`manylinux_2_28`); a pure wheel carrying the core;
+  an sdist.
+
+### Verified
+Against real demo accounts, from clean containers without .NET (Python 3.9, 3.12, 3.13; glibc 2.28 and 2.41):
+read-only and trading suites, reconnects (drops, a refused window, a silent link), every shipped example, and a
+three-hour unattended run (4 recovered drops, no errors, memory flat after warm-up).
+Not verified: Windows, macOS, arm64, musl; netting accounts; client certificates.

pmt5api-1.0.0/LICENSE.txt

@@ -0,0 +1,29 @@
+wmt5api — Commercial SDK License
+================================
+
+Copyright © Sen Trading (mtapi.one). All rights reserved.
+
+This software (the "SDK": wmt5api.dll, its documentation, and the accompanying
+sample) is licensed, not sold. Your use is governed by the commercial license
+agreement under which you obtained your API key.
+
+Subject to that agreement and a valid, active license key, you are granted a
+non-exclusive, non-transferable right to integrate and use the SDK in your own
+applications.
+
+You may NOT, except as expressly permitted by your agreement:
+  • disassemble the SDK, or attempt to discover its source code, internal structure, or algorithms by any means;
+  • redistribute, sublicense, rent, or resell the SDK or your API key;
+  • remove or alter any proprietary notices.
+
+The SDK connects to a hosted licensing service to authorize each connection.
+A license is valid for your subscription period; it stops authorizing new
+connections when the subscription lapses or is cancelled.
+
+THE SDK IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
+INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM,
+DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE SDK.
+
+For license terms, support, or a key: contact your account representative at
+mtapi.one.

pmt5api-1.0.0/PKG-INFO

@@ -0,0 +1,339 @@
+Metadata-Version: 2.5
+Name: pmt5api
+Version: 1.0.0
+Summary: Complete Python interface to the wmt5api MetaTrader 5 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,mt5,trading,wmt5api
+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
+
+# pmt5api — Python for wmt5api
+
+`pmt5api` is the complete Python interface to **wmt5api**, the MetaTrader 5 client library from
+[mtapi.one](https://mtapi.one). The protocol, licensing and trading logic stay in the licensed core
+(`wmt5api.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.
+
+**Parity with the C# library is measured, not claimed:** `pmt5api.COVERAGE` maps every public member of the C#
+`MT5API` class 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/pmt5api/docs/FROM-CSHARP.md) is that table;
+[`docs/API.md`](src/pmt5api/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 pmt5api-<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 wmt5api):
+
+```
+export WMTAPI_KEY=wk_...          # or pass api_key=... to Client(...)
+```
+
+| | |
+|---|---|
+| Python | 3.9, 3.12 and 3.13 verified; 3.9 or newer required |
+| 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 pmt5api 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)
+
+    print(c.quote("EURUSD"))                       # Quote(symbol='EURUSD', 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 pmt5api
+
+c.symbols()                       # dict[str, SymbolInfo]: digits, contract size, min/max/step lots, swaps, ...
+c.symbol("EURUSD")                # one symbol; find_symbol("EURUSD") resolves a suffixed name such as EURUSDm
+c.sessions("EURUSD")              # when it is quoted and traded, per weekday
+c.is_trade_session("EURUSD")      # inside a trade session right now?
+
+h1 = c.bars("EURUSD", "H1", count=500)                   # the latest 500 H1 bars, oldest first
+d1 = c.bars("XAUUSD", "D1", start=datetime(2026, 1, 1))  # everything since a date
+df = pmt5api.to_frame(h1)                                # pandas DataFrame indexed by time
+```
+
+Timeframes: `M1 M2 M3 M4 M5 M6 M10 M12 M15 M20 M30 H1 H2 H3 H4 H6 H8 H12 D1 W1 MN1`. The server delivers one-minute
+bars; higher timeframes are built from them, aligned to the server's calendar (a day starts at server midnight, an H4
+bar at 00, 04, 08, … server time, a week on Sunday, a month on the 1st), with `tick_volume` summed. Minutes after
+`end` are not used; the last bar may still be forming. `spread` is present on M1 bars only.
+
+### Live quotes
+
+```python
+with Client(...) as c:
+    for q in c.quotes("EURUSD", "XAUUSD", timeout=30):    # ends after 30 s without a tick
+        print(q.symbol, q.bid, q.ask)
+```
+
+```python
+async with Client(...) as c:                               # connects without blocking the event loop
+    async with c.aquotes("EURUSD") 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("EURUSD")
+...
+remove()
+```
+
+Callbacks are delivered by **one dispatcher thread per client**, one at a time, in arrival order — you need no locks
+between callbacks, and a slow callback does not stall the connection. 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("pmt5api")`) and swallowed. Order updates keep the state they had at
+the moment they arrived (they are snapshots). 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("EURUSD", 0.10, sl=1.0950, tp=1.1100, magic=424242)   # 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("EURUSD", "buy_stop_limit", 0.10, 1.1200, stop_limit=1.1190,
+                  expiration=datetime(2026, 12, 31, 23, 0))   # also buy_limit sell_limit buy_stop sell_stop
+c.modify(p.ticket, expiration="gtc")
+c.cancel(p.ticket)
+
+c.close(a.ticket, close_by=b.ticket)              # close one position against an opposite one (hedging accounts)
+```
+
+`magic` is your own number for the order: it comes back on `Order.magic` and `Deal.magic` (including the deals
+that close the position), so a bot can find its own orders and history after a restart.
+
+**Without waiting** — a request id now, the outcome through events:
+
+```python
+c.on_order_progress(lambda p: print(p.request_id, p.status, p.ticket))     # REQUEST_ACCEPTED, REQUEST_EXECUTED, ...
+rid = c.buy_async("EURUSD", 0.10)
+```
+
+**In asyncio** — the synchronous calls on a worker thread: `await c.abuy(...)`, `asell`, `aplace_order`, `amodify`,
+`aclose`, `acancel`, `aquote`. Cancelling the `await` (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.
+
+**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. `orders()` can lag a moment behind
+a call that has just returned; `close()` and `modify()` read the position's volume and stops from it, so wait for a
+partial close to show up before acting on the same position again. `positions()` lists open positions only (orders of
+type `Buy` or `Sell`); `orders()` also lists pending orders. A market order needs a price, so even the `*_async`
+calls first wait (up to `quote_timeout`) for the symbol's first quote.
+
+## Sizing and risk
+
+Do not size a trade from a one-line formula: what a price unit is worth depends on how *your* broker configured
+*your* account (two accounts in the same cent currency can differ by a factor of one hundred). The core measures it
+from your own closed deals and refuses to size without that evidence:
+
+```python
+if c.calibrate_money_scale(datetime(2025, 1, 1)):                 # read-only; places no order
+    r = c.lots_for_risk("EURUSD", entry_price=1.1000, stop_price=1.0950, risk_amount=50.0)
+    for w in r.warnings:
+        print("warning:", w)              # read these: ok can still be True with a caveat
+    if r.ok and r.expected_loss_at_stop <= 50.0 * 1.05:
+        c.buy("EURUSD", r.lots, sl=1.0950)
+    else:
+        print("not sizing:", r.reason)
+else:
+    print(c.money_scale_evidence)
+```
+
+`ok` is true even when the smallest allowed volume risks more than you asked for (up to `max_ratio`, default 2×), or
+when nothing independent corroborated the price unit — which is why `warnings` and `expected_loss_at_stop` are there
+to be checked. Also: `required_margin(symbol, lots)`, `order_profit(symbol, open, close, lots)`, `tick_value(symbol)`,
+`ledger_value_per_lot(symbol)`, `money_scale_from_deal(deal)`.
+
+## Account, history and curves
+
+| Call | Returns |
+|---|---|
+| `account(refresh=True)` | `AccountInfo` — balance, equity, floating P/L (with and without swap/commission), margin, free margin, margin level, leverage, account mode, contact details |
+| `orders()` / `positions()` / `closed_orders()` | `list[Order]` — working / open positions only / what this session saw close |
+| `history(start, end)` / `deal_history(year, month)` | `History` — `.orders` and `.deals` (the ledger, including deposits and withdrawals) |
+| `summary(start=None, end=None)` | `AccountSummary` — realized profit, deposits, withdrawals, from the deal ledger |
+| `equity_history(start, "D1")` | `list[EquityPoint]` — balance (exact) and equity (reconstructed) curve with drawdowns |
+| `request_history(...)`, `request_bars(...)` | without waiting; the data arrives through `on_history` / `on_quote_history` |
+
+Times are naive `datetime` values in the **broker's server time**, as the server reports them; an unset time is `None`.
+
+`account()` first quotes each open position's symbol once and recalculates profits, so equity, profit and margin
+level are current (a cold read would otherwise show equity equal to balance). Pass `refresh=False` to skip that.
+
+## Events
+
+`on_quote`, `on_order_update`, `on_order_progress`, `on_connect_progress`, `on_history`, `on_quote_history`,
+`on_symbols_update`, `on_symbol_update` — each returns a function that removes the callback. `quotes()` and
+`order_updates()` (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 with jitter, failover to
+the broker's cluster members, re-subscription). Watch `on_connect_progress` to tell a permanent failure from a
+transient one, and bound it with `reconnect_max_attempts`. Do not poll `connected` and call `connect()` in a loop —
+brokers rate-limit logins that hammer their access servers. After a reconnect, re-query `account()` and `orders()`;
+subscriptions are restored, cached snapshots are not.
+
+## Configuration
+
+| Setting | Argument | Environment variable |
+|---|---|---|
+| API key | `api_key=` | `WMTAPI_KEY` |
+| Licence service URL (leave at its default) | `token_url=` | `WMTAPI_TOKEN_URL` |
+| Core library (only if you do not use a wheel that carries it) | `dll_path=` | `WMTAPI_DLL` |
+| Timeouts (seconds, each > 0) | `connect_timeout` (one attempt on one server), `cluster_member_timeout` (per server while failing over), `token_timeout`, `execution_timeout`, `quote_timeout` / `history_timeout` / `bars_timeout` (the defaults of `quote`, `history`, `bars`), `ping_interval`, `no_message_timeout` | — |
+| Reconnect | `auto_reconnect`, `reconnect_backoff`, `reconnect_max_backoff`, `reconnect_max_attempts` | — |
+| Proxy | `proxy=Proxy("socks5" \| "socks4" \| "https", host, port, user, password)` — `host` must be an IP address | — |
+| Client certificate / common key | `certificate=`, `certificate_password=`, `common_key=` | — |
+| .NET runtime location | — | `DOTNET_ROOT` |
+
+A core path you give (argument or `WMTAPI_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.
+
+### Diagnostics
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+pmt5api.enable_core_logging()          # the core's own messages -> logging.getLogger("pmt5api.core")
+```
+
+### Offline helpers and account administration
+
+`load_servers_dat(path_or_bytes)` / `save_servers_dat(records)` read and write a terminal's `servers.dat`;
+`request_demo_account(DemoAccountRequest(...), host, port)` asks a broker for a demo account (it creates a real
+account at that broker: use it deliberately); `c.change_password(new, investor=False)`.
+
+## Errors
+
+Everything the core raises reaches you as one of these, all subclasses of `pmt5api.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`. |
+| `TokenServiceError` | The licence service could not be reached or answered unusably — retry, don't re-prompt for a key. |
+| `ConnectError` | The broker's access server (or the network, or a proxy) could not be reached. |
+| `ConnectionLostError` | An established connection dropped (the core's `Disconnected`). |
+| `ServerError` / `InvestorModeError` | The broker refused the request (wrong login or password, a rejected order / a read-only login tried to trade). `.code` is the server's return code by name (`REQUOTE`, `NO_MONEY`, `INVALID_PRICE`, …). |
+| `InvalidRequestError` | The request was rejected before it was sent, e.g. an unknown symbol (also a `ValueError`). |
+| `BusyError` | The core allows one request of this kind at a time and one is still running (a history or bars download). |
+| `ProxyError` | The configured proxy failed. |
+| `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. |
+| `NotConnectedError` | The call needs a connection and the client is not connected. |
+| `CoreNotFoundError` / `RuntimeNotFoundError` | `wmt5api.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 pmt5api import Client, LicenseError, TokenServiceError
+
+try:
+    c = Client(...).connect()
+except LicenseError as e:
+    print("licence refused:", e.reason)
+except TokenServiceError as e:
+    print("licence service unreachable:", e)
+```
+
+## What has been verified
+
+Each of these was run against real demo accounts (not only unit-tested), from a clean container with no .NET
+installed: connect and licensing (including the production HTTPS licence path); account, symbols and trading rules;
+quotes and streams; bars (H1 identical to the core's own conversion on every period compared); history; the sizing
+chain (calibration, sizing, refusal of a zero-distance stop, cross-check from a closed deal); summary reconciled
+against the deal ledger and an equity curve ending at the account's balance; order entry — market, pending,
+stop-limit with expiration, modify, partial close, close-by, cancel, asynchronous with progress events — with the
+magic number round-tripping through every deal; a rejected order; connecting through SOCKS5 and HTTPS proxies;
+dropping the connection twice mid-stream and recovering with subscriptions restored; a broker that refuses connections
+for a while; a link that goes silent without closing (noticed at `no_message_timeout`, then recovered); and a
+three-hour unattended run on a demo account — five symbols streamed (147 732 ticks), the account polled every minute
+(179 reads), 17 bar and 17 history downloads, 17 far-away pending orders placed and cancelled, the connection cut
+four times (each recovered in 2.0–2.5 s with the subscriptions restored) — which finished with no error. Resident
+memory settled at about 200 MB (it rises to ~190 MB in the first half hour; between the two halves of the run it
+moved by 4 MB), threads and file descriptors stayed flat. Every shipped example was run against a real account too.
+
+## Known limitations
+
+- **Linux x86-64 is the verified platform.** Windows, macOS, arm64 and musl-based Linux have not been verified.
+- Netting accounts have not been verified (the available demo accounts are all hedging).
+- Client certificates (`certificate=`), `common_key=` and `request_demo_account` have been unit-tested but not run
+  against a broker that requires or serves them.
+- 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.
+- The `state` of an order is the core's value and is not a reliable way to tell a position from a pending order (a
+  freshly opened position can stay `Started`). Use `positions()`, or the order's type, for that.
+- A folder named `wmt5api` 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: `pmt5api/_native/docs/LICENSING.md`, `SECURITY.md` and `ERRORS.md`
+(and the core's `CHANGELOG.md` next to them). `python -m pmt5api` prints where they are.
+
+## Third-party components
+
+The Linux wheel includes the Microsoft .NET runtime (MIT licence; its notices are in `pmt5api/_dotnet/`) and the
+wmt5api core with its own notices (`pmt5api/_native/THIRD-PARTY-NOTICES.txt`).
+
+## Trademarks
+
+MetaTrader, MT4 and MT5 are trademarks of MetaQuotes Ltd. wmt4api/wmt5api/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 wmt5api commercial SDK licence. For keys, support
+and licence terms contact mtapi.one.