synpath 0.1.0__py3-none-any.whl

synpath/trading/__init__.py

@@ -0,0 +1,79 @@
+"""synpath.trading — order entry, the foundations.
+
+Everything in this package is async-native and money is `Decimal`. Every
+public name here is re-exported from the top-level package, so
+`from synpath import OrderRequest` and `from synpath.trading import
+OrderRequest` are the same thing.
+
+```python
+from synpath import KalshiTrading, OrderRequest, Side, OrderType, TimeInForce, load_credentials
+```
+
+The venue signing stacks are part of the base install (`pip install
+synpath`). Should one be missing from an unusual environment, importing this
+package still works -- the types, money helpers and credential loading need
+nothing extra -- and the first thing that needs a signer says what to install.
+"""
+from __future__ import annotations
+
+from .base import TradingExchange
+from .errors import (
+    CredentialsMissing,
+    DuplicateClientOrderId,
+    InsufficientFunds,
+    InvalidOrder,
+    MarketHalted,
+    OrderNotFound,
+    OrderRejected,
+    PermissionDenied,
+    RateBudgetExceeded,
+    RiskRejected,
+)
+from .types import (
+    Account,
+    Balance,
+    EditRequest,
+    FeeEstimate,
+    Fill,
+    HeldBy,
+    Liquidity,
+    Order,
+    OrderRequest,
+    OrderStatus,
+    OrderType,
+    Position,
+    PositionSide,
+    Precision,
+    Settlement,
+    SettlementState,
+    Side,
+    TimeInForce,
+)
+
+from .kalshi import KalshiTrading
+
+
+def __getattr__(name: str):
+    # The Polymarket adapters pull in eth-account and PyJWT; importing them
+    # lazily keeps `import synpath.trading` working for a Kalshi-only install.
+    if name == "PolymarketTrading":
+        from .polymarket import PolymarketTrading
+        return PolymarketTrading
+    if name == "PolymarketUSTrading":
+        from .polymarket_us import PolymarketUSTrading
+        return PolymarketUSTrading
+    if name == "PolymarketUSExchangeTrading":
+        from .polymarket_us_exchange import PolymarketUSExchangeTrading
+        return PolymarketUSExchangeTrading
+    raise AttributeError(name)
+
+
+__all__ = [
+    "TradingExchange", "KalshiTrading", "PolymarketTrading", "PolymarketUSTrading", "PolymarketUSExchangeTrading",
+    "Account", "Balance", "EditRequest", "FeeEstimate", "Fill", "HeldBy", "Liquidity",
+    "Order", "OrderRequest", "OrderStatus", "OrderType", "Position", "PositionSide",
+    "Precision", "Settlement", "SettlementState", "Side", "TimeInForce",
+    "CredentialsMissing", "DuplicateClientOrderId", "InsufficientFunds", "InvalidOrder",
+    "MarketHalted", "OrderNotFound", "OrderRejected", "PermissionDenied",
+    "RateBudgetExceeded", "RiskRejected",
+]

synpath/trading/__main__.py

@@ -0,0 +1,69 @@
+"""`synpath doctor`: what credentials loaded, without printing one.
+
+Reads the environment and a `.env` in the working directory, loads each
+venue's credentials the way the adapters will, and reports per venue whether
+anything is configured, which environment (demo, preprod, prod) it points
+at, and the public half of the identity (a key id, an API key prefix, a
+funder address). Secrets are never printed; the logging filter that scrubs
+them is installed first.
+
+The venue round trip -- calling one harmless authenticated endpoint per
+venue -- arrives with each trading adapter.
+"""
+from __future__ import annotations
+
+import argparse
+import logging
+import sys
+
+from .credentials import ENV_NAMES, load_credentials
+from .errors import CredentialsMissing
+
+
+def doctor(dotenv: str | None) -> int:
+    logging.basicConfig(level=logging.INFO, format="%(message)s")
+    try:
+        loaded = load_credentials(dotenv=dotenv)
+    except CredentialsMissing as exc:
+        print(f"credentials: {exc}")
+        return 2
+    rows = []
+    for venue, creds in loaded.items():
+        if creds is None:
+            names = ENV_NAMES[venue]
+            hint = ", or run synpath init" if venue in ("kalshi", "polymarket", "polymarket_us") else ""
+            rows.append((venue, "not configured", f"set {names[0]}{hint}"))
+            continue
+        stage = getattr(creds, "env", "-")
+        if getattr(creds, "key_id", None):
+            identity = f"key id {creds.key_id}"
+        elif getattr(creds, "participant_id", None):
+            identity = f"participant {creds.participant_id}"
+        elif getattr(creds, "funder", None):
+            identity = f"funder {creds.funder} (signature type {creds.signature_type})"
+        elif getattr(creds, "api_key", None):
+            identity = f"api key {creds.api_key[:8]}…"
+        else:
+            identity = "wallet key loaded"
+        rows.append((venue, f"configured ({stage})", identity))
+    width = max(len(r[0]) for r in rows)
+    for venue, state, detail in rows:
+        print(f"{venue:<{width}}  {state:<22}  {detail}")
+    configured = sum(1 for _, state, _ in rows if state.startswith("configured"))
+    print(f"\n{configured} of {len(rows)} venues configured. No secret was printed.")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="synpath")
+    sub = parser.add_subparsers(dest="command", required=True)
+    doc = sub.add_parser("doctor", help="report which venue credentials load")
+    doc.add_argument("--dotenv", default=None, help="path to a .env file (default: ./.env if present)")
+    args = parser.parse_args(argv)
+    if args.command == "doctor":
+        return doctor(args.dotenv)
+    return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

synpath/trading/base.py

@@ -0,0 +1,126 @@
+"""What every venue's order entry offers, in one async interface.
+
+A trading adapter answers the trading keys in `has` the same way a read
+adapter answers the read keys: `True` for what the venue itself holds and
+does, `False` for what it does not, filled in completely at class creation
+so `has[key]` never raises. It claims nothing the venue does not do; a stop
+or an iceberg is the execution engine's capability, reported by the engine.
+
+Every method is a coroutine. The engine that will drive these holds
+WebSockets on the same event loop, and a blocking call inside it would stall
+every socket for one venue round trip -- the exact moment a stop must fire.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from decimal import Decimal
+from typing import Any
+
+from ..base import Capability, complete_capabilities
+from ..errors import NotSupported
+from ..types import Page
+from .types import (
+    Side,
+    Account, Balance, EditRequest, FeeEstimate, Fill, Order, OrderRequest, Position, Settlement,
+)
+
+
+class TradingExchange(ABC):
+    id: str
+    name: str
+    has: dict[str, Capability] = {}
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        complete_capabilities(cls)
+
+    # -- orders ---------------------------------------------------------------
+
+    @abstractmethod
+    async def create_order(self, request: OrderRequest) -> Order:
+        """Place one order the venue holds: a limit, or a market where the
+        venue has them. Anything else belongs to the engine."""
+
+    async def create_orders(self, requests: list[OrderRequest]) -> list[Order | Exception]:
+        """Many orders in one call, one result per request in the order asked
+        for. A request the venue refused comes back as its exception rather
+        than failing the batch: partial success is normal."""
+        raise NotSupported(f"{self.id}: create_orders")
+
+    @abstractmethod
+    async def cancel_order(self, order_id: str, *, market_id: str | None = None) -> Order:
+        """Cancel one order. Returns the order as the venue reports it after
+        the cancel, with `filled` carrying whatever matched first."""
+
+    async def cancel_orders(self, order_ids: list[str], *, market_id: str | None = None) -> list[Order | Exception]:
+        raise NotSupported(f"{self.id}: cancel_orders")
+
+    async def cancel_all_orders(self, *, market_id: str | None = None) -> int | None:
+        """Cancel every resting order, or every one on a market. Returns how
+        many the venue reports cancelling, or `None` where it acknowledges
+        without a count."""
+        raise NotSupported(f"{self.id}: cancel_all_orders")
+
+    async def edit_order(self, request: EditRequest, *, current: Order | None = None) -> Order:
+        """Change a resting order in place where the venue allows it, or by
+        cancel and replace where it does not. `Order.queue_priority_preserved`
+        says which happened."""
+        raise NotSupported(f"{self.id}: edit_order")
+
+    @abstractmethod
+    async def fetch_order(self, order_id: str) -> Order:
+        """One order by the venue's id."""
+
+    @abstractmethod
+    async def fetch_open_orders(self, *, market_id: str | None = None) -> list[Order]:
+        """Every resting order, or every one on a market."""
+
+    async def fetch_orders(
+        self, *, status: str | None = None, market_id: str | None = None,
+        since: int | None = None, limit: int | None = None, cursor: str | None = None,
+    ) -> Page[Order]:
+        raise NotSupported(f"{self.id}: fetch_orders")
+
+    async def fetch_my_trades(
+        self, *, market_id: str | None = None, order_id: str | None = None,
+        since: int | None = None, limit: int | None = None, cursor: str | None = None,
+    ) -> Page[Fill]:
+        raise NotSupported(f"{self.id}: fetch_my_trades")
+
+    async def fetch_queue_position(self, order_id: str) -> Decimal:
+        """Contracts ahead of this order at its price level."""
+        raise NotSupported(f"{self.id}: fetch_queue_position")
+
+    # -- account --------------------------------------------------------------
+
+    @abstractmethod
+    async def fetch_balance(self, *, account: Account | None = None) -> Balance:
+        """This account's balance at this venue. Never pooled with another."""
+
+    @abstractmethod
+    async def fetch_positions(self, *, market_id: str | None = None, event_id: str | None = None) -> list[Position]:
+        """Open positions, in this venue's own netting model."""
+
+    async def fetch_settlements(
+        self, *, market_id: str | None = None, since: int | None = None,
+        limit: int | None = None, cursor: str | None = None,
+    ) -> Page[Settlement]:
+        raise NotSupported(f"{self.id}: fetch_settlements")
+
+    async def fetch_fee_estimate(self, market_id: str, side: Side, price: Decimal, amount: Decimal) -> FeeEstimate:
+        """What an order on this market would cost, in the YES price."""
+        raise NotSupported(f"{self.id}: fetch_fee_estimate")
+
+    # -- housekeeping ---------------------------------------------------------
+
+    async def close(self) -> None:
+        pass
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"<{type(self).__name__} {self.id}>"

synpath/trading/credentials.py

@@ -0,0 +1,400 @@
+"""Venue credentials: where they come from, and where they never go.
+
+They come from the environment, or from a `.env` file next to the caller
+that is git-ignored; the environment wins. They are
+loaded once into frozen objects whose `repr` shows nothing secret, and every
+secret value is registered with a logging filter so that a stray `%r` in a
+log line prints `***` rather than a private key.
+
+Nothing here talks to a venue. `synpath doctor` reports what
+loaded; the adapters are what use it.
+
+  Kalshi              KALSHI_KEY_ID, KALSHI_PRIVATE_KEY_PATH, KALSHI_ENV (prod, the default, or demo)
+  Polymarket          POLYMARKET_PRIVATE_KEY, POLYMARKET_SIGNATURE_TYPE (0-3),
+                      POLYMARKET_FUNDER, and optionally POLYMARKET_API_KEY /
+                      _API_SECRET / _API_PASSPHRASE, POLYMARKET_BUILDER_CODE,
+                      POLYMARKET_RELAYER_API_KEY / _RELAYER_API_KEY_ADDRESS,
+                      POLYMARKET_RPC_URL
+  Polymarket US       POLYMARKET_US_KEY_ID, POLYMARKET_US_SECRET_KEY
+    (retail API)
+  Polymarket US       POLYMARKET_US_CLIENT_ID, POLYMARKET_US_PRIVATE_KEY_PATH,
+    (exchange API)    POLYMARKET_US_PARTICIPANT_ID, POLYMARKET_US_ACCOUNT,
+                      POLYMARKET_US_ENV (preprod|prod)
+"""
+from __future__ import annotations
+
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Literal, Mapping
+
+from .errors import CredentialsMissing
+
+REDACTED = "***"
+
+
+def _redacted_repr(self: Any) -> str:
+    public = {k: v for k, v in self.__dict__.items() if k in self._public}
+    return f"{type(self).__name__}({', '.join(f'{k}={v!r}' for k, v in public.items())}, secrets={REDACTED})"
+
+
+@dataclass(frozen=True, repr=False)
+class KalshiCredentials:
+    key_id: str
+    private_key_pem: bytes = field(repr=False)
+    """RSA private key, PEM. Signs `timestamp + method + path` per request."""
+    env: Literal["demo", "prod"] = "prod"
+    """`prod` trades on Kalshi itself; `demo` on its practice exchange."""
+    _public = ("key_id", "env")
+    __repr__ = _redacted_repr
+
+    @property
+    def secrets(self) -> list[str]:
+        return [self.private_key_pem.decode(errors="ignore")]
+
+
+SYNPATH_BUILDER_CODE = "0x3373b88f438d41079965d0742b16c602aa932cbc3b7ee589db36cbf85778c869"
+"""Synpath's Polymarket builder code, attached to orders unless the account
+sets its own or opts out (`POLYMARKET_BUILDER_CODE=none`). Its builder fee
+rate is 0: it adds nothing to what an order costs."""
+
+BUILDER_CODE = re.compile(r"^0x[0-9a-fA-F]{64}$")
+
+
+@dataclass(frozen=True, repr=False)
+class PolymarketCredentials:
+    private_key: str = field(repr=False)
+    """The signer's private key, hex. Signs every order (EIP-712) and, when
+    no API credentials are given, derives them."""
+    signature_type: int = 0
+    """Which wallet the orders spend from: 0 an EOA (allowlisted accounts
+    only), 1 a legacy Magic/Google proxy wallet, 2 a legacy Safe, 3 a
+    Deposit Wallet -- the default for every account created since
+    2026-05-04."""
+    funder: str | None = None
+    """The account wallet that holds the pUSD and tokens. Required for types
+    1-3; for an EOA it is the signer's own address."""
+    api_key: str | None = None
+    api_secret: str | None = field(default=None, repr=False)
+    api_passphrase: str | None = field(default=None, repr=False)
+    """CLOB API credentials, when already created. Derived from the wallet
+    key on first use otherwise."""
+    builder_code: str | None = SYNPATH_BUILDER_CODE
+    """A bytes32 builder code attached to every order for attribution. Public,
+    not a secret. Synpath's by default; None attaches none."""
+    relayer_api_key: str | None = field(default=None, repr=False)
+    relayer_api_key_address: str | None = None
+    """A Relayer API key (polymarket.com -> Settings -> API Keys) for gasless
+    wallet transactions: approvals, split, merge, redeem."""
+    rpc_url: str | None = None
+    """A Polygon JSON-RPC endpoint, for an EOA's own on-chain transactions."""
+    _public = ("signature_type", "funder", "api_key", "builder_code", "relayer_api_key_address")
+    __repr__ = _redacted_repr
+
+    @property
+    def secrets(self) -> list[str]:
+        return [v for v in (self.private_key, self.api_secret, self.api_passphrase, self.relayer_api_key) if v]
+
+
+@dataclass(frozen=True, repr=False)
+class PolymarketUSCredentials:
+    """The retail API at `api.polymarket.us`: a key from polymarket.us/developer
+    after identity verification in the app."""
+
+    key_id: str
+    secret_key: str = field(repr=False)
+    """Base64 Ed25519 private key, shown once at creation. Signs
+    `timestamp + METHOD + path` on every request."""
+    _public = ("key_id",)
+    __repr__ = _redacted_repr
+
+    @property
+    def secrets(self) -> list[str]:
+        return [self.secret_key]
+
+
+@dataclass(frozen=True, repr=False)
+class PolymarketUSExchangeCredentials:
+    """The exchange API at `api.{preprod,prod}.polymarketexchange.com`: a
+    firm onboarded by Polymarket US, with a client id, an RSA key pair and a
+    participant id per user."""
+
+    client_id: str
+    private_key_pem: bytes = field(repr=False)
+    """RSA private key, PEM. Signs the client-assertion JWT exchanged for a
+    three-minute access token."""
+    participant_id: str
+    """`firms/<firm>/users/<user>`, exactly as issued at onboarding."""
+    account: str | None = None
+    """The trading account orders are placed on. The first account the user
+    may trade when not given."""
+    env: Literal["preprod", "prod"] = "preprod"
+    _public = ("client_id", "participant_id", "account", "env")
+    __repr__ = _redacted_repr
+
+    @property
+    def secrets(self) -> list[str]:
+        return [self.private_key_pem.decode(errors="ignore")]
+
+
+Credentials = KalshiCredentials | PolymarketCredentials | PolymarketUSCredentials | PolymarketUSExchangeCredentials
+
+ENV_NAMES: dict[str, tuple[str, ...]] = {
+    "kalshi": ("KALSHI_KEY_ID", "KALSHI_PRIVATE_KEY_PATH", "KALSHI_ENV"),
+    "polymarket": (
+        "POLYMARKET_PRIVATE_KEY", "POLYMARKET_SIGNATURE_TYPE", "POLYMARKET_FUNDER",
+        "POLYMARKET_API_KEY", "POLYMARKET_API_SECRET", "POLYMARKET_API_PASSPHRASE",
+        "POLYMARKET_BUILDER_CODE", "POLYMARKET_RELAYER_API_KEY", "POLYMARKET_RELAYER_API_KEY_ADDRESS",
+        "POLYMARKET_RPC_URL",
+    ),
+    "polymarket_us": ("POLYMARKET_US_KEY_ID", "POLYMARKET_US_SECRET_KEY"),
+    "polymarket_us_exchange": (
+        "POLYMARKET_US_CLIENT_ID", "POLYMARKET_US_PRIVATE_KEY_PATH", "POLYMARKET_US_PARTICIPANT_ID",
+        "POLYMARKET_US_ACCOUNT", "POLYMARKET_US_ENV",
+    ),
+}
+"""What each venue reads. The first entry is the one whose absence means
+"not configured"; the rest are optional or have defaults."""
+
+
+def read_dotenv(path: Path | str) -> dict[str, str]:
+    """A `.env` file as a dict. `KEY=value`, `#` comments, optional quotes.
+
+    Deliberately small: it exists so a user can keep credentials in a
+    git-ignored file without another dependency, not to be a shell.
+    """
+    values: dict[str, str] = {}
+    text = Path(path).read_text(encoding="utf-8")
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        if key.startswith("export "):
+            key = key[7:].strip()
+        value = value.strip()
+        if len(value) >= 2 and value[0] == value[-1] and value[0] in "\"'":
+            value = value[1:-1]
+        values[key] = value
+    return values
+
+
+def _read_pem(path: str, *, var: str) -> bytes:
+    try:
+        data = Path(path).expanduser().read_bytes()
+    except OSError as exc:
+        raise CredentialsMissing(f"{var} points at {path!r}, which cannot be read: {exc}") from None
+    if b"-----BEGIN" not in data:
+        raise CredentialsMissing(
+            f"{var} points at {path!r}, which is not a PEM key (no '-----BEGIN' line). "
+            f"If the venue gave you a text file with an id line on top, keep only the "
+            f"BEGIN...END block."
+        )
+    return data
+
+
+def load_kalshi(env: Mapping[str, str]) -> KalshiCredentials | None:
+    key_id = env.get("KALSHI_KEY_ID")
+    if not key_id:
+        return None
+    path = env.get("KALSHI_PRIVATE_KEY_PATH")
+    if not path:
+        raise CredentialsMissing("KALSHI_KEY_ID is set but KALSHI_PRIVATE_KEY_PATH is not")
+    stage = (env.get("KALSHI_ENV") or "prod").lower()
+    if stage not in ("demo", "prod"):
+        raise CredentialsMissing(f"KALSHI_ENV must be demo or prod, got {stage!r}")
+    return KalshiCredentials(key_id=key_id, private_key_pem=_read_pem(path, var="KALSHI_PRIVATE_KEY_PATH"), env=stage)  # type: ignore[arg-type]
+
+
+def load_polymarket(env: Mapping[str, str]) -> PolymarketCredentials | None:
+    key = env.get("POLYMARKET_PRIVATE_KEY")
+    if not key:
+        return None
+    raw_type = env.get("POLYMARKET_SIGNATURE_TYPE") or "0"
+    try:
+        signature_type = int(raw_type)
+    except ValueError:
+        signature_type = -1
+    if signature_type not in (0, 1, 2, 3):
+        raise CredentialsMissing(f"POLYMARKET_SIGNATURE_TYPE must be 0, 1, 2 or 3, got {raw_type!r}")
+    funder = env.get("POLYMARKET_FUNDER") or None
+    if signature_type != 0 and not funder:
+        raise CredentialsMissing(
+            f"POLYMARKET_SIGNATURE_TYPE={signature_type} spends from a smart wallet; set POLYMARKET_FUNDER "
+            f"to its address (polymarket.com -> profile menu)"
+        )
+    api = [env.get(name) or None for name in ("POLYMARKET_API_KEY", "POLYMARKET_API_SECRET", "POLYMARKET_API_PASSPHRASE")]
+    if any(api) and not all(api):
+        raise CredentialsMissing(
+            "POLYMARKET_API_KEY, POLYMARKET_API_SECRET and POLYMARKET_API_PASSPHRASE go together; "
+            "set all three, or none to derive them from the wallet key"
+        )
+    relayer = env.get("POLYMARKET_RELAYER_API_KEY") or None
+    relayer_address = env.get("POLYMARKET_RELAYER_API_KEY_ADDRESS") or None
+    if relayer and not relayer_address:
+        raise CredentialsMissing("POLYMARKET_RELAYER_API_KEY is set but POLYMARKET_RELAYER_API_KEY_ADDRESS is not")
+    return PolymarketCredentials(
+        private_key=key, signature_type=signature_type, funder=funder,
+        api_key=api[0], api_secret=api[1], api_passphrase=api[2],
+        builder_code=_builder_code(env.get("POLYMARKET_BUILDER_CODE")),
+        relayer_api_key=relayer, relayer_api_key_address=relayer_address,
+        rpc_url=env.get("POLYMARKET_RPC_URL") or None,
+    )
+
+
+def _builder_code(raw: str | None) -> str | None:
+    """`POLYMARKET_BUILDER_CODE`: unset or empty is Synpath's code, `none`
+    attaches none, anything else must be a bytes32 hex code."""
+    value = (raw or "").strip()
+    if not value:
+        return SYNPATH_BUILDER_CODE
+    if value.lower() == "none":
+        return None
+    if not BUILDER_CODE.match(value):
+        raise CredentialsMissing(
+            f"POLYMARKET_BUILDER_CODE must be a bytes32 hex code (0x and 64 hex characters) or 'none', got {value!r}"
+        )
+    return value
+
+
+def load_polymarket_us(env: Mapping[str, str]) -> PolymarketUSCredentials | None:
+    key_id = env.get("POLYMARKET_US_KEY_ID")
+    if not key_id:
+        return None
+    secret = env.get("POLYMARKET_US_SECRET_KEY")
+    if not secret:
+        raise CredentialsMissing("POLYMARKET_US_KEY_ID is set but POLYMARKET_US_SECRET_KEY is not")
+    return PolymarketUSCredentials(key_id=key_id, secret_key=secret)
+
+
+def load_polymarket_us_exchange(env: Mapping[str, str]) -> PolymarketUSExchangeCredentials | None:
+    client_id = env.get("POLYMARKET_US_CLIENT_ID")
+    if not client_id:
+        return None
+    path = env.get("POLYMARKET_US_PRIVATE_KEY_PATH")
+    if not path:
+        raise CredentialsMissing("POLYMARKET_US_CLIENT_ID is set but POLYMARKET_US_PRIVATE_KEY_PATH is not")
+    participant = env.get("POLYMARKET_US_PARTICIPANT_ID")
+    if not participant:
+        raise CredentialsMissing(
+            "POLYMARKET_US_CLIENT_ID is set but POLYMARKET_US_PARTICIPANT_ID is not; it is issued at "
+            "onboarding as firms/<firm>/users/<user>"
+        )
+    stage = (env.get("POLYMARKET_US_ENV") or "preprod").lower()
+    if stage not in ("preprod", "prod"):
+        raise CredentialsMissing(f"POLYMARKET_US_ENV must be preprod or prod, got {stage!r}")
+    return PolymarketUSExchangeCredentials(
+        client_id=client_id,
+        private_key_pem=_read_pem(path, var="POLYMARKET_US_PRIVATE_KEY_PATH"),
+        participant_id=participant,
+        account=env.get("POLYMARKET_US_ACCOUNT") or None,
+        env=stage,  # type: ignore[arg-type]
+    )
+
+
+LOADERS = {
+    "kalshi": load_kalshi,
+    "polymarket": load_polymarket,
+    "polymarket_us": load_polymarket_us,
+    "polymarket_us_exchange": load_polymarket_us_exchange,
+}
+
+
+def load_credentials(
+    env: Mapping[str, str] | None = None, *, dotenv: Path | str | None = None,
+    redact_logs: bool = True,
+) -> dict[str, Credentials | None]:
+    """Every venue's credentials, or `None` where none are configured.
+
+    The process environment wins over the `.env` file, so a variable exported
+    for one run overrides what the file says. With `redact_logs`, every secret
+    loaded is registered with the logging filter before anything else can
+    print it.
+    """
+    merged: dict[str, str] = {}
+    if dotenv is not None and Path(dotenv).exists():
+        merged.update(read_dotenv(dotenv))
+    elif dotenv is None and Path(".env").exists():
+        merged.update(read_dotenv(".env"))
+    merged.update(env if env is not None else os.environ)
+    loaded = {venue: loader(merged) for venue, loader in LOADERS.items()}
+    if redact_logs:
+        for creds in loaded.values():
+            if creds is not None:
+                SecretFilter.install(creds.secrets)
+    return loaded
+
+
+def require(venue: str, loaded: Mapping[str, Credentials | None]) -> Credentials:
+    """The venue's credentials, or `CredentialsMissing` naming what to set."""
+    creds = loaded.get(venue)
+    if creds is None:
+        names = ", ".join(ENV_NAMES.get(venue, ()))
+        raise CredentialsMissing(f"no {venue} credentials configured; set {names}")
+    return creds
+
+
+class SecretFilter(logging.Filter):
+    """Replaces registered secret values with `***` in every log record.
+
+    Attached to the root logger once, so every logger in the process is
+    covered, including third-party ones that might echo a request body.
+    Secrets are matched as substrings, so a PEM's base64 lines are scrubbed
+    even when only part of the key is printed.
+    """
+
+    _instance: "SecretFilter | None" = None
+
+    def __init__(self) -> None:
+        super().__init__("synpath-secrets")
+        self._secrets: list[str] = []
+
+    @classmethod
+    def install(cls, secrets: list[str]) -> "SecretFilter":
+        if cls._instance is None:
+            cls._instance = cls()
+            logging.getLogger().addFilter(cls._instance)
+            for handler in logging.getLogger().handlers:
+                handler.addFilter(cls._instance)
+        cls._instance.add(secrets)
+        return cls._instance
+
+    def add(self, secrets: list[str]) -> None:
+        for secret in secrets:
+            for piece in _pieces(secret):
+                if piece and piece not in self._secrets:
+                    self._secrets.append(piece)
+        self._secrets.sort(key=len, reverse=True)
+
+    def scrub(self, text: str) -> str:
+        for secret in self._secrets:
+            if secret in text:
+                text = text.replace(secret, REDACTED)
+        return text
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if not self._secrets:
+            return True
+        try:
+            message = record.getMessage()
+        except Exception:  # pragma: no cover - a broken format string is not ours to fix
+            return True
+        scrubbed = self.scrub(message)
+        if scrubbed != message:
+            record.msg = scrubbed
+            record.args = ()
+        return True
+
+
+def _pieces(secret: str) -> list[str]:
+    """A secret and, for a PEM, each of its base64 lines."""
+    pieces = [secret.strip()]
+    if "-----BEGIN" in secret:
+        pieces += [
+            line.strip() for line in secret.splitlines()
+            if line.strip() and not line.startswith("-----")
+        ]
+    return [p for p in pieces if len(p) >= 8]