pmt5api 1.0.0__py3-none-any.whl

pmt5api/_native/docs/ERRORS.md

@@ -0,0 +1,143 @@
+# Errors & troubleshooting — wmt5api
+
+Applies to wmt5api 3.1.0.
+
+Errors are **typed** — catch what you care about. A licence error is raised during `Connect()`, before any
+account data is read (the broker login handshake has already taken place).
+
+```csharp
+try
+{
+    api.Connect();
+}
+catch (LicenseException ex)      { /* licence refused — inspect ex.Reason */ }
+catch (TokenServiceException ex) { /* licence service unreachable or unusable reply — retry */ }
+catch (TimeoutException ex)      { /* the host did not reply within ConnectTimeout */ }
+catch (ConnectException ex)      { /* cannot connect, or the connection was lost */ }
+catch (ServerException ex)       { /* the broker refused the login — ex.Code is the MT5 return code */ }
+
+try
+{
+    var q = api.GetQuote(symbol, 5000);
+    api.OrderSend(symbol, lots, q.Ask, OrderType.Buy);
+}
+catch (TimeoutException ex)      { /* no quote in time, or the trade was NOT CONFIRMED in time — it may still
+                                      have been accepted: check GetOpenedOrders() before resending */ }
+catch (InvestorModeException ex) { /* the login is read-only (investor) */ }
+catch (ServerException ex)       { /* the broker rejected the request — ex.Code is the MT5 return code */ }
+catch (ConnectException ex)      { /* not connected, or the connection was lost */ }
+catch (ArgumentException ex)     { /* pre-flight validation, for example an unknown symbol */ }
+```
+
+`TimeoutException` means different things at different steps — see the table below. In particular, **never
+resend an order just because a trade call timed out.**
+
+`Connect()` throws the typed exception **directly** — it is never wrapped in an `AggregateException`.
+
+## The exception types
+
+| Type | Derives from | Raised when |
+|---|---|---|
+| `LicenseException` | `Exception` | The licence service refused the licence. `.Reason`, `.ServerError`, `.HttpStatus`. |
+| `TokenServiceException` | `Exception` | The licence service could not be reached, timed out, or returned an unusable reply. |
+| `ServerException` | `Exception` | The broker rejected the login or a trading request. `.Code` is the MT5 return code (`Msg`). |
+| `ConnectException` | `Exception` | The client is not connected, a connection could not be established, or it was lost. |
+| `InvestorModeException` | `Exception` | A trading call was made on a read-only (investor) login. |
+| `ProxyException` | `Exception` | The configured SOCKS or HTTPS proxy refused or failed the connection. |
+| `ConnectionException` | `ApplicationException` | A client certificate (`PfxFile`) was supplied but holds no RSA private key. |
+| `ArgumentException` | `SystemException` | Client-side validation: an unknown symbol, an unknown group, a `CommonKey` that is not 15 bytes. |
+| `TimeoutException` | `SystemException` | The host did not reply within `ConnectTimeout`; a quote did not arrive within its timeout; a history download did not return within `DownloadOrderHistoryTimeoutMs`. |
+| `Exception` (plain) | — | A few state errors, listed [below](#plain-systemexception-state-errors). |
+
+## LicenseException — the licence service refused
+
+`ex.Reason` is a `LicenseReason`:
+
+| Reason | Meaning | What to do |
+|---|---|---|
+| `NoKey` | No API key was supplied | Set `ApiKey` or the `WMTAPI_KEY` environment variable |
+| `Invalid` | The key is not recognised | Check the key; it may be for another product |
+| `Expired` | The licence period ended | Renew the subscription |
+| `Revoked` | The subscription was cancelled or the key revoked | Re-subscribe or obtain a new key |
+| `RateLimited` | Too many requests this minute | Back off and retry |
+| `LoginNotAllowed` | This login is not on the key's allow-list | Use an allowed login, or ask for the key to be widened |
+| `AccountLimitReached` | The licence already has its maximum number of distinct broker logins and this is a new one | Connect with an already-enrolled login, or upgrade the plan |
+| `Unknown` | The service refused for a reason this version does not recognise | Read `ex.ServerError` and `ex.HttpStatus`, and contact support |
+
+`ex.ServerError` is the raw error string the service returned (null for a client-side `NoKey`);
+`ex.HttpStatus` is the HTTP status (0 when the failure was detected client-side).
+
+## TokenServiceException — infrastructure, not a licence decision
+
+The licence service was unreachable, timed out, or returned a reply that could not be used. Transport
+failures are retried a few times before this is thrown. **Retry**, and check your network — do **not**
+re-prompt the user for a key. `TokenServiceTimeout` (default 10 000 ms) bounds each request.
+
+## ServerException — the broker rejected a login or a trade
+
+`ex.Code` is the MT5 return code (the `Msg` enum); the member name is the meaning. The ones you typically
+branch on after an order:
+
+| Code | Meaning |
+|---|---|
+| `DONE` / `REQUEST_EXECUTED` | success |
+| `REQUOTE` / `PRICE_CHANGED` | the price moved — re-quote and resend |
+| `NO_MONEY` | insufficient margin |
+| `MARKET_CLOSED` | the symbol's session is closed |
+| `INVALID_VOLUME` / `INVALID_PRICE` / `INVALID_STOPS` | bad request parameters |
+| `TRADE_DISABLED` / `AUTOTRADE_DISABLE_SERVER` | trading is not permitted |
+| `TOO_MANY_TRADE_REQUESTS` / `TOO_FREQUENT_REQUEST` | slow down |
+
+On login the codes you will meet include `INVALID_ACCOUNT`, `ACCOUNT_DISABLED`, `UNALLOWED_IP_ADDRESS` and
+`OLD_VERSION`. The full `Msg` enum is in IntelliSense.
+
+## What each call can throw
+
+| Call | Typed exceptions |
+|---|---|
+| `Connect()` | `LicenseException`, `TokenServiceException`, `ServerException`, `ConnectException` (including "cannot connect to host:port", with the socket error as `InnerException`), `TimeoutException`, `ProxyException`, `ConnectionException` |
+| `OrderSend`, `OrderClose`, `OrderModify`, `OrderCancel` and their `…AsyncTask` variants | `ArgumentException` (unknown symbol), `ConnectException`, `InvestorModeException`, `ServerException`, `TimeoutException` (the server did not confirm the request within `ExecutionTimeout`, default 30 000 ms — the order may still have been accepted, so check `GetOpenedOrders()` before resending); plain `Exception` (see below). The `…AsyncTask` variants surface these when you `await` the task. |
+| `OrderSendAsync`, `OrderCloseAsync`, `OrderModifyAsync`, `OrderCancelAsync` | The same pre-flight errors are thrown; a broker rejection arrives through `OnOrderProgress`, not as an exception. |
+| `Subscribe`, `GetQuote` | `ArgumentException` (unknown symbol), `TimeoutException` (`GetQuote` with a timeout); both connect first if the client is not connected, so they can also throw the `Connect()` errors. |
+| `Symbols.GetInfo`, `Symbols.GetGroup`, `Symbols.GetGroupByName`, `Symbols.GetComission` | `ConnectException` (symbol list not received yet), `ArgumentException` (no such symbol or group) |
+| `GetTickValue`, `GetAskTickValue`, `GetBidTickValue`, `CalculateOrderProfit` | `double.NaN` when unresolved. `GetTickValue` also throws `ArgumentException`/`ConnectException` from the symbol lookup. |
+| `RequiredMargin` | `double.NaN` if the price does not arrive in time; `ArgumentException` if the broker publishes no route between the two currencies |
+| `CalibrateMoneyScale`, `CalculateLots` | Do not throw for a failed measurement: `CalibrateMoneyScale` returns `false` (read `MoneyScaleEvidence`) and `CalculateLots` returns `Ok = false` with a `Reason`. |
+| `DownloadOrderHistory`, `GetAccountSummary`, `CalculateEquityHistory` | `TimeoutException`; plain `Exception` (see below) |
+| `LoadServersDat` | The usual file errors; `NotImplementedException` if the file holds a record type this version does not know |
+| `RequestDemoAccount` | `ConnectException`/`TimeoutException` from the connection; plain `Exception` carrying the broker's refusal status |
+
+## Plain `System.Exception` state errors
+
+These are raised as a plain `System.Exception`, not a typed exception, so you can match them only by type
+`Exception` and message. Treat each as a state error and do not retry blindly.
+
+| Message | Raised by | Meaning |
+|---|---|---|
+| `Not connected` | `Unsubscribe`, `Subscriptions`, `RequestOrderHistory(from, to)`, `DownloadOrderHistory` | The client is not connected. Call `Connect()` first. |
+| `Download Order History Running` | `DownloadOrderHistory`, `RequestOrderHistory` | Another history download is in progress on this client. Wait for it to finish. |
+| `Request Lots = 0` | `OrderClose`, `OrderCancel` (and their async variants) | The volume rounds to zero. |
+| `Previous request still running` | `DownloadQuoteHistoryToday`, `DownloadQuoteHistoryMonth` | A download for that symbol is already in progress. |
+| `Cannot DownloadQuoteHistory in N ms` | `DownloadQuoteHistoryToday`, `DownloadQuoteHistoryMonth` | The bars did not arrive within `DownloadQuoteHistoryTimeout`. |
+| `If timeframe > 60 it should be in whole hours` | `ConvertToTimeframe`, `DownloadQuoteHistory…` | Use a timeframe of 60 minutes or less, or a whole number of hours. |
+
+## Common issues
+
+- **`Connect()` times out (`TimeoutException`)** → the host and port are wrong or unreachable. `ConnectTimeout`
+  bounds the wait. Brokers often publish several access servers — use one that is reachable. The SDK fails
+  over across the broker's cluster members automatically, but only **after** it has reached the initial host;
+  it cannot fail over away from a dead primary, so pick a live one (try the broker's listed alternatives if the
+  first does not answer).
+- **`RateLimited` is a sliding window, not a hard block** → a key has a per-minute request budget, and every
+  `Connect()` (including each automatic reconnect) uses one request. The first calls in a fresh minute
+  succeed; once the budget is used, further calls get `RateLimited` until the window rolls.
+- **History never returns** → use the bounded `DownloadOrderHistory(from, to, timeoutMs, ct)` overload, or
+  leave `DownloadOrderHistoryTimeoutMs` at its default so the call throws `TimeoutException` instead of
+  waiting.
+- **`IsInvestor == true`** → you connected with a read-only (investor) password; trading is not permitted and
+  trading calls throw `InvestorModeException`. Check `IsTradeAllowed` first.
+- **Equity equals balance and profit reads 0** → the open-position quotes are cold. Subscribe the symbols (or
+  call `GetQuote(symbol, timeout)`), then `UpdateProfits()`.
+- **`CalculateLots` returns `Ok = false`, "not calibrated"** → call `CalibrateMoneyScale(from)` first. If that
+  returns `false`, `MoneyScaleEvidence` says why (typically: too few closed deals without swap or
+  commission).

pmt5api/_native/docs/LICENSING.md

@@ -0,0 +1,67 @@
+# Licensing & key management — wmt5api
+
+Applies to wmt5api 3.1.0.
+
+## How authorization works
+
+Every `Connect()` makes a licence request to our hosted **licence service** over HTTPS, authenticated by your
+**API key**. The service checks the key, its validity period, its rate limit and its allowed logins, and
+answers so that the connection can proceed. Your DLL talks to your broker for trading data and to the licence
+service only for this handshake. No key → no connection.
+
+What the licence request carries:
+
+- your **API key**, in the `X-Api-Key` request header;
+- the name and version of the SDK (for example `wmt5api/3.1.0`);
+- your broker login **number**, and the session handshake data your broker's server issued for this
+  connection.
+
+It does **not** carry your broker password, and it carries no trading data. See [Security](SECURITY.md).
+
+## Supplying the key
+
+Provide the key as a **property** or an **environment variable**. The property wins; the environment variable
+is the fallback. Leave the licence service URL at its default.
+
+| What | Property | Environment variable |
+|---|---|---|
+| API key | `api.ApiKey = "wk_…"` | `WMTAPI_KEY` |
+| Licence service URL (optional — leave at its default) | `api.TokenServiceUrl` | `WMTAPI_TOKEN_URL` |
+
+```csharp
+api = new MT5API(user, password, host, port);
+api.ApiKey = Environment.GetEnvironmentVariable("WMTAPI_KEY");   // or set the property directly
+api.Connect();
+```
+
+A key is shown **once**, at issue time. Treat it like a password (see [Security](SECURITY.md)).
+
+## Validity, expiry, renewal
+
+- A licence is valid for your **subscription period**. On renewal it is extended automatically — your existing
+  key keeps working.
+- If the subscription **lapses or is cancelled**, the key stops authorizing new connections: you get a
+  `LicenseException` with `Reason = Revoked` or `Expired`. Open connections are unaffected until they drop; a
+  reconnect (including an automatic one) needs a new licence request.
+
+## Revoking / rotating
+
+- Cancel a subscription in the dashboard → its keys are revoked on the next connect.
+- To rotate a key, issue a new one and update your deployment; revoke the old one.
+
+## Rate limits, allowed logins and the account limit
+
+- Each key has a per-minute request rate. Every `Connect()` — including each automatic reconnect — makes one
+  licence request. Exceeding the rate → `Reason = RateLimited`; back off and retry.
+- A key may be restricted to specific broker logins. Connecting with a login outside that list →
+  `Reason = LoginNotAllowed`.
+- A plan has a maximum number of distinct broker logins. Connecting with a new login beyond that number →
+  `Reason = AccountLimitReached`; connect with an already-enrolled login, or upgrade the plan.
+
+## When the service cannot be reached
+
+A licence request that fails on the network (unreachable, timeout, malformed reply) is retried a few times
+and then throws `TokenServiceException` — that is not a licence decision, so retry rather than prompting for
+a new key. `TokenServiceTimeout` (default 10 000 ms) bounds each request.
+
+See [Errors & troubleshooting](ERRORS.md) for the full failure matrix.

pmt5api/_native/docs/SECURITY.md

@@ -0,0 +1,50 @@
+# Security — wmt5api
+
+Applies to wmt5api 3.1.0.
+
+## Your API key is a secret
+
+Treat your `wk_…` key like a password. Anyone with it can open licensed connections billed to your account.
+
+- **Never commit it** to source control, log it, or embed it in client-side or shipped binaries.
+- Prefer the **`WMTAPI_KEY` environment variable** (or a secret manager) over a hard-coded `ApiKey`.
+- The SDK never writes your key to a log or to disk. It is sent only to the licence service, over HTTPS, in
+  the `X-Api-Key` request header.
+- Rotate the key if you suspect exposure (issue a new one, update your deployment, revoke the old one).
+
+## Broker credentials
+
+- Use an **investor (read-only) password** for read-only integrations — it cannot place trades.
+- Your broker **password** is used only for the handshake with your broker's server. It is never sent to the
+  licence service.
+- Your broker login **number** is sent to the licence service (it is how the licence's allowed-logins list and
+  account limit are enforced), together with the SDK name and version and session handshake data issued by your
+  broker's server.
+
+## Transport
+
+- The licence request is made over **HTTPS**. Leave `TokenServiceUrl` at its default; do not point it at a host
+  you do not trust.
+- The connection to your broker is the MT5 client protocol to the access server you configure (`host`,
+  `port`), optionally through the SOCKS or HTTPS proxy you set with `ProxyEnable`, `ProxyHost` and the related
+  fields.
+
+## What leaves your machine
+
+| To | What | When |
+|---|---|---|
+| Licence service | Your API key; the SDK name and version; your broker login number; non-secret session handshake data issued by your broker's server | Once per `Connect()` (and per automatic reconnect) |
+| Your broker | Your login and password (used in the standard MT5 handshake), and your trading requests | During the session |
+
+The licence service receives **no** broker password and **no** trading data — only the licence handshake.
+
+## Data handling
+
+- `Account` exposes your own account holder details (name and, if your broker returns them, address and
+  contact fields). This is **your** data from **your** broker; handle it per your privacy obligations if you
+  store it.
+- Nothing in the SDK sends data anywhere beyond your broker and the licence handshake.
+
+## Reporting
+
+Security concerns: contact your account representative at mtapi.one.

pmt5api/_risk.py

@@ -0,0 +1,116 @@
+"""Position sizing, margin and P/L arithmetic that the core computes for the account's own conventions."""
+from __future__ import annotations
+
+import math
+from datetime import datetime
+from typing import Optional
+
+from ._base import _Base
+from ._util import enum_value, finite, to_core_time, translated
+from .errors import InvalidRequestError
+from .models import Deal, LotSizing, _opt_float
+
+
+class _RiskMixin(_Base):
+    @translated
+    def calibrate_money_scale(self, start: datetime, *, min_deals_per_symbol: Optional[int] = None,
+                              max_self_scatter: Optional[float] = None, max_disagreement: Optional[float] = None,
+                              max_snap_distance: Optional[float] = None) -> bool:
+        """Measure what a price unit is worth *on this account* from its own closed deals since ``start``.
+
+        Read-only; places no order. Cent handling is a per-broker configuration, not a property of the currency, so
+        sizing is refused until this has succeeded. Returns ``False`` when the scale cannot be established (read
+        :attr:`money_scale_evidence`); more history usually fixes it.
+        """
+        self._require_connected()
+        kwargs = {}
+        if min_deals_per_symbol is not None:
+            kwargs["minDealsPerSymbol"] = int(min_deals_per_symbol)
+        if max_self_scatter is not None:
+            kwargs["maxSelfScatter"] = float(max_self_scatter)
+        if max_disagreement is not None:
+            kwargs["maxDisagreement"] = float(max_disagreement)
+        if max_snap_distance is not None:
+            kwargs["maxSnapDistance"] = float(max_snap_distance)
+        return bool(self._api.CalibrateMoneyScale(to_core_time(self._server_naive(start)), **kwargs))
+
+    @property
+    def money_scale(self) -> Optional[float]:
+        """The measured scale (``None`` until :meth:`calibrate_money_scale` has succeeded)."""
+        return _opt_float(self._api.MoneyScale)
+
+    @property
+    def money_scale_evidence(self) -> str:
+        """Why the scale is what it is, or why it could not be established."""
+        return str(self._api.MoneyScaleEvidence or "")
+
+    @translated
+    def lots_for_risk(self, symbol: str, entry_price: float, stop_price: float, risk_amount: float, *,
+                      lot_step: Optional[float] = None, min_lot: Optional[float] = None,
+                      max_ratio: Optional[float] = None, max_equity_share: Optional[float] = None,
+                      max_lot: Optional[float] = None) -> LotSizing:
+        """The volume that loses ``risk_amount`` (account currency) if ``stop_price`` is hit, with the evidence.
+
+        Requires a successful :meth:`calibrate_money_scale`; without it the answer is a refusal. The volume is
+        rounded **down**. Check ``ok``: when false, ``lots`` is 0 and ``reason`` says which check failed.
+        """
+        self._require_connected()
+        kwargs = {}
+        for key, value in (("lotStep", lot_step), ("minLot", min_lot), ("maxRatio", max_ratio),
+                           ("maxEquityShare", max_equity_share), ("maxLot", max_lot)):
+            if value is not None:
+                kwargs[key] = float(value)
+        result = self._api.CalculateLots(symbol, float(entry_price), float(stop_price), float(risk_amount), **kwargs)
+        return LotSizing._from_core(result)
+
+    @translated
+    def required_margin(self, symbol: str, lots: float, side: str = "buy", price: float = 0.0) -> float:
+        """The margin needed to open ``lots`` of ``symbol``, computed as the terminal does (``price`` 0 = live quote).
+        A reference figure, not a sizing input."""
+        self._require_connected()
+        kind = enum_value(self._core.DealType, "deal" + str(side), "side")
+        value = float(self._api.RequiredMargin(symbol, finite(lots, "lots", positive=True), kind,
+                                               finite(price, "price", non_negative=True)))
+        if math.isnan(value):
+            raise InvalidRequestError("the margin of %s cannot be computed (no quote or conversion rate yet)" % symbol)
+        return value
+
+    @translated
+    def order_profit(self, symbol: str, open_price: float, close_price: float, lots: float, buy: bool = True) -> float:
+        """The P/L, in account currency, of ``lots`` moving from ``open_price`` to ``close_price`` (cent accounts
+        included). For reporting a completed or hypothetical move; use :meth:`lots_for_risk` to size."""
+        self._require_connected()
+        value = float(self._api.CalculateOrderProfit(symbol, finite(open_price, "open_price"),
+                                                     finite(close_price, "close_price"),
+                                                     finite(lots, "lots", positive=True), bool(buy)))
+        if math.isnan(value):
+            raise InvalidRequestError("the profit of %s cannot be computed (no conversion rate yet)" % symbol)
+        return value
+
+    @translated
+    def money_scale_from_deal(self, deal: Deal) -> Optional[float]:
+        """Re-measure the scale from ONE closed deal — the broker's own accounting of a trade that happened. Compare
+        it with :attr:`money_scale`; a disagreement means every size derived from the calibration was wrong."""
+        self._require_connected()
+        core_deal = self._core.Deal()
+        core_deal.Ticket = int(deal.ticket)
+        core_deal.OrderTicket = int(deal.order_ticket)
+        core_deal.PositionTicket = int(deal.position_ticket)
+        core_deal.Symbol = deal.symbol
+        core_deal.Type = enum_value(self._core.DealType, deal.type, "deal type")
+        core_deal.Direction = enum_value(self._core.Direction, deal.direction, "direction")
+        if deal.time is not None:
+            core_deal.Time = to_core_time(deal.time)
+        core_deal.OpenPrice = float(deal.open_price)
+        core_deal.Price = float(deal.price)
+        core_deal.StopLoss = float(deal.stop_loss)
+        core_deal.TakeProfit = float(deal.take_profit)
+        core_deal.Lots = float(deal.lots)
+        core_deal.Profit = float(deal.profit)
+        core_deal.Commission = float(deal.commission)
+        core_deal.Swap = float(deal.swap)
+        core_deal.ContractSize = float(deal.contract_size)
+        core_deal.Digits = int(deal.digits)
+        core_deal.Comment = deal.comment
+        core_deal.ExpertId = int(deal.magic)
+        return _opt_float(self._api.MoneyScaleFromDeal(core_deal))

pmt5api/_runtime.py

@@ -0,0 +1,154 @@
+"""Locates the .NET runtime and the licensed core library and loads them once per process."""
+from __future__ import annotations
+
+import glob
+import importlib
+import os
+import shutil
+import sys
+import threading
+from pathlib import Path
+from typing import Iterator, Optional
+
+from .errors import CoreNotFoundError, RuntimeNotFoundError
+
+#: Environment variable that points at wmt5api.dll.
+ENV_DLL = "WMTAPI_DLL"
+
+_NAMESPACE = "wmt5api"      # the .NET namespace of the core; NOT the name of this Python package
+_PKG = Path(__file__).resolve().parent
+_BUNDLED_RUNTIME = _PKG / "_dotnet"     # present in the platform wheels: host/fxr + shared/Microsoft.NETCore.App
+_lock = threading.Lock()
+_core = None
+_dll: Optional[Path] = None
+
+
+def find_dll(explicit=None) -> Path:
+    """The core library to load: the caller's path, else ``WMTAPI_DLL``, else the one bundled in the wheel.
+
+    A path the caller gave explicitly (argument or environment) is never silently replaced by another: if it does not
+    exist that is an error.
+    """
+    requested = explicit or os.environ.get(ENV_DLL)
+    if requested:
+        path = Path(requested)
+        if path.is_file():
+            return path
+        raise CoreNotFoundError("wmt5api.dll was not found at %s (from %s)" %
+                                (path, "dll_path" if explicit else ENV_DLL))
+    bundled = _PKG / "_native" / "wmt5api.dll"
+    if bundled.is_file():
+        return bundled
+    raise CoreNotFoundError(
+        "wmt5api.dll was not found. Pass dll_path=..., or set the " + ENV_DLL + " environment variable to the DLL "
+        "taken from your wmt5api package, or install a pmt5api wheel that bundles it (looked for " + str(bundled) + ")."
+    )
+
+
+def _dotnet_root_candidates() -> Iterator[Path]:
+    exe = shutil.which("dotnet")
+    if exe:
+        yield Path(exe).resolve().parent
+    home = Path.home()
+    yield home / ".dotnet"
+    for p in ("/usr/share/dotnet", "/usr/lib/dotnet", "/usr/local/share/dotnet", "/opt/dotnet"):
+        yield Path(p)
+    pf = os.environ.get("ProgramFiles")
+    if pf:
+        yield Path(pf) / "dotnet"
+
+
+def _icu_present() -> bool:
+    """True when a system ICU library is installed (the .NET runtime needs one unless globalization is invariant)."""
+    patterns = ("/usr/lib*/libicuuc.so*", "/usr/lib/*-linux-gnu/libicuuc.so*", "/lib*/libicuuc.so*",
+                "/lib/*-linux-gnu/libicuuc.so*", "/usr/local/lib*/libicuuc.so*", "/opt/homebrew/lib/libicuuc*",
+                "/usr/lib/libicuuc*")
+    return any(glob.glob(p) for p in patterns)
+
+
+def _ensure_dotnet_root() -> None:
+    """Point the runtime host at a .NET runtime: the caller's ``DOTNET_ROOT``, else the one bundled in this package,
+    else an installed one. Say so clearly when there is none."""
+    # Without an ICU library the runtime aborts the whole process (uncatchably) at start-up unless globalization is
+    # invariant. The core does not depend on culture-specific behaviour, so on a machine with no ICU ask for invariant
+    # mode — whichever runtime is used, and including a DOTNET_ROOT inherited from a parent process.
+    if sys.platform.startswith("linux") and not _icu_present():
+        os.environ.setdefault("DOTNET_SYSTEM_GLOBALIZATION_INVARIANT", "1")
+    if os.environ.get("DOTNET_ROOT"):
+        return
+    if (_BUNDLED_RUNTIME / "shared" / "Microsoft.NETCore.App").is_dir():
+        os.environ["DOTNET_ROOT"] = str(_BUNDLED_RUNTIME)
+        return
+    for root in _dotnet_root_candidates():
+        if (root / "shared" / "Microsoft.NETCore.App").is_dir():
+            os.environ["DOTNET_ROOT"] = str(root)
+            return
+    raise RuntimeNotFoundError(
+        "No .NET runtime was found. Install the .NET 8 (or later) runtime, or set DOTNET_ROOT to its install directory."
+    )
+
+
+def runtime_root() -> Optional[Path]:
+    """The .NET root in use (after ``load``), or None."""
+    root = os.environ.get("DOTNET_ROOT")
+    return Path(root) if root else None
+
+
+def _has_entry(path_entry: str, name: str) -> bool:
+    base = path_entry or os.getcwd()
+    try:
+        return os.path.isdir(os.path.join(base, name))
+    except OSError:
+        return False
+
+
+def _import_namespace():
+    """Import the core's .NET namespace even if a same-named folder is lying around on sys.path."""
+    mod = sys.modules.get(_NAMESPACE)
+    if mod is not None and hasattr(mod, "MT5API"):
+        return mod
+    sys.modules.pop(_NAMESPACE, None)
+    saved = list(sys.path)
+    try:
+        sys.path[:] = [p for p in sys.path if not _has_entry(p, _NAMESPACE)]
+        importlib.invalidate_caches()
+        mod = importlib.import_module(_NAMESPACE)
+    finally:
+        sys.path[:] = saved
+    if not hasattr(mod, "MT5API"):
+        raise CoreNotFoundError("the loaded library does not expose MT5API; is it the wmt5api package?")
+    return mod
+
+
+def load(dll_path=None):
+    """Load the runtime and the core (idempotent, thread-safe). Returns the core's .NET namespace module."""
+    global _core, _dll
+    with _lock:
+        if _core is not None:
+            if dll_path is not None and _dll is not None and Path(dll_path).resolve() != _dll.resolve():
+                raise CoreNotFoundError(
+                    "a different core is already loaded in this process (%s); one process can use one core, "
+                    "so dll_path=%s was not loaded" % (_dll, dll_path))
+            return _core
+        dll = find_dll(dll_path)
+        _ensure_dotnet_root()
+        try:
+            from pythonnet import load as _load
+            _load("coreclr")
+            import clr  # noqa: F401  (provided by pythonnet)
+        except Exception as e:  # noqa: BLE001 — anything here means the runtime could not start
+            raise RuntimeNotFoundError("could not start the .NET runtime: %s" % e) from e
+        import clr as _clr
+        from System.Reflection import Assembly      # available once the runtime is up
+        try:
+            Assembly.LoadFrom(str(dll))             # AddReference(<absolute path>) fails on pythonnet 3.0.x
+        except Exception as e:  # noqa: BLE001
+            raise CoreNotFoundError("could not load %s: %s" % (dll, e)) from e
+        _clr.AddReference("wmt5api")                # now by name: registers the namespace for `import`
+        _core = _import_namespace()
+        _dll = dll
+        return _core
+
+
+def loaded_dll() -> Optional[Path]:
+    return _dll