stx-python 0.6.0rc1__py3-none-any.whl

stx/_async_client.py

@@ -0,0 +1,923 @@
+"""``AsyncSTX``: the asyncio REST client.
+
+Every method maps to one REST route under ``/api/v1`` and returns pydantic
+models from :mod:`stx.models`. Money and quantities are strings exactly as
+the API sends them (``"0.5600"``, ``"2.00"``).
+
+Transport is ``httpx``: one library serves this client and the sync
+:class:`stx.STX` wrapper, and its ``MockTransport`` lets the unit tests
+check each request byte for byte without a server.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from decimal import Decimal
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    AsyncIterator,
+    Awaitable,
+    Callable,
+    Dict,
+    List,
+    Mapping,
+    Optional,
+    Sequence,
+    Type,
+    TypeVar,
+    Union,
+)
+
+import httpx
+
+from stx import models
+from stx._config import base_url_for, socket_url_for
+from stx._http import PreparedRequest, build_request, decode_response, split_page
+from stx._operations import OPERATIONS
+from stx._paging import Page
+from stx._results import BatchOrderResult
+from stx._retry import RetryPolicy
+from stx._settings import _SENTINEL as _UNSET
+from stx._settings import resolve_settings
+from stx._signing import ApiKeyCredentials, Signer, credentials_from_settings
+from stx._version import USER_AGENT
+from stx.exceptions import (
+    STXConfigException,
+    STXException,
+    STXNotFoundException,
+    STXTransportException,
+)
+
+if TYPE_CHECKING:
+    from stx._ws import STXWebSocket
+
+logger = logging.getLogger("stx")
+
+T = TypeVar("T")
+
+StrList = Union[str, Sequence[str], None]
+Amount = Union[str, Decimal]
+
+# Fields POST /api/v1/orders accepts, from the NewOrder schema.
+_NEW_ORDER_FIELDS = frozenset(models.NewOrder.model_fields)
+
+
+def _amount(name: str, value: Any, *, required: bool) -> Optional[str]:
+    # Price and quantity go on the wire as strings. A float cannot carry an
+    # exact decimal, and the API refuses JSON numbers for both fields, so
+    # only str and Decimal are accepted here.
+    if value is None:
+        if required:
+            raise ValueError(f"{name} is required")
+        return None
+    if isinstance(value, bool) or not isinstance(value, (str, Decimal)):
+        raise TypeError(
+            f"{name} must be a decimal string such as {'0.56' if name == 'price' else '2'!r}, "
+            f"got {type(value).__name__}"
+        )
+    return str(value)
+
+
+def order_body(
+    market_id: str,
+    action: str,
+    order_type: str,
+    *,
+    price: Optional[Amount] = None,
+    quantity: Amount,
+    client_order_id: Optional[str] = None,
+    expiration: Optional[str] = None,
+    expiration_time: Optional[int] = None,
+    cancel_on_disconnect: Optional[bool] = None,
+    device_id: Optional[str] = None,
+) -> Dict[str, Any]:
+    """The JSON body for one new order. Fields left ``None`` are omitted."""
+    body: Dict[str, Any] = {
+        "market_id": market_id,
+        "action": action,
+        "order_type": order_type,
+        "quantity": _amount("quantity", quantity, required=True),
+    }
+    optional = {
+        "price": _amount("price", price, required=False),
+        "client_order_id": client_order_id,
+        "expiration": expiration,
+        "expiration_time": expiration_time,
+        "cancel_on_disconnect": cancel_on_disconnect,
+        "device_id": device_id,
+    }
+    body.update({k: v for k, v in optional.items() if v is not None})
+    return body
+
+
+def _normalize_order(order: Mapping[str, Any]) -> Dict[str, Any]:
+    unknown = set(order) - _NEW_ORDER_FIELDS
+    if unknown:
+        raise ValueError(
+            f"Unknown order fields {sorted(unknown)}; expected {sorted(_NEW_ORDER_FIELDS)}"
+        )
+    for key in ("market_id", "action", "order_type"):
+        if not order.get(key):
+            raise ValueError(f"{key} is required on every order")
+    fields = {k: v for k, v in order.items() if k not in ("market_id", "action", "order_type")}
+    return order_body(order["market_id"], order["action"], order["order_type"], **fields)
+
+
+def _ids(value: StrList) -> Optional[List[str]]:
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return [value]
+    return list(value)
+
+
+class AsyncSTX:
+    """Async client for the STX exchange.
+
+    Configuration comes from the arguments, then environment variables,
+    then a profile in ``~/.stx/credentials`` (see ``stx._settings``)::
+
+        async with AsyncSTX(profile="us-demo") as client:
+            me = await client.me()
+            page = await client.markets(status="open", limit=10)
+
+    Args:
+        region: with ``env``, picks a known host, e.g. ``region="us", env="demo"``.
+        env: the environment within ``region``, e.g. ``"demo"`` or ``"production"``.
+        host: a hostname or URL, overriding ``region``/``env``.
+        key_id: the API key id.
+        private_key: the key's Ed25519 private key (PEM text or a path to a
+            PEM file).
+        signer: instead of ``private_key``, a callable ``bytes -> bytes``
+            returning the raw Ed25519 signature (for keys in an HSM or KMS).
+        profile: section of ``~/.stx/credentials`` to read.
+        verify_tls: set ``False`` only for a local server.
+        retry: a :class:`stx.RetryPolicy`; ``stx.NO_RETRY`` disables retries.
+        timeout: seconds per HTTP request.
+        transport: an ``httpx.AsyncBaseTransport``, for tests.
+    """
+
+    def __init__(
+        self,
+        *,
+        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,
+        retry: Optional[RetryPolicy] = None,
+        timeout: float = 30.0,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        settings = resolve_settings(
+            region=region,
+            env=env,
+            host=host,
+            key_id=key_id,
+            private_key=private_key,
+            verify_tls=verify_tls,
+            profile=profile,
+        )
+        self.base_url = base_url_for(settings.region, settings.env, settings.host)
+        self.socket_url = socket_url_for(self.base_url)
+        self.profile = settings.profile_name
+        # A signer replaces key material; a key from the environment or a
+        # profile is ignored then, and only an explicit private_key conflicts.
+        key_material = settings.private_key
+        if signer is not None and private_key is _UNSET:
+            key_material = None
+        self.credentials: Optional[ApiKeyCredentials] = credentials_from_settings(
+            settings.key_id, key_material, signer
+        )
+        self.verify_tls = settings.verify_tls
+        self.retry = retry if retry is not None else RetryPolicy()
+        self.timeout = timeout
+        self._transport = transport
+        self._http: Optional[httpx.AsyncClient] = None
+        self._me: Optional[models.Me] = None
+        self._sleep: Callable[[float], Awaitable[None]] = asyncio.sleep
+
+    def __repr__(self) -> str:
+        key = self.credentials.key_id if self.credentials else None
+        return f"AsyncSTX(base_url={self.base_url!r}, key_id={key!r})"
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> AsyncSTX:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the HTTP connection pool. Safe to call twice."""
+        if self._http is not None:
+            await self._http.aclose()
+            self._http = None
+
+    def _client(self) -> httpx.AsyncClient:
+        if self._http is None:
+            self._http = httpx.AsyncClient(
+                base_url=self.base_url,
+                timeout=self.timeout,
+                verify=self.verify_tls,
+                transport=self._transport,
+                headers={"User-Agent": USER_AGENT, "Accept": "application/json"},
+            )
+        return self._http
+
+    # ------------------------------------------------------------------
+    # Transport
+    # ------------------------------------------------------------------
+
+    def _headers(self, request: PreparedRequest) -> Dict[str, str]:
+        if self.credentials is None:
+            raise STXConfigException(
+                "No API key configured. Pass key_id= and private_key= (or set "
+                "STX_KEY_ID and STX_PRIVATE_KEY, or use a profile in "
+                "~/.stx/credentials). Every request is signed."
+            )
+        headers = self.credentials.headers(request.method, request.path)
+        if request.body is not None:
+            headers["Content-Type"] = "application/json"
+        return headers
+
+    async def _send_once(self, request: PreparedRequest) -> Dict[str, Any]:
+        # A fresh signature per attempt: the timestamp must be within 30 s
+        # of the server clock, so a retried request is re-signed.
+        headers = self._headers(request)
+        started = time.monotonic()
+        try:
+            response = await self._client().request(
+                request.method, request.path, headers=headers, content=request.body
+            )
+        except httpx.TimeoutException as exc:
+            raise STXTransportException(
+                f"{request.method} {request.path} timed out after {self.timeout}s",
+                method=request.method,
+                path=request.path,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise STXTransportException(
+                f"{request.method} {request.path} failed: {exc}",
+                method=request.method,
+                path=request.path,
+            ) from exc
+        logger.debug(
+            "%s %s -> %s in %.0f ms",
+            request.method,
+            request.path,
+            response.status_code,
+            (time.monotonic() - started) * 1000,
+        )
+        return decode_response(
+            request, response.status_code, response.content, response.headers.get("Retry-After")
+        )
+
+    async def _send(self, request: PreparedRequest) -> Dict[str, Any]:
+        attempt = 1
+        while True:
+            try:
+                return await self._send_once(request)
+            except STXException as exc:
+                if not self.retry.should_retry(exc, attempt, request.idempotent):
+                    raise
+                delay = self.retry.compute_backoff(attempt, exc)
+                logger.info(
+                    "%s %s failed (%s); retrying in %.2fs", request.method, request.path, exc, delay
+                )
+                await self._sleep(delay)
+                attempt += 1
+
+    async def _call(self, operation_id: str, **kwargs: Any) -> Dict[str, Any]:
+        return await self._send(build_request(operation_id, **kwargs))
+
+    async def _one(self, operation_id: str, model: Type[T], **kwargs: Any) -> T:
+        body = await self._call(operation_id, **kwargs)
+        key = OPERATIONS[operation_id].response_key
+        return model.model_validate(body[key] if key else body)  # type: ignore[attr-defined]
+
+    async def _list(self, operation_id: str, model: Type[T], **kwargs: Any) -> List[T]:
+        body = await self._call(operation_id, **kwargs)
+        items, _ = split_page(operation_id, body)
+        return [model.model_validate(item) for item in items]  # type: ignore[attr-defined]
+
+    async def _page(self, operation_id: str, model: Type[T], query: Dict[str, Any]) -> Page[T]:
+        body = await self._call(operation_id, query=query)
+        items, cursor = split_page(operation_id, body)
+        return Page([model.model_validate(item) for item in items], cursor)  # type: ignore[attr-defined]
+
+    async def _iterate(
+        self, operation_id: str, model: Type[T], query: Dict[str, Any]
+    ) -> AsyncIterator[T]:
+        query = dict(query)
+        while True:
+            page = await self._page(operation_id, model, query)
+            for item in page:
+                yield item
+            if not page.cursor:
+                return
+            query["cursor"] = page.cursor
+
+    # ------------------------------------------------------------------
+    # Identity
+    # ------------------------------------------------------------------
+
+    async def me(self) -> models.Me:
+        """``GET /api/v1/me``: who this key belongs to.
+
+        Returns the ``user_id`` the account channels are keyed by, the
+        ``account_id``, and the key's ``scope`` (``read_only`` or
+        ``read_write``).
+        """
+        self._me = await self._one("me_get", models.Me)
+        return self._me
+
+    async def user_id(self) -> str:
+        """The user id from :meth:`me`, fetched once and cached."""
+        if self._me is None or not self._me.user_id:
+            await self.me()
+        assert self._me is not None and self._me.user_id
+        return self._me.user_id
+
+    # ------------------------------------------------------------------
+    # Markets and events
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _markets_query(
+        market_ids: StrList,
+        event_ids: StrList,
+        status: StrList,
+        trading: Optional[bool],
+        sports: StrList,
+        competitions: StrList,
+        sort_by: Optional[str],
+        sort_direction: Optional[str],
+        limit: Optional[int],
+        cursor: Optional[str],
+    ) -> Dict[str, Any]:
+        return {
+            "market_ids": _ids(market_ids),
+            "event_ids": _ids(event_ids),
+            "status": _ids(status),
+            "trading": trading,
+            "sports": _ids(sports),
+            "competitions": _ids(competitions),
+            "sort_by[name]": sort_by,
+            "sort_by[direction]": sort_direction,
+            "limit": limit,
+            "cursor": cursor,
+        }
+
+    async def markets(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        status: StrList = None,
+        trading: Optional[bool] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Market]:
+        """``GET /api/v1/markets``: one page of markets.
+
+        Filters combine with AND; list filters match any value. ``status``
+        takes one status or a list (``["pre_open", "open"]``). ``sort_by``
+        is ``"event_start"`` with ``sort_direction`` ``"asc"`` or
+        ``"desc"``. ``limit`` defaults to 100, maximum 200.
+        """
+        query = self._markets_query(
+            market_ids, event_ids, status, trading, sports, competitions,
+            sort_by, sort_direction, limit, cursor,
+        )  # fmt: skip
+        return await self._page("markets_get", models.Market, query)
+
+    def iter_markets(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        status: StrList = None,
+        trading: Optional[bool] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[models.Market]:
+        """Every market matching the filters, following the cursor."""
+        query = self._markets_query(
+            market_ids, event_ids, status, trading, sports, competitions,
+            sort_by, sort_direction, limit, None,
+        )  # fmt: skip
+        return self._iterate("markets_get", models.Market, query)
+
+    async def market(self, market_id: str) -> models.Market:
+        """One market by id. Raises ``STXNotFoundException`` if there is none."""
+        page = await self.markets(market_ids=[market_id], limit=1)
+        if not page.items:
+            raise STXNotFoundException(f"Market {market_id} not found", status_code=404)
+        return page.items[0]
+
+    @staticmethod
+    def _events_query(
+        event_ids: StrList,
+        sports: StrList,
+        competitions: StrList,
+        event_types: StrList,
+        title: Optional[str],
+        status: Optional[str],
+        promoted: Optional[bool],
+        sort_by: Optional[str],
+        sort_direction: Optional[str],
+        limit: Optional[int],
+        cursor: Optional[str],
+    ) -> Dict[str, Any]:
+        return {
+            "event_ids": _ids(event_ids),
+            "sports": _ids(sports),
+            "competitions": _ids(competitions),
+            "event_types": _ids(event_types),
+            "title": title,
+            "status": status,
+            "promoted": promoted,
+            "sort_by[name]": sort_by,
+            "sort_by[direction]": sort_direction,
+            "limit": limit,
+            "cursor": cursor,
+        }
+
+    async def events(
+        self,
+        *,
+        event_ids: StrList = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        event_types: StrList = None,
+        title: Optional[str] = None,
+        status: Optional[str] = None,
+        promoted: Optional[bool] = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Event]:
+        """``GET /api/v1/events``: one page of events.
+
+        ``status`` is one of ``scheduled``, ``in_progress``, ``completed``,
+        ``cancelled``. ``sort_by`` is ``"start_time"``.
+        """
+        query = self._events_query(
+            event_ids, sports, competitions, event_types, title, status,
+            promoted, sort_by, sort_direction, limit, cursor,
+        )  # fmt: skip
+        return await self._page("events_get", models.Event, query)
+
+    def iter_events(
+        self,
+        *,
+        event_ids: StrList = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        event_types: StrList = None,
+        title: Optional[str] = None,
+        status: Optional[str] = None,
+        promoted: Optional[bool] = None,
+        sort_by: Optional[str] = None,
+        sort_direction: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[models.Event]:
+        """Every event matching the filters, following the cursor."""
+        query = self._events_query(
+            event_ids, sports, competitions, event_types, title, status,
+            promoted, sort_by, sort_direction, limit, None,
+        )  # fmt: skip
+        return self._iterate("events_get", models.Event, query)
+
+    # ------------------------------------------------------------------
+    # Orders
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _orders_query(
+        order_ids: StrList,
+        client_order_ids: StrList,
+        market_ids: StrList,
+        status: StrList,
+        limit: Optional[int],
+        cursor: Optional[str],
+    ) -> Dict[str, Any]:
+        return {
+            "order_ids": _ids(order_ids),
+            "client_order_ids": _ids(client_order_ids),
+            "market_ids": _ids(market_ids),
+            "status": _ids(status),
+            "limit": limit,
+            "cursor": cursor,
+        }
+
+    async def orders(
+        self,
+        *,
+        order_ids: StrList = None,
+        client_order_ids: StrList = None,
+        market_ids: StrList = None,
+        status: StrList = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Order]:
+        """``GET /api/v1/orders``: one page of your orders, newest first.
+
+        ``status`` takes one status or a list, e.g. ``["open", "delayed"]``.
+        """
+        query = self._orders_query(order_ids, client_order_ids, market_ids, status, limit, cursor)
+        return await self._page("orders_get", models.Order, query)
+
+    def iter_orders(
+        self,
+        *,
+        order_ids: StrList = None,
+        client_order_ids: StrList = None,
+        market_ids: StrList = None,
+        status: StrList = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[models.Order]:
+        """Every order matching the filters, following the cursor."""
+        query = self._orders_query(order_ids, client_order_ids, market_ids, status, limit, None)
+        return self._iterate("orders_get", models.Order, query)
+
+    async def order(self, order_id: str) -> models.Order:
+        """``GET /api/v1/orders/{order_id}``: one of your orders."""
+        return await self._one("orders__id_get", models.Order, path_params={"order_id": order_id})
+
+    async def place_order(
+        self,
+        market_id: str,
+        action: str,
+        order_type: str,
+        *,
+        price: Optional[Amount] = None,
+        quantity: Amount,
+        client_order_id: Optional[str] = None,
+        expiration: Optional[str] = None,
+        expiration_time: Optional[int] = None,
+        cancel_on_disconnect: Optional[bool] = None,
+        device_id: Optional[str] = None,
+    ) -> models.Order:
+        """``POST /api/v1/orders``: place one order.
+
+        ``action`` is ``"buy"`` or ``"sell"``; ``order_type`` is ``"limit"``
+        or ``"market"``. ``price`` (dollars, required for a limit order) and
+        ``quantity`` (contracts) are decimal strings, e.g.
+        ``price="0.56", quantity="2"``. Floats are refused client-side.
+
+        ``expiration`` is ``"good_till_start"`` or ``"good_till_time"``; the
+        latter needs ``expiration_time`` in Unix **microseconds**.
+        ``cancel_on_disconnect=True`` opts this order into cancel-on-
+        disconnect, which also needs the ``orders`` channel joined with it
+        armed (see :meth:`stx.STXWebSocket.orders`).
+
+        The exchange validates the order: a bad price step or a fractional
+        quantity raises ``STXValidationException`` (400) or
+        ``STXRejectedException`` (422) with the API's message.
+
+        A ``POST`` is never retried after a 5xx or a dropped connection;
+        pass ``client_order_id`` so you can look the order up if that
+        happens.
+        """
+        body = order_body(
+            market_id,
+            action,
+            order_type,
+            price=price,
+            quantity=quantity,
+            client_order_id=client_order_id,
+            expiration=expiration,
+            expiration_time=expiration_time,
+            cancel_on_disconnect=cancel_on_disconnect,
+            device_id=device_id,
+        )
+        return await self._one("orders_post", models.Order, body=body)
+
+    async def place_orders(
+        self,
+        orders: Sequence[Mapping[str, Any]],
+        *,
+        geo_location: Optional[str] = None,
+    ) -> List[BatchOrderResult]:
+        """``POST /api/v1/orders/batched``: place several orders in one call.
+
+        Each order is a dict with the same fields as :meth:`place_order`::
+
+            await client.place_orders([
+                {"market_id": m, "action": "buy", "order_type": "limit",
+                 "price": "0.01", "quantity": "1"},
+                {"market_id": m, "action": "buy", "order_type": "limit",
+                 "price": "0.02", "quantity": "1"},
+            ])
+
+        Returns one :class:`stx.BatchOrderResult` per order, in order; a
+        rejected order has ``errors`` instead of ``order`` and does not stop
+        the others.
+        """
+        body: Dict[str, Any] = {"orders": [_normalize_order(o) for o in orders]}
+        if geo_location is not None:
+            body["geo_location"] = geo_location
+        return await self._list("orders_batched_post", BatchOrderResult, body=body)
+
+    async def cancel_order(self, order_id: str) -> models.Cancellation:
+        """``DELETE /api/v1/orders/{order_id}``: request a cancel.
+
+        A cancel is a request: a fill already in flight can still land.
+        """
+        return await self._one(
+            "orders__order_id_delete", models.Cancellation, path_params={"order_id": order_id}
+        )
+
+    async def cancel_orders(self, order_ids: Sequence[str]) -> List[models.Cancellation]:
+        """``DELETE /api/v1/orders/batched``: cancel the named orders."""
+        body = {"orders": [{"order_id": oid} for oid in order_ids]}
+        return await self._list("orders_batched_delete", models.Cancellation, body=body)
+
+    async def cancel_all_orders(self) -> List[models.Cancellation]:
+        """``DELETE /api/v1/orders/all``: cancel everything resting on the account."""
+        return await self._list("orders_all_delete", models.Cancellation)
+
+    # ------------------------------------------------------------------
+    # Fills, positions, balance
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _fills_query(
+        market_ids: StrList,
+        order_ids: StrList,
+        status: Optional[str],
+        limit: Optional[int],
+        cursor: Optional[str],
+    ) -> Dict[str, Any]:
+        return {
+            "market_ids": _ids(market_ids),
+            "order_ids": _ids(order_ids),
+            "status": status,
+            "limit": limit,
+            "cursor": cursor,
+        }
+
+    async def fills(
+        self,
+        *,
+        market_ids: StrList = None,
+        order_ids: StrList = None,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Fill]:
+        """``GET /api/v1/fills``: one page of your executions.
+
+        ``order_ids`` narrows to the fills of those orders. ``status`` is
+        one of ``created``, ``open``, ``settled``, ``cancelled``.
+        """
+        query = self._fills_query(market_ids, order_ids, status, limit, cursor)
+        return await self._page("fills_get", models.Fill, query)
+
+    def iter_fills(
+        self,
+        *,
+        market_ids: StrList = None,
+        order_ids: StrList = None,
+        status: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[models.Fill]:
+        """Every fill matching the filters, following the cursor."""
+        query = self._fills_query(market_ids, order_ids, status, limit, None)
+        return self._iterate("fills_get", models.Fill, query)
+
+    async def positions(self, *, market_ids: StrList = None) -> List[models.Position]:
+        """``GET /api/v1/positions``: your open positions.
+
+        The same objects the ``positions`` channel sends on join.
+        ``position`` is positive when long, negative when short.
+        """
+        return await self._list(
+            "positions_get", models.Position, query={"market_ids": _ids(market_ids)}
+        )
+
+    async def balance(self) -> models.Balance:
+        """``GET /api/v1/account/balance``: balance, liabilities and fee schedule.
+
+        The same object the ``balances`` channel pushes.
+        """
+        return await self._one("account_balance_get", models.Balance)
+
+    @staticmethod
+    def _market_stats_query(
+        market_ids: StrList,
+        event_ids: StrList,
+        exclude_zero_settlements: Optional[bool],
+        from_time: Optional[int],
+        to_time: Optional[int],
+        sports: StrList,
+        competitions: StrList,
+        limit: Optional[int],
+        cursor: Optional[str],
+    ) -> Dict[str, Any]:
+        return {
+            "market_ids": _ids(market_ids),
+            "event_ids": _ids(event_ids),
+            "exclude_zero_settlements": exclude_zero_settlements,
+            "from_time": from_time,
+            "to_time": to_time,
+            "sports": _ids(sports),
+            "competitions": _ids(competitions),
+            "limit": limit,
+            "cursor": cursor,
+        }
+
+    async def account_market_stats(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        exclude_zero_settlements: Optional[bool] = None,
+        from_time: Optional[int] = None,
+        to_time: Optional[int] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.MarketStat]:
+        """``GET /api/v1/account/market_stats``: your exposure and P&L per market.
+
+        Not the public ``market_stats`` channel, which carries prices.
+        """
+        query = self._market_stats_query(
+            market_ids, event_ids, exclude_zero_settlements, from_time, to_time,
+            sports, competitions, limit, cursor,
+        )  # fmt: skip
+        return await self._page("account_market_stats_get", models.MarketStat, query)
+
+    def iter_account_market_stats(
+        self,
+        *,
+        market_ids: StrList = None,
+        event_ids: StrList = None,
+        exclude_zero_settlements: Optional[bool] = None,
+        from_time: Optional[int] = None,
+        to_time: Optional[int] = None,
+        sports: StrList = None,
+        competitions: StrList = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[models.MarketStat]:
+        """Every per-market stat row, following the cursor."""
+        query = self._market_stats_query(
+            market_ids, event_ids, exclude_zero_settlements, from_time, to_time,
+            sports, competitions, limit, None,
+        )  # fmt: skip
+        return self._iterate("account_market_stats_get", models.MarketStat, query)
+
+    # ------------------------------------------------------------------
+    # Portfolio history
+    # ------------------------------------------------------------------
+
+    async def settlements(
+        self,
+        *,
+        market_ids: StrList = None,
+        type: Optional[str] = None,
+        limit: Optional[int] = None,
+        cursor: Optional[str] = None,
+    ) -> Page[models.Settlement]:
+        """``GET /api/v1/portfolio/settlements``: settlements on your account.
+
+        ``type`` is one of ``closed_short``, ``closed_long``,
+        ``expired_short``, ``expired_long``.
+        """
+        query = {"market_ids": _ids(market_ids), "type": type, "limit": limit, "cursor": cursor}
+        return await self._page("portfolio_settlements_get", models.Settlement, query)
+
+    def iter_settlements(
+        self,
+        *,
+        market_ids: StrList = None,
+        type: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> AsyncIterator[models.Settlement]:
+        """Every settlement, following the cursor."""
+        query = {"market_ids": _ids(market_ids), "type": type, "limit": limit}
+        return self._iterate("portfolio_settlements_get", models.Settlement, query)
+
+    async def deposits(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.PaymentTransaction]:
+        """``GET /api/v1/portfolio/deposits``."""
+        query = {"limit": limit, "cursor": cursor}
+        return await self._page("portfolio_deposits_get", models.PaymentTransaction, query)
+
+    def iter_deposits(
+        self, *, limit: Optional[int] = None
+    ) -> AsyncIterator[models.PaymentTransaction]:
+        """Every deposit, following the cursor."""
+        return self._iterate("portfolio_deposits_get", models.PaymentTransaction, {"limit": limit})
+
+    async def withdrawals(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.PaymentTransaction]:
+        """``GET /api/v1/portfolio/withdrawals``."""
+        query = {"limit": limit, "cursor": cursor}
+        return await self._page("portfolio_withdrawals_get", models.PaymentTransaction, query)
+
+    def iter_withdrawals(
+        self, *, limit: Optional[int] = None
+    ) -> AsyncIterator[models.PaymentTransaction]:
+        """Every withdrawal, following the cursor."""
+        return self._iterate(
+            "portfolio_withdrawals_get", models.PaymentTransaction, {"limit": limit}
+        )
+
+    async def adjustments(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.PaymentTransaction]:
+        """``GET /api/v1/portfolio/adjustments``: manual balance adjustments."""
+        query = {"limit": limit, "cursor": cursor}
+        return await self._page("portfolio_adjustments_get", models.PaymentTransaction, query)
+
+    def iter_adjustments(
+        self, *, limit: Optional[int] = None
+    ) -> AsyncIterator[models.PaymentTransaction]:
+        """Every adjustment, following the cursor."""
+        return self._iterate(
+            "portfolio_adjustments_get", models.PaymentTransaction, {"limit": limit}
+        )
+
+    async def fees(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.FeeTransaction]:
+        """``GET /api/v1/portfolio/fees``: fee and fee-refund entries."""
+        query = {"limit": limit, "cursor": cursor}
+        return await self._page("portfolio_fees_get", models.FeeTransaction, query)
+
+    def iter_fees(self, *, limit: Optional[int] = None) -> AsyncIterator[models.FeeTransaction]:
+        """Every fee entry, following the cursor."""
+        return self._iterate("portfolio_fees_get", models.FeeTransaction, {"limit": limit})
+
+    async def loyalty(
+        self, *, limit: Optional[int] = None, cursor: Optional[str] = None
+    ) -> Page[models.Transaction]:
+        """``GET /api/v1/portfolio/loyalty``: loyalty entries."""
+        query = {"limit": limit, "cursor": cursor}
+        return await self._page("portfolio_loyalty_get", models.Transaction, query)
+
+    def iter_loyalty(self, *, limit: Optional[int] = None) -> AsyncIterator[models.Transaction]:
+        """Every loyalty entry, following the cursor."""
+        return self._iterate("portfolio_loyalty_get", models.Transaction, {"limit": limit})
+
+    # ------------------------------------------------------------------
+    # Terms
+    # ------------------------------------------------------------------
+
+    async def accept_terms(
+        self,
+        device_id: str,
+        *,
+        accept_terms: bool = True,
+        accept_privacy: bool = True,
+        accept_house_rules: Optional[bool] = None,
+    ) -> str:
+        """``POST /api/v1/tnc/accept``: accept the current terms. Returns the
+        server's message."""
+        body: Dict[str, Any] = {
+            "device_id": device_id,
+            "accept_terms": accept_terms,
+            "accept_privacy": accept_privacy,
+        }
+        if accept_house_rules is not None:
+            body["accept_house_rules"] = accept_house_rules
+        result = await self._call("tnc_accept_post", body=body)
+        return str(result.get("message", ""))
+
+    # ------------------------------------------------------------------
+    # WebSocket
+    # ------------------------------------------------------------------
+
+    def websocket(self, **kwargs: Any) -> STXWebSocket:
+        """An :class:`stx.STXWebSocket` using this client's host and key.
+
+        Account channels need your user id; the socket fetches it through
+        this client's :meth:`me` on first use.
+        """
+        from stx._ws import STXWebSocket
+
+        return STXWebSocket(rest=self, **kwargs)