synpath 0.1.0__py3-none-any.whl

synpath/engine/router.py

@@ -0,0 +1,261 @@
+"""The router: one order on a bucket, as legs on its member venues.
+
+Pure functions over data the caller already holds. `merge` lays the members'
+books side by side in bucket terms; `plan` walks the merged book from the
+best net price outwards and says how much to put where. Nothing here talks
+to a venue or makes an order; the parent that owns the bucket order does
+that with the plan, and re-plans as fills and books move.
+
+Three rules the plan keeps, because they are the difference between a
+router and a footgun:
+
+* **The legs never sum to more than was asked.** Oversubscribing to fill
+  faster is how a bucket buys twice.
+* **Prices are net of the taker fee**, per level, because on Kalshi the fee
+  is a curve in price and a 0.41 with fee can cost more than a 0.42 without.
+* **A leg below its venue's minimum is dropped and its size goes to the next
+  best venue**, rather than rounded up into more than the caller wanted.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import ROUND_CEILING, ROUND_FLOOR, Decimal
+from typing import Any, Callable, Literal, Mapping
+
+from ..bucket import Bucket, BucketMember
+from ..trading.instruments import VENUE_RULES
+from ..trading.types import Precision, Side
+from ..types import OrderBook
+
+ZERO = Decimal("0")
+FeeFn = Callable[[str, Decimal, Decimal], Decimal]
+"""`fee(market_id, price, contracts)` -> the taker fee for that many contracts
+at that price, in the venue's currency. The plan asks per level."""
+
+Reason = Literal["", "worst_price", "liquidity", "min_amount"]
+
+PriceSize = tuple[Decimal, Decimal]
+
+
+@dataclass(frozen=True)
+class BookView:
+    """One member's book in bucket terms: `asks` is what one bucket YES costs,
+    `bids` what it fetches, both best first, as Decimals."""
+    market_id: str
+    asks: tuple[PriceSize, ...]
+    bids: tuple[PriceSize, ...]
+
+
+def view(book: Any, member: BucketMember, *, face_value: Decimal = Decimal("1")) -> BookView:
+    """A member's book as the bucket sees it.
+
+    Takes an `OrderBook` (either side) or anything with `levels()` giving
+    `(bids, asks)` of price/size pairs (`synpath.ws.LocalBook`, the paper
+    venue's book), which is always the YES side. A flipped member's YES book
+    is turned into its NO book here: NO asks are `face - YES bids`, NO bids
+    `face - YES asks`. An `OrderBook` already on the NO side is taken as is."""
+    def pairs(rows: Any) -> tuple[PriceSize, ...]:
+        out = []
+        for row in rows:
+            if isinstance(row, (tuple, list)):
+                price, size = Decimal(str(row[0])), Decimal(str(row[1]))
+            else:
+                price, size = Decimal(str(row.price)), Decimal(str(row.size))
+            if size > 0:
+                out.append((price, size))
+        return tuple(out)
+
+    side_in = getattr(book, "side", "yes")
+    if callable(getattr(book, "levels", None)):
+        bids, asks = book.levels()
+    else:
+        bids, asks = book.bids, book.asks
+    bids, asks = pairs(bids), pairs(asks)
+    wanted = member.book_side()
+    if side_in == wanted:
+        return BookView(member.market_id, asks, bids)
+    if side_in == "yes" and wanted == "no":
+        return BookView(
+            member.market_id,
+            asks=tuple((face_value - p, s) for p, s in bids),
+            bids=tuple((face_value - p, s) for p, s in asks),
+        )
+    raise ValueError(f"{member.market_id}: book is the {side_in} side, bucket needs {wanted}")
+
+
+def default_precision(market_id: str) -> Precision:
+    """The venue's published rules, for a member whose market has not been read."""
+    venue = market_id.split(":", 1)[0]
+    rules = VENUE_RULES.get(venue, VENUE_RULES["polymarket"])
+    return Precision(tick=rules["default_tick"], min_amount=rules["min_amount"],
+                     amount_step=rules["amount_step"], whole_contracts=rules["whole"])
+
+
+@dataclass(frozen=True)
+class Level:
+    market_id: str
+    price: Decimal
+    """In bucket terms: what one contract of the bucket's YES costs (asks) or fetches (bids)."""
+    net_price: Decimal
+    """`price` plus the taker fee per contract on a buy, minus it on a sell."""
+    size: Decimal
+
+
+@dataclass
+class Leg:
+    market_id: str
+    flip: bool
+    side: Side
+    """The member's own side, after `flip`."""
+    price: Decimal
+    """The member's own YES price, after `flip` and tick rounding. What the venue receives."""
+    amount: Decimal
+    bucket_price: Decimal
+    """The worst bucket-terms price this leg reaches, before fees."""
+    net_price: Decimal
+    """Volume-weighted net price of the levels this leg takes, in bucket terms."""
+
+
+@dataclass
+class Plan:
+    side: Side
+    amount: Decimal
+    limit: Decimal
+    legs: list[Leg] = field(default_factory=list)
+    unfilled: Decimal = ZERO
+    reason: Reason = ""
+
+    @property
+    def allocated(self) -> Decimal:
+        return sum((leg.amount for leg in self.legs), ZERO)
+
+    @property
+    def expected_net_price(self) -> Decimal | None:
+        if not self.legs:
+            return None
+        return sum((leg.net_price * leg.amount for leg in self.legs), ZERO) / self.allocated
+
+
+def merge(bucket: Bucket, books: Mapping[str, Any], fee: FeeFn) -> tuple[list[Level], list[Level]]:
+    """The members' books as one, in bucket terms: `(asks, bids)`, asks
+    cheapest-net first, bids richest-net first. Books go through `view`, so a
+    flipped member may hand in either side."""
+    asks: list[Level] = []
+    bids: list[Level] = []
+    for member in bucket.members:
+        book = books.get(member.market_id)
+        if book is None:
+            continue
+        seen = book if isinstance(book, BookView) else view(book, member)
+        for price, size in seen.asks:
+            asks.append(Level(member.market_id, price, price + _per_contract(fee, member.market_id, price), size))
+        for price, size in seen.bids:
+            bids.append(Level(member.market_id, price, price - _per_contract(fee, member.market_id, price), size))
+    asks.sort(key=lambda l: (l.net_price, l.price))
+    bids.sort(key=lambda l: (-l.net_price, -l.price))
+    return asks, bids
+
+
+def _per_contract(fee: FeeFn, market_id: str, price: Decimal) -> Decimal:
+    charged = fee(market_id, price, Decimal("1"))
+    return charged if charged > 0 else ZERO
+
+
+def plan(
+    bucket: Bucket,
+    books: Mapping[str, Any],
+    precision: Mapping[str, Precision],
+    fee: FeeFn,
+    *,
+    side: Side,
+    amount: Decimal,
+    limit: Decimal,
+) -> Plan:
+    """How to take `amount` of the bucket at no worse than `limit` net, given
+    what the books show now. Walks the merged book best-net first, stops at
+    the limit, then drops any leg under its venue's minimum and re-walks with
+    that venue excluded so its size goes to the next best."""
+    asks, bids = merge(bucket, books, fee)
+    levels = asks if side == Side.BUY else bids
+    excluded: set[str] = set()
+    out = Plan(side=side, amount=amount, limit=limit)
+    for _ in range(len(bucket.members) + 1):
+        legs, remaining, reason = _walk(bucket, levels, precision, side, amount, limit, excluded)
+        short = [leg for leg in legs if leg.amount < precision[leg.market_id].min_amount]
+        if not short:
+            out.legs, out.unfilled, out.reason = legs, remaining, reason
+            if remaining > 0 and reason == "" :
+                out.reason = "min_amount"
+            return out
+        excluded.update(leg.market_id for leg in short)
+    out.legs, out.unfilled, out.reason = [], amount, "min_amount"
+    return out
+
+
+def _walk(
+    bucket: Bucket,
+    levels: list[Level],
+    precision: Mapping[str, Precision],
+    side: Side,
+    amount: Decimal,
+    limit: Decimal,
+    excluded: set[str],
+) -> tuple[list[Leg], Decimal, Reason]:
+    taken: dict[str, dict[str, Decimal]] = {}
+    remaining = amount
+    reason: Reason = "liquidity"
+    for lvl in levels:
+        if remaining <= 0:
+            reason = ""
+            break
+        if lvl.market_id in excluded:
+            continue
+        if (side == Side.BUY and lvl.net_price > limit) or (side == Side.SELL and lvl.net_price < limit):
+            reason = "worst_price"
+            break
+        take = min(lvl.size, remaining)
+        slot = taken.setdefault(lvl.market_id, {"amount": ZERO, "cost": ZERO, "worst": lvl.price})
+        slot["amount"] += take
+        slot["cost"] += lvl.net_price * take
+        slot["worst"] = max(slot["worst"], lvl.price) if side == Side.BUY else min(slot["worst"], lvl.price)
+        remaining -= take
+    else:
+        if remaining <= 0:
+            reason = ""
+    legs: list[Leg] = []
+    for market_id, slot in taken.items():
+        member = bucket.member(market_id)
+        spec = precision[market_id]
+        qty = _round_amount(slot["amount"], spec)
+        if qty <= 0:
+            remaining += slot["amount"]
+            continue
+        remaining += slot["amount"] - qty
+        member_side, member_price = member.to_member(side, slot["worst"])
+        member_price = _round_price(member_price, spec.tick, member_side)
+        legs.append(Leg(
+            market_id=market_id, flip=member.flip, side=member_side, price=member_price, amount=qty,
+            bucket_price=slot["worst"], net_price=slot["cost"] / slot["amount"],
+        ))
+    return legs, remaining, reason
+
+
+def _round_amount(amount: Decimal, spec: Precision) -> Decimal:
+    """Down, never up: a leg may fall short of what the level offered but must
+    not exceed it."""
+    if spec.whole_contracts:
+        return Decimal(int(amount))
+    if spec.amount_step:
+        return (amount / spec.amount_step).to_integral_value(rounding=ROUND_FLOOR) * spec.amount_step
+    return amount
+
+
+def _round_price(price: Decimal, tick: Decimal, side: Side) -> Decimal:
+    """Onto the venue's tick, toward the side that cannot worsen the limit:
+    a buy rounds down, a sell rounds up."""
+    rounding = ROUND_FLOOR if side == Side.BUY else ROUND_CEILING
+    return (price / tick).to_integral_value(rounding=rounding) * tick
+
+
+def member_from_plan(bucket: Bucket, leg: Leg) -> BucketMember:
+    return bucket.member(leg.market_id)

synpath/errors.py

@@ -0,0 +1,98 @@
+"""Error hierarchy, named after ccxt's so the reflexes transfer.
+
+Two branches under `SynpathError`, and the split is the one a caller actually
+acts on:
+
+  * `NetworkError`  — the request never got a verdict from the venue. Retrying
+    the identical call is reasonable.
+  * `ExchangeError` — the venue answered and said no. Retrying unchanged will
+    fail again; the caller has to change the request.
+
+`RateLimitExceeded` sits under `NetworkError` for exactly this reason, which
+surprises people until they notice that waiting and retrying is the correct
+response to it.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class SynpathError(Exception):
+    """Base for everything this library raises on purpose."""
+
+
+class NetworkError(SynpathError):
+    """No verdict from the venue: timeout, DNS, connection reset, 5xx."""
+
+
+class ExchangeNotAvailable(NetworkError):
+    """The venue is up but refusing service — maintenance, 502/503.
+
+    `body` is the venue's parsed payload when it sent one: some venues say
+    *why* they refuse (cancel-only mode, a scheduled pause) in a 503.
+    """
+
+    def __init__(self, message: str, *, body: Any = None, status: int | None = None):
+        super().__init__(message)
+        self.body = body
+        self.status = status
+
+
+class RequestTimeout(NetworkError):
+    """The venue did not answer inside the timeout."""
+
+
+class RateLimitExceeded(NetworkError):
+    """Too many requests. Retry after backing off."""
+
+    def __init__(self, message: str, *, retry_after: float | None = None):
+        super().__init__(message)
+        self.retry_after = retry_after
+        """Seconds to wait, when the venue said. Kalshi does not, so usually None."""
+
+
+class ExchangeError(SynpathError):
+    """The venue answered and rejected the request.
+
+    `body` is the venue's parsed error payload when it sent JSON, and
+    `status` the HTTP status, so a caller (or a trading adapter) can branch
+    on the venue's own error code rather than on message text.
+    """
+
+    def __init__(self, message: str, *, body: Any = None, status: int | None = None):
+        super().__init__(message)
+        self.body = body
+        self.status = status
+
+    @property
+    def code(self) -> str | None:
+        """The venue's error code, where its payload carries one."""
+        if isinstance(self.body, dict):
+            inner = self.body.get("error") if isinstance(self.body.get("error"), dict) else self.body
+            code = inner.get("code") if isinstance(inner, dict) else None
+            return str(code) if code is not None else None
+        return None
+
+
+class BadRequest(ExchangeError):
+    """Malformed or invalid parameters (4xx that is not auth or not-found)."""
+
+
+class BadSymbol(BadRequest):
+    """A market, event or instrument id this venue does not recognise."""
+
+
+class MarketNotFound(BadSymbol):
+    """The id is well-formed but the venue has no such market."""
+
+
+class NotSupported(SynpathError):
+    """This venue does not offer the capability.
+
+    Raised rather than returning empty, so a missing feature is never mistaken
+    for an absence of data. Check `exchange.has` to branch before calling.
+    """
+
+
+class AuthenticationError(ExchangeError):
+    """Credentials missing, malformed, or rejected."""

synpath/history.py

@@ -0,0 +1,71 @@
+"""Historical order books and trades, from Synpath's hosted history service.
+
+```python
+import synpath
+
+at = synpath.fetch_order_book_at("kalshi:KXQUANTUM-30", as_of_ms=1789509599000)
+if at.book is None:
+    print("no book:", at.absence_reason)       # coverage is not continuous
+else:
+    print(at.book.best_bid, at.book.best_ask)
+```
+
+Needs a Synpath API key (`SYNPATH_API_KEY`, or `api_key=`). The service lives at
+`https://api2.synpath.dev` unless `base_url=` or `SYNPATH_HISTORY_URL` says otherwise.
+Times are recorder receive times in Unix milliseconds. Coverage varies by market and
+has gaps, which every answer says explicitly: a missing book comes back with an
+`absence_reason`, never as an empty book. A range too large to return whole raises
+`BadRequest`; narrow it or raise `limit` (`examples/track_historical_book.py`
+splits long walks for you).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .hosted import call, hosted_client
+from .matching import _validate
+from .types import BookSide, OrderBookAtResponse, OrderBookRangeResponse, TradesRangeResponse
+
+BASE_URL_ENV = "SYNPATH_HISTORY_URL"
+DEFAULT_URL = "https://api2.synpath.dev"
+
+
+def _post(path: str, body: dict[str, Any], *, base_url: str | None, client: Any, api_key: str | None) -> Any:
+    _validate(body["market_id"])
+    http = hosted_client(base_url=base_url, env=BASE_URL_ENV, default=DEFAULT_URL, http_client=client)
+    payload = {k: v for k, v in body.items() if v is not None}
+    return call(http, "POST", path, json=payload, api_key=api_key, owned=client is None, use_stored=True)
+
+
+def fetch_order_book_at(
+    market_id: str, as_of_ms: int, *, side: BookSide | None = None, depth: int | None = None,
+    api_key: str | None = None, base_url: str | None = None, client: Any = None,
+) -> OrderBookAtResponse:
+    """The book as it stood at `as_of_ms`. `book` is `None`, with `absence_reason`, where
+    there is no coverage at that time."""
+    body = _post("/v1/order-book/at", {"market_id": market_id, "as_of_ms": as_of_ms, "side": side, "depth": depth},
+                 base_url=base_url, client=client, api_key=api_key)
+    return OrderBookAtResponse.model_validate(body)
+
+
+def fetch_order_book_range(
+    market_id: str, start_ms: int, end_ms: int, *, side: BookSide | None = None, limit: int | None = None,
+    api_key: str | None = None, base_url: str | None = None, client: Any = None,
+) -> OrderBookRangeResponse:
+    """Every change to the book between `start_ms` and `end_ms`: each segment starts from a
+    full book, and an interval without coverage is its own segment rather than a gap."""
+    body = _post("/v1/order-book/range", {"market_id": market_id, "start_ms": start_ms, "end_ms": end_ms,
+                                          "side": side, "limit": limit},
+                 base_url=base_url, client=client, api_key=api_key)
+    return OrderBookRangeResponse.model_validate(body)
+
+
+def fetch_trades_range(
+    market_id: str, start_ms: int, end_ms: int, *, limit: int | None = None,
+    api_key: str | None = None, base_url: str | None = None, client: Any = None,
+) -> TradesRangeResponse:
+    """Trades between `start_ms` and `end_ms`, with the coverage they were recorded under."""
+    body = _post("/v1/trades/range", {"market_id": market_id, "start_ms": start_ms, "end_ms": end_ms,
+                                      "limit": limit},
+                 base_url=base_url, client=client, api_key=api_key)
+    return TradesRangeResponse.model_validate(body)

synpath/hosted.py

@@ -0,0 +1,86 @@
+"""Synpath's own hosted services, as opposed to the venues.
+
+Two of them, each with a default address and an environment variable that
+overrides it:
+
+  matching   https://api.synpath.dev    SYNPATH_MATCHING_URL   `match_market`, `match_event`
+  history    https://api2.synpath.dev   SYNPATH_HISTORY_URL    `fetch_order_book_at`, ...
+
+Both take a Synpath API key as `Authorization: Bearer <key>`, from `api_key=`,
+`SYNPATH_API_KEY`, or the key `synpath keys create` saved. The key goes to Synpath's services only, never to a
+venue, and nothing that runs on your own machine needs it.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from .base import HttpClient, RateLimiter
+from .errors import AuthenticationError, BadRequest, ExchangeError, ExchangeNotAvailable, MarketNotFound, NetworkError
+
+API_KEY_ENV = "SYNPATH_API_KEY"
+LABEL = "synpath"
+
+
+def api_key_from(explicit: str | None = None, *, use_stored: bool = False) -> str | None:
+    if explicit or os.environ.get(API_KEY_ENV):
+        return explicit or os.environ.get(API_KEY_ENV)
+    if use_stored:
+        from .hosted_auth import stored_api_key
+        return stored_api_key()
+    return None
+
+
+def auth_headers(api_key: str | None = None, *, use_stored: bool = False) -> dict[str, str]:
+    key = api_key_from(api_key, use_stored=use_stored)
+    return {"Authorization": f"Bearer {key}"} if key else {}
+
+
+def hosted_client(*, base_url: str | None, env: str, default: str, http_client: Any = None) -> HttpClient:
+    url = base_url or os.environ.get(env) or default
+    return HttpClient(url, limiter=RateLimiter(rate_per_second=10), client=http_client, venue=LABEL)
+
+
+def _is_ours(body: Any) -> bool:
+    """Whether an error body came from a Synpath service rather than the host in front of it.
+    Ours carry `detail` (FastAPI) or `error` with a `code` (the newer shape)."""
+    if not isinstance(body, dict):
+        return False
+    if "detail" in body:
+        return True
+    error = body.get("error")
+    return isinstance(error, dict) and "code" in error
+
+
+def call(http: HttpClient, method: str, path: str, *, api_key: str | None, owned: bool,
+         use_stored: bool = False, **kwargs: Any) -> Any:
+    """One request to a hosted service, with the key and plainer errors: a
+    refused key says which variable to set, and a range too large to answer
+    whole says to narrow it."""
+    try:
+        return http.request(method, path, headers=auth_headers(api_key, use_stored=use_stored), **kwargs)
+    except MarketNotFound as exc:
+        if _is_ours(exc.body):
+            raise
+        # A 404 that is not our service's own answer is the host in front of it saying there is
+        # no application there: the service is down, not the market missing.
+        raise ExchangeNotAvailable(
+            f"{LABEL}: the service at {http.base_url} is not running or not deployed (it answered 404 "
+            f"without a Synpath error body); try again later or check {http.base_url}",
+            body=exc.body, status=exc.status,
+        ) from None
+    except NetworkError as exc:
+        reason = str(exc).removeprefix(f"{LABEL}: ")
+        raise NetworkError(f"{LABEL}: could not reach {http.base_url}: {reason}") from None
+    except AuthenticationError as exc:
+        hint = "" if api_key_from(api_key, use_stored=use_stored) else (
+            f"; run `synpath login` then `synpath keys create`, or set {API_KEY_ENV}")
+        raise AuthenticationError(f"{exc}{hint}", body=exc.body, status=exc.status) from None
+    except ExchangeError as exc:
+        if exc.status == 413:
+            raise BadRequest(f"{LABEL}: the result is too large to return whole; narrow the range or raise limit",
+                             body=exc.body, status=exc.status) from None
+        raise
+    finally:
+        if owned:
+            http.close()