synpath 0.1.0__py3-none-any.whl

synpath/trading/limiter.py

@@ -0,0 +1,177 @@
+"""A venue's request budget, read and write, with a fast lane and a hard edge.
+
+The read API's `RateLimiter` is one bucket of requests per second. Trading
+needs three things it does not have:
+
+  * **Two buckets.** Kalshi meters reads and writes separately, in tokens
+    per second by tier (Basic: 200 read / 100 write; an order costs 10, a
+    batch cancel 2 per item). A price loop must not starve an order.
+  * **A fast lane.** A cancel or a kill switch may not queue behind new
+    orders. A high-priority call draws from a small borrow bucket and goes
+    at once; the normal callers already waiting are pushed back by exactly
+    what it took, so the venue still sees one budget.
+  * **A hard edge.** A stop that fires late is worse than one that fails
+    loudly. A call whose wait would exceed its deadline raises
+    `RateBudgetExceeded` before anything is sent, instead of being delayed
+    and looking like it ran on time.
+
+`configure` replaces the rates from the venue's own report (`GET
+/account/limits` on Kalshi), so a strategy built on a Premier account does
+not silently throttle on Basic.
+
+How the ordering works without a queue: a normal call *reserves* its tokens
+immediately, driving the bucket negative, and sleeps for exactly the refill
+its own draw needs. Callers therefore go in reservation order. A fast-lane
+draw deducts from the same bucket and adds its cost to a running `shift`;
+each sleeping normal caller, on waking, sleeps again for whatever shift
+accrued since it reserved. Nothing is ever dispatched out of order and the
+sum of what goes out never exceeds the refill.
+"""
+from __future__ import annotations
+
+import asyncio
+import threading
+import time
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Literal
+
+from .errors import RateBudgetExceeded
+
+Kind = Literal["read", "write"]
+
+
+class Priority(IntEnum):
+    HIGH = 0
+    """Cancels, kill switch, the replace half of an edit."""
+    NORMAL = 1
+
+
+@dataclass
+class _Bucket:
+    rate: float
+    capacity: float
+    tokens: float
+    updated: float
+
+    def refill(self, now: float) -> None:
+        self.tokens = min(self.capacity, self.tokens + (now - self.updated) * self.rate)
+        self.updated = now
+
+
+@dataclass
+class _Lane:
+    main: _Bucket
+    """The venue's budget, as reserved by every caller."""
+    fast: _Bucket
+    """What a high-priority call may borrow ahead of the queue."""
+    shift: float = 0.0
+    """Seconds of delay injected ahead of sleeping normal callers."""
+
+
+@dataclass(frozen=True)
+class Reservation:
+    kind: str
+    cost: float
+    wait: float
+    shift_then: float
+
+
+class BudgetLimiter:
+    def __init__(
+        self,
+        *,
+        read_per_second: float,
+        write_per_second: float,
+        burst_seconds: float = 2.0,
+        borrow_seconds: float = 1.0,
+        max_wait_s: float = 5.0,
+    ):
+        self.burst_seconds = burst_seconds
+        self.borrow_seconds = borrow_seconds
+        self.max_wait_s = max_wait_s
+        self._lock = threading.Lock()
+        now = time.monotonic()
+        self._lanes: dict[str, _Lane] = {
+            "read": self._lane(read_per_second, now),
+            "write": self._lane(write_per_second, now),
+        }
+
+    def _lane(self, rate: float, now: float) -> _Lane:
+        return _Lane(
+            main=_Bucket(rate, rate * self.burst_seconds, rate * self.burst_seconds, now),
+            fast=_Bucket(rate, rate * self.borrow_seconds, rate * self.borrow_seconds, now),
+        )
+
+    def configure(self, *, read_per_second: float | None = None, write_per_second: float | None = None) -> None:
+        """Adopt the venue's reported budget. Unspent tokens are kept, capped
+        at the new capacity."""
+        with self._lock:
+            now = time.monotonic()
+            for kind, rate in (("read", read_per_second), ("write", write_per_second)):
+                if rate is None:
+                    continue
+                lane = self._lanes[kind]
+                for bucket, seconds in ((lane.main, self.burst_seconds), (lane.fast, self.borrow_seconds)):
+                    bucket.refill(now)
+                    bucket.rate = rate
+                    bucket.capacity = rate * seconds
+                    bucket.tokens = min(bucket.tokens, bucket.capacity)
+
+    def reserve(self, cost: float, kind: Kind, priority: Priority = Priority.NORMAL) -> Reservation:
+        """Take `cost` tokens now and say how long to wait before using them."""
+        with self._lock:
+            lane = self._lanes[kind]
+            now = time.monotonic()
+            lane.main.refill(now)
+            lane.fast.refill(now)
+            if priority == Priority.HIGH and lane.fast.tokens >= cost:
+                lane.fast.tokens -= cost
+                lane.main.tokens -= cost
+                lane.shift += cost / lane.main.rate
+                return Reservation(kind, cost, 0.0, lane.shift)
+            lane.main.tokens -= cost
+            deficit = -lane.main.tokens
+            wait = deficit / lane.main.rate if deficit > 0 else 0.0
+            return Reservation(kind, cost, wait, lane.shift)
+
+    def release(self, reservation: Reservation) -> None:
+        """Give back a reservation that will not be used."""
+        with self._lock:
+            bucket = self._lanes[reservation.kind].main
+            bucket.tokens = min(bucket.capacity, bucket.tokens + reservation.cost)
+
+    def shift_since(self, reservation: Reservation) -> float:
+        with self._lock:
+            return self._lanes[reservation.kind].shift - reservation.shift_then
+
+    async def acquire(
+        self, cost: float = 10.0, kind: Kind = "write", priority: Priority = Priority.NORMAL,
+        max_wait_s: float | None = None,
+    ) -> None:
+        """Wait for budget, or refuse if the wait would exceed the deadline."""
+        deadline = self.max_wait_s if max_wait_s is None else max_wait_s
+        reservation = self.reserve(cost, kind, priority)
+        if reservation.wait > deadline:
+            self.release(reservation)
+            raise RateBudgetExceeded(
+                f"{kind} budget: {reservation.wait:.2f}s of queue ahead, more than the "
+                f"{deadline:.2f}s this call allows; nothing was sent",
+                wait_s=reservation.wait,
+            )
+        wait = reservation.wait
+        while wait > 0:
+            await asyncio.sleep(wait)
+            # A fast-lane draw since the reservation pushed the queue back by
+            # its cost; sleep that much more, then check again.
+            wait = self.shift_since(reservation)
+            reservation = Reservation(kind, cost, 0.0, reservation.shift_then + wait)
+
+    def snapshot(self) -> dict[str, dict[str, float]]:
+        with self._lock:
+            now = time.monotonic()
+            out = {}
+            for kind, lane in self._lanes.items():
+                lane.main.refill(now)
+                out[kind] = {"rate": lane.main.rate, "capacity": lane.main.capacity, "tokens": lane.main.tokens}
+            return out

synpath/trading/money.py

@@ -0,0 +1,172 @@
+"""Money as `Decimal`, and the venues' wire formats for it.
+
+The read API carries prices as `float`, the ccxt convention, and a float is
+fine to look at. It is not fine to sign: `0.1 + 0.2` is not `0.3`, a tick of
+`0.001` cannot be represented exactly, and a price that rounds to the wrong
+side of a tick is an order the venue rejects at best and fills at the wrong
+level at worst. Everything that will be signed goes through here as
+`Decimal`, is checked against the instrument's precision, and is rendered
+into the venue's own string format only at the boundary.
+
+Wire formats seen on the three venues:
+
+  Kalshi          fixed-point dollar strings, four decimals ("0.5600"), and
+                  fixed-point contract counts, two decimals ("10.00")
+  Polymarket      token and collateral amounts as integers scaled by 10^6;
+                  prices as decimal strings on the instrument's tick
+  Polymarket US   decimal strings, four decimals, whole contracts only
+"""
+from __future__ import annotations
+
+from decimal import ROUND_DOWN, ROUND_HALF_EVEN, ROUND_HALF_UP, ROUND_UP, Decimal, InvalidOperation
+from typing import Any, Literal
+
+from .errors import InvalidOrder
+from .types import Precision
+
+Rounding = Literal["nearest", "down", "up", "bankers"]
+_MODES = {
+    "nearest": ROUND_HALF_UP,
+    "down": ROUND_DOWN,
+    "up": ROUND_UP,
+    "bankers": ROUND_HALF_EVEN,
+}
+
+ONE = Decimal("1")
+
+
+def D(value: Any) -> Decimal:
+    """A `Decimal` from anything a caller might reasonably hand over.
+
+    Floats go through `str` first, so `D(0.1)` is `0.1` and not
+    `0.1000000000000000055511151231257827`. `None` is refused rather than
+    read as zero: an absent price is not a free order.
+    """
+    if isinstance(value, Decimal):
+        return value
+    if value is None or value == "":
+        raise InvalidOrder("a Decimal is required, got None")
+    if isinstance(value, bool):
+        raise InvalidOrder(f"a Decimal is required, got {value!r}")
+    if isinstance(value, float):
+        value = repr(value)
+    try:
+        return Decimal(str(value))
+    except InvalidOperation:
+        raise InvalidOrder(f"not a number: {value!r}") from None
+
+
+def round_to(value: Decimal, step: Decimal, mode: Rounding = "nearest") -> Decimal:
+    """`value` on the grid of `step`, rounded as asked.
+
+    `nearest` is what a human expects; `down` is what a buyer wants (never
+    pay more than typed) and `up` what a seller wants; `bankers` is how
+    Polymarket US rounds fees.
+    """
+    if step <= 0:
+        raise InvalidOrder(f"step must be positive, got {step}")
+    quotient = (value / step).quantize(ONE, rounding=_MODES[mode])
+    return (quotient * step).quantize(step)
+
+
+def complement(price: Decimal, *, face_value: Decimal = ONE) -> Decimal:
+    """The same order seen from the other side: a YES bid at p is a NO ask at
+    `face_value - p`."""
+    return face_value - price
+
+
+def validate_price(price: Decimal, precision: Precision) -> Decimal:
+    """`price`, or `InvalidOrder` saying exactly why the venue would refuse it.
+
+    A price is checked, never silently rounded: an order typed at 0.1065 on a
+    0.001 tick is a mistake to point out, not a 0.107 to place.
+    """
+    tick = precision.tick
+    if price <= 0 or price >= precision.face_value:
+        raise InvalidOrder(
+            f"price {price} is outside (0, {precision.face_value}); the ends are "
+            f"placeholders, not prices"
+        )
+    if (price / tick) % 1 != 0:
+        raise InvalidOrder(f"price {price} is not on the {tick} tick; nearest are "
+                           f"{round_to(price, tick, 'down')} and {round_to(price, tick, 'up')}")
+    return price
+
+
+def validate_amount(amount: Decimal, precision: Precision) -> Decimal:
+    """`amount`, or `InvalidOrder` naming the rule it breaks."""
+    if amount <= 0:
+        raise InvalidOrder(f"amount must be positive, got {amount}")
+    if precision.whole_contracts and amount % 1 != 0:
+        raise InvalidOrder(f"amount {amount}: this venue trades whole contracts only")
+    if amount < precision.min_amount:
+        raise InvalidOrder(f"amount {amount} is below the minimum {precision.min_amount}")
+    step = precision.amount_step
+    if step and (amount / step) % 1 != 0:
+        raise InvalidOrder(f"amount {amount} is not a multiple of {step}")
+    return amount
+
+
+# -- Kalshi --------------------------------------------------------------------
+
+KALSHI_PRICE_PLACES = Decimal("0.0001")
+KALSHI_COUNT_PLACES = Decimal("0.01")
+
+
+def kalshi_dollars(price: Decimal) -> str:
+    """A price as Kalshi V2's fixed-point dollar string: `Decimal("0.56")` -> `"0.5600"`."""
+    return str(price.quantize(KALSHI_PRICE_PLACES))
+
+
+def kalshi_count(amount: Decimal) -> str:
+    """A contract count as Kalshi's `count` string: `Decimal("10")` -> `"10.00"`."""
+    return str(amount.quantize(KALSHI_COUNT_PLACES))
+
+
+def from_kalshi_cents(cents: Any) -> Decimal:
+    """The legacy integer-cents price as a dollar `Decimal`: `56` -> `0.56`."""
+    return (D(cents) / 100).quantize(KALSHI_PRICE_PLACES)
+
+
+def from_kalshi_dollars(text: Any) -> Decimal:
+    return D(text)
+
+
+# -- Polymarket ----------------------------------------------------------------
+
+POLY_SCALE = Decimal(10) ** 6
+
+
+def poly_raw_amount(amount: Decimal) -> int:
+    """A share or USDC amount as the on-chain integer, six decimals: `1.5` -> `1500000`.
+
+    Rounded down: a maker amount rounded up is an order for more than the
+    caller has.
+    """
+    return int((amount * POLY_SCALE).quantize(ONE, rounding=ROUND_DOWN))
+
+
+def from_poly_raw_amount(raw: Any) -> Decimal:
+    return (D(raw) / POLY_SCALE).quantize(Decimal("0.000001"))
+
+
+def poly_price(price: Decimal, tick: Decimal) -> str:
+    """A price as the CLOB's decimal string, on the instrument's tick."""
+    return str(price.quantize(tick))
+
+
+# -- Polymarket US -------------------------------------------------------------
+
+POLYUS_PLACES = Decimal("0.0001")
+
+
+def polyus_amount(value: Decimal) -> str:
+    """A price or quantity as the gateway's four-place decimal string."""
+    return str(value.quantize(POLYUS_PLACES))
+
+
+def from_polyus_amount(value: Any) -> Decimal:
+    """The gateway's `{"value": "0.1060", "currency": "USD"}` or a bare string."""
+    if isinstance(value, dict):
+        value = value.get("value")
+    return D(value)