crowdbook 0.13.0__tar.gz

crowdbook-0.13.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christopher Lee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

crowdbook-0.13.0/PKG-INFO

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: crowdbook
+Version: 0.13.0
+Summary: Trade in a crowdbook market from Python, by hand or with a bot
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# crowdbook for Python
+
+Trade in a market served by `crowdbook serve`, from Python, by hand or with a bot. The package
+uses only the standard library and needs Python 3.11 or later.
+
+```bash
+pip install ./clients/python
+```
+
+A bot overrides the callbacks it needs and acts through its methods:
+
+```python
+import crowdbook
+
+class DipBuyer(crowdbook.Bot):
+    def on_trade(self, trade):
+        if trade.price < self.settings.reference_price - 5 and self.ledger.position < 10:
+            self.buy_market(1)
+
+end = crowdbook.run(DipBuyer(), host="127.0.0.1", port=7878, seat="alice")
+print(end.pnl)
+```
+
+- **Callbacks:** `on_start`, `on_wakeup`, `on_trade`, `on_top`, `on_depth`, `on_phase`,
+  `on_indicative`, `on_accepted`, `on_rejected`, `on_modified`, `on_filled`, `on_cancelled`,
+  `on_error` and `on_end`, each with the message as it arrived.
+- **Actions:** `buy` and `sell` at a limit price, with a time in force (`good-till-cancel`,
+  `immediate-or-cancel` or `post-only`), `buy_market` and `sell_market`, `cancel`, `cancel_all`
+  and `modify`. Orders are named by ids the bot gives them, so a bot can cancel an order before
+  it is acknowledged. `wake_after` asks for `on_wakeup` after a stretch of the market's time.
+- **State:** `ledger` holds the seat's cash, position, fees and orders, built from what the bot
+  sent and heard back; `book` the best prices, the depth, the last trade and, in a market with a
+  trading day, the phase and, in an auction, the indicative price; `settings` the
+  market's length, reference price, fees, latency and the seat's limits; `now` the market's time
+  in nanoseconds.
+
+Lower down, `crowdbook.Connection` sends and receives the protocol's messages, defined in
+`crowdbook.protocol`; [docs/protocol.md](../../docs/protocol.md) specifies them.
+
+[examples](examples) has a market maker, a trend follower and an execution algorithm that works a
+challenge's target evenly over the session. Each runs against a served market:
+
+```bash
+./build/release/apps/crowdbook serve examples/scenarios/playable.toml --seat maker --seat trend
+python clients/python/examples/market_maker.py --seat maker
+python clients/python/examples/momentum.py --seat trend
+```
+
+A seat in a scored challenge gets the challenge's name, briefing and scoring rules in
+`settings.challenge` and `settings.scoring`, and its score at the end, in points, in the `End`
+that `run` returns.
+
+The tests run with `python -m unittest discover -s tests` from this directory; the ones that
+trade against a real server need `CROWDBOOK` set to the `crowdbook` command, as CTest does.

crowdbook-0.13.0/README.md

@@ -0,0 +1,54 @@
+# crowdbook for Python
+
+Trade in a market served by `crowdbook serve`, from Python, by hand or with a bot. The package
+uses only the standard library and needs Python 3.11 or later.
+
+```bash
+pip install ./clients/python
+```
+
+A bot overrides the callbacks it needs and acts through its methods:
+
+```python
+import crowdbook
+
+class DipBuyer(crowdbook.Bot):
+    def on_trade(self, trade):
+        if trade.price < self.settings.reference_price - 5 and self.ledger.position < 10:
+            self.buy_market(1)
+
+end = crowdbook.run(DipBuyer(), host="127.0.0.1", port=7878, seat="alice")
+print(end.pnl)
+```
+
+- **Callbacks:** `on_start`, `on_wakeup`, `on_trade`, `on_top`, `on_depth`, `on_phase`,
+  `on_indicative`, `on_accepted`, `on_rejected`, `on_modified`, `on_filled`, `on_cancelled`,
+  `on_error` and `on_end`, each with the message as it arrived.
+- **Actions:** `buy` and `sell` at a limit price, with a time in force (`good-till-cancel`,
+  `immediate-or-cancel` or `post-only`), `buy_market` and `sell_market`, `cancel`, `cancel_all`
+  and `modify`. Orders are named by ids the bot gives them, so a bot can cancel an order before
+  it is acknowledged. `wake_after` asks for `on_wakeup` after a stretch of the market's time.
+- **State:** `ledger` holds the seat's cash, position, fees and orders, built from what the bot
+  sent and heard back; `book` the best prices, the depth, the last trade and, in a market with a
+  trading day, the phase and, in an auction, the indicative price; `settings` the
+  market's length, reference price, fees, latency and the seat's limits; `now` the market's time
+  in nanoseconds.
+
+Lower down, `crowdbook.Connection` sends and receives the protocol's messages, defined in
+`crowdbook.protocol`; [docs/protocol.md](../../docs/protocol.md) specifies them.
+
+[examples](examples) has a market maker, a trend follower and an execution algorithm that works a
+challenge's target evenly over the session. Each runs against a served market:
+
+```bash
+./build/release/apps/crowdbook serve examples/scenarios/playable.toml --seat maker --seat trend
+python clients/python/examples/market_maker.py --seat maker
+python clients/python/examples/momentum.py --seat trend
+```
+
+A seat in a scored challenge gets the challenge's name, briefing and scoring rules in
+`settings.challenge` and `settings.scoring`, and its score at the end, in points, in the `End`
+that `run` returns.
+
+The tests run with `python -m unittest discover -s tests` from this directory; the ones that
+trade against a real server need `CROWDBOOK` set to the `crowdbook` command, as CTest does.

crowdbook-0.13.0/pyproject.toml

@@ -0,0 +1,13 @@
+[project]
+name = "crowdbook"
+version = "0.13.0"
+description = "Trade in a crowdbook market from Python, by hand or with a bot"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.8,<0.12"]
+build-backend = "uv_build"

crowdbook-0.13.0/pyproject.toml.orig

@@ -0,0 +1,13 @@
+[project]
+name = "crowdbook"
+version = "0.13.0"
+description = "Trade in a crowdbook market from Python, by hand or with a bot"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.8,<0.12"]
+build-backend = "uv_build"

crowdbook-0.13.0/src/crowdbook/__init__.py

@@ -0,0 +1,15 @@
+"""A client for crowdbook: trade in a served market from Python.
+
+    import crowdbook
+
+    class Buyer(crowdbook.Bot):
+        def on_start(self):
+            self.buy_market(5)
+
+    crowdbook.run(Buyer(), port=7878, seat="alice")
+"""
+
+from .client import Book, Bot, Connection, Ledger, Order, run
+from .protocol import ProtocolError
+
+__all__ = ["Book", "Bot", "Connection", "Ledger", "Order", "ProtocolError", "run"]

crowdbook-0.13.0/src/crowdbook/client.py

@@ -0,0 +1,334 @@
+"""Trading in a served crowdbook market: the connection, the seat's own books, and bots."""
+
+from __future__ import annotations
+
+import heapq
+import itertools
+import select
+import socket
+from dataclasses import dataclass
+from typing import Optional
+
+from . import protocol
+from .protocol import (AUCTIONS, Accepted, Cancel, Cancelled, ClientMessage, Clock, Depth, End,
+                       Error, Filled, Hello, Indicative, Level, Modified, Modify, NewOrder,
+                       OrderEvent, PhaseChange, Rejected, ServerMessage, Side, Start,
+                       TimeInForce, Top, Trade, Welcome)
+
+
+@dataclass
+class Order:
+    """One of the seat's own orders, as the client knows it."""
+
+    id: int
+    side: Side
+    order_type: str
+    price: Optional[int]
+    leaves: int  # open quantity as last reported; the full size until acknowledged
+    order_id: int = 0  # the exchange's id, 0 until acknowledged
+    acknowledged: bool = False
+    cancel_requested: bool = False
+
+
+class Ledger:
+    """The seat's cash, position, fees and orders, built only from the requests the client sent
+    and the order events it received. With latency it lags the exchange: orders are in flight
+    until acknowledged, and a cancel can cross a fill."""
+
+    def __init__(self, cash: int = 0, position: int = 0, fees: int = 0) -> None:
+        self.cash = cash
+        self.position = position
+        self.fees = fees  # in thousandths of a tick-lot, net of rebates
+        self.orders: dict[int, Order] = {}  # open or in flight, by the client's id
+
+    def record(self, message: ClientMessage) -> None:
+        """Records a request the client is sending. Raises ValueError for a new order whose id
+        is already live."""
+        if isinstance(message, NewOrder):
+            if message.id in self.orders:
+                raise ValueError(f"order id {message.id} is already live")
+            self.orders[message.id] = Order(id=message.id, side=message.side,
+                                            order_type=message.order_type, price=message.price,
+                                            leaves=message.quantity)
+        elif isinstance(message, Cancel) and message.id in self.orders:
+            self.orders[message.id].cancel_requested = True
+        # A modify changes nothing until the exchange confirms it.
+
+    def apply(self, event: OrderEvent) -> None:
+        """Applies one of the seat's order events. Raises KeyError for an event about an order
+        the client never sent."""
+        if isinstance(event, Accepted):
+            order = self.orders[event.id]
+            order.acknowledged = True
+            order.order_id = event.order_id
+        elif isinstance(event, Rejected):
+            if event.request == "new":
+                del self.orders[event.id]
+            elif event.request == "cancel" and event.id in self.orders:
+                # The cancel failed; an order that is gone finished while it was on its way.
+                self.orders[event.id].cancel_requested = False
+        elif isinstance(event, Modified):
+            order = self.orders[event.id]
+            order.price = event.price
+            order.leaves = event.quantity
+        elif isinstance(event, Filled):
+            order = self.orders[event.id]
+            sign = 1 if event.side == "buy" else -1
+            self.position += sign * event.quantity
+            self.cash -= sign * event.price * event.quantity
+            self.fees += event.fee
+            order.leaves = event.leaves
+            if order.leaves == 0:
+                del self.orders[event.id]
+        elif isinstance(event, Cancelled):
+            del self.orders[event.id]
+
+    def open_quantity(self, side: Side) -> int:
+        """Open quantity on one side, including orders still in flight."""
+        return sum(order.leaves for order in self.orders.values() if order.side == side)
+
+
+class Book:
+    """The public market as the client has heard it: best prices, depth, the last trade, and in
+    a market with a trading day its phase and, during an auction, the indicative price."""
+
+    def __init__(self) -> None:
+        self.bid: Optional[Level] = None
+        self.ask: Optional[Level] = None
+        self.bids: tuple[Level, ...] = ()  # best first; empty without a depth feed
+        self.asks: tuple[Level, ...] = ()
+        self.last_price: Optional[int] = None
+        self.trades = 0
+        self.volume = 0
+        self.phase = "continuous"
+        self.indicative: Optional[Indicative] = None
+
+    @property
+    def in_auction(self) -> bool:
+        return self.phase in AUCTIONS
+
+    def apply(self, message: ServerMessage) -> None:
+        if isinstance(message, PhaseChange):
+            self.phase = message.phase
+            if not self.in_auction:
+                self.indicative = None
+        elif isinstance(message, Indicative):
+            self.indicative = message if message.price is not None else None
+        elif isinstance(message, Trade):
+            self.last_price = message.price
+            self.trades += 1
+            self.volume += message.quantity
+        elif isinstance(message, Top):
+            self.bid, self.ask = message.bid, message.ask
+        elif isinstance(message, Depth):
+            self.bids, self.asks = message.bids, message.asks
+
+    @property
+    def mid(self) -> Optional[float]:
+        if self.bid is None or self.ask is None:
+            return None
+        return (self.bid.price + self.ask.price) / 2
+
+
+class Connection:
+    """A TCP connection to a crowdbook server that sends and receives whole messages."""
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 7878, timeout: float = 10.0) -> None:
+        self._socket = socket.create_connection((host, port), timeout=timeout)
+        self._socket.setsockopt(socket.IPPROTO_TCP, socket.TCP_NODELAY, 1)
+        self._buffer = b""
+        self.closed = False
+
+    def send(self, message: ClientMessage) -> bool:
+        """Sends a message. Returns False, and marks the connection closed, if the server has
+        gone."""
+        if self.closed:
+            return False
+        try:
+            self._socket.sendall(protocol.encode(message).encode("ascii"))
+        except (BrokenPipeError, ConnectionResetError):
+            self.closed = True
+            return False
+        return True
+
+    def receive(self, timeout: float) -> list[ServerMessage]:
+        """The messages that arrive within `timeout` seconds, as soon as there is at least one;
+        none if the time runs out or the server has closed the connection."""
+        messages: list[ServerMessage] = []
+        while not messages and not self.closed:
+            ready, _, _ = select.select([self._socket], [], [], timeout)
+            if not ready:
+                break
+            try:
+                chunk = self._socket.recv(65536)
+            except ConnectionResetError:
+                chunk = b""
+            if not chunk:
+                self.closed = True
+                break
+            self._buffer += chunk
+            *lines, self._buffer = self._buffer.split(b"\n")
+            messages.extend(protocol.decode(line.decode("ascii")) for line in lines)
+        return messages
+
+    def close(self) -> None:
+        self._socket.close()
+        self.closed = True
+
+
+class Bot:
+    """A trading program for one seat. Override the callbacks you need and act through the
+    methods; `run` connects it and calls them as messages arrive.
+
+    Times are the market's simulated nanoseconds. Each callback runs after the message has been
+    applied, so `ledger` and `book` already include it."""
+
+    def __init__(self) -> None:
+        self.ledger = Ledger()
+        self.book = Book()
+        self.settings: Optional[Welcome] = None
+        self.now = 0
+        self.started = False
+        self.ended: Optional[End] = None
+        self._connection: Optional[Connection] = None
+        self._next_id = 1
+        self._timers: list[tuple[int, int, object]] = []
+        self._sequence = itertools.count()
+
+    # Callbacks.
+
+    def on_start(self) -> None: ...
+    def on_wakeup(self, tag: object) -> None: ...
+    def on_trade(self, trade: Trade) -> None: ...
+    def on_top(self, top: Top) -> None: ...
+    def on_depth(self, depth: Depth) -> None: ...
+    def on_phase(self, phase: PhaseChange) -> None: ...
+    def on_indicative(self, indicative: Indicative) -> None: ...
+    def on_accepted(self, event: Accepted) -> None: ...
+    def on_rejected(self, event: Rejected) -> None: ...
+    def on_modified(self, event: Modified) -> None: ...
+    def on_filled(self, event: Filled) -> None: ...
+    def on_cancelled(self, event: Cancelled) -> None: ...
+    def on_error(self, error: Error) -> None: ...
+    def on_end(self, end: End) -> None: ...
+
+    # Actions. Each returns the id that names the order in later events.
+
+    def buy(self, price: int, quantity: int,
+            time_in_force: TimeInForce = "good-till-cancel") -> int:
+        return self._submit("buy", "limit", quantity, price, time_in_force)
+
+    def sell(self, price: int, quantity: int,
+             time_in_force: TimeInForce = "good-till-cancel") -> int:
+        return self._submit("sell", "limit", quantity, price, time_in_force)
+
+    def buy_market(self, quantity: int) -> int:
+        return self._submit("buy", "market", quantity, None, None)
+
+    def sell_market(self, quantity: int) -> int:
+        return self._submit("sell", "market", quantity, None, None)
+
+    def cancel(self, order_id: int) -> None:
+        self._send(Cancel(id=order_id))
+
+    def cancel_all(self) -> None:
+        """Cancels every open order whose cancel has not been asked for already."""
+        for order in list(self.ledger.orders.values()):
+            if not order.cancel_requested:
+                self.cancel(order.id)
+
+    def modify(self, order_id: int, price: int, quantity: int) -> None:
+        self._send(Modify(id=order_id, price=price, quantity=quantity))
+
+    def wake_after(self, delay: int, tag: object = None) -> None:
+        """Asks for on_wakeup once the market's time has moved on by `delay` nanoseconds. Wakeups
+        happen as messages bring news of the time, about ten times a second at the least."""
+        heapq.heappush(self._timers, (self.now + delay, next(self._sequence), tag))
+
+    # Running.
+
+    def _submit(self, side: Side, order_type: str, quantity: int, price: Optional[int],
+                time_in_force: Optional[TimeInForce]) -> int:
+        order = NewOrder(id=self._next_id, side=side, order_type=order_type,  # type: ignore
+                         quantity=quantity, price=price, time_in_force=time_in_force)
+        self._send(order)
+        self._next_id += 1
+        return order.id
+
+    def _send(self, message: ClientMessage) -> None:
+        if self._connection is None or not self.started or self.ended is not None:
+            raise RuntimeError("orders can only be sent while the market is open")
+        # Once the server has gone nothing more reaches the market, so nothing is recorded.
+        if self._connection.send(message):
+            self.ledger.record(message)
+
+    def _dispatch(self, message: ServerMessage) -> None:
+        if isinstance(message, Welcome):
+            self.settings = message
+            account = message.account
+            self.ledger = Ledger(account.cash, account.position, account.fees)
+            for order in message.orders:
+                self.ledger.orders[order.id] = Order(
+                    id=order.id, side=order.side, order_type=order.order_type, price=order.price,
+                    leaves=order.leaves, order_id=order.order_id,
+                    acknowledged=order.acknowledged, cancel_requested=order.cancel_requested)
+                self._next_id = max(self._next_id, order.id + 1)
+            self.now = message.time
+            self.book.phase = message.phase
+            if message.started:
+                self.started = True
+                self.on_start()
+            return
+        if isinstance(message, Error):
+            self.on_error(message)
+            return
+        self.now = message.time
+        if isinstance(message, Start):
+            self.started = True
+            self.on_start()
+        elif isinstance(message, End):
+            self.ended = message
+            self.on_end(message)
+            return
+        elif isinstance(message, (Accepted, Rejected, Modified, Filled, Cancelled)):
+            self.ledger.apply(message)
+            handler = {Accepted: self.on_accepted, Rejected: self.on_rejected,
+                       Modified: self.on_modified, Filled: self.on_filled,
+                       Cancelled: self.on_cancelled}[type(message)]
+            handler(message)  # type: ignore[operator]
+        elif isinstance(message, (Trade, Top, Depth, PhaseChange, Indicative)):
+            self.book.apply(message)
+            if isinstance(message, Trade):
+                self.on_trade(message)
+            elif isinstance(message, Top):
+                self.on_top(message)
+            elif isinstance(message, Depth):
+                self.on_depth(message)
+            elif isinstance(message, PhaseChange):
+                self.on_phase(message)
+            else:
+                self.on_indicative(message)
+        while self._timers and self._timers[0][0] <= self.now and self.ended is None:
+            _, _, tag = heapq.heappop(self._timers)
+            self.on_wakeup(tag)
+
+
+def run(bot: Bot, host: str = "127.0.0.1", port: int = 7878, seat: str = "you",
+        token: Optional[str] = None) -> Optional[End]:
+    """Connects the bot to a server, claims the seat and runs the bot until the session ends.
+    Returns the seat's results, or None if the connection closed first. Raises ConnectionError if
+    the server turns the seat away."""
+    connection = Connection(host, port)
+    bot._connection = connection
+    try:
+        connection.send(Hello(seat=seat, token=token))
+        while bot.ended is None and not connection.closed:
+            for message in connection.receive(timeout=1.0):
+                bot._dispatch(message)
+                if isinstance(message, Error) and message.fatal:
+                    raise ConnectionError(f"the server closed the connection: {message.message}")
+                if bot.ended is not None:
+                    break
+        return bot.ended
+    finally:
+        connection.close()

crowdbook-0.13.0/src/crowdbook/protocol.py

@@ -0,0 +1,392 @@
+"""The messages of the crowdbook protocol and their encoding as JSON lines.
+
+docs/protocol.md in the crowdbook repository specifies them. Client messages are encoded exactly
+as the server expects; server messages are decoded leniently, ignoring fields this version does
+not know, so that a newer server can add fields without breaking older clients.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Literal, Optional, Union
+
+VERSION = 1
+
+Side = Literal["buy", "sell"]
+OrderType = Literal["limit", "market"]
+TimeInForce = Literal["good-till-cancel", "immediate-or-cancel", "post-only"]
+
+SIDES = ("buy", "sell")
+ORDER_TYPES = ("limit", "market")
+TIMES_IN_FORCE = ("good-till-cancel", "immediate-or-cancel", "post-only")
+
+
+class ProtocolError(ValueError):
+    """A line that is not a message this client understands."""
+
+
+# Client messages.
+
+
+@dataclass(frozen=True)
+class Hello:
+    seat: str
+    token: Optional[str] = None
+    protocol: int = VERSION
+
+
+@dataclass(frozen=True)
+class NewOrder:
+    id: int
+    side: Side
+    order_type: OrderType
+    quantity: int
+    price: Optional[int] = None  # limit orders only
+    time_in_force: Optional[TimeInForce] = None  # limit orders only
+    parent: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class Cancel:
+    id: int
+
+
+@dataclass(frozen=True)
+class Modify:
+    id: int
+    price: int
+    quantity: int
+
+
+ClientMessage = Union[Hello, NewOrder, Cancel, Modify]
+
+
+def encode(message: ClientMessage) -> str:
+    """One line of JSON, ending in a newline."""
+    if isinstance(message, Hello):
+        body: dict = {"type": "hello", "protocol": message.protocol, "seat": message.seat}
+        if message.token is not None:
+            body["token"] = message.token
+    elif isinstance(message, NewOrder):
+        if message.side not in SIDES or message.order_type not in ORDER_TYPES:
+            raise ValueError(f"not an order: {message}")
+        body = {"type": "new", "id": message.id, "side": message.side,
+                "order_type": message.order_type}
+        if message.order_type == "limit":
+            if message.price is None:
+                raise ValueError("a limit order needs a price")
+            time_in_force = message.time_in_force or "good-till-cancel"
+            if time_in_force not in TIMES_IN_FORCE:
+                raise ValueError(f"no time in force '{time_in_force}'")
+            body["time_in_force"] = time_in_force
+            body["price"] = message.price
+        elif message.price is not None or message.time_in_force is not None:
+            raise ValueError("a market order has no price and no time in force")
+        body["quantity"] = message.quantity
+        if message.parent is not None:
+            body["parent"] = message.parent
+    elif isinstance(message, Cancel):
+        body = {"type": "cancel", "id": message.id}
+    elif isinstance(message, Modify):
+        body = {"type": "modify", "id": message.id, "price": message.price,
+                "quantity": message.quantity}
+    else:
+        raise TypeError(f"not a client message: {message!r}")
+    return json.dumps(body, separators=(",", ":")) + "\n"
+
+
+# Server messages.
+
+
+@dataclass(frozen=True)
+class Level:
+    price: int
+    quantity: int
+    orders: int
+
+
+@dataclass(frozen=True)
+class Latency:
+    to_exchange: int
+    from_exchange: int
+    jitter: int
+
+
+@dataclass(frozen=True)
+class Account:
+    initial_cash: int
+    initial_position: int
+    cash: int
+    position: int
+    fees: int
+    max_position: int
+    max_order_quantity: int
+
+
+@dataclass(frozen=True)
+class OpenOrder:
+    id: int
+    order_id: int
+    side: Side
+    order_type: OrderType
+    price: int
+    leaves: int
+    acknowledged: bool
+    cancel_requested: bool
+
+
+@dataclass(frozen=True)
+class Challenge:
+    name: str
+    briefing: str
+
+
+@dataclass(frozen=True)
+class TargetRule:
+    """A large order the seat is asked to work."""
+
+    side: Side
+    quantity: int
+    benchmark: Literal["vwap", "reference"]
+    unfinished_penalty: int  # points per lot not done
+
+
+@dataclass(frozen=True)
+class Scoring:
+    """How the seat is scored. Amounts are in points, thousandths of a tick-lot."""
+
+    mark: Literal["last", "value", "book"]
+    inventory_penalty: int  # per lot per second held
+    close_penalty: int  # per lot held at the end
+    max_loss: int  # in tick-lots; 0 for no limit
+    target: Optional[TargetRule] = None
+
+
+@dataclass(frozen=True)
+class Score:
+    """A seat's score and its parts, in points: total = pnl - inventory - close - paper -
+    unfinished."""
+
+    total: int
+    pnl: int
+    inventory: int
+    close: int
+    paper: int
+    unfinished: int
+    unfinished_lots: int
+    stopped_at: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class Welcome:
+    protocol: int
+    seat: str
+    started: bool
+    time: int
+    duration: int
+    reference_price: int
+    depth_levels: int
+    maker_fee: int
+    taker_fee: int
+    latency: Latency
+    account: Account
+    orders: tuple[OpenOrder, ...] = ()
+    challenge: Optional[Challenge] = None
+    scoring: Optional[Scoring] = None
+    auction_fee: int = 0
+    phase: str = "continuous"
+    # "flat", or "probability": a fill at price p pays the fees times 4 p (1 - p), for p the
+    # price as a share of the payout, max_price + 1
+    fee_curve: str = "flat"
+    max_price: int = 1_000_000_000  # the highest limit price: 99 in a prediction market
+
+
+@dataclass(frozen=True)
+class Start:
+    time: int
+
+
+@dataclass(frozen=True)
+class Clock:
+    time: int
+
+
+@dataclass(frozen=True)
+class Accepted:
+    time: int
+    id: int
+    order_id: int
+    side: Side
+    order_type: OrderType
+    quantity: int
+    price: Optional[int] = None
+    time_in_force: Optional[TimeInForce] = None
+
+
+@dataclass(frozen=True)
+class Rejected:
+    time: int
+    id: int
+    request: Literal["new", "cancel", "modify"]
+    reason: str
+
+
+@dataclass(frozen=True)
+class Modified:
+    time: int
+    id: int
+    order_id: int
+    price: int
+    quantity: int
+
+
+@dataclass(frozen=True)
+class Filled:
+    time: int
+    id: int
+    order_id: int
+    side: Side
+    price: int
+    quantity: int
+    leaves: int
+    liquidity: Literal["maker", "taker"]
+    fee: int
+
+
+@dataclass(frozen=True)
+class Cancelled:
+    time: int
+    id: int
+    order_id: int
+    quantity: int
+    reason: Literal["requested", "immediate-or-cancel", "self-trade", "cleared"]
+
+
+@dataclass(frozen=True)
+class Trade:
+    time: int
+    price: int
+    quantity: int
+    aggressor: Side
+    auction: bool = False  # part of an auction's uncross
+
+
+Phase = Literal["opening-auction", "continuous", "halt", "closing-auction", "closed"]
+AUCTIONS = ("opening-auction", "halt", "closing-auction")
+
+
+@dataclass(frozen=True)
+class PhaseChange:
+    """The market moved to another phase of its trading day; leaving an auction, `price` is
+    where it uncrossed."""
+
+    time: int
+    phase: Phase
+    price: Optional[int] = None
+
+
+@dataclass(frozen=True)
+class Indicative:
+    """During an auction: where the book would uncross now; `price` is None while nothing
+    would trade."""
+
+    time: int
+    price: Optional[int]
+    volume: int
+    imbalance: int
+
+
+@dataclass(frozen=True)
+class Top:
+    time: int
+    bid: Optional[Level]
+    ask: Optional[Level]
+
+
+@dataclass(frozen=True)
+class Depth:
+    time: int
+    bids: tuple[Level, ...] = field(default_factory=tuple)
+    asks: tuple[Level, ...] = field(default_factory=tuple)
+
+
+@dataclass(frozen=True)
+class End:
+    time: int
+    cash: int
+    position: int
+    fees: int
+    pnl: int
+    score: Optional[Score] = None
+
+
+@dataclass(frozen=True)
+class Error:
+    message: str
+    fatal: bool
+
+
+OrderEvent = Union[Accepted, Rejected, Modified, Filled, Cancelled]
+ServerMessage = Union[Welcome, Start, Clock, Accepted, Rejected, Modified, Filled, Cancelled,
+                      Trade, Top, Depth, PhaseChange, Indicative, End, Error]
+
+
+def _fields(cls, body: dict) -> dict:
+    """The body's values for the dataclass's fields, ignoring any others."""
+    names = cls.__dataclass_fields__.keys()
+    return {name: body[name] for name in names if name in body}
+
+
+def _level(body: Optional[dict]) -> Optional[Level]:
+    return None if body is None else Level(**_fields(Level, body))
+
+
+def _levels(bodies: list) -> tuple[Level, ...]:
+    return tuple(Level(**_fields(Level, body)) for body in bodies)
+
+
+def _scoring(body: Optional[dict]) -> Optional[Scoring]:
+    if body is None:
+        return None
+    target = body.get("target")
+    return Scoring(**{k: v for k, v in _fields(Scoring, body).items() if k != "target"},
+                   target=None if target is None else TargetRule(**_fields(TargetRule, target)))
+
+
+_SIMPLE = {
+    "start": Start, "clock": Clock, "accepted": Accepted, "rejected": Rejected,
+    "modified": Modified, "filled": Filled, "cancelled": Cancelled, "trade": Trade,
+    "phase": PhaseChange, "indicative": Indicative, "error": Error,
+}
+
+
+def decode(line: str) -> ServerMessage:
+    """Decodes one line from the server. Raises ProtocolError if it is not a known message."""
+    try:
+        body = json.loads(line)
+        kind = body["type"]
+        if kind == "welcome":
+            return Welcome(
+                **{k: v for k, v in _fields(Welcome, body).items()
+                   if k not in ("latency", "account", "orders", "challenge", "scoring")},
+                latency=Latency(**_fields(Latency, body["latency"])),
+                account=Account(**_fields(Account, body["account"])),
+                orders=tuple(OpenOrder(**_fields(OpenOrder, order)) for order in body["orders"]),
+                challenge=(None if body.get("challenge") is None
+                           else Challenge(**_fields(Challenge, body["challenge"]))),
+                scoring=_scoring(body.get("scoring")),
+            )
+        if kind == "end":
+            score = body.get("score")
+            return End(**{k: v for k, v in _fields(End, body).items() if k != "score"},
+                       score=None if score is None else Score(**_fields(Score, score)))
+        if kind == "top":
+            return Top(time=body["time"], bid=_level(body["bid"]), ask=_level(body["ask"]))
+        if kind == "depth":
+            return Depth(time=body["time"], bids=_levels(body["bids"]),
+                         asks=_levels(body["asks"]))
+        cls = _SIMPLE[kind]
+        return cls(**_fields(cls, body))
+    except (ValueError, KeyError, TypeError) as error:
+        raise ProtocolError(f"cannot decode {line.strip()!r}: {error}") from error