synpath 0.1.0__py3-none-any.whl

synpath/trading/errors.py

@@ -0,0 +1,94 @@
+"""Trading errors, under the same two branches as the read API's.
+
+`ExchangeError` still means "the venue answered and said no" and
+`NetworkError` still means "no verdict". Two things are new. `RiskRejected`
+is neither: the request never reached a venue because this library's own
+pre-trade checks refused it, and retrying unchanged will be refused again.
+`RateBudgetExceeded` is a refusal from the local budget limiter -- the queue
+ahead of the request was already too long for it to be honoured in time --
+which is deliberately not `RateLimitExceeded`: nothing was sent, and waiting
+longer is the wrong answer for an order that had a deadline.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from ..errors import AuthenticationError, BadRequest, ExchangeError, SynpathError
+
+
+class InvalidOrder(BadRequest):
+    """The order cannot be placed as written: off-tick price, size below the
+    minimum, a market order without a protection price, a sell with no
+    inventory on a venue that does not net. Caught before signing."""
+
+
+class DuplicateClientOrderId(InvalidOrder):
+    """A `client_order_id` this account has already used.
+
+    Raised rather than resubmitted: the id is the idempotency key, and a
+    second order under the same id is exactly the duplicate it exists to
+    prevent.
+    """
+
+
+class InsufficientFunds(ExchangeError):
+    """The venue refused for lack of balance or buying power."""
+
+
+class OrderNotFound(ExchangeError):
+    """No order under that id at the venue -- already gone, or never there."""
+
+
+class OrderRejected(ExchangeError):
+    """The venue took the order and rejected it: post-only would have crossed,
+    the market is closed, self-trade prevention fired. `info` says which."""
+
+    def __init__(
+        self, message: str, *, reason: str | None = None, info: dict | None = None,
+        body: Any = None, status: int | None = None,
+    ):
+        super().__init__(message, body=body, status=status)
+        self.reason = reason
+        self.info = info or {}
+
+
+class MarketHalted(ExchangeError):
+    """The market is listed but not accepting orders right now."""
+
+
+class PermissionDenied(AuthenticationError):
+    """Credentials are valid but not allowed to do this: a read-only key, a
+    subaccount the key was not granted, a venue the account has not enabled."""
+
+
+class CredentialsMissing(AuthenticationError):
+    """No credentials configured for this venue.
+
+    Says which environment variables to set. Distinct from `PermissionDenied`
+    on purpose: one is a setup gap, the other is a decision someone made.
+    """
+
+
+class RiskRejected(SynpathError):
+    """Refused by this library's pre-trade checks before anything was sent.
+
+    `rule` names the check that fired. Not an `ExchangeError`: no venue was
+    involved, and retrying unchanged will be refused again.
+    """
+
+    def __init__(self, message: str, *, rule: str):
+        super().__init__(message)
+        self.rule = rule
+
+
+class RateBudgetExceeded(SynpathError):
+    """The local budget limiter could not honour the request in time.
+
+    Nothing was sent. The queue ahead of the request was already longer than
+    its deadline allowed, and quietly delaying it would have let a stop fire
+    late while looking like it fired on time.
+    """
+
+    def __init__(self, message: str, *, wait_s: float):
+        super().__init__(message)
+        self.wait_s = wait_s

synpath/trading/init.py

@@ -0,0 +1,233 @@
+"""`synpath init`: ask for each venue's keys and write them to a `.env` file.
+
+For someone who has never made a `.env` file: it asks venue by venue, checks
+each value as it is typed (a Kalshi key file that exists and is PEM, a
+Polymarket key and wallet address of the right shape), types secrets without
+echoing them, and writes the file readable by its owner only. An existing
+`.env` is updated in place: the settings asked about are replaced, every other
+line is kept. Nothing leaves the machine; at the end it runs `synpath doctor`
+on the file it wrote.
+"""
+from __future__ import annotations
+
+import argparse
+import getpass
+import os
+import re
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+
+from .credentials import read_dotenv
+
+PRIVATE_KEY = re.compile(r"^(0x)?[0-9a-fA-F]{64}$")
+ADDRESS = re.compile(r"^0x[0-9a-fA-F]{40}$")
+
+
+@dataclass
+class Prompter:
+    """How the command talks to a person; tests pass scripted answers."""
+
+    ask: Callable[[str], str] = input
+    ask_secret: Callable[[str], str] = getpass.getpass
+    say: Callable[[str], None] = print
+
+    def confirm(self, question: str, *, default: bool) -> bool:
+        hint = "[Y/n]" if default else "[y/N]"
+        while True:
+            answer = self.ask(f"{question} {hint} ").strip().lower()
+            if not answer:
+                return default
+            if answer in ("y", "yes"):
+                return True
+            if answer in ("n", "no"):
+                return False
+            self.say("  Please answer y or n.")
+
+    def value(self, question: str, *, check: Callable[[str], str | None], secret: bool = False,
+              default: str | None = None) -> str:
+        """Ask until `check` returns no complaint. `check` gets the stripped
+        answer and returns an error message, or None when it is fine."""
+        suffix = f" [{default}]" if default else ""
+        while True:
+            raw = (self.ask_secret if secret else self.ask)(f"  {question}{suffix}: ").strip()
+            if not raw and default is not None:
+                raw = default
+            problem = check(raw)
+            if problem is None:
+                return raw
+            self.say(f"  {problem}")
+
+
+def _required(what: str) -> Callable[[str], str | None]:
+    return lambda raw: None if raw else f"{what} is required."
+
+
+def _pem_file(raw: str) -> str | None:
+    if not raw:
+        return "The path to the private key file is required."
+    path = Path(raw).expanduser()
+    if not path.is_file():
+        return f"No file at {path}. Give the full path to the key file Kalshi downloaded."
+    try:
+        head = path.read_bytes()[:4096]
+    except OSError as exc:
+        return f"{path} cannot be read: {exc}"
+    if b"-----BEGIN" not in head:
+        return f"{path} is not a PEM key (no '-----BEGIN' line). Keep only the BEGIN...END block."
+    return None
+
+
+def _choice(*options: str) -> Callable[[str], str | None]:
+    return lambda raw: None if raw in options else f"Enter one of: {', '.join(options)}."
+
+
+def ask_kalshi(p: Prompter) -> dict[str, str]:
+    p.say("\nKalshi: Profile Settings -> API Keys -> Create New API Key on kalshi.com (or demo.kalshi.co).")
+    key_id = p.value("Key ID", check=_required("The Key ID"))
+    path = p.value("Path to the private key file it downloaded", check=_pem_file)
+    env = p.value("Environment, prod (real money) or demo", check=_choice("prod", "demo"), default="prod")
+    if env == "prod":
+        p.say("  prod trades real money.")
+    return {"KALSHI_KEY_ID": key_id, "KALSHI_PRIVATE_KEY_PATH": str(Path(path).expanduser().resolve()),
+            "KALSHI_ENV": env}
+
+
+def ask_polymarket(p: Prompter) -> dict[str, str]:
+    p.say("\nPolymarket: export your key on polymarket.com under Settings -> Private Key -> Start Export,")
+    p.say("and copy your trading wallet address from the profile menu. The key is typed hidden.")
+    key = p.value("Private key (0x...)", secret=True,
+                  check=lambda raw: None if PRIVATE_KEY.match(raw) else "That is not a private key: 64 hex characters, "
+                                                                        "optionally starting with 0x.")
+    funder = p.value("Trading wallet address (0x...)",
+                     check=lambda raw: None if ADDRESS.match(raw) else "That is not a wallet address: 0x and 40 hex "
+                                                                       "characters.")
+    signature = p.value("Signature type: 3 for accounts made since May 2026, 1 or 2 for older ones",
+                        check=_choice("0", "1", "2", "3"), default="3")
+    return {"POLYMARKET_PRIVATE_KEY": key if key.startswith("0x") else "0x" + key,
+            "POLYMARKET_FUNDER": funder, "POLYMARKET_SIGNATURE_TYPE": signature}
+
+
+def ask_polymarket_us(p: Prompter) -> dict[str, str]:
+    p.say("\nPolymarket US: create an API key at polymarket.us/developer after identity verification.")
+    key_id = p.value("Key ID", check=_required("The key ID"))
+    secret = p.value("Secret key (typed hidden)", secret=True, check=_required("The secret key"))
+    return {"POLYMARKET_US_KEY_ID": key_id, "POLYMARKET_US_SECRET_KEY": secret}
+
+
+VENUES: list[tuple[str, str, Callable[[Prompter], dict[str, str]]]] = [
+    ("Kalshi", "KALSHI_KEY_ID", ask_kalshi),
+    ("Polymarket", "POLYMARKET_PRIVATE_KEY", ask_polymarket),
+    ("Polymarket US", "POLYMARKET_US_KEY_ID", ask_polymarket_us),
+]
+
+
+def _quote(value: str) -> str:
+    return f'"{value}"' if any(ch.isspace() for ch in value) or "#" in value else value
+
+
+def merge(existing_text: str, values: dict[str, str]) -> str:
+    """The file with `values` set: a line already naming a key is rewritten in
+    place, new keys are appended, every other line is kept as it was."""
+    lines = existing_text.splitlines()
+    done: set[str] = set()
+    out: list[str] = []
+    for line in lines:
+        name = line.split("=", 1)[0].strip().removeprefix("export ").strip() if "=" in line else ""
+        if name in values and not line.lstrip().startswith("#"):
+            if name not in done:
+                out.append(f"{name}={_quote(values[name])}")
+                done.add(name)
+            continue
+        out.append(line)
+    new = [name for name in values if name not in done]
+    if new:
+        if out and out[-1].strip():
+            out.append("")
+        out.append("# written by synpath init")
+        out.extend(f"{name}={_quote(values[name])}" for name in new)
+    return "\n".join(out) + "\n"
+
+
+def write_private(path: Path, text: str) -> None:
+    """Write the file readable and writable by its owner only (0600), also
+    when it already existed with looser permissions."""
+    if path.exists():
+        os.chmod(path, 0o600)       # tighten before the secrets go in, not after
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as handle:
+        handle.write(text)
+    os.chmod(path, 0o600)
+
+
+def _git_ignores(path: Path) -> bool | None:
+    """True or False inside a git work tree; None when there is no git or no repository."""
+    if shutil.which("git") is None:
+        return None
+    folder = path.parent
+    inside = subprocess.run(["git", "rev-parse", "--is-inside-work-tree"], cwd=folder,
+                            capture_output=True, text=True)
+    if inside.returncode != 0:
+        return None
+    ignored = subprocess.run(["git", "check-ignore", "-q", path.name], cwd=folder)
+    return ignored.returncode == 0
+
+
+def run(path: Path, p: Prompter) -> int:
+    existing = read_dotenv(path) if path.exists() else {}
+    p.say(f"This sets up your venue keys in {path}. They stay on this machine; secrets are typed hidden.")
+    if path.exists():
+        p.say("That file exists: the settings you enter replace the ones there, everything else is kept.")
+    values: dict[str, str] = {}
+    for name, marker, ask in VENUES:
+        already = " (already set)" if existing.get(marker) else ""
+        if p.confirm(f"\nSet up {name}{already}?", default=False):
+            values.update(ask(p))
+    if not values:
+        p.say("\nNothing changed.")
+        return 0
+    text = merge(path.read_text(encoding="utf-8") if path.exists() else "", values)
+    write_private(path, text)
+    p.say(f"\nWrote {path}, readable by you only.")
+    try:
+        add = _git_ignores(path) is False and p.confirm(f"{path.name} is not ignored by git. Add it to .gitignore?",
+                                                        default=True)
+    except (KeyboardInterrupt, EOFError):
+        p.say("")
+        add = False
+    if add:
+        ignore = path.parent / ".gitignore"
+        current = ignore.read_text(encoding="utf-8") if ignore.exists() else ""
+        ignore.write_text(current + ("" if not current or current.endswith("\n") else "\n") + f"{path.name}\n",
+                          encoding="utf-8")
+        p.say(f"Added {path.name} to {ignore}.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="synpath init", description=__doc__.split("\n\n")[0])
+    parser.add_argument("--path", default=".env", help="the file to write (default: .env in this folder)")
+    args = parser.parse_args(argv)
+    if not sys.stdin.isatty():
+        print("synpath init asks questions: run it in a terminal.", file=sys.stderr)
+        return 2
+    path = Path(args.path).expanduser().resolve()
+    try:
+        result = run(path, Prompter())
+    except (KeyboardInterrupt, EOFError):
+        print("\nStopped; nothing was written.")
+        return 130
+    if result == 0 and path.exists():
+        from .__main__ import doctor
+
+        print("\nChecking what loads:\n")
+        doctor(str(path))
+        print("\nNext: synpath serve")
+    return result
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

synpath/trading/instruments.py

@@ -0,0 +1,162 @@
+"""The market master: what an order must satisfy, cached and dated.
+
+Every order is checked against reference data before it is signed -- the
+tick, the minimum size, whether the market is taking orders right now, when
+it closes. The read API has all of it on a `Market`; this turns one into a
+compact spec per market, applies the rules each venue does not write into
+its payload, and keeps the result with the time it was read so a stale spec
+is visibly stale rather than silently trusted.
+
+Venue rules that are not in any payload:
+
+  Kalshi          contracts are fixed-point with two decimals; tick from the
+                  market's price ladder, 0.01 when it publishes none
+  Polymarket      five shares minimum; tick per market, 0.01 by default
+  Polymarket US   whole contracts only; tick per market
+"""
+from __future__ import annotations
+
+import time
+from decimal import Decimal
+from typing import Any, Awaitable, Callable
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .. import ids
+from ..types import Market
+from .money import D
+from .types import Precision
+
+VENUE_RULES: dict[str, dict[str, Any]] = {
+    "kalshi": {"default_tick": Decimal("0.01"), "min_amount": Decimal("0.01"), "amount_step": Decimal("0.01"), "whole": False},
+    # Shares carry two decimals; the minimum (usually 5) is per market, read
+    # from its book by the trading adapter.
+    "polymarket": {"default_tick": Decimal("0.01"), "min_amount": Decimal("5"), "amount_step": Decimal("0.01"), "whole": False},
+    # Every live market trades whole contracts today, but a market may set a
+    # fractional `minimumTradeQty`; the trading adapters read it per market.
+    "polymarket_us": {"default_tick": Decimal("0.001"), "min_amount": Decimal("1"), "amount_step": Decimal("1"), "whole": True},
+}
+
+
+class MarketSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    market_id: str
+    """Synpath id, `venue:native`."""
+    venue: str
+    precision: Precision
+    tradable: bool
+    """Accepting orders right now, as far as the catalog knew."""
+    tradable_yes: bool = True
+    tradable_no: bool = True
+    """Per side, where a venue says (Polymarket US). Both true elsewhere."""
+    status: str
+    close_at: int | None = None
+    resolution_at: int | None = None
+    position_limit: Decimal | None = None
+    """A per-market cap the venue imposes, where it publishes one."""
+    yes_token: str | None = None
+    no_token: str | None = None
+    """The venue's own ids for the two sides, where it has them (Polymarket)."""
+    read_at: int = Field(default_factory=lambda: int(time.time() * 1000))
+    info: dict[str, Any] = Field(default_factory=dict)
+
+    def age_s(self, now_ms: int | None = None) -> float:
+        now = now_ms if now_ms is not None else int(time.time() * 1000)
+        return max(0.0, (now - self.read_at) / 1000)
+
+
+InstrumentSpec = MarketSpec
+"""The old name, kept so an import written against it still resolves."""
+
+
+def precision_for(market: Market) -> Precision:
+    rules = VENUE_RULES.get(market.venue, VENUE_RULES["polymarket"])
+    tick = D(market.tick_size) if market.tick_size else rules["default_tick"]
+    return Precision(
+        tick=tick,
+        min_amount=rules["min_amount"],
+        amount_step=rules["amount_step"],
+        whole_contracts=rules["whole"],
+        face_value=D(market.face_value),
+    )
+
+
+def spec_from_market(market: Market) -> MarketSpec:
+    yes_info, no_info = market.yes.info or {}, market.no.info or {}
+    tradable_yes = bool(yes_info.get("tradable", True))   # Polymarket US publishes it per side
+    tradable_no = bool(no_info.get("tradable", True))
+    return MarketSpec(
+        market_id=market.id,
+        venue=market.venue,
+        precision=precision_for(market),
+        tradable=bool(market.active) and tradable_yes and tradable_no,
+        tradable_yes=tradable_yes,
+        tradable_no=tradable_no,
+        status=market.status,
+        close_at=market.close_timestamp,
+        resolution_at=market.resolution_timestamp,
+        position_limit=None,
+        yes_token=market.yes.venue_token_id,
+        no_token=market.no.venue_token_id,
+        info={"native_status": market.native_status},
+    )
+
+
+Loader = Callable[[str, list[str]], Awaitable[list[Market]]]
+"""`(venue, market_ids) -> markets`, however the caller reaches the venue."""
+
+
+class MarketMaster:
+    """Specs by Synpath market id, with a freshness rule.
+
+    Reads never block on the network: `get` returns what is held or raises
+    `KeyError`, and `stale` says which held specs are past `ttl_s` so the
+    caller can refresh them through a loader of its choosing. Loading is the
+    caller's concern because the read adapters are synchronous today and the
+    engine will not run them on its loop thread.
+    """
+
+    def __init__(self, *, ttl_s: float = 300.0):
+        self.ttl_s = ttl_s
+        self._specs: dict[str, MarketSpec] = {}
+
+    def put(self, specs: list[MarketSpec]) -> None:
+        for spec in specs:
+            self._specs[spec.market_id] = spec
+
+    def put_market(self, market: Market) -> None:
+        self.put([spec_from_market(market)])
+
+    def get(self, market_id: str) -> MarketSpec:
+        return self._specs[market_id]
+
+    def find(self, market_id: str) -> MarketSpec | None:
+        return self._specs.get(market_id)
+
+    def stale(self, market_ids: list[str] | None = None, *, now_ms: int | None = None) -> list[str]:
+        """Held specs older than `ttl_s`, plus ids not held at all."""
+        wanted = market_ids if market_ids is not None else list(self._specs)
+        out = []
+        for market_id in wanted:
+            spec = self._specs.get(market_id)
+            if spec is None or spec.age_s(now_ms) > self.ttl_s:
+                out.append(market_id)
+        return out
+
+    async def refresh(self, loader: Loader, market_ids: list[str]) -> None:
+        """Reload `market_ids` through `loader`, grouped by venue. The venue
+        is read off the id itself, which is what the prefix is for."""
+        wanted: dict[str, list[str]] = {}
+        for market_id in market_ids:
+            wanted.setdefault(ids.venue_of(market_id), []).append(market_id)
+        for venue, batch in wanted.items():
+            for market in await loader(venue, list(dict.fromkeys(batch))):
+                self.put_market(market)
+
+    def __len__(self) -> int:
+        return len(self._specs)
+
+
+InstrumentMaster = MarketMaster
+"""The old name, kept so an import written against it still resolves."""