PythonMetaTrader5 2.3.2__py3-none-any.whl → 3.0.1__py3-none-any.whl

PythonMetaTrader5/application/execution.py

@@ -0,0 +1,108 @@
+"""Sending a request with a bounded, outcome-aware retry loop."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from dataclasses import dataclass, replace
+
+from PythonMetaTrader5.application.ports import Clock, Terminal
+from PythonMetaTrader5.domain.errors import ErrorKind, TradeError
+from PythonMetaTrader5.domain.market import TradeReceipt
+from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest
+from PythonMetaTrader5.domain.retcodes import DONE, DONE_PARTIAL, Outcome, classify, error_for
+from PythonMetaTrader5.result import Err, Ok, Result
+
+log = logging.getLogger("PythonMetaTrader5")
+
+RequestFactory = Callable[[], Result[OrderRequest | CancelRequest, TradeError]]
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    attempts: int = 3
+    delay_seconds: float = 0.5
+
+    def __post_init__(self) -> None:
+        # Misconfiguration is a programming error, not a market outcome, so it
+        # fails loudly at construction instead of travelling as a Result.
+        if self.attempts < 1 or self.delay_seconds < 0:
+            raise ValueError(f"invalid retry policy: {self}")
+
+
+def execute(
+    terminal: Terminal, clock: Clock, build: RequestFactory, policy: RetryPolicy
+) -> Result[TradeReceipt, TradeError]:
+    """Rebuild and send the request until it succeeds, fails, or attempts run out.
+
+    The request is rebuilt on every attempt so a requote is answered with the
+    current price instead of re-sending the stale one.
+    """
+    last: TradeReceipt | None = None
+    for attempt in range(1, policy.attempts + 1):
+        request = build()
+        if isinstance(request, Err):
+            # Nothing was sent, so waiting is safe; a symbol just added to Market
+            # Watch typically has no quote for the first few hundred milliseconds.
+            if request.error.kind is ErrorKind.NO_PRICE and attempt < policy.attempts:
+                clock.sleep(policy.delay_seconds)
+                continue
+            return request
+        sent = terminal.send(request.value)
+        if isinstance(sent, Err):
+            return sent
+        last = sent.value
+        outcome = classify(last.retcode)
+        if outcome is Outcome.SUCCESS:
+            return _confirm(request.value, last)
+        if outcome is Outcome.FAIL:
+            return Err(replace(error_for(last.retcode), receipt=last))
+        log.warning("retcode %s on attempt %s/%s", last.retcode, attempt, policy.attempts)
+        if attempt < policy.attempts:
+            clock.sleep(policy.delay_seconds)
+    if last is None:  # pragma: no cover - range(1, attempts + 1) is never empty
+        raise AssertionError("retry loop ran zero times")
+    return Err(
+        TradeError(
+            ErrorKind.RETRIES_EXHAUSTED,
+            f"gave up after {policy.attempts} attempts: {error_for(last.retcode).message}",
+            retcode=last.retcode,
+            receipt=last,
+        )
+    )
+
+
+def _confirm(
+    request: OrderRequest | CancelRequest, receipt: TradeReceipt
+) -> Result[TradeReceipt, TradeError]:
+    """Only DONE proves a market deal (entry or close) executed in full.
+
+    PARTIAL leaves volume unfilled (an entry is smaller than asked, a close leaves
+    a remainder open) and PLACED means queued, not executed. Both come back as
+    errors carrying the receipt, and neither is retried: part of the deal may
+    already exist, so re-sending could double it.
+    """
+    if (
+        not isinstance(request, OrderRequest)
+        or request.pending is not None
+        or receipt.retcode == DONE
+    ):
+        return Ok(receipt)
+    if receipt.retcode == DONE_PARTIAL:
+        return Err(
+            TradeError(
+                ErrorKind.PARTIAL_FILL,
+                f"executed {receipt.volume} of {request.volume} lots; with RETURN "
+                "filling the rest may still be working as an order",
+                retcode=receipt.retcode,
+                receipt=receipt,
+            )
+        )
+    return Err(
+        TradeError(
+            ErrorKind.OUTCOME_UNKNOWN,
+            "accepted but not executed yet; check positions before re-sending",
+            retcode=receipt.retcode,
+            receipt=receipt,
+        )
+    )

PythonMetaTrader5/application/magic_scope.py

@@ -0,0 +1,75 @@
+"""Which magic a close-all / cancel-all acts on when the caller gives none (ADR 0011).
+
+Kept apart from Trader: the rule and the warnings it owes are one decision,
+and they would otherwise push trader.py past the file-length limit.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from typing import TypeVar
+
+from PythonMetaTrader5.domain.errors import TradeError
+from PythonMetaTrader5.domain.inputs import ANY_MAGIC, AnyMagic, magic_filter
+from PythonMetaTrader5.result import Ok, Result
+
+log = logging.getLogger("PythonMetaTrader5")
+_T = TypeVar("_T")
+
+
+def resolve(
+    own: int, magic: int | AnyMagic | None, ticket: int | None
+) -> Result[int | AnyMagic, TradeError]:
+    """The magic to filter by: the caller's, else the trader's own."""
+    checked = magic_filter(magic)
+    if not isinstance(checked, Ok):
+        return checked
+    if checked.value is not None:
+        return Ok(checked.value)
+    # A named ticket is explicit intent: filtering it out by magic would
+    # report Ok([]) for a position the caller asked to close.
+    return Ok(ANY_MAGIC if ticket is not None else own)
+
+
+def warn_about_default(
+    own: int,
+    magic: object,
+    ticket: int | None,
+    matched: list[_T],
+    everything: Callable[[], Result[list[_T], TradeError]],
+) -> None:
+    """Say what the own-magic default cannot know; quiet once a magic is given."""
+    if magic is not None or ticket is not None:
+        return
+    if matched:
+        if own == 0:
+            # magic 0 stays allowed (it is the connect() default), but then
+            # "own" includes every manual trade.
+            log.warning(
+                "trader magic is 0, which manual trades share: this close/cancel "
+                "includes them; set magic at connect(), or pass magic=0 to confirm"
+            )
+        return
+    # Matched nothing: on netting the bot's deal may have merged into a position
+    # that kept another magic, and Ok([]) alone would read as "flat". The extra
+    # listing runs only on this path.
+    others = everything()
+    if not isinstance(others, Ok):
+        # Not turned into an Err: the close/cancel itself did what was asked,
+        # and failing it would make a bot retry an action that already ran.
+        log.warning(
+            "nothing with magic %s to close/cancel, and could not check for items "
+            "with other magics left open: %s",
+            own,
+            others.error,
+        )
+        return
+    if others.value:
+        log.warning(
+            "nothing with magic %s to close/cancel; %d item(s) with other magics "
+            "left open (on netting a deal merges into a position that keeps its "
+            "first magic); pass magic=ANY_MAGIC to include them",
+            own,
+            len(others.value),
+        )

PythonMetaTrader5/application/ports.py

@@ -0,0 +1,75 @@
+"""The only two process boundaries of the library: the MT5 terminal and time."""
+
+from __future__ import annotations
+
+import operator
+from dataclasses import dataclass, field
+from typing import Protocol
+
+from PythonMetaTrader5.domain.errors import TradeError
+from PythonMetaTrader5.domain.market import PendingOrder, Position, Tick, TradeReceipt
+from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest
+from PythonMetaTrader5.domain.symbol import SymbolSpec
+from PythonMetaTrader5.result import Result
+
+
+@dataclass(frozen=True, slots=True)
+class Credentials:
+    login: int
+    # repr=False keeps the password out of logs, tracebacks and debugger dumps.
+    password: str = field(repr=False)
+    server: str
+    path: str | None = None
+    timeout_ms: int = 60_000
+
+    def __post_init__(self) -> None:
+        # The type itself enforces the login rule, so no construction path can
+        # hand MT5 True or a float that it would turn into another account.
+        if parse_login(self.login) != self.login:
+            raise ValueError(f"login must be a positive integer, got {self.login!r}")
+
+
+def parse_login(login: object) -> int | None:
+    """Account number from an int-like value or an ASCII digit string, else None.
+
+    int() is deliberately avoided: int(True) == 1 and int(12345678.9) == 12345678
+    would log into another account without any error, and int() accepts
+    non-ASCII digits such as "\u0661\u0662\u0663".
+    """
+    if isinstance(login, bool):
+        return None
+    if isinstance(login, str):
+        text = login.strip()
+        number = int(text) if text.isascii() and text.isdecimal() else 0
+    else:
+        try:
+            number = operator.index(login)  # type: ignore[arg-type]
+        except TypeError:
+            return None
+    return number if number > 0 else None
+
+
+class Terminal(Protocol):
+    def connect(self, credentials: Credentials) -> Result[None, TradeError]: ...
+
+    def shutdown(self) -> None: ...
+
+    def symbol(self, name: str) -> Result[SymbolSpec, TradeError]: ...
+
+    def tick(self, name: str) -> Result[Tick, TradeError]: ...
+
+    def send(self, request: OrderRequest | CancelRequest) -> Result[TradeReceipt, TradeError]:
+        """Err only when the request could not be delivered; broker refusals are receipts."""
+        ...
+
+    def positions(
+        self, *, symbol: str | None = None, ticket: int | None = None
+    ) -> Result[list[Position], TradeError]: ...
+
+    def pending_orders(
+        self, *, symbol: str | None = None
+    ) -> Result[list[PendingOrder], TradeError]: ...
+
+
+class Clock(Protocol):
+    def sleep(self, seconds: float) -> None: ...

PythonMetaTrader5/application/trader.py

@@ -0,0 +1,275 @@
+"""Trading use cases: open, close, place and cancel orders, query state."""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from types import TracebackType
+
+from PythonMetaTrader5.application import magic_scope
+from PythonMetaTrader5.application.batch import BatchFailure, run_batch, with_magic
+from PythonMetaTrader5.application.entries import StopInput, validate_entry
+from PythonMetaTrader5.application.execution import RetryPolicy, execute
+from PythonMetaTrader5.application.ports import Clock, Terminal
+from PythonMetaTrader5.domain.errors import TradeError
+from PythonMetaTrader5.domain.inputs import (
+    ANY_MAGIC,
+    AnyMagic,
+    magic_filter,
+    own_magic,
+    symbol_filter,
+    ticket_filter,
+)
+from PythonMetaTrader5.domain.market import PendingKind, PendingOrder, Position, TradeReceipt
+from PythonMetaTrader5.domain.orders import Side, validate_comment
+from PythonMetaTrader5.domain.requests import CancelRequest, OrderRequest
+from PythonMetaTrader5.domain.symbol import SymbolSpec
+from PythonMetaTrader5.result import Err, Ok, Result
+
+
+class Trader:
+    def __init__(
+        self,
+        terminal: Terminal,
+        clock: Clock,
+        *,
+        magic: int = 0,
+        deviation: int = 10,
+        retry: RetryPolicy | None = None,
+    ) -> None:
+        self._terminal = terminal
+        self._clock = clock
+        own = own_magic(magic)
+        if isinstance(own, Err):
+            # A constructor cannot return a Result; connect() reports this as Err.
+            raise ValueError(own.error.message)
+        self._magic = own.value
+        self._deviation = deviation
+        self._retry = retry or RetryPolicy()
+
+    # ------------------------------------------------------------------ entries
+
+    def open_position(
+        self,
+        symbol: str,
+        side: Side | str,
+        volume: float,
+        *,
+        sl: StopInput = None,
+        tp: StopInput = None,
+        price: float | None = None,
+        comment: str | None = None,
+    ) -> Result[TradeReceipt, TradeError]:
+        """Open a market position; ``sl``/``tp`` floats are prices, ``Stop.points`` distances.
+
+        Without ``price`` the current quote is used and requotes are retried with a
+        fresh quote. An explicit ``price`` is sent once: re-sending the same price
+        after a requote cannot succeed.
+        """
+        entry = validate_entry(
+            self._terminal, symbol, side, volume, comment=comment, sl=sl, tp=tp, price=price
+        )
+        if isinstance(entry, Err):
+            return entry
+        e = entry.value
+
+        def build() -> Result[OrderRequest | CancelRequest, TradeError]:
+            quote = None
+            if e.price is None:
+                tick = self._terminal.tick(symbol)
+                if isinstance(tick, Err):
+                    return tick
+                quote = tick.value.entry_price(e.side)
+            return e.request(quote, pending=None, deviation=self._deviation, magic=self._magic)
+
+        policy = self._retry if e.price is None else replace(self._retry, attempts=1)
+        return execute(self._terminal, self._clock, build, policy)
+
+    def place_limit_order(
+        self,
+        symbol: str,
+        side: Side | str,
+        volume: float,
+        price: float,
+        *,
+        sl: StopInput = None,
+        tp: StopInput = None,
+        comment: str | None = None,
+    ) -> Result[TradeReceipt, TradeError]:
+        """Place a BUY/SELL LIMIT at ``price``; point stops are measured from that level.
+
+        A limit on the wrong side of the market is refused by the server
+        (INVALID_PRICE) rather than converted into a market order.
+        """
+        entry = validate_entry(
+            self._terminal,
+            symbol,
+            side,
+            volume,
+            comment=comment,
+            sl=sl,
+            tp=tp,
+            price=price,
+            price_required=True,
+        )
+        if isinstance(entry, Err):
+            return entry
+        request = entry.value.request(
+            pending=PendingKind.LIMIT, deviation=self._deviation, magic=self._magic
+        )
+        if isinstance(request, Err):
+            return request
+        return execute(self._terminal, self._clock, lambda: request, self._retry)
+
+    # ------------------------------------------------------------------- exits
+
+    def close_positions(
+        self,
+        symbol: str | None = None,
+        *,
+        ticket: int | None = None,
+        magic: int | AnyMagic | None = None,
+        comment: str | None = None,
+    ) -> Result[list[TradeReceipt], BatchFailure]:
+        """Close matching positions; ``ticket`` takes precedence over ``symbol``.
+
+        Only the trader's own ``magic`` unless another ``magic`` is given;
+        ``magic=ANY_MAGIC`` closes every position, manual ones included. A
+        ``ticket`` is closed whatever its magic.
+        """
+        text = validate_comment(comment)
+        if isinstance(text, Err):
+            return Err(BatchFailure((), (text.error,)))
+        own = magic_scope.resolve(self._magic, magic, ticket)
+        if isinstance(own, Err):
+            return Err(BatchFailure((), (own.error,)))
+        listed = self.positions(
+            None if ticket is not None else symbol, ticket=ticket, magic=own.value
+        )
+        if isinstance(listed, Err):
+            return Err(BatchFailure((), (listed.error,)))
+        scope = None if ticket is not None else symbol
+        magic_scope.warn_about_default(
+            self._magic, magic, ticket, listed.value, lambda: self.positions(scope, magic=ANY_MAGIC)
+        )
+        # One spec lookup per symbol, not per position: close-all is time-critical.
+        specs: dict[str, Result[SymbolSpec, TradeError]] = {}
+
+        def close(position: Position) -> Result[TradeReceipt, TradeError]:
+            if position.symbol not in specs:
+                specs[position.symbol] = self._terminal.symbol(position.symbol)
+            return self._close_one(position, specs[position.symbol], text.value)
+
+        return run_batch(listed.value, close)
+
+    def cancel_pending_orders(
+        self,
+        symbol: str | None = None,
+        *,
+        magic: int | AnyMagic | None = None,
+        kind: PendingKind | None = None,
+    ) -> Result[list[TradeReceipt], BatchFailure]:
+        """Cancel matching pending orders of the trader's own ``magic`` by default.
+
+        ``magic=ANY_MAGIC`` cancels every order on the account, manual ones included.
+        """
+        own = magic_scope.resolve(self._magic, magic, None)
+        if isinstance(own, Err):
+            return Err(BatchFailure((), (own.error,)))
+        listed = self.pending_orders(symbol, magic=own.value, kind=kind)
+        if isinstance(listed, Err):
+            return Err(BatchFailure((), (listed.error,)))
+        magic_scope.warn_about_default(
+            self._magic,
+            magic,
+            None,
+            listed.value,
+            lambda: self.pending_orders(symbol, magic=ANY_MAGIC, kind=kind),
+        )
+        return run_batch(listed.value, self._cancel_one)
+
+    # ----------------------------------------------------------------- queries
+
+    def positions(
+        self,
+        symbol: str | None = None,
+        *,
+        ticket: int | None = None,
+        magic: int | AnyMagic | None = None,
+    ) -> Result[list[Position], TradeError]:
+        """Every position by default: a read never needs the own-magic guard."""
+        checked = magic_filter(magic)
+        if isinstance(checked, Err):
+            return checked
+        for check in (symbol_filter(symbol), ticket_filter(ticket)):
+            if isinstance(check, Err):
+                return check
+        listed = self._terminal.positions(symbol=symbol, ticket=ticket)
+        if isinstance(listed, Err):
+            return listed
+        return Ok(with_magic(listed.value, checked.value))
+
+    def pending_orders(
+        self,
+        symbol: str | None = None,
+        *,
+        magic: int | AnyMagic | None = None,
+        kind: PendingKind | None = None,
+    ) -> Result[list[PendingOrder], TradeError]:
+        checked = magic_filter(magic)
+        if isinstance(checked, Err):
+            return checked
+        symbol_checked = symbol_filter(symbol)
+        if isinstance(symbol_checked, Err):
+            return symbol_checked
+        listed = self._terminal.pending_orders(symbol=symbol)
+        if isinstance(listed, Err):
+            return listed
+        orders = with_magic(listed.value, checked.value)
+        return Ok(orders if kind is None else [o for o in orders if o.kind is kind])
+
+    def shutdown(self) -> None:
+        self._terminal.shutdown()
+
+    def __enter__(self) -> Trader:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.shutdown()
+
+    # ----------------------------------------------------------------- helpers
+
+    def _close_one(
+        self, position: Position, spec: Result[SymbolSpec, TradeError], comment: str
+    ) -> Result[TradeReceipt, TradeError]:
+        if isinstance(spec, Err):
+            return spec
+        filling = spec.value.market_filling()
+
+        def build() -> Result[OrderRequest | CancelRequest, TradeError]:
+            tick = self._terminal.tick(position.symbol)
+            if isinstance(tick, Err):
+                return tick
+            return Ok(
+                OrderRequest(
+                    symbol=position.symbol,
+                    side=position.side.opposite,
+                    volume=position.volume,
+                    price=tick.value.exit_price(position.side),
+                    filling=filling,
+                    deviation=self._deviation,
+                    magic=self._magic,
+                    comment=comment,
+                    position=position.ticket,
+                )
+            )
+
+        return execute(self._terminal, self._clock, build, self._retry)
+
+    def _cancel_one(self, order: PendingOrder) -> Result[TradeReceipt, TradeError]:
+        request = CancelRequest(order=order.ticket)
+        return execute(self._terminal, self._clock, lambda: Ok(request), self._retry)

PythonMetaTrader5/connection.py

@@ -0,0 +1,52 @@
+"""Composition root: wires the real adapters into a Trader."""
+
+from __future__ import annotations
+
+import logging
+
+from PythonMetaTrader5.adapters.mt5_terminal import MetaTrader5Terminal
+from PythonMetaTrader5.adapters.system_clock import SystemClock
+from PythonMetaTrader5.application.execution import RetryPolicy
+from PythonMetaTrader5.application.ports import Credentials, parse_login
+from PythonMetaTrader5.application.trader import Trader
+from PythonMetaTrader5.domain.errors import ErrorKind, TradeError
+from PythonMetaTrader5.domain.inputs import own_magic
+from PythonMetaTrader5.result import Err, Ok, Result
+
+log = logging.getLogger("PythonMetaTrader5")
+
+
+def connect(
+    login: int | str,
+    password: str,
+    server: str,
+    *,
+    path: str | None = None,
+    timeout_ms: int = 60_000,
+    magic: int = 0,
+    deviation: int = 10,
+    retry: RetryPolicy | None = None,
+) -> Result[Trader, TradeError]:
+    """Start (or attach to) the MT5 terminal, log in, and return a ready Trader."""
+    account = parse_login(login)
+    if account is None:
+        return Err(
+            TradeError(
+                ErrorKind.INVALID_ARGUMENT, f"login must be a positive integer, got {login!r}"
+            )
+        )
+    own = own_magic(magic)
+    if isinstance(own, Err):
+        return own
+    loaded = MetaTrader5Terminal.load()
+    if isinstance(loaded, Err):
+        return loaded
+    terminal = loaded.value
+    credentials = Credentials(account, str(password), str(server), path, timeout_ms)
+    connected = terminal.connect(credentials)
+    if isinstance(connected, Err):
+        return connected
+    # Login and server only: account_info() also carries the owner's name and
+    # balance, which do not belong in application logs.
+    log.info("connected to %s as %s", server, account)
+    return Ok(Trader(terminal, SystemClock(), magic=own.value, deviation=deviation, retry=retry))

PythonMetaTrader5/domain/__init__.py

@@ -0,0 +1 @@
+"""Pure trading rules: no I/O, no MetaTrader5 import."""

PythonMetaTrader5/domain/amounts.py

@@ -0,0 +1,33 @@
+"""The one rule for "a positive finite number", shared by Stop and the input checks."""
+
+from __future__ import annotations
+
+import math
+from decimal import Decimal
+from numbers import Real
+
+
+def positive_float(value: object, *, unsigned: bool = False) -> float | None:
+    """``value`` as a positive finite float, or None when it is not one.
+
+    numbers.Real rather than float, so numpy scalars from pandas-based bots
+    pass, plus Decimal (not a Real) for bots that keep money as Decimal. bool
+    is excluded because it is a Real (True == 1) and would trade one lot.
+    NaN Decimals are refused before float(): float(Decimal("sNaN")) raises.
+    ``unsigned`` drops the sign first (a distance), after the NaN check, because
+    abs(Decimal("sNaN")) raises too.
+    """
+    if isinstance(value, bool) or not isinstance(value, (Real, Decimal)):
+        return None
+    if isinstance(value, Decimal) and value.is_nan():
+        return None
+    try:
+        number = abs(float(value)) if unsigned else float(value)
+    except ArithmeticError:
+        # None rather than raising: a number outside float range (10**400, or a
+        # numpy longdouble under np.seterr(over="raise")) is bad input like NaN,
+        # and raising would break the Result boundary. ValueError/TypeError are
+        # not caught: they are bugs in the caller's own type and must keep
+        # their traceback.
+        return None
+    return number if math.isfinite(number) and number > 0 else None

PythonMetaTrader5/domain/errors.py

@@ -0,0 +1,53 @@
+"""Typed failure vocabulary shared by every layer."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from PythonMetaTrader5.domain.market import TradeReceipt
+
+
+class ErrorKind(Enum):
+    INVALID_ARGUMENT = "invalid_argument"
+    INVALID_VOLUME = "invalid_volume"
+    INVALID_PRICE = "invalid_price"
+    INVALID_STOPS = "invalid_stops"
+    INVALID_FILLING = "invalid_filling"
+    NO_MONEY = "no_money"
+    MARKET_CLOSED = "market_closed"
+    TRADE_DISABLED = "trade_disabled"
+    ALGO_TRADING_DISABLED = "algo_trading_disabled"
+    LIMIT_REACHED = "limit_reached"
+    # Only part of the volume was executed; the rest is still open/unfilled.
+    PARTIAL_FILL = "partial_fill"
+    # The request may or may not have reached the trade server: never auto-retried.
+    OUTCOME_UNKNOWN = "outcome_unknown"
+    RETRIES_EXHAUSTED = "retries_exhausted"
+    REJECTED = "rejected"
+    SYMBOL_NOT_FOUND = "symbol_not_found"
+    NO_PRICE = "no_price"
+    TERMINAL_ERROR = "terminal_error"
+    # The terminal reports symbol data that cannot price an order (a point of 0,
+    # a NaN tick size, a volume step of 0). Unlike TERMINAL_ERROR it does not
+    # clear on a resend, so it has its own kind: a bot must escalate, not retry.
+    BROKEN_SYMBOL_DATA = "broken_symbol_data"
+    CONNECTION_FAILED = "connection_failed"
+
+
+@dataclass(frozen=True, slots=True)
+class TradeError:
+    kind: ErrorKind
+    message: str
+    retcode: int | None = None
+    # Kept so callers (and the 2.x facade) can inspect the broker's raw answer.
+    receipt: TradeReceipt | None = None
+    # Set when the failure concerns one position/order of a batch operation.
+    ticket: int | None = None
+
+    def __str__(self) -> str:
+        code = f" (retcode {self.retcode})" if self.retcode is not None else ""
+        ticket = f" [ticket {self.ticket}]" if self.ticket is not None else ""
+        return f"{self.kind.value}: {self.message}{code}{ticket}"