stx-python 0.6.0rc1__py3-none-any.whl

stx/_ws.py

@@ -0,0 +1,1016 @@
+"""``STXWebSocket``: Phoenix channels over one signed socket.
+
+One socket carries every topic. Each join method returns a
+:class:`Channel`; messages reach you through an ``on_message`` callback,
+by iterating the channel (``async for msg in channel``), or both.
+
+What the client does for you:
+
+* signs the handshake with your API key (``GET /socket/websocket``, query
+  string dropped), with a fresh signature on every connect;
+* sends the socket heartbeat on the ``phoenix`` topic and reconnects when a
+  heartbeat goes unanswered;
+* pings each joined channel on a timer; on ``orders`` with
+  ``cancel_on_disconnect`` the ping runs at 60% of the ``ping_timeout`` the
+  server granted, which is a separate deadline from the socket heartbeat;
+* reconnects with backoff after a drop, re-signs, and rejoins every channel
+  with its current filters (including ``market_updates`` watches), so the
+  snapshot events arrive again;
+* converts the cents in ``markets`` and ``market_updates`` to dollar
+  strings (see ``stx._money``).
+
+What stays yours: reconciling after a reconnect. Pass ``on_reconnect`` to
+be told when to take a fresh REST snapshot.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import itertools
+import json
+import logging
+import random
+from dataclasses import dataclass, field
+from typing import (
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Optional,
+    Sequence,
+    Union,
+)
+
+import websockets
+
+from stx._money import convert_market_payload, convert_markets_frame
+from stx._settings import _SENTINEL as _UNSET
+from stx._signing import Signer
+from stx._version import USER_AGENT
+from stx.exceptions import STXChannelException, STXConfigException, STXTransportException
+
+logger = logging.getLogger("stx.ws")
+
+PHOENIX_TOPIC = "phoenix"
+
+# Events that carry state on join, by channel name (topic prefix).
+SNAPSHOT_EVENTS: Dict[str, tuple] = {
+    "orders": ("all_orders",),
+    "fills": ("all_trades",),
+    "positions": ("all_positions",),
+    "balances": ("balances",),
+    "account": ("all_orders", "all_trades", "all_positions", "balances"),
+    "user_info": ("user_updated",),
+}
+
+# Channels whose join reply itself is the snapshot.
+REPLY_SNAPSHOT_CHANNELS = frozenset({"market_stats"})
+
+ACCOUNT_CHANNELS = frozenset(
+    {"orders", "fills", "positions", "settlements", "balances", "account", "user_info"}
+)
+
+
+@dataclass
+class ChannelMessage:
+    """One pushed frame.
+
+    ``payload`` is the event's JSON object as documented for the channel,
+    with money and quantities as strings. ``channel`` is the topic without
+    the user id (``"orders"`` for ``orders:<user_id>``).
+    """
+
+    topic: str
+    event: str
+    payload: Any
+    ref: Optional[str] = None
+    join_ref: Optional[str] = None
+
+    @property
+    def channel(self) -> str:
+        return self.topic.split(":", 1)[0]
+
+    @property
+    def is_snapshot(self) -> bool:
+        """``True`` for the state-on-join events (``all_orders``, ``balances``...)."""
+        return self.event in SNAPSHOT_EVENTS.get(self.channel, ())
+
+
+MessageHandler = Callable[[ChannelMessage], Union[Awaitable[None], None]]
+
+
+def _handshake_headers_kwarg() -> str:
+    """``additional_headers`` on websockets >= 13, ``extra_headers`` before."""
+    try:
+        params = inspect.signature(websockets.connect).parameters
+    except (TypeError, ValueError):  # pragma: no cover
+        return "extra_headers"
+    return "additional_headers" if "additional_headers" in params else "extra_headers"
+
+
+@dataclass
+class ReconnectPolicy:
+    """Backoff between reconnect attempts. ``max_attempts=None`` never gives up."""
+
+    initial_backoff: float = 0.5
+    max_backoff: float = 30.0
+    max_attempts: Optional[int] = None
+    jitter: bool = True
+
+    def delay(self, attempt: int) -> float:
+        base = min(self.initial_backoff * (2 ** (attempt - 1)), self.max_backoff)
+        return base * (0.5 + random.random() * 0.5) if self.jitter else base
+
+
+class Channel:
+    """One joined topic.
+
+    Attributes:
+        topic: the wire topic, e.g. ``orders:<user_id>``.
+        name: the topic without the user id, e.g. ``orders``.
+        join_payload: what the next (re)join sends; updated by the
+            ``select_*`` and ``watch`` helpers so a reconnect keeps them.
+        reply: the ``response`` object from the latest join reply, e.g.
+            ``{"selected_market_ids": None}``.
+        snapshots: the latest snapshot payload per snapshot event name.
+    """
+
+    def __init__(
+        self,
+        ws: STXWebSocket,
+        topic: str,
+        join_payload: Dict[str, Any],
+        on_message: Optional[MessageHandler],
+        *,
+        ping_interval: Optional[float],
+        queue_size: int,
+    ) -> None:
+        self.ws = ws
+        self.topic = topic
+        self.name = topic.split(":", 1)[0]
+        self.join_payload = dict(join_payload)
+        self.on_message = on_message
+        self.ping_interval = ping_interval
+        self.reply: Dict[str, Any] = {}
+        self.snapshots: Dict[str, Any] = {}
+        self.watches: List[str] = []
+        self.join_ref: Optional[str] = None
+        self.joined = False
+        self.closed = False
+        self._queue: asyncio.Queue[Optional[ChannelMessage]] = asyncio.Queue(queue_size)
+        self._snapshot_event = asyncio.Event()
+        self._ping_task: Optional[asyncio.Task] = None
+
+    def __repr__(self) -> str:
+        state = "joined" if self.joined else ("closed" if self.closed else "joining")
+        return f"Channel({self.topic!r}, {state})"
+
+    # -- receiving ------------------------------------------------------
+
+    def __aiter__(self) -> AsyncIterator[ChannelMessage]:
+        return self._iter()
+
+    async def _iter(self) -> AsyncIterator[ChannelMessage]:
+        while True:
+            msg = await self._queue.get()
+            if msg is None:
+                return
+            yield msg
+
+    async def next(self, timeout: Optional[float] = None) -> ChannelMessage:
+        """The next message on this channel. Raises ``asyncio.TimeoutError``."""
+        msg = await asyncio.wait_for(self._queue.get(), timeout)
+        if msg is None:
+            raise STXChannelException(f"{self.topic} is closed", topic=self.topic)
+        return msg
+
+    async def wait_snapshot(self, timeout: Optional[float] = 10.0) -> Dict[str, Any]:
+        """Wait for the state-on-join and return it as ``{event: payload}``.
+
+        ``orders`` gives ``{"all_orders": {...}}``; ``account`` waits for all
+        four of its snapshots. ``market_stats`` returns the join reply, which
+        carries the series. Channels with no snapshot (``settlements``,
+        ``ticker``, ``trades``, ``orderbook``, ``markets``,
+        ``market_updates``) raise ``ValueError``.
+        """
+        if self.name in REPLY_SNAPSHOT_CHANNELS:
+            return {"reply": self.reply}
+        if self.name not in SNAPSHOT_EVENTS:
+            raise ValueError(f"{self.name} sends no snapshot on join")
+        await asyncio.wait_for(self._snapshot_event.wait(), timeout)
+        return dict(self.snapshots)
+
+    async def _deliver(self, msg: ChannelMessage) -> None:
+        expected = SNAPSHOT_EVENTS.get(self.name, ())
+        if msg.event in expected:
+            self.snapshots[msg.event] = msg.payload
+            if all(e in self.snapshots for e in expected):
+                self._snapshot_event.set()
+        if self.on_message is not None:
+            try:
+                result = self.on_message(msg)
+                if inspect.isawaitable(result):
+                    await result
+            except Exception:  # a bad callback must not kill the reader
+                logger.exception("on_message for %s raised", self.topic)
+        if self._queue.full():
+            # Drop the oldest so a slow consumer sees current state.
+            try:
+                self._queue.get_nowait()
+            except asyncio.QueueEmpty:  # pragma: no cover
+                pass
+            logger.warning("%s queue full; dropped the oldest message", self.topic)
+        self._queue.put_nowait(msg)
+
+    # -- sending --------------------------------------------------------
+
+    async def push(self, event: str, payload: Any = None, timeout: Optional[float] = None) -> Any:
+        """Send ``event`` on this channel and return the reply's ``response``.
+
+        Raises ``STXChannelException`` when the reply status is ``error``.
+        """
+        if not self.joined or self.join_ref is None:
+            raise STXChannelException(f"{self.topic} is not joined", topic=self.topic)
+        return await self.ws._request(self.topic, event, {} if payload is None else payload,
+                                      self.join_ref, timeout)  # fmt: skip
+
+    async def ping(self) -> Any:
+        """Channel ``ping``. On ``orders`` with cancel-on-disconnect armed this
+        resets the cancel deadline; on ``account`` and ``orders`` it keeps the
+        session alive."""
+        return await self.push("ping", {})
+
+    async def select_market_ids(self, market_ids: Optional[Sequence[str]]) -> Any:
+        """Change the ``market_ids`` filter without rejoining.
+
+        On ``orders``, ``fills``, ``positions``, ``settlements`` and
+        ``account`` ``None`` clears the filter; ``orderbook`` and
+        ``market_stats`` require at least one id. Returns the reply, whose
+        ``selected_market_ids`` is what the server applied.
+        """
+        ids = None if market_ids is None else list(market_ids)
+        reply = await self.push("select_market_ids", {"market_ids": ids})
+        self.join_payload["market_ids"] = ids
+        return reply
+
+    async def select_filters(self, **filters: Optional[Sequence[str]]) -> Any:
+        """``ticker`` (``sports``, ``competitions``) and ``trades``
+        (``market_ids``, ``event_ids``): change filters without rejoining."""
+        payload = {k: (None if v is None else list(v)) for k, v in filters.items()}
+        reply = await self.push("select_filters", payload)
+        self.join_payload.update(payload)
+        return reply
+
+    async def select_rule_filters(self, rule_filters: Optional[Sequence[str]]) -> Any:
+        """``markets``: change the ``rules`` filter; ``None`` disables it."""
+        value = None if rule_filters is None else list(rule_filters)
+        reply = await self.push("select_rule_filters", {"rule_filters": value})
+        self.join_payload["rule_filters"] = value
+        return reply
+
+    async def select_message_types(self, message_types: Optional[Sequence[str]]) -> Any:
+        """``markets``: receive ``market_created``, ``market_updated`` or both."""
+        value = None if message_types is None else list(message_types)
+        reply = await self.push("select_message_types", {"message_types": value})
+        self.join_payload["message_types"] = value
+        return reply
+
+    async def watch(self, market_ids: Sequence[str]) -> Any:
+        """``market_updates``: start receiving ``created``/``updated`` for
+        these markets. Re-sent automatically after a reconnect. Returns the
+        reply, whose ``subscriptions.watches`` lists what is watched."""
+        ids = list(market_ids)
+        reply = await self.push("watch", ids)
+        for mid in ids:
+            if mid not in self.watches:
+                self.watches.append(mid)
+        return reply
+
+    async def request_series(self, market_ids: Sequence[str], range: str = "all") -> Any:
+        """``market_stats``: fetch history at ``range`` (``day``, ``week``,
+        ``month``, ``all``) without changing the subscription."""
+        return await self.push("request_series", {"market_ids": list(market_ids), "range": range})
+
+    async def leave(self) -> None:
+        """Leave the topic. The channel stops receiving and its iterator ends."""
+        await self.ws._leave(self)
+
+    # -- internals ------------------------------------------------------
+
+    def _start_pinger(self) -> None:
+        self._stop_pinger()
+        interval = self.ping_interval
+        granted = self.reply.get("ping_timeout") if isinstance(self.reply, dict) else None
+        if isinstance(granted, int) and self.join_payload.get("cancel_on_disconnect"):
+            # Cancel-on-disconnect deadline: ping at 60% of what the server
+            # granted, whatever the general interval is.
+            cod = granted / 1000.0 * 0.6
+            interval = cod if interval is None else min(interval, cod)
+        if interval:
+            self._ping_task = asyncio.ensure_future(self._ping_loop(interval))
+
+    def _stop_pinger(self) -> None:
+        if self._ping_task is not None and not self._ping_task.done():
+            self._ping_task.cancel()
+        self._ping_task = None
+
+    async def _ping_loop(self, interval: float) -> None:
+        while self.joined and not self.closed:
+            await asyncio.sleep(interval)
+            if not self.joined:
+                return
+            try:
+                await self.push("ping", {}, timeout=max(interval, 5.0))
+            except asyncio.CancelledError:
+                raise
+            except Exception as exc:
+                logger.warning("%s ping failed: %s", self.topic, exc)
+
+    def _reset_for_rejoin(self) -> None:
+        self.joined = False
+        self.snapshots.clear()
+        self._snapshot_event.clear()
+        self._stop_pinger()
+
+    def _close(self) -> None:
+        self.closed = True
+        self.joined = False
+        self._stop_pinger()
+        try:
+            self._queue.put_nowait(None)
+        except asyncio.QueueFull:
+            self._queue.get_nowait()
+            self._queue.put_nowait(None)
+
+
+@dataclass
+class _Pending:
+    future: asyncio.Future[Any]
+    topic: str
+    event: str
+
+
+@dataclass
+class _State:
+    pending: Dict[str, _Pending] = field(default_factory=dict)
+
+
+class STXWebSocket:
+    """Async Phoenix-channels client for the documented STX topics.
+
+    Build it from an ``AsyncSTX`` client, which supplies the host, the key
+    and your user id::
+
+        async with AsyncSTX(profile="us-demo") as client:
+            async with client.websocket() as ws:
+                book = await ws.orderbook(["<market-id>"], on_message=print)
+                orders = await ws.orders()
+                print(await orders.wait_snapshot())
+                await ws.run_forever()
+
+    or standalone with the same settings arguments as ``AsyncSTX``.
+
+    Args:
+        rest: an ``AsyncSTX`` to take host, key and user id from.
+        user_id: your user id, if you already have it (skips ``GET /me``).
+        heartbeat_interval: seconds between socket heartbeats. The server
+            closes a socket silent for 60 s.
+        channel_ping_interval: seconds between channel ``ping`` frames on
+            every joined topic; ``None`` disables them. ``orders`` with
+            cancel-on-disconnect pings faster, from the granted timeout.
+        reconnect: reconnect after a drop (default ``True``).
+        reconnect_policy: backoff for reconnects.
+        on_reconnect: called (sync or async) after every successful
+            reconnect and rejoin: the moment to call ``orders()`` and
+            anything else you show again.
+        join_timeout: seconds to wait for a join or push reply.
+        queue_size: messages buffered per channel for ``async for``; the
+            oldest is dropped when full.
+    """
+
+    def __init__(
+        self,
+        *,
+        rest: Any = None,
+        region: Any = _UNSET,
+        env: Any = _UNSET,
+        host: Any = _UNSET,
+        key_id: Any = _UNSET,
+        private_key: Any = _UNSET,
+        signer: Optional[Signer] = None,
+        profile: Any = _UNSET,
+        verify_tls: Any = _UNSET,
+        user_id: Optional[str] = None,
+        heartbeat_interval: float = 25.0,
+        channel_ping_interval: Optional[float] = 30.0,
+        reconnect: bool = True,
+        reconnect_policy: Optional[ReconnectPolicy] = None,
+        on_reconnect: Optional[Callable[[], Union[Awaitable[None], None]]] = None,
+        join_timeout: float = 10.0,
+        queue_size: int = 10_000,
+    ) -> None:
+        if rest is None:
+            from stx._async_client import AsyncSTX
+
+            rest = AsyncSTX(
+                region=region,
+                env=env,
+                host=host,
+                key_id=key_id,
+                private_key=private_key,
+                signer=signer,
+                profile=profile,
+                verify_tls=verify_tls,
+            )
+            self._owns_rest = True
+        else:
+            self._owns_rest = False
+        self.rest = rest
+        self.url: str = rest.socket_url
+        self.credentials = rest.credentials
+        self.verify_tls: bool = rest.verify_tls
+        self._user_id = user_id
+        self.heartbeat_interval = heartbeat_interval
+        self.channel_ping_interval = channel_ping_interval
+        self.reconnect = reconnect
+        self.reconnect_policy = reconnect_policy or ReconnectPolicy()
+        self.on_reconnect = on_reconnect
+        self.join_timeout = join_timeout
+        self.queue_size = queue_size
+
+        self.channels: Dict[str, Channel] = {}
+        self._conn: Any = None
+        self._refs = itertools.count(1)
+        self._state = _State()
+        self._reader: Optional[asyncio.Task] = None
+        self._heartbeat: Optional[asyncio.Task] = None
+        self._supervisor: Optional[asyncio.Task] = None
+        # Created on first use inside the running loop (Python 3.9 binds
+        # asyncio primitives to the loop current at construction).
+        self._connected_ev: Optional[asyncio.Event] = None
+        self._closed = False
+        self._closed_ev: Optional[asyncio.Event] = None
+        self._pending_heartbeat: Optional[str] = None
+        self._tasks: set[asyncio.Task] = set()
+        self.reconnects = 0
+
+    def __repr__(self) -> str:
+        return f"STXWebSocket({self.url!r}, channels={list(self.channels)})"
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> STXWebSocket:
+        await self.connect()
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    @property
+    def _connected(self) -> asyncio.Event:
+        if self._connected_ev is None:
+            self._connected_ev = asyncio.Event()
+        return self._connected_ev
+
+    @property
+    def _closed_event(self) -> asyncio.Event:
+        if self._closed_ev is None:
+            self._closed_ev = asyncio.Event()
+        return self._closed_ev
+
+    @property
+    def connected(self) -> bool:
+        return self._connected_ev is not None and self._connected_ev.is_set()
+
+    async def connect(self) -> None:
+        """Open the socket. Idempotent."""
+        if self._closed:
+            raise STXTransportException("This STXWebSocket is closed; create a new one.")
+        if self._connected.is_set():
+            return
+        await self._open()
+        self._supervisor = asyncio.ensure_future(self._supervise())
+
+    async def close(self) -> None:
+        """Leave every channel and close the socket. Safe to call twice."""
+        if self._closed:
+            return
+        self._closed = True
+        for channel in list(self.channels.values()):
+            channel.closed = True
+            if channel.joined and self._connected.is_set():
+                try:
+                    await asyncio.wait_for(
+                        self._request(channel.topic, "phx_leave", {}, channel.join_ref, 2.0), 3.0
+                    )
+                except Exception:
+                    pass
+            channel._close()
+        self.channels.clear()
+        for task in (self._supervisor, self._heartbeat, self._reader, *self._tasks):
+            if task is not None and not task.done():
+                task.cancel()
+                try:
+                    await task
+                except (asyncio.CancelledError, Exception):
+                    pass
+        await self._close_conn()
+        self._fail_pending(STXTransportException("socket closed"))
+        self._closed_event.set()
+        if self._owns_rest:
+            await self.rest.close()
+
+    async def run_forever(self) -> None:
+        """Block until :meth:`close` is called (or reconnects are exhausted)."""
+        await self._closed_event.wait()
+
+    async def user_id(self) -> str:
+        """Your user id, from ``user_id=`` or ``GET /api/v1/me``."""
+        if self._user_id is None:
+            self._user_id = await self.rest.user_id()
+        return self._user_id
+
+    # ------------------------------------------------------------------
+    # Public market channels
+    # ------------------------------------------------------------------
+
+    async def orderbook(
+        self, market_ids: Sequence[str], *, on_message: Optional[MessageHandler] = None
+    ) -> Channel:
+        """``orderbook``: the aggregated book, one ``book`` push per market.
+
+        Each push is a full snapshot of that market's book; replace what you
+        hold rather than merging. ``market_ids`` is required.
+        """
+        if not market_ids:
+            raise ValueError("orderbook needs at least one market id")
+        return await self.join("orderbook", {"market_ids": list(market_ids)}, on_message)
+
+    async def ticker(
+        self,
+        *,
+        sports: Optional[Sequence[str]] = None,
+        competitions: Optional[Sequence[str]] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``ticker``: a ``ticker`` push whenever a market's price, top of
+        book, volume or open interest moves. No snapshot on join."""
+        payload = _drop_none({"sports": _opt_list(sports), "competitions": _opt_list(competitions)})
+        return await self.join("ticker", payload, on_message)
+
+    async def trades(
+        self,
+        *,
+        market_ids: Optional[Sequence[str]] = None,
+        event_ids: Optional[Sequence[str]] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``trades``: every execution on the exchange, anonymised. ``action``
+        is the taker's side. Not your fills: see :meth:`fills`."""
+        payload = _drop_none(
+            {"market_ids": _opt_list(market_ids), "event_ids": _opt_list(event_ids)}
+        )
+        return await self.join("trades", payload, on_message)
+
+    async def markets(
+        self,
+        *,
+        rule_filters: Optional[Sequence[str]] = None,
+        message_types: Optional[Sequence[str]] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``markets``: ``market_created`` and ``market_updated`` for every
+        market. Each payload maps market id to a market object;
+        ``market_updated`` carries only the changed fields. Prices arrive in
+        cents on the wire and are converted to dollar strings here."""
+        payload = _drop_none(
+            {"rule_filters": _opt_list(rule_filters), "message_types": _opt_list(message_types)}
+        )
+        return await self.join("markets", payload, on_message)
+
+    async def market_stats(
+        self,
+        market_ids: Sequence[str],
+        *,
+        range: Optional[str] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``market_stats``: a price series per market. The history is in the
+        join reply (``channel.reply["markets"]``); ``market_stats`` pushes
+        changed buckets (upsert by ``timestamp_us``) and
+        ``market_stats_snapshot`` replaces a series."""
+        if not market_ids:
+            raise ValueError("market_stats needs at least one market id")
+        payload = _drop_none({"market_ids": list(market_ids), "range": range})
+        return await self.join("market_stats", payload, on_message)
+
+    async def market_updates(
+        self,
+        watch: Optional[Sequence[str]] = None,
+        *,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``market_updates``: ``created`` and ``updated`` for the markets you
+        watch. Nothing arrives until you watch something; pass ``watch=`` or
+        call ``channel.watch([...])``. Prices are converted from cents to
+        dollar strings here."""
+        channel = await self.join("market_updates", {}, on_message)
+        if watch:
+            await channel.watch(watch)
+        return channel
+
+    # ------------------------------------------------------------------
+    # Account channels
+    # ------------------------------------------------------------------
+
+    async def orders(
+        self,
+        *,
+        market_ids: Optional[Sequence[str]] = None,
+        cancel_on_disconnect: bool = False,
+        ping_timeout: Optional[int] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``orders:{user_id}``: ``all_orders`` on join, then ``new_open_order``.
+
+        ``cancel_on_disconnect=True`` arms cancel-on-disconnect for orders
+        placed with ``cancel_on_disconnect=True``. ``ping_timeout`` is in
+        milliseconds, clamped by the server to 5000 to 20000; the granted
+        value is in ``channel.reply["ping_timeout"]`` and the SDK pings at
+        60% of it for as long as the channel is joined.
+        """
+        payload: Dict[str, Any] = _drop_none({"market_ids": _opt_list(market_ids)})
+        if cancel_on_disconnect:
+            payload["cancel_on_disconnect"] = True
+            payload["ping_timeout"] = int(ping_timeout if ping_timeout is not None else 5000)
+        return await self._join_account("orders", payload, on_message)
+
+    async def fills(
+        self,
+        *,
+        market_ids: Optional[Sequence[str]] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``fills:{user_id}``: ``all_trades`` on join, then one ``trade`` per
+        execution or status change."""
+        payload = _drop_none({"market_ids": _opt_list(market_ids)})
+        return await self._join_account("fills", payload, on_message)
+
+    async def positions(
+        self,
+        *,
+        market_ids: Optional[Sequence[str]] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``positions:{user_id}``: ``all_positions`` on join, then
+        ``updated_positions`` deltas with only the changed positions."""
+        payload = _drop_none({"market_ids": _opt_list(market_ids)})
+        return await self._join_account("positions", payload, on_message)
+
+    async def settlements(
+        self,
+        *,
+        market_ids: Optional[Sequence[str]] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``settlements:{user_id}``: ``new_settlements`` as they are recorded.
+        No snapshot; history is ``AsyncSTX.settlements()``."""
+        payload = _drop_none({"market_ids": _opt_list(market_ids)})
+        return await self._join_account("settlements", payload, on_message)
+
+    async def balances(
+        self,
+        *,
+        account_id: Optional[str] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``balances:{user_id}``: ``balances`` on join, then ``update`` and
+        ``payment_update``. ``account_id`` picks one of your accounts."""
+        payload = _drop_none({"account_id": account_id})
+        return await self._join_account("balances", payload, on_message)
+
+    async def account(
+        self,
+        *,
+        market_ids: Optional[Sequence[str]] = None,
+        on_message: Optional[MessageHandler] = None,
+    ) -> Channel:
+        """``account:{user_id}``: everything the five channels above carry, on
+        one join. Do not also join a per-type channel (you would get every
+        message twice), and use ``orders`` if you need cancel-on-disconnect."""
+        payload = _drop_none({"market_ids": _opt_list(market_ids)})
+        return await self._join_account("account", payload, on_message)
+
+    async def user_info(self, *, on_message: Optional[MessageHandler] = None) -> Channel:
+        """``user_info:{user_id}``: ``user_updated`` right after joining, then
+        on every profile change."""
+        return await self._join_account("user_info", {}, on_message)
+
+    # ------------------------------------------------------------------
+    # Generic join
+    # ------------------------------------------------------------------
+
+    async def join(
+        self,
+        topic: str,
+        payload: Optional[Dict[str, Any]] = None,
+        on_message: Optional[MessageHandler] = None,
+        *,
+        ping_interval: Any = _UNSET,
+    ) -> Channel:
+        """Join ``topic`` with ``payload`` and wait for the reply.
+
+        Raises ``STXChannelException`` with the server's reason (for example
+        ``market_ids_required`` or ``unauthorized``) if the join is refused.
+        """
+        if topic in self.channels and not self.channels[topic].closed:
+            raise STXChannelException(f"Already joined {topic}", topic=topic)
+        await self.connect()
+        interval = self.channel_ping_interval if ping_interval is _UNSET else ping_interval
+        channel = Channel(
+            self, topic, payload or {}, on_message,
+            ping_interval=interval, queue_size=self.queue_size,
+        )  # fmt: skip
+        self.channels[topic] = channel
+        try:
+            await self._join(channel)
+        except BaseException:
+            self.channels.pop(topic, None)
+            channel._close()
+            raise
+        return channel
+
+    async def _join_account(
+        self, name: str, payload: Dict[str, Any], on_message: Optional[MessageHandler]
+    ) -> Channel:
+        if self.credentials is None:
+            raise STXConfigException(
+                f"The {name} channel is private and needs an API key; the socket "
+                "must be signed. Configure key_id and private_key."
+            )
+        return await self.join(f"{name}:{await self.user_id()}", payload, on_message)
+
+    async def _join(self, channel: Channel) -> None:
+        ref = str(next(self._refs))
+        channel.join_ref = ref
+        channel._reset_for_rejoin()
+        # A join's ref doubles as its join_ref, as Phoenix clients do.
+        reply = await self._request(channel.topic, "phx_join", channel.join_payload, ref, ref=ref)
+        channel.reply = reply if isinstance(reply, dict) else {"response": reply}
+        channel.joined = True
+        if channel.watches:
+            await channel.push("watch", list(channel.watches))
+        channel._start_pinger()
+
+    async def _leave(self, channel: Channel) -> None:
+        # Marked closed first so the server's phx_close is not taken as a
+        # reason to rejoin.
+        channel.closed = True
+        if channel.joined and self._connected.is_set():
+            try:
+                await self._request(channel.topic, "phx_leave", {}, channel.join_ref, 5.0)
+            except Exception:
+                pass
+        channel._close()
+        self.channels.pop(channel.topic, None)
+
+    # ------------------------------------------------------------------
+    # Wire
+    # ------------------------------------------------------------------
+
+    async def _open(self) -> None:
+        # A fresh signature per connect: the timestamp must be within 30 s.
+        headers = {"User-Agent": USER_AGENT}
+        if self.credentials is not None:
+            headers.update(self.credentials.headers("GET", "/socket/websocket"))
+        kwargs: Dict[str, Any] = {_handshake_headers_kwarg(): headers, "max_size": None}
+        if self.url.startswith("wss://") and not self.verify_tls:
+            import ssl
+
+            ctx = ssl.create_default_context()
+            ctx.check_hostname = False
+            ctx.verify_mode = ssl.CERT_NONE
+            kwargs["ssl"] = ctx
+        try:
+            self._conn = await asyncio.wait_for(websockets.connect(self.url, **kwargs), 15.0)
+        except Exception as exc:
+            raise STXTransportException(f"Could not open {self.url}: {exc}") from exc
+        self._pending_heartbeat = None
+        self._connected.set()
+        self._reader = asyncio.ensure_future(self._read_loop())
+        self._heartbeat = asyncio.ensure_future(self._heartbeat_loop())
+        logger.debug("connected to %s", self.url)
+
+    async def _close_conn(self) -> None:
+        self._connected.clear()
+        conn, self._conn = self._conn, None
+        if conn is not None:
+            try:
+                await conn.close()
+            except Exception:
+                pass
+
+    async def _send(self, frame: List[Any]) -> None:
+        if self._conn is None or not self._connected.is_set():
+            raise STXTransportException("socket is not connected")
+        await self._conn.send(json.dumps(frame))
+
+    async def _request(
+        self,
+        topic: str,
+        event: str,
+        payload: Any,
+        join_ref: Optional[str],
+        timeout: Optional[float] = None,
+        ref: Optional[str] = None,
+    ) -> Any:
+        ref = ref or str(next(self._refs))
+        future: asyncio.Future[Any] = asyncio.get_running_loop().create_future()
+        self._state.pending[ref] = _Pending(future, topic, event)
+        try:
+            await self._send([join_ref, ref, topic, event, payload])
+            return await asyncio.wait_for(future, timeout or self.join_timeout)
+        except asyncio.TimeoutError:
+            raise STXChannelException(
+                f"No reply to {event} on {topic} within {timeout or self.join_timeout}s",
+                topic=topic,
+            ) from None
+        finally:
+            self._state.pending.pop(ref, None)
+
+    def _fail_pending(self, exc: Exception) -> None:
+        for pending in list(self._state.pending.values()):
+            if not pending.future.done():
+                pending.future.set_exception(exc)
+        self._state.pending.clear()
+
+    async def _read_loop(self) -> None:
+        conn = self._conn
+        try:
+            async for raw in conn:
+                try:
+                    frame = json.loads(raw)
+                    join_ref, ref, topic, event, payload = frame
+                except (ValueError, TypeError):
+                    logger.warning("unparseable frame: %r", raw[:200])
+                    continue
+                await self._dispatch(join_ref, ref, topic, event, payload)
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            logger.info("socket read ended: %s", exc)
+        finally:
+            if self._conn is conn:
+                self._connected.clear()
+
+    async def _dispatch(
+        self, join_ref: Any, ref: Any, topic: str, event: str, payload: Any
+    ) -> None:
+        if event == "phx_reply":
+            if topic == PHOENIX_TOPIC and ref == self._pending_heartbeat:
+                self._pending_heartbeat = None
+            pending = self._state.pending.get(str(ref)) if ref is not None else None
+            if pending is not None and not pending.future.done():
+                status = payload.get("status") if isinstance(payload, dict) else None
+                response = payload.get("response") if isinstance(payload, dict) else payload
+                if status == "ok":
+                    pending.future.set_result(response)
+                else:
+                    reason = response.get("reason") if isinstance(response, dict) else None
+                    pending.future.set_exception(
+                        STXChannelException(
+                            f"{pending.event} on {topic} failed: {reason or response}",
+                            topic=topic,
+                            reply=response,
+                        )
+                    )
+            return
+        channel = self.channels.get(topic)
+        if channel is None:
+            return
+        if (
+            join_ref is not None
+            and channel.join_ref is not None
+            and str(join_ref) != channel.join_ref
+        ):
+            return  # a frame for an earlier join of this topic
+        if event in ("phx_error", "phx_close"):
+            if not channel.closed and not self._closed:
+                logger.warning("%s: server sent %s; rejoining", topic, event)
+                channel._reset_for_rejoin()
+                task = asyncio.ensure_future(self._rejoin_later(channel))
+                self._tasks.add(task)
+                task.add_done_callback(self._tasks.discard)
+            return
+        if channel.name == "markets":
+            payload = convert_markets_frame(payload)
+        elif channel.name == "market_updates" and isinstance(payload, dict):
+            payload = convert_market_payload(payload)
+        await channel._deliver(ChannelMessage(topic, event, payload, ref, join_ref))
+
+    async def _rejoin_later(self, channel: Channel) -> None:
+        attempt = 1
+        while not channel.closed and not self._closed:
+            await asyncio.sleep(self.reconnect_policy.delay(attempt))
+            if not self._connected.is_set():
+                return  # the socket reconnect will rejoin it
+            try:
+                await self._join(channel)
+                return
+            except STXChannelException as exc:
+                logger.error("rejoin %s failed: %s", channel.topic, exc)
+                if isinstance(exc.reply, dict) and exc.reply.get("reason") == "unauthorized":
+                    channel._close()
+                    return
+            attempt += 1
+
+    async def _heartbeat_loop(self) -> None:
+        while self._connected.is_set():
+            await asyncio.sleep(self.heartbeat_interval)
+            if self._pending_heartbeat is not None:
+                logger.warning("heartbeat unanswered; reconnecting")
+                await self._close_conn()
+                return
+            ref = str(next(self._refs))
+            self._pending_heartbeat = ref
+            try:
+                await self._send([None, ref, PHOENIX_TOPIC, "heartbeat", {}])
+            except Exception:
+                await self._close_conn()
+                return
+
+    async def _supervise(self) -> None:
+        # Waits for the socket to drop, then reconnects and rejoins.
+        while not self._closed:
+            reader = self._reader
+            if reader is not None:
+                try:
+                    await reader
+                except asyncio.CancelledError:
+                    if self._closed:
+                        return
+                except Exception:
+                    pass
+            if self._closed:
+                return
+            await self._close_conn()
+            if self._heartbeat is not None:
+                self._heartbeat.cancel()
+            self._fail_pending(STXTransportException("socket dropped"))
+            for channel in self.channels.values():
+                channel._reset_for_rejoin()
+            if not self.reconnect:
+                await self._shutdown_after_drop()
+                return
+            if not await self._reconnect():
+                await self._shutdown_after_drop()
+                return
+
+    async def _reconnect(self) -> bool:
+        attempt = 1
+        while not self._closed:
+            policy = self.reconnect_policy
+            if policy.max_attempts is not None and attempt > policy.max_attempts:
+                logger.error("giving up after %d reconnect attempts", attempt - 1)
+                return False
+            await asyncio.sleep(policy.delay(attempt))
+            try:
+                await self._open()
+                for channel in list(self.channels.values()):
+                    if channel.closed:
+                        continue
+                    try:
+                        await self._join(channel)
+                    except STXChannelException as exc:
+                        logger.error("rejoin %s failed: %s", channel.topic, exc)
+                self.reconnects += 1
+                logger.info("reconnected (%d)", self.reconnects)
+                if self.on_reconnect is not None:
+                    result = self.on_reconnect()
+                    if inspect.isawaitable(result):
+                        await result
+                return True
+            except STXTransportException as exc:
+                logger.warning("reconnect attempt %d failed: %s", attempt, exc)
+                await self._close_conn()
+                attempt += 1
+        return False
+
+    async def _shutdown_after_drop(self) -> None:
+        for channel in list(self.channels.values()):
+            channel._close()
+        self._closed = True
+        self._closed_event.set()
+
+
+def _opt_list(value: Optional[Sequence[str]]) -> Optional[List[str]]:
+    return None if value is None else list(value)
+
+
+def _drop_none(payload: Dict[str, Any]) -> Dict[str, Any]:
+    return {k: v for k, v in payload.items() if v is not None}