pmquant 0.3.0__tar.gz → 0.4.1__tar.gz

{pmquant-0.3.0 → pmquant-0.4.1}/.github/workflows/canary.yml

@@ -12,8 +12,8 @@ jobs:
   canary:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: "3.12"
       - run: pip install -e ".[dev]"

{pmquant-0.3.0 → pmquant-0.4.1}/.github/workflows/publish.yml

@@ -11,10 +11,10 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.12"
 

{pmquant-0.3.0 → pmquant-0.4.1}/.github/workflows/test.yml

@@ -7,12 +7,13 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "3.12"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - run: pip install -e ".[dev]"
       - run: ruff check .
-      - run: pytest -q
+      - run: mypy
+      - run: pytest -q --cov=pmq --cov-fail-under=85

{pmquant-0.3.0 → pmquant-0.4.1}/.gitignore

@@ -6,3 +6,4 @@ build/
 .venv/
 .pytest_cache/
 .env
+.coverage

{pmquant-0.3.0 → pmquant-0.4.1}/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 0.4.1 (2026-07-03)
+
+* Introspection guard now also verifies `OrderArgsV2` fields (including
+  `builder_code`, which the limit-order path depends on): a client that
+  dropped it is refused at startup instead of failing at call time.
+  pmq-doctor mirrors the same check.
+* Distribution: `server.json` manifest for the MCP registry, and an
+  `mcp-name` ownership token in the README (visible to the registry's PyPI
+  verification, invisible when rendered).
+
+## 0.4.0 (2026-07-03)
+
+* Typing: the whole public API is annotated and ships a `py.typed` marker;
+  `mypy --strict` runs in CI. New exported types `ParsedMarket` and
+  `BookMeta` (TypedDicts) describe what `parse_market` and `book_meta`
+  return.
+* Builder attribution: the code now rides explicitly inside EVERY order's
+  args (market and limit paths) in addition to the client-level
+  BuilderConfig, and tests pin all three layers: executor args, real client
+  construction, and the dependency's own config injection. Disclosure and
+  one-line opt-out unchanged.
+* Tests: 97 (from 39). Executable table of the fail-closed fill contract
+  (one row per possible exchange outcome, both order paths), deep pmq-doctor
+  scenarios with mocked RPC and CLOB (sig_type advice, alternative sig_type
+  probing, market section), MCP tool coverage including the gated live
+  tools. Coverage gate at 85% in CI.
+* pmq-doctor fixes: an RPC failure now fails the run (it used to leave the
+  verdict green), and a non-numeric POLY_SIG_TYPE is diagnosed instead of
+  crashing.
+* CI: test matrix extended to Python 3.10 through 3.14, classifiers updated
+  accordingly.
+* Template: the dash brands itself pmq-bot-dash, matching the shipped
+  pmq-bot.service unit name.
+
 ## 0.3.0 (2026-07-03)
 
 * New: `pmq-doctor`, a read-only diagnosis command for Polymarket V2 setups.

{pmquant-0.3.0 → pmquant-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pmquant
-Version: 0.3.0
+Version: 0.4.1
 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
@@ -13,11 +13,19 @@ Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: Financial and Insurance Industry
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Typing :: Typed
 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: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.6; extra == 'dev'
 Provides-Extra: mcp
@@ -26,9 +34,13 @@ Description-Content-Type: text/markdown
 
 # pmq
 
+<!-- mcp-name: io.github.crp4222/pmq -->
+
 [![PyPI](https://img.shields.io/pypi/v/pmquant)](https://pypi.org/project/pmquant/)
 [![tests](https://github.com/crp4222/pmq/actions/workflows/test.yml/badge.svg)](https://github.com/crp4222/pmq/actions/workflows/test.yml)
 [![canary](https://github.com/crp4222/pmq/actions/workflows/canary.yml/badge.svg)](https://github.com/crp4222/pmq/actions/workflows/canary.yml)
+[![coverage gate](https://img.shields.io/badge/coverage-%E2%89%A585%25%20enforced%20in%20CI-blue)](.github/workflows/test.yml)
+[![typed](https://img.shields.io/badge/types-mypy%20strict-blue)](pyproject.toml)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 Fail-closed execution and market data for **Polymarket CLOB V2**, in Python.

{pmquant-0.3.0 → pmquant-0.4.1}/README.md

@@ -1,8 +1,12 @@
 # pmq
 
+<!-- mcp-name: io.github.crp4222/pmq -->
+
 [![PyPI](https://img.shields.io/pypi/v/pmquant)](https://pypi.org/project/pmquant/)
 [![tests](https://github.com/crp4222/pmq/actions/workflows/test.yml/badge.svg)](https://github.com/crp4222/pmq/actions/workflows/test.yml)
 [![canary](https://github.com/crp4222/pmq/actions/workflows/canary.yml/badge.svg)](https://github.com/crp4222/pmq/actions/workflows/canary.yml)
+[![coverage gate](https://img.shields.io/badge/coverage-%E2%89%A585%25%20enforced%20in%20CI-blue)](.github/workflows/test.yml)
+[![typed](https://img.shields.io/badge/types-mypy%20strict-blue)](pyproject.toml)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 Fail-closed execution and market data for **Polymarket CLOB V2**, in Python.

{pmquant-0.3.0 → pmquant-0.4.1}/bot-template/dash/bot_dash.py

@@ -3,7 +3,7 @@
 
 Design constraints:
   - stdlib only (http.server), one process, a few MB of RSS: safe on the Pi
-  - READ ONLY: parses bot_runs CSVs, systemctl show and the favbot journal;
+  - READ ONLY: parses bot_runs CSVs, systemctl show and the bot's journal;
     never reads live.env, never talks to any exchange API, no secrets
   - the phone does the rendering; this process only ships small JSON + one
     static HTML file (cached in memory, CSVs re-parsed only on mtime change)
@@ -67,7 +67,7 @@ def _run(cmd):
 
 
 def service_state():
-    """favbot systemd state + last collateral line from its journal."""
+    """bot systemd state + last collateral line from its journal."""
     with _lock:
         cached = _cache.get("svc")
         if cached and time.time() - cached[0] < SVC_CACHE_S:
@@ -141,7 +141,7 @@ def api_payload():
 
 
 class Handler(BaseHTTPRequestHandler):
-    server_version = "favbot-dash"
+    server_version = "pmq-bot-dash"
 
     def _send(self, code, ctype, body):
         self.send_response(code)
@@ -172,5 +172,5 @@ class Handler(BaseHTTPRequestHandler):
 
 if __name__ == "__main__":
     srv = ThreadingHTTPServer(("0.0.0.0", PORT), Handler)
-    print(f"favbot-dash listening on :{PORT}", flush=True)
+    print(f"pmq-bot-dash listening on :{PORT}", flush=True)
     srv.serve_forever()

{pmquant-0.3.0 → pmquant-0.4.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pmquant"
-version = "0.3.0"
+version = "0.4.1"
 description = "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."
 readme = "README.md"
 license = { text = "MIT" }
@@ -22,7 +22,13 @@ classifiers = [
     "Intended Audience :: Financial and Insurance Industry",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Office/Business :: Financial :: Investment",
+    "Typing :: Typed",
 ]
 
 [project.urls]
@@ -31,7 +37,7 @@ Issues = "https://github.com/crp4222/pmq/issues"
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.2"]
-dev = ["pytest>=8", "mcp>=1.2", "ruff>=0.6"]
+dev = ["pytest>=8", "pytest-cov>=5", "mcp>=1.2", "ruff>=0.6", "mypy>=1.10"]
 
 [project.scripts]
 pmq-mcp = "pmq.mcp:main"
@@ -40,6 +46,16 @@ pmq-doctor = "pmq.doctor:main"
 [tool.hatch.build.targets.wheel]
 packages = ["src/pmq"]
 
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/pmq"]
+
+[[tool.mypy.overrides]]
+module = ["py_clob_client_v2.*", "eth_account.*"]
+ignore_missing_imports = true
+follow_imports = "skip"
+
 [tool.ruff]
 line-length = 100
 target-version = "py310"

pmquant-0.4.1/server.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.crp4222/pmq",
+  "title": "pmq (Polymarket CLOB V2)",
+  "description": "Fail-closed Polymarket CLOB V2 data and execution. Read tools (markets, book, fees, account) need no credentials; trading tools are registered only when the operator sets PMQ_MCP_LIVE=1, with a per-order USD cap.",
+  "repository": {
+    "url": "https://github.com/crp4222/pmq",
+    "source": "github"
+  },
+  "version": "0.4.1",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "pmquant",
+      "version": "0.4.1",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "PMQ_MCP_LIVE",
+          "description": "Set to 1 to register the trading tools (fak_buy, fak_sell, cancel_and_reconcile). Unset or any other value keeps the server read-only.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "PMQ_MCP_MAX_USD",
+          "description": "Per-order hard cap in USD enforced before any live buy (default 10). Only relevant when PMQ_MCP_LIVE=1.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "POLY_PRIVATE_KEY",
+          "description": "EOA private key used only to sign orders locally when trading tools are enabled. Never printed or transmitted. Not needed for the read-only tools.",
+          "isRequired": false,
+          "isSecret": true
+        },
+        {
+          "name": "POLY_FUNDER",
+          "description": "Funder wallet address. Required with signature_type > 0 (deposit wallets). Only used when trading tools are enabled.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "POLY_SIG_TYPE",
+          "description": "Polymarket signature type: 0 EOA, 1 POLY_PROXY, 2 POLY_GNOSIS_SAFE, 3 POLY_1271 (app deposit wallet). Run pmq-doctor if unsure.",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "POLY_BUILDER_CODE",
+          "description": "Optional bytes32 builder attribution code. Defaults to the maintainer's public zero-commission code (disclosed in the README); set your own or leave empty to opt out.",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

{pmquant-0.3.0 → pmquant-0.4.1}/src/pmq/__init__.py

@@ -25,7 +25,7 @@ from .data import (
 )
 from .exceptions import IntrospectionMismatch, OrderUncertain, PmqError
 
-__version__ = "0.3.0"
+__version__ = "0.4.1"
 __all__ = [
     "FEE_RATES", "band_ask_depth_usd", "best_bid_ask", "book_inferred_winner",
     "book_meta", "event_markets", "fee", "get_book", "get_market", "get_tape",
@@ -36,7 +36,7 @@ __all__ = [
 ]
 
 
-def __getattr__(name):
+def __getattr__(name: str) -> object:
     # Lazy import: the data layer must stay usable without py-clob-client-v2.
     if name in ("PolymarketExecutor", "Fill", "DEFAULT_BUILDER_CODE"):
         from . import executor

{pmquant-0.3.0 → pmquant-0.4.1}/src/pmq/data.py

@@ -19,10 +19,15 @@ Facts this module encodes (verified live, July 2026):
   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.
 """
+from __future__ import annotations
+
 import calendar
 import json
 import time
 import urllib.request
+from typing import Any, Callable, TypedDict
+
+Logger = Callable[[str], None]
 
 UA = {"User-Agent": "Mozilla/5.0"}
 GAMMA = "https://gamma-api.polymarket.com"
@@ -31,7 +36,7 @@ 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 = {
+FEE_RATES: dict[str, float] = {
     "crypto": 0.07,
     "sports": 0.03,
     "finance": 0.04,
@@ -45,7 +50,28 @@ FEE_RATES = {
 }
 
 
-def fee(price, shares, rate=FEE_RATES["crypto"]):
+class ParsedMarket(TypedDict):
+    """Normalized view of a Gamma market object, see :func:`parse_market`."""
+    condition_id: str | None
+    slug: str | None
+    token_a: str
+    token_b: str
+    outcome_a: str
+    outcome_b: str
+    outcome_prices_raw: Any
+    idx_a: int
+    end_ts: int | None
+
+
+class BookMeta(TypedDict):
+    """Exchange metadata riding on a book response, see :func:`book_meta`."""
+    min_order_size: float | None
+    tick_size: float | None
+    neg_risk: bool | None
+    last_trade_price: float | None
+
+
+def fee(price: float, shares: float, rate: float = FEE_RATES["crypto"]) -> float:
     """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
@@ -54,7 +80,8 @@ def fee(price, shares, rate=FEE_RATES["crypto"]):
     return rate * price * (1.0 - price) * shares
 
 
-def http_get_json(url, retries=3, timeout=10, logger=None):
+def http_get_json(url: str, retries: int = 3, timeout: float = 10,
+                  logger: Logger | None = None) -> Any:
     """GET a JSON document with linear backoff. Returns None on final failure."""
     for i in range(retries):
         try:
@@ -70,18 +97,20 @@ def http_get_json(url, retries=3, timeout=10, logger=None):
     return None
 
 
-def get_market(slug, logger=None):
+def get_market(slug: str, logger: Logger | None = None) -> dict[str, Any] | 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]
+        first: dict[str, Any] = data[0]
+        return first
     ev = http_get_json(f"{GAMMA}/events?slug={slug}", logger=logger)
     if ev and ev[0].get("markets"):
-        return ev[0]["markets"][0]
+        fallback: dict[str, Any] = ev[0]["markets"][0]
+        return fallback
     return None
 
 
-def _end_ts(m):
+def _end_ts(m: dict[str, Any]) -> int | None:
     """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"):
@@ -92,7 +121,8 @@ def _end_ts(m):
     return None
 
 
-def parse_market(m, outcome_a=None, outcome_b=None):
+def parse_market(m: dict[str, Any] | None, outcome_a: str | None = None,
+                 outcome_b: str | None = None) -> ParsedMarket | None:
     """Extract condition id and outcome token ids from a Gamma market object.
 
     Works on ANY binary market: politics, sports, crypto, whatever the
@@ -104,26 +134,26 @@ def parse_market(m, outcome_a=None, outcome_b=None):
     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")
+        outcomes: Any = json.loads(m["outcomes"]) if isinstance(m.get("outcomes"), str) else m["outcomes"]
+        token_ids: Any = json.loads(m["clobTokenIds"]) if isinstance(m.get("clobTokenIds"), str) else m["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),
-        }
+        return ParsedMarket(
+            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=int(a),
+            end_ts=_end_ts(m),
+        )
     except Exception:
         return None
 
 
-def resolved_winner(pm):
+def resolved_winner(pm: ParsedMarket | None) -> str | None:
     """Winning outcome name from settled Gamma outcomePrices; None if unsettled."""
     if not pm:
         return None
@@ -139,12 +169,14 @@ def resolved_winner(pm):
         return None
 
 
-def get_book(token_id, logger=None):
+def get_book(token_id: str, logger: Logger | None = None) -> dict[str, Any] | 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)
+    book: dict[str, Any] | None = http_get_json(f"{CLOB}/book?token_id={token_id}", logger=logger)
+    return book
 
 
-def best_bid_ask(book):
+def best_bid_ask(book: dict[str, Any] | None,
+                 ) -> tuple[float | None, float | None, float | None, float | None]:
     """(best_bid, bid_size, best_ask, ask_size), sizes summed at the level."""
     if not book:
         return None, None, None, None
@@ -157,12 +189,13 @@ def best_bid_ask(book):
     return bb, bb_sz, ba, ba_sz
 
 
-def book_meta(book):
+def book_meta(book: dict[str, Any] | None) -> BookMeta:
     """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):
+
+    def _f(k: str) -> float | None:
         try:
             return float(b[k])
         except (KeyError, TypeError, ValueError):
@@ -171,14 +204,15 @@ def book_meta(book):
             "neg_risk": b.get("neg_risk"), "last_trade_price": _f("last_trade_price")}
 
 
-def band_ask_depth_usd(book, lo, hi):
+def band_ask_depth_usd(book: dict[str, Any] | None, lo: float, hi: float) -> float:
     """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):
+def book_inferred_winner(bid_a: float | None, bid_b: float | None,
+                         threshold: float = 0.90) -> str | None:
     """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
@@ -191,14 +225,14 @@ def book_inferred_winner(bid_a, bid_b, threshold=0.90):
     return None
 
 
-def event_markets(slug, logger=None):
+def event_markets(slug: str, logger: Logger | None = None) -> list[ParsedMarket]:
     """All binary markets of one event (multi-outcome events like elections
     or tournaments are one binary market per candidate). Returns a list of
     :func:`parse_market` dicts; unparseable members are skipped."""
     ev = http_get_json(f"{GAMMA}/events?slug={slug}", logger=logger)
     if not ev:
         return []
-    out = []
+    out: list[ParsedMarket] = []
     for m in ev[0].get("markets") or []:
         pm = parse_market(m)
         if pm:
@@ -206,7 +240,8 @@ def event_markets(slug, logger=None):
     return out
 
 
-def positions(user_address, logger=None, limit=200):
+def positions(user_address: str, logger: Logger | None = None,
+              limit: int = 200) -> list[dict[str, Any]]:
     """Current holdings of a wallet per the data-api (public, ~1 min lag).
     Answers "what do I hold?" after fills: list of dicts with asset,
     conditionId, size, avgPrice, currentValue and friends."""
@@ -214,13 +249,14 @@ def positions(user_address, logger=None, limit=200):
                          logger=logger) or []
 
 
-def get_tape(condition_id, since_ts, max_pages=4, logger=None):
+def get_tape(condition_id: str, since_ts: float, max_pages: int = 4,
+             logger: Logger | None = None) -> list[dict[str, Any]]:
     """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 = []
+    out: list[dict[str, Any]] = []
     for page in range(max_pages):
         batch = http_get_json(
             f"{DATA}/trades?market={condition_id}&limit=500&offset={page*500}",