pmt5api 1.0.0__py3-none-any.whl

pmt5api/_trading.py

@@ -0,0 +1,367 @@
+"""Order entry: market and pending orders, modify, close (also partial and close-by), cancel; synchronous, with a
+request id and progress events, and awaitable.
+
+Nothing here is ever retried or resent. If the server does not confirm within the execution timeout the call raises
+``RequestTimeout`` and the order MAY have been accepted: look at ``orders()`` before sending again.
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+from datetime import date, datetime
+from typing import Any, Dict, Optional, Union
+
+from ._base import _Base
+from ._util import enum_value, finite, placed_type as _placed, to_core_time, translated
+from .errors import InvalidRequestError, ServerError
+from .models import Order
+
+Expiry = Union[None, str, datetime, date]
+
+_PENDING = {"buy_limit": "BuyLimit", "sell_limit": "SellLimit", "buy_stop": "BuyStop", "sell_stop": "SellStop",
+            "buy_stop_limit": "BuyStopLimit", "sell_stop_limit": "SellStopLimit"}
+_FILL = {"fok": "FillOrKill", "ioc": "ImmediateOrCancel", "flash": "FlashFill", "any": "Any"}
+
+
+class _TradingMixin(_Base):
+    # ---- helpers -----------------------------------------------------------------------------------------------
+
+    def _open_order(self, ticket: int) -> Any:
+        for o in self._api.GetOpenedOrders():
+            if int(o.Ticket) == int(ticket):
+                return o
+        raise InvalidRequestError("no open order or position with ticket %d" % int(ticket))
+
+    def _fill(self, value: Optional[str]) -> Any:
+        if value is None:
+            return None
+        policy = enum_value(self._core.FillPolicy, _FILL.get(str(value).lower(), value), "fill policy")
+        if str(policy) not in ("Any", "FillOrKill") and self._core_at_least(3, 1, 0) is False:
+            raise ValueError("fill_policy %r needs wmt5api 3.1.0 or newer: earlier cores ignore it and send "
+                             "fill-or-kill" % value)
+        return policy
+
+    def _core_at_least(self, major: int, minor: int, patch: int) -> Optional[bool]:
+        try:
+            parts = tuple(int(x) for x in self.core_version.split(".")[:3])
+        except (ValueError, AttributeError):
+            return None
+        return parts >= (major, minor, patch)
+
+    def _expiry(self, value: Expiry) -> Any:
+        if value is None:
+            return None
+        e = self._core.Expiration()
+        kinds = self._core.ExpirationType
+        if isinstance(value, str):
+            key = value.strip().lower()
+            if key == "gtc":
+                e.Type = kinds.GTC
+            elif key == "today":
+                e.Type = kinds.Today
+            else:
+                raise ValueError("expiration must be 'gtc', 'today', a datetime or a date")
+        elif isinstance(value, datetime):
+            e.Type = kinds.Specified
+            e.DateTime = to_core_time(self._server_naive(value))
+        elif isinstance(value, date):
+            e.Type = kinds.SpecifiedDay
+            e.DateTime = to_core_time(datetime(value.year, value.month, value.day))
+        else:
+            raise ValueError("expiration must be 'gtc', 'today', a datetime or a date")
+        return e
+
+    def _open_position(self, ticket: int) -> Any:
+        o = self._open_order(ticket)
+        if str(o.OrderType) not in ("Buy", "Sell"):
+            raise InvalidRequestError("ticket %d is a pending order (%s), not a position: use cancel()"
+                                      % (int(ticket), o.OrderType))
+        return o
+
+    def _open_pending(self, ticket: int) -> Any:
+        o = self._open_order(ticket)
+        if str(o.OrderType) in ("Buy", "Sell"):
+            raise InvalidRequestError("ticket %d is an open position, not a pending order: use close()" % int(ticket))
+        return o
+
+    def _current_expiry(self, o: Any) -> Any:
+        """The expiration a pending order has now, as the core's ``Expiration``, so a modify that does not mention it
+        leaves it alone (an omitted expiration would otherwise become the broker's default)."""
+        if str(o.OrderType) in ("Buy", "Sell"):
+            return None
+        e = self._core.Expiration()
+        e.Type = o.ExpirationType
+        if o.ExpirationTime is not None:
+            e.DateTime = o.ExpirationTime
+        return e
+
+    def _modify_options(self, o: Any, stop_limit: Optional[float], expiration: Expiry,
+                        comment: Optional[str]) -> Dict[str, Any]:
+        """What a modify must carry besides the new stops: the order's own magic, and everything about a pending order
+        that the caller did not change (stop-limit price, expiration)."""
+        named = self._options(comment=comment)
+        named["stoplimit"] = float(stop_limit) if stop_limit is not None else float(o.StopLimitPrice)
+        exp = self._expiry(expiration)
+        if exp is None:
+            exp = self._current_expiry(o)
+        if exp is not None:
+            named["expiration"] = exp
+        named["expertID"] = int(o.ExpertId)
+        return named
+
+    def _options(self, **given: Any) -> Dict[str, Any]:
+        """The optional named arguments of a core order call that the caller actually set."""
+        return {k: v for k, v in given.items() if v is not None}
+
+    def _market_price(self, symbol: str, side: str) -> float:
+        """The side's current price. May wait up to the client's ``quote_timeout`` for the symbol's first quote;
+        :class:`NoQuoteError` (nothing was sent) when none arrives."""
+        q = self._get_quote(symbol, int(self._api.GetQuoteTimeoutMs))
+        return float(q.Ask) if side == "Buy" else float(q.Bid)
+
+    def _send_args(self, symbol: str, kind: str, lots: float, price: Optional[float], sl: float, tp: float,
+                   deviation: int, comment: Optional[str], magic: int, stop_limit: float, expiration: Expiry,
+                   fill_policy: Optional[str], trade_type: Optional[str], placed_type: Optional[str]):
+        lots = finite(lots, "lots", positive=True)
+        sl = finite(sl, "sl", non_negative=True)
+        tp = finite(tp, "tp", non_negative=True)
+        stop_limit = finite(stop_limit, "stop_limit", non_negative=True)
+        if kind.endswith("StopLimit") and stop_limit <= 0:
+            raise ValueError("a stop-limit order needs stop_limit, the price of the limit order it becomes")
+        if price is None:
+            price = self._market_price(symbol, kind)
+        else:
+            price = finite(price, "price", positive=True)
+        positional = (symbol, lots, price, getattr(self._core.OrderType, kind))
+        named = self._options(
+            sl=sl, tp=tp, deviation=int(deviation), comment=comment, expertID=int(magic),
+            stoplimit=stop_limit if stop_limit else None, expiration=self._expiry(expiration),
+            fillPolicy=self._fill(fill_policy),
+            tradeType=enum_value(self._core.TradeType, trade_type, "trade type") if trade_type else None,
+            placedType=_placed(self._core.PlacedType, placed_type))
+        return positional, named
+
+    @staticmethod
+    def _pending_kind(kind: str) -> str:
+        key = str(kind).strip().lower()
+        if key not in _PENDING:
+            raise ValueError("kind must be one of %s" % ", ".join(_PENDING))
+        return _PENDING[key]
+
+    def _confirmed(self, result: Any) -> Order:
+        if result is None:
+            raise ServerError("the server did not confirm the order; check orders() before sending again")
+        return Order._from_core(result)
+
+    # ---- synchronous -------------------------------------------------------------------------------------------
+
+    @translated
+    def buy(self, symbol: str, lots: float, *, sl: float = 0.0, tp: float = 0.0, deviation: int = 0,
+            comment: Optional[str] = None, magic: int = 0, fill_policy: Optional[str] = None,
+            trade_type: Optional[str] = None, placed_type: Optional[str] = None) -> Order:
+        """Buy at market (the current ask). ``sl`` / ``tp`` are prices (0 = none); ``deviation`` is the allowed
+        slippage in points; ``magic`` is your own number, readable back on :class:`Order` and :class:`Deal`;
+        ``fill_policy`` is ``fok``, ``ioc``, ``flash`` or ``any``."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, "Buy", lots, None, sl, tp, deviation, comment, magic, 0.0, None,
+                                     fill_policy, trade_type, placed_type)
+        return self._confirmed(self._api.OrderSend(*pos, **named))
+
+    @translated
+    def sell(self, symbol: str, lots: float, *, sl: float = 0.0, tp: float = 0.0, deviation: int = 0,
+             comment: Optional[str] = None, magic: int = 0, fill_policy: Optional[str] = None,
+             trade_type: Optional[str] = None, placed_type: Optional[str] = None) -> Order:
+        """Sell at market (the current bid)."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, "Sell", lots, None, sl, tp, deviation, comment, magic, 0.0, None,
+                                     fill_policy, trade_type, placed_type)
+        return self._confirmed(self._api.OrderSend(*pos, **named))
+
+    @translated
+    def place_order(self, symbol: str, kind: str, lots: float, price: float, *, sl: float = 0.0, tp: float = 0.0,
+                    stop_limit: float = 0.0, expiration: Expiry = None, deviation: int = 0,
+                    comment: Optional[str] = None, magic: int = 0, fill_policy: Optional[str] = None,
+                    trade_type: Optional[str] = None, placed_type: Optional[str] = None) -> Order:
+        """Place a pending order. ``kind`` is one of ``buy_limit sell_limit buy_stop sell_stop buy_stop_limit
+        sell_stop_limit`` (the two stop-limit kinds also need ``stop_limit``, the limit price). ``expiration`` is
+        ``None`` (the broker's default), ``"gtc"``, ``"today"``, a ``datetime`` (that moment) or a ``date`` (that day)."""
+        self._require_connected()
+        pos, named = self._send_args(symbol, self._pending_kind(kind), lots, price, sl, tp, deviation, comment, magic,
+                                     stop_limit, expiration, fill_policy, trade_type, placed_type)
+        return self._confirmed(self._api.OrderSend(*pos, **named))
+
+    @translated
+    def modify(self, ticket: int, *, sl: Optional[float] = None, tp: Optional[float] = None,
+               price: Optional[float] = None, stop_limit: Optional[float] = None, expiration: Expiry = None,
+               comment: Optional[str] = None) -> None:
+        """Change a position's stop-loss / take-profit, or a pending order's price / stops / expiration. Anything
+        left as ``None`` keeps its current value."""
+        self._require_connected()
+        if sl is None and tp is None and price is None and stop_limit is None and expiration is None:
+            raise ValueError("nothing to change")
+        o = self._open_order(ticket)
+        named = self._modify_options(o, stop_limit, expiration, comment)
+        self._api.OrderModify(o.Ticket, o.Symbol, o.Lots, float(price) if price is not None else float(o.OpenPrice),
+                              o.OrderType, float(sl) if sl is not None else float(o.StopLoss),
+                              float(tp) if tp is not None else float(o.TakeProfit), **named)
+
+    @translated
+    def close(self, ticket: int, lots: Optional[float] = None, *, deviation: int = 0, comment: Optional[str] = None,
+              fill_policy: Optional[str] = None, close_by: Optional[int] = None,
+              placed_type: Optional[str] = None) -> Order:
+        """Close a position at market, completely or (with ``lots``) in part. ``close_by`` closes it against an
+        opposite position of the same symbol (hedging accounts)."""
+        self._require_connected()
+        o = self._open_position(ticket)
+        amount = float(o.Lots) if lots is None else finite(lots, "lots", positive=True)
+        if amount > float(o.Lots) + 1e-9:
+            raise ValueError("lots must be between 0 and the position's %g" % float(o.Lots))
+        q = self._get_quote(str(o.Symbol), int(self._api.GetQuoteTimeoutMs))
+        price = float(q.Bid) if str(o.OrderType) == "Buy" else float(q.Ask)    # a buy closes at the bid
+        # the closing order carries the position's own magic number, so its deals stay attributable to the bot
+        named = self._options(deviation=int(deviation) if deviation else None, fillPolicy=self._fill(fill_policy),
+                              comment=comment, closeByTicket=int(close_by) if close_by else None,
+                              placedType=_placed(self._core.PlacedType, placed_type))
+        named["expertId"] = int(o.ExpertId)
+        return self._confirmed(self._api.OrderClose(o.Ticket, o.Symbol, price, amount, o.OrderType, **named))
+
+    @translated
+    def cancel(self, ticket: int, *, fill_policy: Optional[str] = None, comment: Optional[str] = None,
+               placed_type: Optional[str] = None) -> Order:
+        """Delete a pending order."""
+        self._require_connected()
+        o = self._open_pending(ticket)
+        named = self._options(fillPolicy=self._fill(fill_policy), comment=comment,
+                              placedType=_placed(self._core.PlacedType, placed_type))
+        named["expertId"] = int(o.ExpertId)
+        return self._confirmed(self._api.OrderCancel(o.Ticket, o.Symbol, o.Lots, o.OrderType, **named))
+
+    # ---- with a request id and progress events ------------------------------------------------------------------
+
+    @translated
+    def new_request_id(self) -> int:
+        """A unique id for an asynchronous trade call (the ``*_async`` methods take one for you)."""
+        return int(self._api.GetRequestId())
+
+    @translated
+    def buy_async(self, symbol: str, lots: float, *, request_id: Optional[int] = None, sl: float = 0.0,
+                  tp: float = 0.0, deviation: int = 0, comment: Optional[str] = None, magic: int = 0,
+                  fill_policy: Optional[str] = None, trade_type: Optional[str] = None,
+                  placed_type: Optional[str] = None) -> int:
+        """Send a market buy and return with its request id as soon as the request is on the wire; the outcome arrives
+        through :meth:`on_order_progress` (and :meth:`on_order_update`).
+
+        A market order needs a price: if the symbol has no quote yet this first waits (up to the client's
+        ``quote_timeout``) for one, and raises :class:`NoQuoteError` — nothing sent — if none arrives."""
+        return self._send_async("Buy", symbol, lots, None, request_id, sl, tp, deviation, comment, magic, 0.0, None,
+                                fill_policy, trade_type, placed_type)
+
+    @translated
+    def sell_async(self, symbol: str, lots: float, *, request_id: Optional[int] = None, sl: float = 0.0,
+                   tp: float = 0.0, deviation: int = 0, comment: Optional[str] = None, magic: int = 0,
+                   fill_policy: Optional[str] = None, trade_type: Optional[str] = None,
+                   placed_type: Optional[str] = None) -> int:
+        """Send a market sell and return at once with its request id; see :meth:`buy_async`."""
+        return self._send_async("Sell", symbol, lots, None, request_id, sl, tp, deviation, comment, magic, 0.0, None,
+                                fill_policy, trade_type, placed_type)
+
+    @translated
+    def place_order_async(self, symbol: str, kind: str, lots: float, price: float, *,
+                          request_id: Optional[int] = None, sl: float = 0.0, tp: float = 0.0,
+                          stop_limit: float = 0.0, expiration: Expiry = None, deviation: int = 0,
+                          comment: Optional[str] = None, magic: int = 0, fill_policy: Optional[str] = None,
+                          trade_type: Optional[str] = None, placed_type: Optional[str] = None) -> int:
+        """Place a pending order and return at once with its request id; see :meth:`place_order` and :meth:`buy_async`."""
+        return self._send_async(self._pending_kind(kind), symbol, lots, price, request_id, sl, tp, deviation,
+                                comment, magic, stop_limit, expiration, fill_policy, trade_type, placed_type)
+
+    def _send_async(self, kind: str, symbol: str, lots: float, price: Optional[float], request_id: Optional[int],
+                    sl: float, tp: float, deviation: int, comment: Optional[str], magic: int, stop_limit: float,
+                    expiration: Expiry, fill_policy: Optional[str], trade_type: Optional[str],
+                    placed_type: Optional[str]) -> int:
+        self._require_connected()
+        rid = int(request_id) if request_id is not None else int(self._api.GetRequestId())
+        pos, named = self._send_args(symbol, kind, lots, price, sl, tp, deviation, comment, magic, stop_limit,
+                                     expiration, fill_policy, trade_type, placed_type)
+        self._api.OrderSendAsync(rid, *pos, **named)
+        return rid
+
+    @translated
+    def modify_async(self, ticket: int, *, request_id: Optional[int] = None, sl: Optional[float] = None,
+                     tp: Optional[float] = None, price: Optional[float] = None, stop_limit: Optional[float] = None,
+                     expiration: Expiry = None, comment: Optional[str] = None) -> int:
+        """Modify a position or pending order and return at once with its request id; see :meth:`modify`."""
+        self._require_connected()
+        if sl is None and tp is None and price is None and stop_limit is None and expiration is None:
+            raise ValueError("nothing to change")
+        o = self._open_order(ticket)
+        rid = int(request_id) if request_id is not None else int(self._api.GetRequestId())
+        named = self._modify_options(o, stop_limit, expiration, comment)
+        self._api.OrderModifyAsync(rid, o.Ticket, o.Symbol, o.Lots,
+                                   float(price) if price is not None else float(o.OpenPrice), o.OrderType,
+                                   float(sl) if sl is not None else float(o.StopLoss),
+                                   float(tp) if tp is not None else float(o.TakeProfit), **named)
+        return rid
+
+    @translated
+    def close_async(self, ticket: int, lots: Optional[float] = None, *, request_id: Optional[int] = None,
+                    deviation: int = 0, comment: Optional[str] = None, fill_policy: Optional[str] = None,
+                    close_by: Optional[int] = None, placed_type: Optional[str] = None) -> int:
+        """Close a position (or part of it) at market and return at once with its request id; see :meth:`close`."""
+        self._require_connected()
+        o = self._open_position(ticket)
+        amount = float(o.Lots) if lots is None else finite(lots, "lots", positive=True)
+        if amount > float(o.Lots) + 1e-9:
+            raise ValueError("lots must be between 0 and the position's %g" % float(o.Lots))
+        q = self._get_quote(str(o.Symbol), int(self._api.GetQuoteTimeoutMs))
+        price = float(q.Bid) if str(o.OrderType) == "Buy" else float(q.Ask)
+        rid = int(request_id) if request_id is not None else int(self._api.GetRequestId())
+        named = self._options(deviation=int(deviation) if deviation else None, fillPolicy=self._fill(fill_policy),
+                              comment=comment, closeByTicket=int(close_by) if close_by else None,
+                              placedType=_placed(self._core.PlacedType, placed_type))
+        named["expertId"] = int(o.ExpertId)
+        self._api.OrderCloseAsync(rid, o.Ticket, o.Symbol, price, amount, o.OrderType, **named)
+        return rid
+
+    @translated
+    def cancel_async(self, ticket: int, *, request_id: Optional[int] = None, fill_policy: Optional[str] = None,
+                     comment: Optional[str] = None, placed_type: Optional[str] = None) -> int:
+        """Delete a pending order and return at once with its request id; see :meth:`cancel`."""
+        self._require_connected()
+        o = self._open_pending(ticket)
+        rid = int(request_id) if request_id is not None else int(self._api.GetRequestId())
+        named = self._options(fillPolicy=self._fill(fill_policy), comment=comment,
+                              placedType=_placed(self._core.PlacedType, placed_type))
+        named["expertId"] = int(o.ExpertId)
+        self._api.OrderCancelAsync(rid, o.Ticket, o.Symbol, o.Lots, o.OrderType, **named)
+        return rid
+
+    # ---- awaitable ----------------------------------------------------------------------------------------------
+    # The synchronous calls, run on a worker thread so they never block the event loop.
+
+    async def _run(self, fn: Any, *args: Any, **kwargs: Any) -> Any:
+        return await asyncio.get_running_loop().run_in_executor(None, functools.partial(fn, *args, **kwargs))
+
+    async def abuy(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`buy`."""
+        return await self._run(self.buy, *args, **kwargs)
+
+    async def asell(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`sell`."""
+        return await self._run(self.sell, *args, **kwargs)
+
+    async def aplace_order(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`place_order`."""
+        return await self._run(self.place_order, *args, **kwargs)
+
+    async def amodify(self, *args: Any, **kwargs: Any) -> None:
+        """Awaitable :meth:`modify`."""
+        return await self._run(self.modify, *args, **kwargs)
+
+    async def aclose(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`close`."""
+        return await self._run(self.close, *args, **kwargs)
+
+    async def acancel(self, *args: Any, **kwargs: Any) -> Order:
+        """Awaitable :meth:`cancel`."""
+        return await self._run(self.cancel, *args, **kwargs)

pmt5api/_util.py

@@ -0,0 +1,78 @@
+"""Small helpers shared by the client modules."""
+from __future__ import annotations
+
+import functools
+import math
+from datetime import datetime
+from typing import Any, Callable, Optional
+
+from .errors import WmtError, translate
+
+
+def translated(fn: Callable) -> Callable:
+    """Re-raise the core's exceptions as the pmt5api hierarchy (the core exception stays as ``__cause__``)."""
+    @functools.wraps(fn)
+    def wrapper(*args: Any, **kwargs: Any) -> Any:
+        try:
+            return fn(*args, **kwargs)
+        except WmtError:
+            raise
+        except Exception as exc:  # noqa: BLE001 — translate() returns None for anything that is not the core's
+            mapped = translate(exc)
+            if mapped is None:
+                raise
+            raise mapped from exc
+    return wrapper
+
+
+def to_core_time(value: datetime) -> Any:
+    """A naive ``datetime`` as a .NET ``DateTime`` (kind unspecified: the value is used exactly as given)."""
+    import System  # available once the runtime is loaded
+    return System.DateTime(value.year, value.month, value.day, value.hour, value.minute, value.second,
+                           value.microsecond // 1000)
+
+
+def seconds_to_ms(value: Optional[float], name: str = "timeout") -> Optional[int]:
+    """Seconds to the core's milliseconds. A timeout must be positive and finite: zero would make every call "time
+    out" the instant it is made, which for an order means "sent, unconfirmed" — an invitation to resend."""
+    if value is None:
+        return None
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value) or value <= 0:
+        raise ValueError("%s must be a positive number of seconds, not %r" % (name, value))
+    return max(1, int(round(value * 1000)))
+
+
+def finite(value: float, name: str, *, positive: bool = False, non_negative: bool = False) -> float:
+    """``value`` as a float, refusing NaN and infinity (which the core would turn into undefined volumes or prices)."""
+    v = float(value)
+    if not math.isfinite(v):
+        raise ValueError("%s must be a finite number, not %r" % (name, value))
+    if positive and v <= 0:
+        raise ValueError("%s must be positive" % name)
+    if non_negative and v < 0:
+        raise ValueError("%s must not be negative" % name)
+    return v
+
+
+def enum_value(enum_type: Any, value: Any, what: str) -> Any:
+    """Look an enum member up by name (case-insensitive, ``-``/``_``/space ignored); ``None`` stays ``None``."""
+    if value is None:
+        return None
+    key = str(value).replace("_", "").replace("-", "").replace(" ", "").lower()
+    for name in dir(enum_type):
+        if name.startswith("_"):
+            continue
+        if name.replace("_", "").lower() == key:
+            return getattr(enum_type, name)
+    raise ValueError("unknown %s %r" % (what, value))
+
+
+_PLACED = {"manual": "Manually", "manually": "Manually", "expert": "ByExpert", "dealer": "ByDealer",
+           "mobile": "Mobile", "web": "Web"}
+
+
+def placed_type(enum_type: Any, value: Optional[str]) -> Any:
+    """``PlacedType`` by name or by the friendly aliases ``manual`` / ``expert`` / ``dealer``."""
+    if value is None:
+        return None
+    return enum_value(enum_type, _PLACED.get(str(value).strip().lower(), value), "placed type")

pmt5api/bars.py

@@ -0,0 +1,98 @@
+"""OHLC bars: the value type and the timeframe aggregation.
+
+The server delivers one-minute bars. Higher timeframes are built here from those minutes, aligned to the server's
+calendar (the day starts at server midnight, an H4 bar starts at 00, 04, 08, ... server time), with the tick volume
+summed. A bar for the period that is still running is returned as it stands; it is not marked, so do not treat the
+last bar of a live series as final. A weekly bar starts on Sunday 00:00 server time, a monthly bar on the 1st.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+from typing import Any, Dict, Iterable, List, Optional, Tuple, Union
+
+from .models import _time
+
+#: Supported timeframes, in minutes. Weekly and monthly bars are calendar-aligned (their minute counts are nominal).
+TIMEFRAMES: Dict[str, int] = {
+    "M1": 1, "M2": 2, "M3": 3, "M4": 4, "M5": 5, "M6": 6, "M10": 10, "M12": 12, "M15": 15, "M20": 20, "M30": 30,
+    "H1": 60, "H2": 120, "H3": 180, "H4": 240, "H6": 360, "H8": 480, "H12": 720,
+    "D1": 1440, "W1": 10080, "MN1": 43200,
+}
+_WEEK, _MONTH = 10080, 43200
+
+
+@dataclass(frozen=True)
+class Bar:
+    time: datetime              # start of the period, server time
+    open: float
+    high: float
+    low: float
+    close: float
+    tick_volume: int            # number of ticks in the period (summed for aggregated bars)
+    volume: int                 # real volume where the broker reports it (0 for most FX symbols)
+    spread: Optional[int] = None  # points, as the server stored it; present on M1 bars only
+
+    @classmethod
+    def _from_core(cls, b: Any) -> "Bar":
+        return cls(time=_time(b.Time), open=float(b.OpenPrice), high=float(b.HighPrice), low=float(b.LowPrice),
+                   close=float(b.ClosePrice), tick_volume=int(b.TickVolume), volume=int(b.Volume),
+                   spread=int(b.Spread))
+
+
+def timeframe_minutes(timeframe: Union[str, int]) -> int:
+    if isinstance(timeframe, str):
+        key = timeframe.strip().upper()
+        if key in TIMEFRAMES:
+            return TIMEFRAMES[key]
+    elif isinstance(timeframe, int) and timeframe in TIMEFRAMES.values():
+        return timeframe
+    raise ValueError("unsupported timeframe %r; use one of %s" % (timeframe, ", ".join(TIMEFRAMES)))
+
+
+def _bucket(t: datetime, minutes: int) -> datetime:
+    day = datetime(t.year, t.month, t.day)
+    if minutes == _MONTH:
+        return datetime(t.year, t.month, 1)
+    if minutes == _WEEK:
+        return day - timedelta(days=(t.weekday() + 1) % 7)       # the week starts on Sunday
+    if minutes >= 1440:
+        return day
+    elapsed = t.hour * 60 + t.minute
+    return day + timedelta(minutes=elapsed - elapsed % minutes)
+
+
+def aggregate(minute_bars: Iterable[Bar], minutes: int) -> List[Bar]:
+    """Build ``minutes``-long bars from one-minute bars (any order; a repeated minute keeps its last value)."""
+    by_time: Dict[datetime, Bar] = {b.time: b for b in minute_bars}
+    ordered = [by_time[t] for t in sorted(by_time)]
+    if minutes == 1:
+        return ordered
+    out: List[Bar] = []
+    current: Optional[Bar] = None
+    for b in ordered:
+        start = _bucket(b.time, minutes)
+        if current is None or current.time != start:
+            if current is not None:
+                out.append(current)
+            current = Bar(time=start, open=b.open, high=b.high, low=b.low, close=b.close,
+                          tick_volume=b.tick_volume, volume=b.volume, spread=None)
+        else:
+            current = Bar(time=current.time, open=current.open, high=max(current.high, b.high),
+                          low=min(current.low, b.low), close=b.close,
+                          tick_volume=current.tick_volume + b.tick_volume, volume=current.volume + b.volume,
+                          spread=None)
+    if current is not None:
+        out.append(current)
+    return out
+
+
+@dataclass(frozen=True)
+class QuoteHistoryEvent:
+    """One-minute bars the server delivered after :meth:`Client.request_bars`."""
+    symbol: str
+    bars: Tuple[Bar, ...]
+
+    @classmethod
+    def _from_core(cls, e: Any) -> "QuoteHistoryEvent":
+        return cls(symbol=str(e.Symbol), bars=tuple(Bar._from_core(b) for b in (e.Bars or ())))