pmquant 0.1.0__py3-none-any.whl

pmq/__init__.py

@@ -0,0 +1,31 @@
+"""pmq: fail-closed execution and market data for Polymarket CLOB V2.
+
+Data layer (no keys needed): get_market, parse_market, get_book,
+best_bid_ask, band_ask_depth_usd, resolved_winner, book_inferred_winner,
+get_tape, fee, FEE_RATES.
+
+Execution layer (keys stay local, nothing booked without exchange
+confirmation): PolymarketExecutor, Fill, OrderUncertain.
+"""
+from .data import (FEE_RATES, band_ask_depth_usd, best_bid_ask,
+                   book_inferred_winner, book_meta, fee, get_book, get_market,
+                   get_tape, http_get_json, parse_market, resolved_winner)
+from .exceptions import IntrospectionMismatch, OrderUncertain, PmqError
+
+__version__ = "0.1.0"
+__all__ = [
+    "FEE_RATES", "band_ask_depth_usd", "best_bid_ask", "book_inferred_winner",
+    "book_meta", "fee", "get_book", "get_market", "get_tape", "http_get_json",
+    "parse_market", "resolved_winner",
+    "PolymarketExecutor", "Fill",
+    "PmqError", "OrderUncertain", "IntrospectionMismatch",
+    "__version__",
+]
+
+
+def __getattr__(name):
+    # Lazy import: the data layer must stay usable without py-clob-client-v2.
+    if name in ("PolymarketExecutor", "Fill", "DEFAULT_BUILDER_CODE"):
+        from . import executor
+        return getattr(executor, name)
+    raise AttributeError(name)

pmq/data.py

@@ -0,0 +1,208 @@
+"""Market data layer for Polymarket, with the operational knowledge encoded.
+
+Facts this module encodes (verified live, July 2026):
+
+* The CLOB ``/book`` endpoint is REAL TIME (served by the matching engine,
+  includes ``last_trade_price``). The data-api ``/trades`` indexer LAGS
+  matching by 1 to 3 minutes (measured: freshest visible trade 120s old).
+  Therefore: books drive live decisions; the trade tape is for OFFLINE
+  scoring only, at least 5 minutes after the window closes.
+* Gamma ``/markets?slug=`` returns ``[]`` for EXPIRED short-lived markets;
+  ``/events?slug=`` still resolves them. :func:`get_market` does the
+  fallback for you.
+* Gamma settlement (outcomePrices pinned to 0.99+) can lag the market close
+  by more than 15 minutes; the last pre-close book identifies the winner
+  immediately (a side bid pinned at 0.90+ means that side won). See
+  :func:`book_inferred_winner`.
+* Taker fees (since 2026-03-30, decided at match time under CLOB V2):
+  ``fee = rate * price * (1 - price) * shares`` with a per-category rate,
+  see :data:`FEE_RATES`. Makers always pay zero. The ``maker/taker_base_fee``
+  of 1000 bps seen in API responses is an on-chain CAP, never the charge.
+"""
+import calendar
+import json
+import time
+import urllib.request
+
+UA = {"User-Agent": "Mozilla/5.0"}
+GAMMA = "https://gamma-api.polymarket.com"
+CLOB = "https://clob.polymarket.com"
+DATA = "https://data-api.polymarket.com"
+
+#: Official taker fee rates per market category (docs.polymarket.com/trading/fees,
+#: fetched 2026-07-03). Fee in $ = rate * p * (1 - p) * shares. Makers pay 0.
+FEE_RATES = {
+    "crypto": 0.07,
+    "sports": 0.03,
+    "finance": 0.04,
+    "politics": 0.04,
+    "mentions": 0.04,
+    "tech": 0.04,
+    "economics": 0.05,
+    "culture": 0.05,
+    "weather": 0.05,
+    "geopolitics": 0.0,
+}
+
+
+def fee(price, shares, rate=FEE_RATES["crypto"]):
+    """Taker fee in $ under the current schedule. Makers pay zero.
+
+    The fee peaks at price 0.50 and vanishes toward 0 and 1: a taker fill at
+    0.95 costs about a third of one at 0.50 for the same share count.
+    """
+    return rate * price * (1.0 - price) * shares
+
+
+def http_get_json(url, retries=3, timeout=10, logger=None):
+    """GET a JSON document with linear backoff. Returns None on final failure."""
+    for i in range(retries):
+        try:
+            req = urllib.request.Request(url, headers=UA)
+            with urllib.request.urlopen(req, timeout=timeout) as r:
+                return json.loads(r.read().decode())
+        except Exception as e:
+            if i == retries - 1:
+                if logger:
+                    logger(f"GET failed permanently: {url} ({e})")
+                return None
+            time.sleep(1.5 * (i + 1))
+    return None
+
+
+def get_market(slug, logger=None):
+    """Gamma market object for a slug, falling back to /events for expired ones."""
+    data = http_get_json(f"{GAMMA}/markets?slug={slug}", logger=logger)
+    if data:
+        return data[0]
+    ev = http_get_json(f"{GAMMA}/events?slug={slug}", logger=logger)
+    if ev and ev[0].get("markets"):
+        return ev[0]["markets"][0]
+    return None
+
+
+def _end_ts(m):
+    """Market close time as unix epoch, or None. Gamma sends UTC ISO 8601."""
+    raw = m.get("endDate") or m.get("endDateIso") or ""
+    for fmt in ("%Y-%m-%dT%H:%M:%SZ", "%Y-%m-%dT%H:%M:%S.%fZ"):
+        try:
+            return calendar.timegm(time.strptime(raw, fmt))
+        except (ValueError, OverflowError):
+            continue
+    return None
+
+
+def parse_market(m, outcome_a=None, outcome_b=None):
+    """Extract condition id and outcome token ids from a Gamma market object.
+
+    Works on ANY binary market: politics, sports, crypto, whatever the
+    outcome names are (Yes/No, Up/Down, team names). By default the two
+    outcomes are taken in the order the market declares them; pass
+    ``outcome_a``/``outcome_b`` to pin a specific one to the ``a`` slot.
+    Returns None on any shape surprise (fail closed).
+    """
+    if not m:
+        return None
+    try:
+        outcomes = json.loads(m["outcomes"]) if isinstance(m.get("outcomes"), str) else m.get("outcomes")
+        token_ids = json.loads(m["clobTokenIds"]) if isinstance(m.get("clobTokenIds"), str) else m.get("clobTokenIds")
+        a = outcomes.index(outcome_a) if outcome_a else 0
+        b = outcomes.index(outcome_b) if outcome_b else (1 if a == 0 else 0)
+        return {
+            "condition_id": m.get("conditionId"),
+            "slug": m.get("slug"),
+            "token_a": token_ids[a],
+            "token_b": token_ids[b],
+            "outcome_a": outcomes[a],
+            "outcome_b": outcomes[b],
+            "outcome_prices_raw": m.get("outcomePrices"),
+            "idx_a": a,
+            "end_ts": _end_ts(m),
+        }
+    except Exception:
+        return None
+
+
+def resolved_winner(pm):
+    """Winning outcome name from settled Gamma outcomePrices; None if unsettled."""
+    if not pm:
+        return None
+    try:
+        op = pm["outcome_prices_raw"]
+        op = json.loads(op) if isinstance(op, str) else op
+        op = [float(x) for x in op]
+        if max(op) < 0.99:
+            return None
+        ia = pm.get("idx_a", 0)
+        return pm["outcome_a"] if op[ia] > op[1 - ia] else pm["outcome_b"]
+    except Exception:
+        return None
+
+
+def get_book(token_id, logger=None):
+    """Real-time CLOB book. THE live data source; never the trade tape."""
+    return http_get_json(f"{CLOB}/book?token_id={token_id}", logger=logger)
+
+
+def best_bid_ask(book):
+    """(best_bid, bid_size, best_ask, ask_size), sizes summed at the level."""
+    if not book:
+        return None, None, None, None
+    bids = book.get("bids") or []
+    asks = book.get("asks") or []
+    bb = max((float(b["price"]) for b in bids), default=None)
+    ba = min((float(a["price"]) for a in asks), default=None)
+    bb_sz = sum(float(b["size"]) for b in bids if float(b["price"]) == bb) if bb is not None else None
+    ba_sz = sum(float(a["size"]) for a in asks if float(a["price"]) == ba) if ba is not None else None
+    return bb, bb_sz, ba, ba_sz
+
+
+def book_meta(book):
+    """Exchange metadata riding on the book response: per-market minimum
+    order size (shares), tick size, neg_risk flag, last trade price. Read
+    these from the live book instead of hardcoding exchange rules."""
+    b = book or {}
+    def _f(k):
+        try:
+            return float(b[k])
+        except (KeyError, TypeError, ValueError):
+            return None
+    return {"min_order_size": _f("min_order_size"), "tick_size": _f("tick_size"),
+            "neg_risk": b.get("neg_risk"), "last_trade_price": _f("last_trade_price")}
+
+
+def band_ask_depth_usd(book, lo, hi):
+    """Total $ notional of asks resting within [lo, hi]."""
+    asks = (book or {}).get("asks") or []
+    return round(sum(float(a["price"]) * float(a["size"]) for a in asks
+                     if lo <= float(a["price"]) <= hi), 2)
+
+
+def book_inferred_winner(bid_a, bid_b, threshold=0.90):
+    """Winner from a last pre-close book snapshot; None if ambiguous.
+
+    Use when Gamma settlement lags: a side whose BID is pinned at or above
+    ``threshold`` at close identifies the winner immediately.
+    """
+    if bid_a is not None and bid_a >= threshold:
+        return "a"
+    if bid_b is not None and bid_b >= threshold:
+        return "b"
+    return None
+
+
+def get_tape(condition_id, since_ts, max_pages=4, logger=None):
+    """Complete trade tape for a closed market (paginated, newest first).
+
+    OFFLINE USE ONLY: the indexer lags matching by 1 to 3 minutes; call at
+    least 5 minutes after close or you will score against missing fills.
+    """
+    out = []
+    for page in range(max_pages):
+        batch = http_get_json(
+            f"{DATA}/trades?market={condition_id}&limit=500&offset={page*500}",
+            logger=logger) or []
+        out.extend(batch)
+        if not batch or min(int(t.get("timestamp", 0)) for t in batch) < since_ts:
+            break
+    return out

pmq/exceptions.py

@@ -0,0 +1,19 @@
+"""pmq exceptions. The taxonomy matters: callers must be able to tell a clean
+rejection (order does not exist) from an unknown outcome (order MAY exist)."""
+
+
+class PmqError(Exception):
+    """Base class for pmq errors."""
+
+
+class OrderUncertain(PmqError):
+    """An order was sent but its outcome is unknown (timeout, 5xx, exception
+    after send). It MAY exist server-side. The caller must cancel, reconcile
+    against exchange truth (get_trades) and stop trading that market until
+    reconciled. Never book anything on this exception."""
+
+
+class IntrospectionMismatch(PmqError):
+    """The installed py-clob-client-v2 no longer matches the API surface pmq
+    was verified against. Refusing to trade is the only safe behavior: a
+    silently changed parameter meaning can turn guards into no-ops."""

pmq/executor.py

@@ -0,0 +1,329 @@
+"""Fail-closed execution layer for Polymarket CLOB V2.
+
+Design contract, in one paragraph: nothing is ever booked unless the exchange
+confirmed it. A fill exists only if the order response is a dict bearing an
+orderID and not flagged failed, and only for the matched size the response
+reports. A 4xx is a clean rejection (the order does not exist). A timeout or
+5xx raises :class:`~pmq.exceptions.OrderUncertain` and the caller must
+reconcile via :meth:`PolymarketExecutor.reconcile` before trading that market
+again. Unparseable responses count as zero fill. This is the difference
+between a bot that survives a flaky network and one that buys its stake again
+on every poll.
+
+Production notes baked in (all verified live on CLOB V2, July 2026):
+
+* FAK/FOK BUY orders are treated by the CLOB as MARKET orders: the maker
+  amount is USDC with at most 2 decimals. Posting them as plain limit orders
+  fails with ``invalid amounts, the market buy orders maker amount supports a
+  max accuracy of 2 decimals``. pmq routes them through the market-order
+  builder, which applies the correct rounding.
+* A 400 ``no orders found to match with FAK order`` WITH an orderID in the
+  body is a clean no-fill (the ask vanished between your poll and your send),
+  not an error state.
+* The balance endpoint derives the funding wallet server-side from the
+  authenticated EOA and ``signature_type``; the ``funder`` parameter is never
+  sent. Funds held by a deposit wallet (ERC-1271) are only visible with
+  ``signature_type=3`` (POLY_1271).
+* Builder attribution rides INSIDE the signed order (bytes32 code); HTTP
+  headers attribute nothing on V2.
+"""
+import inspect
+import logging
+import os
+import re
+from dataclasses import dataclass, field
+
+from .data import FEE_RATES, fee
+from .exceptions import IntrospectionMismatch, OrderUncertain
+
+log = logging.getLogger("pmq")
+
+HOST = "https://clob.polymarket.com"
+CHAIN_ID = 137
+BYTES32_RE = re.compile(r"0x[0-9a-fA-F]{64}")
+
+# Builder attribution default. DISCLOSURE: this is the pmq maintainer's public
+# builder code (commission 0/0: it never adds fees to your orders). It funds
+# the project through Polymarket's builder program at zero cost to you.
+# Opt out with PolymarketExecutor(builder_code=None) or use your own code
+# from https://polymarket.com/settings?tab=builder
+DEFAULT_BUILDER_CODE = "0x4b22812cf929165a247b575eb417a3b6c9e3c12e96f0159c4d0ad39f78d17371"
+_UNSET = object()
+
+
+@dataclass
+class Fill:
+    """Exchange-confirmed execution result. ``matched_shares == 0`` means no
+    fill happened and NOTHING must be booked, whatever the caller hoped."""
+    order_id: str = ""
+    matched_shares: float = 0.0
+    matched_usd: float = 0.0
+    rejected: bool = False
+    error: str = ""
+    raw: dict = field(default_factory=dict)
+
+    @property
+    def price(self):
+        return self.matched_usd / self.matched_shares if self.matched_shares else None
+
+    def __bool__(self):
+        return self.matched_shares > 0
+
+
+# (method name, parameters that must exist) verified against py-clob-client-v2
+# 1.0.2 by introspection. If the installed client drifts, we refuse to start.
+_EXPECTED_METHODS = {
+    "create_and_post_market_order": ("order_args", "order_type"),
+    "create_and_post_order": ("order_args", "order_type"),
+    "cancel_market_orders": ("payload",),
+    "get_open_orders": ("params",),
+    "get_trades": ("params",),
+    "get_balance_allowance": ("params",),
+}
+_EXPECTED_MARKET_ARGS = ("token_id", "amount", "side", "price", "builder_code")
+
+
+class PolymarketExecutor:
+    """Thin, fail-closed wrapper around the official py-clob-client-v2.
+
+    Reads POLY_PRIVATE_KEY, POLY_FUNDER, POLY_SIG_TYPE and POLY_BUILDER_CODE
+    from the environment unless passed explicitly. The private key is used to
+    instantiate the signer and is never logged.
+
+    ``signature_type``: 0 EOA, 1 POLY_PROXY (email/Magic), 2 POLY_GNOSIS_SAFE,
+    3 POLY_1271 (deposit wallet, the default wallet of the Polymarket app).
+    If the CLOB shows a 0 balance while the funds sit on your funder address
+    on-chain, your signature_type is wrong: only the matching type makes the
+    server derive the wallet that actually holds the pUSD.
+    """
+
+    def __init__(self, key=None, funder=None, signature_type=None,
+                 builder_code=_UNSET, host=HOST, chain_id=CHAIN_ID,
+                 client=None, derive_creds=True):
+        from py_clob_client_v2.clob_types import (
+            AssetType, BalanceAllowanceParams, BuilderConfig,
+            MarketOrderArgsV2, OpenOrderParams, OrderArgsV2,
+            OrderMarketCancelParams, OrderType, TradeParams)
+        from py_clob_client_v2.exceptions import PolyApiException
+        self._t = {
+            "AssetType": AssetType, "BalanceAllowanceParams": BalanceAllowanceParams,
+            "MarketOrderArgs": MarketOrderArgsV2, "OpenOrderParams": OpenOrderParams,
+            "OrderArgs": OrderArgsV2, "OrderMarketCancelParams": OrderMarketCancelParams,
+            "OrderType": OrderType, "TradeParams": TradeParams,
+        }
+        self.PolyApiException = PolyApiException
+
+        if builder_code is _UNSET:
+            builder_code = os.environ.get("POLY_BUILDER_CODE", DEFAULT_BUILDER_CODE)
+        if builder_code and not BYTES32_RE.fullmatch(builder_code):
+            raise ValueError("builder_code must be bytes32 hex (0x + 64 hex chars) or None")
+        self.builder_code = builder_code
+
+        if client is not None:
+            self.client = client
+        else:
+            from py_clob_client_v2.client import ClobClient
+            key = key or os.environ.get("POLY_PRIVATE_KEY")
+            if not key:
+                raise ValueError("POLY_PRIVATE_KEY missing (env or key= argument)")
+            funder = funder or os.environ.get("POLY_FUNDER")
+            if signature_type is None:
+                signature_type = int(os.environ.get("POLY_SIG_TYPE", "0"))
+            if signature_type > 0 and not funder:
+                raise ValueError("signature_type > 0 requires the funder wallet address")
+            builder_config = BuilderConfig(builder_code=builder_code) if builder_code else None
+            self.client = ClobClient(host, chain_id=chain_id, key=key,
+                                     signature_type=signature_type, funder=funder,
+                                     builder_config=builder_config,
+                                     use_server_time=True, retry_on_error=True)
+            if derive_creds:
+                self.client.set_api_creds(self.client.create_or_derive_api_key())
+        self._verify_client_surface()
+        log.info("executor ready (builder=%s)", "on" if builder_code else "off")
+
+    # ---------------- introspection guard ----------------
+    def _verify_client_surface(self):
+        drifts = []
+        for name, params in _EXPECTED_METHODS.items():
+            fn = getattr(self.client, name, None)
+            if fn is None:
+                drifts.append(f"method {name} missing")
+                continue
+            try:
+                have = set(inspect.signature(fn).parameters)
+            except (TypeError, ValueError):
+                continue
+            for p in params:
+                if p not in have:
+                    drifts.append(f"{name}() lost parameter {p}")
+        margs = self._t["MarketOrderArgs"]
+        have = set(inspect.signature(margs).parameters)
+        for p in _EXPECTED_MARKET_ARGS:
+            if p not in have:
+                drifts.append(f"MarketOrderArgsV2 lost field {p}")
+        if not hasattr(self._t["OrderType"], "FAK"):
+            drifts.append("OrderType.FAK missing")
+        if drifts:
+            raise IntrospectionMismatch(
+                "installed py-clob-client-v2 drifted from the verified surface: "
+                + "; ".join(drifts) + ". Refusing to trade; pin the version pmq "
+                "was tested with or upgrade pmq.")
+
+    # ---------------- balance ----------------
+    def collateral(self):
+        """Available pUSD collateral as seen by the CLOB for this EOA and
+        signature_type. Raw 6-decimal units converted to $. Any parse failure
+        returns 0.0 (fail closed)."""
+        try:
+            bal = self.client.get_balance_allowance(self._t["BalanceAllowanceParams"](
+                asset_type=self._t["AssetType"].COLLATERAL))
+            return float(bal.get("balance", 0)) / 1e6 if isinstance(bal, dict) else 0.0
+        except Exception as e:
+            log.warning("collateral check failed: %s", e)
+            return 0.0
+
+    def require_collateral(self, min_usd):
+        """Raise if the CLOB-visible collateral is below ``min_usd``."""
+        usdc = self.collateral()
+        if usdc < min_usd:
+            raise RuntimeError(
+                f"collateral {usdc:.2f} USDC below required {min_usd:.2f}. If the "
+                f"funds ARE on your funder address on-chain, your signature_type "
+                f"is wrong (deposit wallets need 3).")
+        return usdc
+
+    # ---------------- orders ----------------
+    def _parse_fill(self, resp, side):
+        if not (isinstance(resp, dict) and resp.get("orderID")
+                and resp.get("success") is not False):
+            return Fill(rejected=True, error=repr(resp)[:300],
+                        raw=resp if isinstance(resp, dict) else {})
+        # For a BUY the maker amount is USDC given and the taker amount shares
+        # received; a SELL mirrors it. Unparseable counts as zero (fail closed).
+        try:
+            making = float(resp.get("makingAmount") or 0.0)
+            taking = float(resp.get("takingAmount") or 0.0)
+        except (TypeError, ValueError):
+            making = taking = 0.0
+        usd, shares = (making, taking) if side == "BUY" else (taking, making)
+        return Fill(order_id=str(resp["orderID"]), matched_shares=shares,
+                    matched_usd=usd, raw=resp)
+
+    def _market_order(self, token_id, amount, side, price):
+        t = self._t
+        try:
+            resp = self.client.create_and_post_market_order(
+                t["MarketOrderArgs"](token_id=token_id, amount=amount,
+                                     side=side, price=price),
+                order_type=t["OrderType"].FAK)
+        except self.PolyApiException as e:
+            status = getattr(e, "status_code", None)
+            msg = str(getattr(e, "error_msg", e))[:300]
+            if status is not None and 400 <= status < 500:
+                # clean rejection, the order does not exist server-side;
+                # "no orders found to match" lands here and is a no-fill
+                return Fill(rejected=True, error=f"{status}: {msg}")
+            raise OrderUncertain(f"status={status} {msg}")
+        except Exception as e:
+            raise OrderUncertain(repr(e)[:300])
+        return self._parse_fill(resp, side)
+
+    def buy_fak(self, token_id, price_cap, usd):
+        """Fill-and-kill market BUY: spend up to ``usd`` (rounded DOWN to the
+        cent, the exchange accuracy for market-buy maker amounts) at prices no
+        worse than ``price_cap``. Whatever does not match immediately is
+        killed by the exchange; nothing ever rests. Returns a :class:`Fill`;
+        book ONLY ``fill.matched_shares`` and ``fill.matched_usd``.
+        Raises :class:`OrderUncertain` when the outcome is unknown."""
+        usd = int(usd * 100) / 100.0
+        if usd <= 0:
+            return Fill(rejected=True, error="usd amount rounds to zero")
+        return self._market_order(token_id, usd, "BUY", price_cap)
+
+    def sell_fak(self, token_id, price_floor, shares):
+        """Fill-and-kill market SELL of ``shares`` at prices no worse than
+        ``price_floor``. Same confirmation contract as :meth:`buy_fak`.
+        The buy path has carried live volume; the sell path follows the same
+        documented semantics but flag it as less battle-tested."""
+        shares = int(shares * 100) / 100.0
+        if shares <= 0:
+            return Fill(rejected=True, error="share amount rounds to zero")
+        return self._market_order(token_id, shares, "SELL", price_floor)
+
+    def limit_gtc(self, token_id, price, size, side, post_only=False):
+        """Resting GTC limit order. Returns a :class:`Fill` whose matched
+        amounts reflect only what crossed IMMEDIATELY; the rest is resting
+        (track it via :meth:`open_orders`, settle via :meth:`trades_totals`).
+        Maker fills cost zero fee."""
+        t = self._t
+        try:
+            resp = self.client.create_and_post_order(
+                t["OrderArgs"](token_id=token_id, price=price, size=size, side=side),
+                order_type=t["OrderType"].GTC, post_only=post_only)
+        except self.PolyApiException as e:
+            status = getattr(e, "status_code", None)
+            msg = str(getattr(e, "error_msg", e))[:300]
+            if status is not None and 400 <= status < 500:
+                return Fill(rejected=True, error=f"{status}: {msg}")
+            raise OrderUncertain(f"status={status} {msg}")
+        except Exception as e:
+            raise OrderUncertain(repr(e)[:300])
+        return self._parse_fill(resp, side)
+
+    # ---------------- reconciliation ----------------
+    def cancel_market(self, condition_id):
+        """Cancel every resting order of ours on one market. Never raises."""
+        try:
+            self.client.cancel_market_orders(
+                self._t["OrderMarketCancelParams"](market=condition_id))
+            return True
+        except Exception as e:
+            log.warning("cancel_market(%s) failed: %s", condition_id, e)
+            return False
+
+    def open_orders(self, condition_id=None):
+        try:
+            return self.client.get_open_orders(
+                self._t["OpenOrderParams"](market=condition_id)) or []
+        except Exception as e:
+            log.warning("get_open_orders failed: %s", e)
+            return None
+
+    def trades_totals(self, condition_id, token_id=None, side="BUY",
+                      fee_rate=FEE_RATES["crypto"]):
+        """Exchange truth for one market: (shares, usd, fee_estimate) actually
+        traded on our account, or None if the API is unreachable. FAILED
+        trades are excluded; maker fills carry zero fee."""
+        try:
+            trades = self.client.get_trades(
+                self._t["TradeParams"](market=condition_id, asset_id=token_id))
+        except Exception as e:
+            log.warning("get_trades(%s) failed: %s", condition_id, e)
+            return None
+        sh = usd = fees = 0.0
+        for t in trades or []:
+            if not isinstance(t, dict) or t.get("side") != side:
+                continue
+            if t.get("status") == "FAILED":
+                continue
+            try:
+                s, p = float(t.get("size") or 0), float(t.get("price") or 0)
+            except (TypeError, ValueError):
+                continue
+            sh += s
+            usd += p * s
+            if t.get("trader_side") != "MAKER":
+                fees += fee(p, s, fee_rate)
+        return sh, usd, fees
+
+    def reconcile(self, condition_id, token_id=None):
+        """After :class:`OrderUncertain`: cancel anything possibly resting,
+        verify nothing stayed open, then return exchange-truth totals. Call
+        this BEFORE placing any new order on that market."""
+        self.cancel_market(condition_id)
+        still = self.open_orders(condition_id)
+        if still:
+            log.warning("reconcile(%s): %d orders still open after cancel, retrying",
+                        condition_id, len(still))
+            self.cancel_market(condition_id)
+        return self.trades_totals(condition_id, token_id)

pmq/mcp.py

@@ -0,0 +1,188 @@
+"""pmq-mcp: MCP server exposing pmq to LLM agents, safety rails included.
+
+Run with ``pmq-mcp`` (stdio transport). Design rules:
+
+* Read tools work with no credentials and never touch keys.
+* Trading tools exist ONLY when the operator sets ``PMQ_MCP_LIVE=1`` in the
+  server's environment. An agent cannot talk its way past a tool that was
+  never registered.
+* Every order is capped by ``PMQ_MCP_MAX_USD`` (default 10) per call.
+* On an unknown outcome (timeout, 5xx) the server reconciles automatically
+  and reports exchange truth instead of guessing.
+* POLY_PRIVATE_KEY is read by the executor, used to sign, never returned.
+"""
+import os
+import urllib.parse
+
+from . import data
+from .exceptions import OrderUncertain
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError as e:  # pragma: no cover
+    raise SystemExit("pmq-mcp needs the optional dependency: pip install 'pmq[mcp]'") from e
+
+LIVE_ENABLED = os.environ.get("PMQ_MCP_LIVE") == "1"
+MAX_USD = float(os.environ.get("PMQ_MCP_MAX_USD", "10"))
+
+mcp = FastMCP(
+    "pmq",
+    instructions=(
+        "Polymarket CLOB V2 data and fail-closed execution. Books are real "
+        "time; the trade tape lags 1 to 3 minutes, never trade off it. "
+        + ("Trading tools are ENABLED; every order is capped at "
+           f"{MAX_USD:.2f} USD per call." if LIVE_ENABLED else
+           "Trading tools are DISABLED (operator did not set PMQ_MCP_LIVE=1); "
+           "this server is read-only.")),
+)
+
+_executor = None
+
+
+def _ex():
+    global _executor
+    if _executor is None:
+        from .executor import PolymarketExecutor
+        _executor = PolymarketExecutor()
+    return _executor
+
+
+def _fill_dict(fill):
+    return {"order_id": fill.order_id, "matched_shares": fill.matched_shares,
+            "matched_usd": fill.matched_usd, "price": fill.price,
+            "rejected": fill.rejected, "error": fill.error,
+            "booked": bool(fill)}
+
+
+@mcp.tool()
+def find_markets(query: str = "", limit: int = 10) -> list:
+    """Discover tradeable Polymarket markets of ANY kind (politics, sports,
+    crypto, culture). With a query, full-text search; without, the most
+    active events by 24h volume. Returns event title plus, per market, the
+    slug to pass to the `market` tool and the outcome names."""
+    if query:
+        res = data.http_get_json(
+            f"{data.GAMMA}/public-search?q={urllib.parse.quote(query)}"
+            f"&limit_per_type={min(limit, 20)}") or {}
+        events = res.get("events") or []
+    else:
+        events = data.http_get_json(
+            f"{data.GAMMA}/events?closed=false&order=volume24hr&ascending=false"
+            f"&limit={min(limit, 20)}") or []
+    out = []
+    for ev in events[:limit]:
+        for m in (ev.get("markets") or [])[:4]:
+            pm = data.parse_market(m)
+            if pm:
+                out.append({"event": ev.get("title"), "market_slug": pm["slug"],
+                            "outcomes": [pm["outcome_a"], pm["outcome_b"]],
+                            "volume24hr": ev.get("volume24hr")})
+    return out or [{"error": "nothing found"}]
+
+
+@mcp.tool()
+def market(slug: str) -> dict:
+    """Resolve one Polymarket market by its gamma slug (any category, works
+    for expired short-lived markets too). Returns condition_id, the outcome
+    names mapped to their token ids (use those token ids with `book` and the
+    trading tools), the close time and the settled winner if resolution
+    already happened."""
+    pm = data.parse_market(data.get_market(slug))
+    if not pm:
+        return {"error": f"no market found for slug {slug!r}"}
+    return {"condition_id": pm["condition_id"],
+            "outcomes": {pm["outcome_a"]: pm["token_a"], pm["outcome_b"]: pm["token_b"]},
+            "end_ts": pm["end_ts"],
+            "settled_winner": data.resolved_winner(pm)}
+
+
+@mcp.tool()
+def book(token_id: str, depth_lo: float = 0.0, depth_hi: float = 1.0) -> dict:
+    """REAL-TIME order book summary for one outcome token: best bid/ask with
+    sizes, plus the $ notional of asks resting inside [depth_lo, depth_hi].
+    This endpoint is served by the matching engine; trust it over the trade
+    tape for any live decision."""
+    b = data.get_book(token_id)
+    if not b:
+        return {"error": "book unavailable"}
+    bid, bid_sz, ask, ask_sz = data.best_bid_ask(b)
+    return {"bid": bid, "bid_size": bid_sz, "ask": ask, "ask_size": ask_sz,
+            "ask_depth_usd_in_range": data.band_ask_depth_usd(b, depth_lo, depth_hi),
+            **data.book_meta(b)}
+
+
+@mcp.tool()
+def taker_fee(price: float, shares: float, category: str = "crypto") -> dict:
+    """Official Polymarket taker fee in $ (fee = rate * p * (1-p) * shares).
+    Categories and rates: crypto 0.07, sports 0.03, finance/politics/mentions/
+    tech 0.04, economics/culture/weather 0.05, geopolitics 0. Makers pay 0."""
+    rate = data.FEE_RATES.get(category)
+    if rate is None:
+        return {"error": f"unknown category, pick one of {sorted(data.FEE_RATES)}"}
+    return {"fee_usd": data.fee(price, shares, rate), "rate": rate,
+            "cost_per_share_incl_fee": price + data.fee(price, 1.0, rate)}
+
+
+@mcp.tool()
+def account_collateral() -> dict:
+    """Collateral (pUSD, $) the CLOB sees for the configured account. If this
+    is 0 while funds are on-chain, the operator's POLY_SIG_TYPE is wrong
+    (the Polymarket app's deposit wallet needs 3)."""
+    return {"collateral_usd": _ex().collateral()}
+
+
+@mcp.tool()
+def account_trades(condition_id: str, token_id: str = "") -> dict:
+    """Exchange-truth totals of OUR account's BUY trades on one market:
+    (shares, usd, fee estimate). This is the reconciliation source, use it
+    after any uncertainty instead of trusting local bookkeeping."""
+    totals = _ex().trades_totals(condition_id, token_id or None)
+    if totals is None:
+        return {"error": "trades endpoint unreachable"}
+    sh, usd, fees = totals
+    return {"shares": sh, "usd": usd, "fee_estimate": fees}
+
+
+if LIVE_ENABLED:
+    @mcp.tool()
+    def fak_buy(token_id: str, price_cap: float, usd: float) -> dict:
+        """Place a fill-and-kill market BUY: spend up to `usd` at prices no
+        worse than `price_cap`. Nothing rests on the book. Book ONLY what
+        `matched_shares`/`matched_usd` report; `booked: false` means nothing
+        happened. Hard-capped per call by the operator's PMQ_MCP_MAX_USD."""
+        if usd > MAX_USD:
+            return {"error": f"refused: {usd} exceeds the {MAX_USD} USD per-order cap"}
+        try:
+            return _fill_dict(_ex().buy_fak(token_id, price_cap, usd))
+        except OrderUncertain as e:
+            return {"error": f"outcome unknown ({e}); call cancel_and_reconcile "
+                             "on this market before any new order"}
+
+    @mcp.tool()
+    def fak_sell(token_id: str, price_floor: float, shares: float) -> dict:
+        """Fill-and-kill market SELL of `shares` at prices no worse than
+        `price_floor`. Same confirmation contract as fak_buy."""
+        try:
+            return _fill_dict(_ex().sell_fak(token_id, price_floor, shares))
+        except OrderUncertain as e:
+            return {"error": f"outcome unknown ({e}); "
+                             "call account_trades before any new order"}
+
+    @mcp.tool()
+    def cancel_and_reconcile(condition_id: str, token_id: str = "") -> dict:
+        """Cancel every resting order of ours on one market, verify none
+        stayed open, and return exchange-truth totals. Call this after any
+        'outcome unknown' before placing new orders on that market."""
+        totals = _ex().reconcile(condition_id, token_id or None)
+        if totals is None:
+            return {"cancelled": True, "error": "trades endpoint unreachable"}
+        sh, usd, fees = totals
+        return {"cancelled": True, "shares": sh, "usd": usd, "fee_estimate": fees}
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

pmquant-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: pmquant
+Version: 0.1.0
+Summary: Fail-closed execution and market-data layer for Polymarket CLOB V2: local signing, confirmed fills only, fee-correct math, working deposit-wallet (POLY_1271) support.
+Project-URL: Homepage, https://github.com/crp4222/pmq
+Project-URL: Issues, https://github.com/crp4222/pmq/issues
+Author: crp4222
+License: MIT
+License-File: LICENSE
+Keywords: builder-code,clob,clob-v2,deposit-wallet,execution,fak,market-order,orderbook,poly-1271,polymarket,prediction-markets,quant,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Requires-Dist: py-clob-client-v2<2,>=1.0.2
+Provides-Extra: dev
+Requires-Dist: mcp>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# pmq
+
+Fail-closed execution and market data for **Polymarket CLOB V2**, in Python.
+Local signing (your keys never leave your process), exchange-confirmed fills
+only, fee-correct math, and deposit-wallet (`POLY_1271`) support that actually
+works in production.
+
+```bash
+pip install pmquant        # distribution name pmquant, import name pmq
+```
+
+(PyPI's similarity check reserves the bare name; the module you import is
+`pmq`, same pattern as beautifulsoup4/bs4.)
+
+As of 2026-07-03 this is, to our knowledge, the **only maintained Python
+layer combining local CLOB V2 signing, an exchange-confirmed fill contract,
+and working deposit-wallet (POLY_1271) auth**. That claim is dated and
+falsifiable: the comparison table below names the alternatives and what each
+does instead; open an issue if it goes stale.
+
+## Why this exists
+
+Polymarket cut over to CLOB V2 on 2026-04-28. V1-signed orders are rejected in
+production, the fee schedule is decided at match time, and the official client
+examples leave several traps undocumented. Every line of pmq was paid for with
+a real error in live trading:
+
+* `invalid amounts, the market buy orders maker amount supports a max accuracy
+  of 2 decimals`: the CLOB treats FAK/FOK buys as **market orders**. pmq routes
+  them through the market-order builder with the correct rounding.
+* `no orders found to match with FAK order` (HTTP 400, yet with an `orderID`):
+  a clean no-fill, not an error. pmq returns an empty `Fill` instead of crashing
+  or, worse, retrying blindly.
+* CLOB shows `balance: 0` while your pUSD sits on-chain: the balance endpoint
+  ignores your `funder` parameter and derives the wallet from your EOA and
+  `signature_type`. Funds in the Polymarket app's default wallet (an ERC-1271
+  deposit wallet) are only visible with `signature_type=3`.
+
+The full write-up with reproduction details: [docs/war-story.md](docs/war-story.md).
+
+## The contract: nothing is booked without exchange confirmation
+
+| Situation | What pmq does |
+|---|---|
+| Response is a dict with `orderID`, not flagged failed | `Fill` with the **matched** size read from the response |
+| Error dict on HTTP 200, string body, `success: false` | `Fill(rejected=True)`, zero booked |
+| HTTP 4xx (incl. FAK no-match) | `Fill(rejected=True)`, zero booked |
+| Timeout, 5xx, exception after send | raises `OrderUncertain`: the order MAY exist. Call `reconcile()` before trading that market again |
+| Unparseable matched amounts | zero booked (fail closed) |
+
+`reconcile(condition_id)` cancels anything resting, verifies nothing stayed
+open, and returns `(shares, usd, fees)` from `get_trades`: the exchange truth,
+not your hopes.
+
+At startup pmq **introspects the installed py-clob-client-v2** against the API
+surface it was verified on, and refuses to trade on drift instead of sending
+orders through changed semantics.
+
+## Quickstart
+
+Market data needs no keys:
+
+```python
+import pmq
+
+m = pmq.parse_market(pmq.get_market("btc-updown-15m-1783062000"))
+book = pmq.get_book(m["token_a"])
+bid, bid_sz, ask, ask_sz = pmq.best_bid_ask(book)
+print(ask, pmq.band_ask_depth_usd(book, 0.90, 0.97))
+print(pmq.fee(price=0.95, shares=100))          # taker fee in $, crypto rate
+```
+
+Execution (reads `POLY_PRIVATE_KEY`, `POLY_FUNDER`, `POLY_SIG_TYPE` from the
+environment):
+
+```python
+from pmq import PolymarketExecutor, OrderUncertain
+
+ex = PolymarketExecutor()                        # signature_type=3 for the app's deposit wallet
+ex.require_collateral(5.0)                       # fail fast, with a diagnostic that names sig_type
+
+try:
+    fill = ex.buy_fak(token_id=m["token_a"], price_cap=0.95, usd=5.00)
+except OrderUncertain:
+    ex.reconcile(m["condition_id"], m["token_a"])   # exchange truth before anything else
+else:
+    if fill:                                     # book ONLY what matched
+        print(fill.matched_shares, "shares at", fill.price, "order", fill.order_id)
+```
+
+`sell_fak` and `limit_gtc` follow the same contract. The buy path has carried
+live volume; treat the sell path as following the same documented semantics
+with less battle time.
+
+## The signature_type table nobody gives you
+
+| `signature_type` | Wallet | When it is yours |
+|---|---|---|
+| 0 | the EOA itself | you trade from a bare private key |
+| 1 | `POLY_PROXY` | email/Magic accounts (legacy) |
+| 2 | `POLY_GNOSIS_SAFE` | browser-wallet proxy |
+| 3 | `POLY_1271` deposit wallet | **the Polymarket app's default wallet** |
+
+If `collateral()` returns 0 while the funds are visible on-chain on your funder
+address, your `signature_type` is wrong. Debug trick: `eth_call` `owner()`
+(`0x8da5cb5b`) on the funder; if it returns your EOA and the wallet bytecode is
+an ERC-1167 proxy, you want `signature_type=3`.
+
+## Comparison (2026-07-03, factual)
+
+| | pmq | py-clob-client-v2 (official) | pmxt | NautilusTrader | caiovicentino MCP |
+|---|---|---|---|---|---|
+| CLOB V2 signing | yes, local | yes, local | writes via its hosted backend | yes, local | V1 only (rejected in prod since 2026-04-28) |
+| Confirmed-fill contract | yes (core design) | no (raw responses) | n/a | engine-level | no |
+| Deposit wallet / POLY_1271 | yes, production-proven | open issues (#70 and others) | n/a | untested claim | no |
+| Fee math | official per-category formula | fee at match, no helper | via backend | fee model | fee-blind |
+| Reconciliation helper | yes | no | n/a | engine-level | no |
+| Footprint | one small lib | one small lib | multi-venue platform | full trading framework | MCP server |
+
+NautilusTrader is excellent if you want a full framework; pmq is the small
+library you embed in your own bot. pmxt is convenient if you accept routing
+writes through their backend; pmq exists for self-custody.
+
+## Builder code disclosure
+
+pmq ships with the maintainer's public Polymarket **builder code** as default
+attribution inside signed orders (`pmq.executor.DEFAULT_BUILDER_CODE`). Its
+commission is set to **0/0: it never adds any fee to your orders**. Attribution
+feeds Polymarket's builder program and funds this project at zero cost to you.
+
+Opt out or replace it, one line either way:
+
+```python
+PolymarketExecutor(builder_code=None)            # no attribution
+PolymarketExecutor(builder_code="0xYOURS...")    # your own code
+```
+
+or set the `POLY_BUILDER_CODE` environment variable. (Same model as
+JKorf/Polymarket.Net; the official client defaults to zero attribution.)
+
+## MCP server (agents)
+
+`pip install "pmquant[mcp]"` then run `pmq-mcp` (stdio). Read tools (market,
+book, taker_fee, account_collateral, account_trades) always exist. Trading
+tools (`fak_buy`, `fak_sell`, `cancel_and_reconcile`) are **only registered
+when the operator sets `PMQ_MCP_LIVE=1`** in the server environment: an
+agent cannot talk its way past a tool that was never created. Every order is
+capped per call by `PMQ_MCP_MAX_USD` (default 10).
+
+```json
+{
+  "mcpServers": {
+    "pmq": {
+      "command": "pmq-mcp",
+      "env": { "POLY_PRIVATE_KEY": "...", "POLY_FUNDER": "0x...", "POLY_SIG_TYPE": "3" }
+    }
+  }
+}
+```
+
+Leave the `POLY_*` variables out entirely for a read-only market-data server.
+
+## Bot template
+
+[bot-template/](bot-template/) is a complete bot minus the strategy, for ANY
+market (politics, sports, crypto, culture): paper mode against real books
+with real fees, per-market budgets with fee headroom, poisoned-market
+reconciliation, consecutive-failure halt, disk-persisted daily loss halt, a
+systemd unit with `RestartPreventExitStatus=42` so halts stay halted, and a
+lightweight phone dashboard. You implement `watchlist()` and `decide()`; the
+shipped demo strategy is an API illustration meant to be replaced.
+
+## Security posture
+
+* Keys are read from the environment, used to instantiate the signer, and
+  never logged. No custody, no backend, no telemetry, zero network calls
+  besides Polymarket endpoints.
+* Beware of the documented wave of fake "polymarket bot" repositories that
+  steal private keys. Read the source: pmq is small on purpose.
+* Fund the trading wallet with what you can afford to lose. Nothing here is
+  financial advice; prediction-market access is restricted in some
+  jurisdictions and compliance is on you.
+
+## License
+
+MIT

pmquant-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pmq/__init__.py,sha256=PMuCY0rHDqRcuSJBpKgYIMqIwVfRc7Nm0LPF1YV8ig0,1274
+pmq/data.py,sha256=GTOFGI-kMkycvO1cbTHVMY6Xdr90An86NJ8sJmPxQAU,7951
+pmq/exceptions.py,sha256=A5O45Fv0Sa9whxb352pUHCKwvTyVFAMHznAhzrvkPk0,806
+pmq/executor.py,sha256=EA4RYbzG2cZE70-XgyNGCKByBtyIleZjGk_uBnRSWo0,15602
+pmq/mcp.py,sha256=u-B6NskztWDEun7Qc93psTQgpPUjE4UTCGosVvx3M94,7902
+pmquant-0.1.0.dist-info/METADATA,sha256=NG6OcE4joCCXXIJ-Pdw2cbihBl6A19j3etN4r5ez2aM,9278
+pmquant-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+pmquant-0.1.0.dist-info/entry_points.txt,sha256=KA0pbQsoNqTk8q05jSsalaEoxfTe9T_EzClj0rksTco,41
+pmquant-0.1.0.dist-info/licenses/LICENSE,sha256=ONNtjWb-5LmWWI44Qg3AXhr4iDwHLVWEa0wHWOUSK3c,1064
+pmquant-0.1.0.dist-info/RECORD,,

pmquant-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

pmquant-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pmq-mcp = pmq.mcp:main

pmquant-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crp4222
+
+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.