pmt4api 1.0.0__py3-none-any.whl

pmt4api/_native/CHANGELOG.md

@@ -0,0 +1,362 @@
+# Changelog — wmt4api
+
+What changed in each release, from the point of view of the code you write. Versions follow semantic
+versioning: a patch release (3.1.x) changes no public API.
+
+## [3.2.0] — 2026-10-12
+Additive release. **No breaking change** — code that builds against 3.1.2 builds unchanged against 3.2.0.
+
+### Added
+- **`GetSymbolNames()`** returns the names of every symbol the broker offers on the account, sorted. Before, a name
+  could only be looked up if you already knew it; brokers add their own suffixes (`EURUSDm`, `XAUUSD.s`), so there was
+  no way to discover them.
+- **`NoServerMessagesTimeout`** (ms, default 30000, 0 disables): the session is declared dead and closed when nothing
+  at all has arrived for that long. A healthy session is never silent for more than a few seconds, so this catches a
+  link that stopped carrying traffic without being closed — which the operating system reports only after many
+  minutes, if at all. The close raises `OnDisconnect` and starts `AutoReconnect`, like any other drop.
+- `GetQuote` now fills in `Time` (the server time of the tick), `High`, `Low` and `Spread`, and returns the symbol's
+  canonical name in `Symbol` whatever case you asked with.
+
+### Fixed
+- **A cached quote could be stale without any sign of it.** The server streams a default set of symbols until you
+  subscribe to something; from then on it streams only what you subscribed. A price cached from the default feed for
+  a symbol you had not subscribed therefore stopped updating, yet `GetQuote`, `GetTickValue` and the equity and
+  margin figures kept using it. They now subscribe the symbol and wait for a tick that arrives afterwards (if none
+  arrives in time — a closed market — the last price held is used, and `Quote.Time` says how old it is). Prices
+  from an earlier session are also discarded on a reconnect.
+- **A position's symbol was subscribed only at connect.** A position that appeared later — one you opened, or one
+  another terminal opened on the account — was priced from whatever the cache held, and once anything was
+  subscribed the server stopped sending it, so its `Order.Profit`, `AccountEquity` and margin figures froze. The
+  symbol is now subscribed as soon as the position exists.
+- **A server that stalled or hung up while the account data was loading** (after the login) was not failed over
+  from, and its socket stayed open until garbage collection. It is now treated like one that cannot be dialled: the
+  next endpoint is tried and the socket is closed.
+- **`Disconnect()` did not abort a connect in flight**: with the primary silent and backups listed, the call
+  carried on dialling them for tens of seconds. It now aborts the handshake, the data load and the remaining
+  candidates. A `Reconnect()` you call yourself after a `Disconnect()` starts a session again (the supervisor
+  still never undoes your `Disconnect()`).
+- **`IsInvestor` was never set**, so an investor (read-only) login was not recognised and the `InvestorModeException`
+  guard never fired (the server's own refusal arrived instead). It is now read from the account record, the field
+  the vendor client reads. (Checked on trading logins; no investor password was available to exercise the true case.)
+- **A transient broker refusal of a reconnect** (a busy server, too many requests) ended `AutoReconnect` for good, as
+  if the password were wrong. Only the refusals waiting cannot cure — client too old, not enough rights, account
+  disabled, invalid account or password — stop it now; the rest are retried with the usual growing delay.
+- `Unsubscribe` of a symbol that has an open position is ignored (the position's profit and the account's equity are
+  priced from that feed), and a symbol you subscribe explicitly waits for a tick that arrives after the request
+  instead of returning what the cache held.
+- `CalculateLots` refused nothing for a NaN or infinite input and returned NaN lots; it now refuses. The rounding
+  down to the step no longer loses a whole step to binary dust (entry 1.1000, stop 1.0950, risk 50 sized to 0.09
+  lots instead of 0.10).
+- `NoServerMessagesTimeout` below 10 s is treated as 10 s: a shorter limit would close a healthy, quiet session.
+- **`Connect()` after a drop or a `Disconnect()`** did not restore the quote subscriptions (`Subscribe` of a name
+  already in the set sent nothing), so quotes did not resume. It now does, and calling `Connect()` on a connected
+  client is a no-op instead of opening a second session.
+- **`Disconnect()` while a reconnect was in flight** could be undone: the reconnect completed, the client reported
+  `Connected` and the session ran on. `Disconnect()` now wins, and what the reconnect had opened is closed.
+- A server that accepted the connection and then said nothing made `Connect()` wait forever; the handshake and the
+  initial data load now give up after 30 s (and the next endpoint is tried).
+- The heartbeat was only sent when something had arrived, so a session whose feed went quiet depended on the server
+  to keep it alive. The client now pings every 4 s on its own clock.
+- The symbol table is replaced in one step on a reconnect, so a quote tick or a call from another thread can no
+  longer see it half rebuilt.
+
+## [3.1.2] — 2026-10-12
+Maintenance release. **No API change** — code that builds against 3.1.1 builds unchanged against 3.1.2.
+
+### Changed
+- The licence notice, the package metadata and the support and key contact lines now name **mtapi.one** as the
+  licensor and the place to contact. The behaviour of the SDK is unchanged.
+
+## [3.1.1] — 2026-10-11
+Maintenance release. **No API change** — code that builds against 3.1.0 builds unchanged against 3.1.1.
+
+### Fixed
+- **`ReconnectMaxAttempts` was not a cap.** After that many failed attempts the watchdog started over, so a
+  permanent failure meant a broker login and a licence request every few seconds, indefinitely. It now stops
+  after `ReconnectMaxAttempts` attempts, stops at once when the licence service or the broker *refuses* the
+  login (an expired or revoked licence, a login not allowed, an account limit, a bad password), and backs off
+  exponentially (the configured delay, doubling up to 60 s) between attempts. `Reconnect()` or `Connect()`
+  resumes self-healing afterwards.
+- A login that the broker accepted but the licence refused no longer leaves its socket open until garbage
+  collection.
+- `Connect()` to an unreachable host or port now throws the documented typed exception: `ConnectException`, or
+  `TimeoutException` when no endpoint answered within `ConnectTimeout`. Before, it threw a plain
+  `System.Exception`, so a mistyped host surfaced as an unhandled error in code that caught the documented types.
+  Both derive from `Exception`, so code that already caught `Exception` is unaffected.
+
+### Changed
+- Internal clean-up of the shipped library. No public type, member or signature changed.
+- The licence request now also carries the SDK name and version (for example `wmt4api/3.1.1`), so the licence
+  service can tell which release is calling. Nothing else is sent in addition (see `docs/SECURITY.md`).
+- The IntelliSense documentation (`wmt4api.xml`) was reworded: no member changed; several summaries were
+  corrected where they described behaviour that no longer applies or promised more than the library does.
+
+### Documentation and samples
+- The guides were rewritten for the 3.x API (`MT4API`, `OrderType`, `OrderCancel`, …): the quick start, API
+  reference, errors, licensing and security pages previously described the 2.x names.
+- `README.md` states the real relationship with the MT5 SDK — the same names, different signatures — with a
+  table of the differences.
+- `README.md` and the guides describe `CalculateLots` as it behaves: what it reads from the account, when it
+  refuses, and that no cent-account conversion is applied.
+- `MIGRATION.md` was corrected: `Order.Type` keeps its name in 3.x (only its type changed, `Op` →
+  `OrderType`); added the `SymbolSpec.Execution` → `ExecutionType` and `OrderDeleteAsync` →
+  `OrderCancelAsync` renames.
+- `connect.cs`, `pnl.cs`, `sizing.cs` and `Sample.cs`: an unreachable host or port now ends with a one-line
+  message instead of an unhandled exception.
+- `docs/ERRORS.md` lists what `Connect()` actually throws, the common MT4 trade-return codes, and the
+  `AccountLimitReached` licence reason.
+
+### Notes
+- `EquityPoint.RealizedPL` is still present and returns the same value as `BalanceChange`. It is obsolete and
+  may be removed in a future major release (earlier builds said 3.0.0; that did not happen). Use
+  `BalanceChange`, or `GetAccountSummary().RealizedProfit` for the trading result.
+- `OrderSend` accepts a `magic` argument but does not transmit it in this release, so `Order.ExpertId` reads 0
+  on orders placed through this client. Use `comment` to tag orders.
+- `AccountMargin`, `AccountFreeMargin` and `AccountMarginLevel` may wait up to `GetQuoteTimeoutMs` the first
+  time a conversion-pair quote has to be fetched; call `UpdateProfits()` after connect to warm them.
+
+## [3.1.0] — 2026-09-11
+Position sizing. Additive — no breaking changes.
+
+### Added
+- **`CalculateLots(symbol, entry, stop, risk, lotStep, minLot, maxRatio, maxEquityShare, maxLot)`** →
+  `LotSizing` — turns a risk budget and a stop price into a volume, rounded **down** to the broker's volume
+  step, and **refuses rather than guessing** when it cannot size safely (`Ok` is `false`, `Lots` is 0 and
+  `Reason` says why). `LotSizing` carries `Ok`, `Lots`, `ExpectedLossAtStop`, `RiskRequested`,
+  `MinimumTradeCost` (what the broker's smallest trade costs at your stop, so you can tell whether the account
+  is big enough for the instrument), `Ratio`, `Reason` and `Warnings`. The MT5 SDK has a `CalculateLots` and a
+  `LotSizing` of the same names.
+- **`GetAskTickValue(Quote)` / `GetBidTickValue(Quote)`** — the direction-aware value of a price unit per lot in
+  the account currency (a SELL sizes against the bid side). The same quantity as `GetTickValue`.
+- **`SymbolSpec.MinLot` / `MaxLot` / `LotStep` / `SecurityIndex`** — the broker's per-symbol volume rules, read
+  from the account's security group; `CalculateLots` uses them automatically (pass an argument to override a
+  specific one).
+- **`sizing.cs`** quick start added to the package.
+
+### Notes
+- Sizing uses `GetTickValue`, which converts through direct, inverse and USD-bridge pairs into the account
+  currency, so there is no calibration step: sizing works as soon as the symbol has a live quote. Amounts are
+  in the currency the account reports; no cent-unit conversion is applied.
+
+## [3.0.0] — 2026-09-11
+A breaking release that renames the MT4 API to use the same names as the MT5 SDK (`wmt5api`). Names and a few
+usage patterns changed; the connection behaviour and every calculation are unchanged. Existing 2.x code must be
+updated — see **`MIGRATION.md`** for the full old → new map.
+
+### Changed (breaking — renamed to match MT5)
+- **Main client class `QuoteClient` → `MT4API`** (as MT5 uses `MT5API`).
+- **Trading is available on the client:** call `OrderSend` / `OrderModify` / `OrderClose` / `OrderCancel` /
+  `OrderCloseBy` / `OrderMultipleCloseBy` (and the `*Async` forms) directly on `MT4API`. The method names match
+  the MT5 SDK; the argument lists differ (see the README). The first call creates the execution client for you;
+  the `OrderClient` property remains for the `OnOrderProgress` event and the awaitable `Order*AsyncTask` forms.
+- **`OrderDelete` → `OrderCancel`** (cancel a pending order), with `OrderDeleteAsync` → `OrderCancelAsync` and
+  `OrderDeleteAsyncTask` → `OrderCancelAsyncTask`.
+- **`GetQuote(symbol, timeout)` now returns a `Quote`** (`.Bid` / `.Ask`, or `null` when there is no quote), not
+  a `(bid, ask)` tuple.
+- **Enum `Op` → `OrderType`**; `Order.Type` keeps its name and now has the type `OrderType`.
+- **`Order.MagicNumber` → `ExpertId`**, **`Order.Expiration` → `ExpirationTime`**.
+- **`AccountInfo.Name` → `UserName`** (the account holder name).
+- **`ConnectTimeoutMs` → `ConnectTimeout`**, **`ServerBuild` → `ServerTradeBuild`**,
+  **`DownloadQuoteHistoryTimeoutMs` → `DownloadQuoteHistoryTimeout`**.
+- **Type renames:** `QuoteEventArgs` → `Quote`, `OrderUpdateEventArgs` → `OrderUpdate`,
+  `OrderProgressEventArgs` → `OrderProgress`, `UpdateAction` → `UpdateType`, `Execution` → `ExecutionType`
+  (and `SymbolSpec.Execution` → `SymbolSpec.ExecutionType`), `ConSymbolGroup` → `SymGroup`.
+
+### Added
+- **`UpdateProfits()`** (parameterless) — warms every open-position symbol so the next account read prices from
+  live ticks. (`UpdateProfits(symbol)` still exists for a single symbol.)
+- **`ApiKey` also reads `WMTAPI_KEY`** when `WMT4API_KEY` is not set.
+- **`Bar.OpenPrice` / `HighPrice` / `LowPrice` / `ClosePrice`** — alternative names for `Open` / `High` / `Low` /
+  `Close` (the names the MT5 SDK uses), over the same values.
+
+### Unchanged (MT4 platform-specific — kept by design)
+- `int` login (MT4 logins are 32-bit), `servers.ini` access (`LoadServersIni` / `SaveServersIni`), the
+  order-centric model (`OrderType.Balance` / `Credit` rows), `OrderCloseBy` / `OrderMultipleCloseBy`,
+  `LoginRejectedException` / `RequoteException` / `TradeTimeoutException`, and `GetSymbolSpec`.
+
+## [2.4.1] — 2026-08-30
+
+### Fixed
+- **`OrderSend` and its siblings now refuse a volume that is not a real volume.** A `NaN`, negative or infinite
+  volume used to be converted to a number and sent — for example an infinite volume, which is what a sizing
+  formula produces when the stop sits on the entry price. Such volumes now throw `ArgumentOutOfRangeException`
+  naming the value received, and nothing is sent. The call refuses rather than clamping, because clamping would
+  turn a programming error into a real order at a size nobody chose.
+  **This is a behaviour change:** code that sent such a volume and got a silent result now gets an exception.
+  `ArgumentOutOfRangeException` derives from `ArgumentException`, so existing `catch` blocks still catch it.
+  Valid volumes are unchanged.
+- **`GetTickValue` and `CalculateOrderProfit` returned `NaN` for CFD and futures symbols on brokers that name
+  their FX pairs with a suffix.** The conversion-pair lookup asked for the bare six-character name (`USDTHB`)
+  where the broker lists the suffixed one (`USDTHBm`). The suffix is now discovered from the broker's own
+  symbol table.
+
+### Documentation
+- `NaN` from `GetTickValue` is explained correctly: the commonest cause is that a **currency conversion**
+  could not be resolved, which can happen even with a live, cached quote — not only a missing quote.
+- `GetTickValue` is described as the raw value per price unit per lot, not as a ready-made sizing recipe.
+
+## [2.4.0] — 2026-08-21
+
+### Added
+- **`GetAccountSummary([from, to])`** → `AccountSummary { Balance, Credit, RealizedProfit, Deposit, Withdrawal }`
+  — the realized account figures a terminal shows in its account-history view, computed from the order ledger.
+  `RealizedProfit` is the cumulative closed-trade P/L (commission and swap included) — the terminal's "Profit",
+  **distinct from `AccountProfit`, which is the FLOATING P/L of the open positions**. `Deposit` / `Withdrawal`
+  are the balance operations (`Op.Balance` rows, by sign). All-time by default; pass a range for a bounded
+  window.
+
+### Deprecated
+- **`EquityPoint.RealizedPL` → `EquityPoint.BalanceChange`.** The old name claimed a trading result; the value
+  is a **balance difference**, so it also contains deposits and withdrawals — on a funded account that had lost
+  money it read as a large profit. The new name says what the number is; for the trading result use
+  `GetAccountSummary().RealizedProfit`.
+  **This is not a breaking change.** `RealizedPL` is still the field and `BalanceChange` reads and writes the
+  same value. Existing source still compiles (with an obsolete warning), and existing compiled programs keep
+  working when the new DLL is dropped in beside them.
+
+### Fixed
+- **The quick starts handle connect failures instead of crashing.** `connect.cs` and `pnl.cs` tested
+  `if (!Connected)` after `Connect()` — a line that can never run, because `Connect()` throws rather than
+  returning a flag. They now catch the typed failures and print one actionable line.
+
+### Documentation
+- **`pnl.cs` no longer reports deposits as profit.** It now shows the realized trading result from
+  `GetAccountSummary`, lists deposits and withdrawals beside it, and prints the identity
+  `balance change = realized trading P/L + deposits + withdrawals`.
+- `EquityPoint.RealizedPL` / `BalanceChange` summaries lead with BALANCE CHANGE and point to
+  `GetAccountSummary` for the trading result.
+- README: every top-level `.cs` is a complete program with its own `Main()`; building several in one project
+  fails with `CS0017`.
+
+## [2.3.2] — 2026-08-16
+
+### Fixed
+- `CalculateEquityHistory` historical `Equity` / `UnrealizedPL`: a position that was open at a step is now
+  priced from the bar **at or before** that step (and contributes 0 floating when no bar covers that time)
+  instead of from the most recent bar, which could price an old position from a far-later quote and produce a
+  wildly wrong, even sign-flipped, figure on deep history. `Balance` / `RealizedPL` are unaffected.
+
+### Documentation
+- The README states that historical `Equity` / `UnrealizedPL` are a reconstruction priced from bars
+  (approximate, bounded by the broker's bar history), while `Balance` / `RealizedPL` come from the order ledger.
+
+## [2.3.1] — 2026-08-15
+
+### Added
+- **`pnl.cs`** quick start: the floating P/L of the open positions next to the realized total since a date and
+  the balance/equity curve, from `CalculateEquityHistory`.
+- README: a section separating the floating P/L (`AccountProfit`) from the realized total, and
+  `CalculateEquityHistory(from[, tf])` in the capability table.
+
+The library itself is unchanged from 2.3.0.
+
+## [2.3.0] — 2026-08-14
+
+### Added
+- **`LoadServersIni` / `SaveServersIni`** — read and write a `servers.ini` file offline (no connection), as
+  `Mt4Server[] { Name, Company, IsDemo, MainHost, (Host, Port)[] Access }`. Use it to discover or persist the
+  brokers and their access servers from a terminal's `servers.ini`.
+- **`connect.cs`** quick start (fill in your login → connects and prints the live account state: balance,
+  equity, floating P/L, margin, free margin, margin level — using the warm-first read pattern so the floating
+  figures aren't read cold as zero) and **`servers.cs`** (list every access server host:port each broker
+  publishes, read offline from a `servers.ini` file — no login needed).
+
+## [2.2.1] — 2026-08-14
+
+### Added
+- **`AccountMarginLevel`** — margin level (percent) = equity / margin × 100, the same ratio the terminal shows;
+  0 when the account is flat (no used margin) or before connect.
+
+### Documentation
+- Documented the warm-first pattern for reading account state (`AccountEquity` / `AccountProfit` /
+  `AccountFreeMargin` / `AccountMarginLevel` reflect the floating P/L of open positions and are computed from
+  cached quotes — warm the open-position symbols before reading), and completed the capability table
+  (`AccountMargin` / `AccountFreeMargin` / `AccountMarginLevel`). `Sample.cs` (`ShowAccount`) warms then prints
+  the full account state.
+
+## [2.2.0] — 2026-08-12
+
+### Added
+- **Account margin** — `AccountMargin`, `AccountFreeMargin`, `AccountLeverage`, `AccountType`. Margin is derived
+  on the client (the server sends only balance and credit), like the terminal: Forex via leverage, CFD via the
+  symbol's margin divider, converted to the account currency.
+- `RequiredMargin(symbol, lots, type, price)` — pre-trade margin estimate.
+- `Unsubscribe(symbol)` / `IsSubscribed(symbol)` — the other half of the quote-subscription lifecycle.
+- `UpdateProfits(symbol)` / `UpdateMargin()` — force-refresh a symbol's cached quote so `AccountEquity` /
+  `AccountProfit` / `AccountMargin` reprice from a current tick.
+- `DownloadOrderHistoryTimeoutMs` (default 30000, 0 = wait indefinitely).
+
+### Fixed
+- **`DownloadOrderHistory(from, to)`** now waits up to `DownloadOrderHistoryTimeoutMs` and throws
+  `TimeoutException` instead of hanging when a broker withholds history; the equity-curve builder inherits the
+  bound.
+
+## [2.1.0] — 2026-07-24
+
+### Added — events and async trading
+All new; no behavioural change to existing calls.
+
+- **Events** (standard .NET shape `(object sender, args)`): `OnQuote` (live ticks; the quote carries
+  `High` / `Low` / `Spread` from the session refresh, plus `GetBid()` / `GetAsk()`), `OnConnect`,
+  `OnDisconnect`, `OnOrderUpdate`, `OnQuoteHistory`, `OnSymbolsUpdate`, and `OnOrderProgress` on `OrderClient`.
+  Library diagnostics stream through the static `Logger.OnMsg` / `OnMsgEx`.
+- **Trading** — `OrderSend` gained an optional trailing `PlacedType` argument (source-compatible; recompile
+  callers that were built against an earlier release); a full **async family**:
+  `Order{Send,Close,Modify,Delete,CloseBy,MultipleCloseBy}Async` return a temp id (the result arrives through the
+  events), plus awaitable `Order*AsyncTask` → `Task<Order>`.
+- **Symbols** — `Groups` lists the broker's configured symbol groups.
+
+## [2.0.3] — 2026-07-19
+
+### Documentation
+Documentation-only release: the quick start, licensing and security pages described the licence key and the
+licence service address incorrectly, which caused connection failures. Corrected. The library and API are
+unchanged from 2.0.2.
+
+## [2.0.2] — 2026-07-16
+
+### Documentation — "Staying connected" (AutoReconnect)
+Documented the built-in resilient-connection feature (no code change): opt-in `AutoReconnect` re-establishes
+a dropped session with **broker server-list failover and symbol re-subscribe**, retrying every
+`ReconnectBackoffMs` (a fixed delay, not exponential) up to `ReconnectMaxAttempts` (0 = until `Disconnect()`).
+You can also drive it yourself with the public `Reconnect()` (re-establish + re-subscribe, returns a bool).
+`Connected` is kept current by a heartbeat (~4–8 s). MT4 has no connect-progress event. The README and Sample
+show both paths and warn against the poll-`Connected`-and-`Connect()` connect-storm pattern.
+
+## [2.0.1] — 2026-07-15
+
+### Fixed — the licence service address now defaults to the hosted service
+`TokenServiceUrl` now defaults to the hosted licence service instead of a local address, so setting **only**
+your `ApiKey` connects out of the box. Previously, if you did not also set the service address, `Connect()`
+failed with a `TokenServiceException` (service unreachable). The `WMT4API_TOKEN_URL` environment variable and
+the `TokenServiceUrl` field still override the default. The Sample now sets `ApiKey` explicitly.
+
+## [2.0.0] — 2026-06-20
+
+### Breaking — dynamic methods now return `double.NaN` instead of `0` when unresolved
+`GetTickValue` and `CalculateOrderProfit` now return `double.NaN` when no live quote has resolved yet
+(previously `0`). This makes the "not yet ready" state unambiguous and distinguishable from a legitimate zero.
+
+**Migration:** if your code tested the return value with `== 0` as an "unresolved" sentinel, switch to
+`double.IsNaN(value)`. If you already guard with `tickValue > 0` (as `Sample.cs` shows), no change is needed —
+`NaN > 0` is `false`.
+
+### Added
+- **`GetTickValue(symbol[, timeout])`** — the account-currency value of a full 1.0 price-unit move per 1.0 lot.
+  It subscribes the symbol and waits for a live quote; the timeout defaults to 5000 ms.
+- `CalculateOrderProfit` is documented as a reporting function: it converts the P/L of a price move into the
+  account currency.
+
+## [1.1.0] — 2026-06-17
+
+### Added
+- **`LoginRejectedException`** (with `Code`) — thrown at `Connect()` when the broker rejects the account number
+  or password, instead of a bare `Exception`, so it can be told apart from a licence failure or an SDK fault.
+- **`LicenseReason.AccountLimitReached`** — a licence can carry a limit on the number of distinct broker logins;
+  connecting a new login beyond it throws `LicenseException` with this reason. Logins already enrolled keep
+  working.
+
+### Documentation
+- `Servers` is documented as a read-only list of `(host, port)` tuples that you mutate, not assign.
+- `ApiKey`, `TokenServiceUrl` and `TokenServiceTimeout` are documented as public fields, not properties.
+- The Quickstart constructor example compiles against the Sample (`user:` rather than `login:`).

pmt4api/_native/THIRD-PARTY-NOTICES.txt

@@ -0,0 +1,7 @@
+THIRD-PARTY NOTICES — wmt4api
+==============================
+
+wmt4api.dll references only the .NET platform (netstandard 2.0). It bundles no third-party library.
+
+It contains an implementation of the LZO1X-compatible decompression format, which it uses to read the
+compressed records a trading server sends.

pmt4api/_native/docs/ERRORS.md

@@ -0,0 +1,136 @@
+# Errors & troubleshooting — wmt4api
+
+Errors are **typed** — catch what you care about. A licence refusal stops the connect before it completes:
+nothing is read from, or traded on, the account. (The broker login handshake has already taken place by then;
+what is refused is the licence, before any account data is loaded.)
+
+The snippets use ordinary local variables you declare yourself: `api` (an `MT4API`), `symbol`, `lots`,
+`slippage`, `from` and `to`.
+
+```csharp
+try
+{
+    api.Connect();
+    Quote tick = api.GetQuote(symbol, 5000);
+    api.OrderSend(symbol, OrderType.Buy, lots, tick.Ask, slippage);
+}
+catch (LicenseException ex)            { /* licence refused — inspect ex.Reason */ }
+catch (TokenServiceException ex)       { /* licence service unreachable or timed out — retry */ }
+catch (LoginRejectedException ex)      { /* the broker rejected the login — ex.Code; bad account number or password */ }
+catch (RequoteException ex)            { /* price moved — ex.Bid / ex.Ask are the new prices; re-quote and resend */ }
+catch (TradeTimeoutException ex)       { /* no trade reply in time — reconcile with GetOpenedOrders before resending */ }
+catch (InvestorModeException ex)       { /* a read-only (investor) login cannot trade */ }
+catch (TimeoutException ex)            { /* no endpoint answered within ConnectTimeout — check the host and port */ }
+catch (ConnectException ex)            { /* no endpoint could be reached, or the connection dropped while a trade was in flight */ }
+catch (ServerException ex)             { /* the broker rejected the trade — ex.Code is the MT4 trade-return code */ }
+catch (ArgumentOutOfRangeException ex) { /* the volume is not a real volume — nothing was sent */ }
+catch (Exception ex)                   { /* anything else */ }
+```
+
+`Connect()` throws the typed licence/service exception **directly** (it is not wrapped in an
+`AggregateException`).
+
+## LicenseException — the licence service refused
+`ex.Reason` is a `LicenseReason`. `ex.ServerError` and `ex.HttpStatus` carry the service's raw answer for support.
+
+| Reason | Meaning | What to do |
+|---|---|---|
+| `NoKey` | No API key supplied | Set `ApiKey` or the `WMT4API_KEY` environment variable (`WMTAPI_KEY` is also read) |
+| `Invalid` | Key not recognised | Check the key; use it exactly as issued |
+| `Expired` | Licence period ended | Renew the subscription |
+| `Revoked` | Subscription cancelled / key revoked | Re-subscribe or ask for a new key |
+| `RateLimited` | Too many requests this minute | Back off and retry; reuse a connection instead of reconnecting |
+| `LoginNotAllowed` | This login isn't on the key's allowed-logins list | Use an allowed login, or ask for the list to be widened |
+| `AccountLimitReached` | The licence already has its maximum number of distinct broker logins enrolled and this is a new one | Connect with an already-enrolled login, or upgrade the plan |
+| `Unknown` | The service refused for a reason the client did not recognise | Inspect `ex.ServerError` / `ex.HttpStatus`, then retry or contact support |
+
+## TokenServiceException — infrastructure, not a licence decision
+The licence service was unreachable, timed out (`TokenServiceTimeout`, default 10000 ms) or returned an unusable
+reply. The client already retries a failed contact up to three times before throwing. **Retry later**, and check
+your network access to the licence service — do **not** re-prompt the user for a key.
+
+## LoginRejectedException — the broker refused the login
+Thrown at `Connect()` when the **broker's access server** rejects the login: a wrong account number or
+password, a disabled/expired login, or an authorization refusal. `ex.Code` is the non-zero status the server
+returned (a wrong account number or password is typically reported as 65). This is distinct from a licence
+failure (`LicenseException`) and from the licence service being down (`TokenServiceException`). It is **not**
+an SDK fault — fix the broker credentials. The broker login is checked first, so with both a wrong password
+and a bad key you see this exception first. (A credential rejection is not a dial failure, so it does **not**
+fail over across `Servers`.)
+
+## An unreachable host
+When no endpoint can be dialled, `Connect()` throws a **`ConnectException`** whose message names how many
+endpoints were tried and the last error (for example `cannot connect: all 1 endpoint(s) failed; last: Connection
+refused`). When the last attempt timed out instead (no answer within `ConnectTimeout`) it throws a
+**`TimeoutException`**, with the timeout as its `InnerException`. Neither is a licence or login problem: check
+the host and port. A host that answered but rejected the login is a `LoginRejectedException`.
+
+## Trade-time exceptions
+- **`ServerException`** — the broker rejected the trade. `ex.Code` is the MT4 trade-return code; branch on it to
+  decide whether to retry, resize, or surface the failure. Common codes (the standard MetaTrader 4 trade error
+  numbers; your broker may use others):
+
+  | Code | Meaning |
+  |---|---|
+  | 3 | Invalid trade parameters |
+  | 128 | Trade timeout |
+  | 129 | Invalid price |
+  | 130 | Invalid stops (stop-loss / take-profit too close or on the wrong side) |
+  | 131 | Invalid volume |
+  | 132 | Market is closed |
+  | 133 | Trade is disabled (for the symbol or the account) |
+  | 134 | Not enough money |
+  | 135 | Price changed |
+  | 136 | Off quotes |
+  | 137 | Broker is busy |
+  | 141 | Too many requests |
+  | 145 | Modification denied (too close to the market) |
+  | 146 | Trade context busy |
+  | 147 | Expiration denied by the broker |
+  | 148 | Too many open and pending orders |
+
+- **`RequoteException`** — an instant-execution price moved before the fill. `ex.Bid` / `ex.Ask` carry the new
+  prices the server is offering: re-quote and resend.
+- **`TradeTimeoutException`** — no reply arrived within `OrderClient.TradeTimeout` (default 30 s). The outcome is
+  unknown; reconcile against `GetOpenedOrders` before blindly resending.
+- **`InvestorModeException`** — you connected with a read-only (investor) password; trading is rejected before
+  any request leaves the client. Use a trading password.
+- **`ConnectException`** — the session dropped while a trade was in flight. The outcome is unknown; reconnect and
+  reconcile.
+- **`ArgumentOutOfRangeException`** (an `ArgumentException`) — the `volume` was `NaN`, infinite or not greater
+  than zero. Nothing is sent. Check the arithmetic that produced it: a stop on the entry price, or a `NaN` tick
+  value, makes a division non-finite.
+
+## Other exceptions
+- **`TimeoutException`** — `DownloadOrderHistory` or `DownloadQuoteHistory` did not complete in time
+  (`DownloadOrderHistoryTimeoutMs`, `DownloadQuoteHistoryTimeout`).
+- **`OperationCanceledException`** — the `CancellationToken` you passed to `DownloadOrderHistory` was cancelled.
+- **`InvalidOperationException`** — a quote-history request for the same symbol and timeframe is already in
+  flight.
+
+## Common issues
+- **`Connect()` fails to reach the broker** → the host:port is wrong or unreachable. `ConnectTimeout` bounds each
+  attempt. Brokers often publish several access servers: the client fails over across `Servers` (and, on a
+  reconnect, the list the broker published at the earlier connect) when a host cannot be **dialled** (refused or
+  timed out). A handshake or login
+  rejection is not a dial failure and does not fail over, so bad credentials are not retried across hosts. Add
+  known alternates with `api.Servers.Add(("alt.broker.example", 443));` — `Servers` is a **read-only list of
+  `(string host, int port)` tuples you mutate**.
+- **`RateLimited`** → a key has a per-minute allowance of licence requests. Every `Connect()`, every
+  `Reconnect()` attempt and every `DownloadOrderHistory` call (which opens its own short-lived broker
+  connection) is one request. Once the allowance is used further requests are refused until the minute rolls
+  over. Reuse one connection; do not poll-and-reconnect in a tight loop.
+- **History is slow or times out** → `DownloadOrderHistory(from, to)` waits up to
+  `DownloadOrderHistoryTimeoutMs` (default 30 s) and then throws `TimeoutException`. Use the
+  `DownloadOrderHistory(from, to, timeoutMs, ct)` overload for a per-call timeout and cancellation, and narrow
+  the date range.
+- **A quote never arrives** → `GetQuote(symbol, timeoutMs)` subscribes and waits; it returns `null` if the
+  symbol is unknown or no tick arrived in time. Symbol names are matched case-insensitively but must include
+  your broker's suffix (for example `EURUSDm`). Outside market hours there may be no tick.
+- **`GetTickValue` or `CalculateOrderProfit` returns `NaN`** → the value could not be resolved — usually a
+  currency conversion, not a missing quote. Test with `double.IsNaN()`; `CalculateLots` refuses in this case
+  and says so in `Reason`.
+- **`IsInvestor == true`** → you connected with a read-only (investor) password; trading is not permitted (a
+  trade throws `InvestorModeException`).
+- **Using the client before `Connect()` succeeds** is not supported — trading, history and quote calls need a
+  live session.

pmt4api/_native/docs/LICENSING.md

@@ -0,0 +1,55 @@
+# Licensing & key management — wmt4api
+
+## How authorization works
+Every connection is authorised by our hosted **licence service**, gated by your **API key**. That happens on each
+connect: the initial `Connect()`, every `Reconnect()` attempt (including the automatic ones), and the short-lived
+broker connection that each `DownloadOrderHistory` call opens. Your DLL talks to your broker for trading data and
+to the licence service only for this authorisation. No key → no connection. What is sent is listed in
+[Security](SECURITY.md).
+
+## Supplying the key
+You supply **only your API key** — as a **field** on the `MT4API` or as an **environment variable**. The field
+is initialised from the environment variable when the client is created, and assigning it overrides the
+variable. `ApiKey`, `TokenServiceUrl` and `TokenServiceTimeout` are plain public fields — assign them directly.
+
+| What | Field | Environment variable |
+|---|---|---|
+| API key | `api.ApiKey = "…"` | `WMT4API_KEY` (`WMTAPI_KEY` is read when it is not set) |
+| Licence service address | `api.TokenServiceUrl` | `WMT4API_TOKEN_URL` |
+| Licence request timeout | `api.TokenServiceTimeout` (ms, default 10000) | — |
+
+```csharp
+api = new MT4API(user, password, host, port);
+api.ApiKey = Environment.GetEnvironmentVariable("WMT4API_KEY") ?? apiKey;   // or assign the field directly
+api.Connect();                                                              // the service address defaults to the hosted service
+```
+
+`TokenServiceUrl` already defaults to our hosted licence service — **leave it unchanged** unless support asks
+you to change it. Keep your key out of source control and out of shipped binaries (see [Security](SECURITY.md)).
+
+## Validity, expiry, renewal
+- A licence is valid for your **subscription period**. When the period ends, or the subscription is cancelled,
+  the key stops authorising new connections and `Connect()` throws `LicenseException` with `Reason = Expired` or
+  `Revoked`. Once the licence is renewed, the next connect succeeds.
+- Connections that are already open are unaffected until they drop; a reconnect needs a valid licence.
+
+## Revoking and rotating
+- Cancelling a subscription revokes its key: the next connect is refused with `Reason = Revoked`.
+- To rotate a key, ask for a new one, update your deployment, and have the old one revoked.
+
+## Rate limits, allowed logins and account limits
+- Each key has a per-minute allowance of licence requests; every connect, reconnect attempt and history
+  download is one request. Exceeding it → `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 licence may carry a limit on the number of **distinct broker logins** it can be used with. When that limit is
+  reached, a new login is refused with `Reason = AccountLimitReached`; logins already enrolled keep working.
+
+## Network access
+From the machine that runs your program you need:
+
+- outbound **TCP** to your broker's MT4 access servers (the host and port you pass to `MT4API`, plus any
+  `Servers` you add and the access servers the broker publishes at connect); and
+- outbound **HTTPS (port 443)** to the licence service (`https://auth4.mtapi.one` by default).
+
+See [Errors & troubleshooting](ERRORS.md) for the full failure matrix.

pmt4api/_native/docs/SECURITY.md

@@ -0,0 +1,38 @@
+# Security — wmt4api
+
+## Your API key is a secret
+Treat your API 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 **`WMT4API_KEY` environment variable** (or a secret manager) over a hard-coded `ApiKey`.
+- The SDK does not write your key to its log output 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 (ask for a new one, update your deployment, have the old one revoked).
+
+## Broker credentials
+- Use an **investor (read-only) password** for read-only integrations — it cannot place trades: any trading
+  call throws `InvestorModeException` before a request is sent.
+- Your broker login and password are used only to log in to your broker's access server, as a terminal does.
+  The password is never sent to the licence service.
+
+## Transport
+- The licence request uses **HTTPS** to our hosted licence service. `TokenServiceUrl` defaults to it; leave it
+  unchanged, and never point it at a host you do not trust — it receives your API key.
+- The connection to your broker is the MT4 access-server protocol, exactly as a terminal makes it.
+
+## What leaves your machine
+| To | What | When |
+|---|---|---|
+| Licence service | Your API key (`X-Api-Key` header); the SDK name and version (`X-Wmt-Sdk` header); your broker login **number**; the broker server's build number; the connection-handshake data from your broker's server | each connect, reconnect attempt and history download |
+| Your broker | Login and password (as the standard MT4 login), and your own requests: quotes, history, trades | during the session |
+
+The licence service receives **no** broker password and **no** trading data — no orders, positions, balances,
+quotes or history. Nothing else in the SDK sends data anywhere: no telemetry, no crash reports.
+
+## Data handling
+- `Account` exposes your own account details (holder name, broker company, group, balance and credit,
+  currency). This is **your** data from **your** broker; handle it per your privacy obligations if you store it.
+- `LoadServersIni` reads only the file you name; `SaveServersIni` returns bytes and writes nothing.
+
+## Reporting
+Security concerns: contact your account representative at mtapi.one.