pmquant 0.2.0__tar.gz → 0.4.0__tar.gz

{pmquant-0.2.0 → pmquant-0.4.0}/.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.2.0 → pmquant-0.4.0}/.github/workflows/publish.yml

@@ -11,13 +11,24 @@ 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"
 
+      - name: Tag matches pyproject version
+        if: github.event_name == 'release'
+        run: |
+          pkg=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          init=$(grep -m1 '^__version__' src/pmq/__init__.py | cut -d'"' -f2)
+          tag="${GITHUB_REF_NAME#v}"
+          if [ "$pkg" != "$tag" ] || [ "$init" != "$tag" ]; then
+            echo "tag v$tag, pyproject $pkg, __init__ $init: bump all three before releasing"
+            exit 1
+          fi
+
       - name: Install
         run: pip install -e ".[dev]"
 

{pmquant-0.2.0 → pmquant-0.4.0}/.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.2.0 → pmquant-0.4.0}/.gitignore

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

pmquant-0.4.0/CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+## 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.
+  Checks the installed py-clob-client-v2 against the verified surface,
+  derives the EOA from `POLY_PRIVATE_KEY` (never printed), reads the funder
+  on-chain (contract vs EOA, `owner()`), advises the right `POLY_SIG_TYPE`,
+  verifies the CLOB sees collateral with the configured identity (and probes
+  the other signature types when it does not), and optionally checks one
+  market (`--market <slug>`: book, min_order_size, tick, taker fee).
+* Docs: docs/recipes.md cookbook (trade a market, paper-test a strategy,
+  read positions, verify builder attribution on-chain), demo card in the
+  README.
+* CI: the publish workflow refuses to upload when the release tag does not
+  match the version in pyproject.toml (the failure mode that blocked the
+  first 0.3.0 release).
+
+## 0.2.0 (2026-07-03)
+
+* New: `positions(user)` and `event_markets(slug)` in the data layer; `event`
+  tool in the MCP server; `fee_rate(condition_id)` (authoritative per-market
+  taker rate from the exchange) and `cancel_order(order_id)` on the executor.
+* Trust: weekly live canary workflow (real-endpoint checks, auto-opens an
+  issue on drift), SECURITY.md, production receipt in the README,
+  docs/rounding-study.md (measured V2 rounding behavior).
+* Quality: ruff in CI, tests for the bot-template engine (34 tests total).
+
+## 0.1.0 (2026-07-03)
+
+First release.
+
+* `pmq.data`: real-time books (with per-market exchange rules via
+  `book_meta`), gamma slug resolution with expired-market fallback,
+  market-agnostic `parse_market` (any binary outcomes, close time), settled
+  and book-inferred winners, offline trade tape, official per-category taker
+  fee formula.
+* `pmq.executor.PolymarketExecutor`: fail-closed CLOB V2 execution. FAK
+  buys/sells through the market-order path, exchange-confirmed fills only,
+  `OrderUncertain` + `reconcile()` from get_trades, deposit-wallet
+  (POLY_1271) support, collateral fail-fast, builder-code default with
+  disclosure and opt-out, startup introspection of the installed
+  py-clob-client-v2.
+* `pmq.mcp` (`pmq-mcp`): MCP server. Read tools always available
+  (find_markets, market, book, taker_fee, account tools); trading tools only
+  registered when the operator sets `PMQ_MCP_LIVE=1`, per-order cap via
+  `PMQ_MCP_MAX_USD`.
+* `bot-template/`: market-agnostic bot engine (strategy owns `watchlist()`
+  and `decide()`), honest paper mode against real books, risk rails (budget
+  with fee headroom, poisoning, halts with exit code 42, disk-persisted
+  daily halt), systemd unit, phone dashboard.

pmquant-0.4.0/CLAUDE.md

@@ -0,0 +1,52 @@
+# pmq: engineering invariants for agents CONTRIBUTING to this repo
+
+(AGENTS.md in this repo is for agents USING the library; this file is for
+agents EDITING it. Read both before changing code.)
+
+## Never weaken (the product IS these properties)
+
+1. **The fail-closed fill contract**: a `Fill` books only what the exchange
+   confirmed (`orderID` + `success is not False` + matched amounts); 4xx is a
+   clean rejection; timeout/5xx raises `OrderUncertain`; unparseable = zero.
+   Any change that books more optimistically is a regression by definition,
+   whatever it fixes elsewhere. `reconcile()` must keep meaning cancel +
+   `get_trades` truth.
+2. **Startup introspection** (`_EXPECTED_METHODS`/`_EXPECTED_MARKET_ARGS`):
+   the executor REFUSES to run on a drifted py-clob-client-v2. When bumping
+   the client dependency, re-verify signatures by introspection and update
+   the tables in the same commit.
+3. **Builder code policy**: default = maintainer's code, DISCLOSED in README
+   and code comment, opt-out one line (`builder_code=None` / env). Never
+   hide it, never remove the disclosure, never make opt-out harder. This is
+   the trust model (JKorf pattern).
+4. **No strategy content, ever**: the maintainer's private bot strategy
+   (bands, timing, hours, families, sizing) must never appear in code, docs,
+   tests, commits or issues. The bot-template ships deliberately naive
+   demos only.
+5. **Claims must be falsifiable**: no superlatives in README/docs; dated
+   claims with evidence (comparison table, on-chain receipts, measured
+   studies). If you cannot prove it, do not write it.
+6. **MCP safety gates**: trading tools are REGISTERED only when the operator
+   sets `PMQ_MCP_LIVE=1`; per-order `PMQ_MCP_MAX_USD` cap enforced before
+   any client call. Read tools must keep working with zero credentials.
+
+## Working rules
+
+* Tests green (`pytest -q`) and `ruff check .` clean before any push; add
+  tests with every behavior change. Network-touching tests go to
+  `tests/test_canary_live.py` behind `PMQ_CANARY=1`, never in default CI.
+* Exchange rules (min size, tick, fee rate) are READ from the venue
+  (`book_meta`, `fee_rate`), not hardcoded. `FEE_RATES` is a documented
+  snapshot of the official schedule used for estimates.
+* Releases: bump version in `pyproject.toml` AND `src/pmq/__init__.py`,
+  update CHANGELOG.md, push, then `gh release create vX.Y.Z`: PyPI publish
+  is automatic via trusted publishing (no tokens anywhere). PyPI name is
+  `pmquant`, import name `pmq`: keep the README line explaining it.
+* The weekly canary workflow is the drift alarm: if it opens an issue, the
+  fix starts by re-running the introspection against the new surface, not
+  by loosening the checks.
+* Keep the library small and auditable (five modules): resist adding
+  dependencies; stdlib first. Anything bot-shaped belongs in bot-template/,
+  not in the package.
+* Style: no em-dashes and no " - " connectors anywhere (strong user rule);
+  keep comments sparse and constraint-focused.

pmquant-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# pmq: engineering invariants for agents CONTRIBUTING to this repo
+
+(AGENTS.md in this repo is for agents USING the library; this file is for
+agents EDITING it. Read both before changing code.)
+
+## Never weaken (the product IS these properties)
+
+1. **The fail-closed fill contract**: a `Fill` books only what the exchange
+   confirmed (`orderID` + `success is not False` + matched amounts); 4xx is a
+   clean rejection; timeout/5xx raises `OrderUncertain`; unparseable = zero.
+   Any change that books more optimistically is a regression by definition,
+   whatever it fixes elsewhere. `reconcile()` must keep meaning cancel +
+   `get_trades` truth.
+2. **Startup introspection** (`_EXPECTED_METHODS`/`_EXPECTED_MARKET_ARGS`):
+   the executor REFUSES to run on a drifted py-clob-client-v2. When bumping
+   the client dependency, re-verify signatures by introspection and update
+   the tables in the same commit.
+3. **Builder code policy**: default = maintainer's code, DISCLOSED in README
+   and code comment, opt-out one line (`builder_code=None` / env). Never
+   hide it, never remove the disclosure, never make opt-out harder. This is
+   the trust model (JKorf pattern).
+4. **No strategy content, ever**: the maintainer's private bot strategy
+   (bands, timing, hours, families, sizing) must never appear in code, docs,
+   tests, commits or issues. The bot-template ships deliberately naive
+   demos only.
+5. **Claims must be falsifiable**: no superlatives in README/docs; dated
+   claims with evidence (comparison table, on-chain receipts, measured
+   studies). If you cannot prove it, do not write it.
+6. **MCP safety gates**: trading tools are REGISTERED only when the operator
+   sets `PMQ_MCP_LIVE=1`; per-order `PMQ_MCP_MAX_USD` cap enforced before
+   any client call. Read tools must keep working with zero credentials.
+
+## Working rules
+
+* Tests green (`pytest -q`) and `ruff check .` clean before any push; add
+  tests with every behavior change. Network-touching tests go to
+  `tests/test_canary_live.py` behind `PMQ_CANARY=1`, never in default CI.
+* Exchange rules (min size, tick, fee rate) are READ from the venue
+  (`book_meta`, `fee_rate`), not hardcoded. `FEE_RATES` is a documented
+  snapshot of the official schedule used for estimates.
+* Releases: bump version in `pyproject.toml` AND `src/pmq/__init__.py`,
+  update CHANGELOG.md, push, then `gh release create vX.Y.Z`: PyPI publish
+  is automatic via trusted publishing (no tokens anywhere). PyPI name is
+  `pmquant`, import name `pmq`: keep the README line explaining it.
+* The weekly canary workflow is the drift alarm: if it opens an issue, the
+  fix starts by re-running the introspection against the new surface, not
+  by loosening the checks.
+* Keep the library small and auditable (five modules): resist adding
+  dependencies; stdlib first. Anything bot-shaped belongs in bot-template/,
+  not in the package.
+* Style: no em-dashes and no " - " connectors anywhere (strong user rule);
+  keep comments sparse and constraint-focused.

{pmquant-0.2.0 → pmquant-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pmquant
-Version: 0.2.0
+Version: 0.4.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
@@ -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
@@ -29,6 +37,8 @@ Description-Content-Type: text/markdown
 [![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.
@@ -80,6 +90,24 @@ settled, with the builder code visible in the calldata. Additionally, a weekly
 and the installed client surface, and opens an issue by itself if Polymarket
 drifts.
 
+## pmq-doctor: diagnose your setup in one command
+
+```bash
+pip install pmquant && pmq-doctor --market <slug>
+```
+
+It checks, in order: the installed client surface (introspection), your
+derived EOA, the funder wallet on-chain (`owner()` and bytecode: is it a
+deposit wallet?), whether `POLY_SIG_TYPE` matches the wallet type, whether
+the CLOB actually sees your collateral (and if not, WHICH sig_type does),
+and the target market's minimum size and tick. Real output on a real
+deposit-wallet account:
+
+![pmq-doctor output](docs/assets/pmq-doctor.svg)
+
+If you landed here from "the order signer address has to be the address of
+the API KEY" or a CLOB balance of 0 with funds on-chain: this is the tool.
+
 ## The contract: nothing is booked without exchange confirmation
 
 | Situation | What pmq does |

{pmquant-0.2.0 → pmquant-0.4.0}/README.md

@@ -3,6 +3,8 @@
 [![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.
@@ -54,6 +56,24 @@ settled, with the builder code visible in the calldata. Additionally, a weekly
 and the installed client surface, and opens an issue by itself if Polymarket
 drifts.
 
+## pmq-doctor: diagnose your setup in one command
+
+```bash
+pip install pmquant && pmq-doctor --market <slug>
+```
+
+It checks, in order: the installed client surface (introspection), your
+derived EOA, the funder wallet on-chain (`owner()` and bytecode: is it a
+deposit wallet?), whether `POLY_SIG_TYPE` matches the wallet type, whether
+the CLOB actually sees your collateral (and if not, WHICH sig_type does),
+and the target market's minimum size and tick. Real output on a real
+deposit-wallet account:
+
+![pmq-doctor output](docs/assets/pmq-doctor.svg)
+
+If you landed here from "the order signer address has to be the address of
+the API KEY" or a CLOB balance of 0 with funds on-chain: this is the tool.
+
 ## The contract: nothing is booked without exchange confirmation
 
 | Situation | What pmq does |

{pmquant-0.2.0 → pmquant-0.4.0}/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.4.0/docs/assets/pmq-doctor.svg

@@ -0,0 +1,17 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="880" height="292" font-family="SFMono-Regular,Consolas,Menlo,monospace" font-size="12.5">
+<rect width="880" height="292" rx="10" fill="#16161a"/>
+<circle cx="20" cy="20" r="5.5" fill="#ff5f57"/><circle cx="38" cy="20" r="5.5" fill="#febc2e"/><circle cx="56" cy="20" r="5.5" fill="#28c840"/>
+<text x="440.0" y="24" fill="#71717a" text-anchor="middle" font-size="11">pmq-doctor · real account, real output</text>
+<text x="18" y="54" fill="#ffffff" xml:space="preserve">pmq-doctor: Polymarket V2 setup diagnosis (read-only, no key ever printed)</text>
+<text x="18" y="73" fill="#22c55e" xml:space="preserve">[ok] installed py-clob-client-v2 matches the verified surface</text>
+<text x="18" y="92" fill="#22c55e" xml:space="preserve">[ok] POLY_PRIVATE_KEY present (never printed)</text>
+<text x="18" y="111" fill="#c3c2b7" xml:space="preserve">     derived EOA: 0xdb581D8BE7b5C53C6D832083a8A49D0CBF73d6e1</text>
+<text x="18" y="130" fill="#c3c2b7" xml:space="preserve">     POLY_FUNDER: 0x76cd962fc8c5f5e5a0cbe14c74339aa78268da58   POLY_SIG_TYPE: 3</text>
+<text x="18" y="149" fill="#22c55e" xml:space="preserve">[ok] funder wallet on-chain: funder is a contract owned by your EOA: a deposit wallet, signature_type=3 (POLY_1271)</text>
+<text x="18" y="168" fill="#c3c2b7" xml:space="preserve">     on-chain pUSD at funder: 39.42</text>
+<text x="18" y="187" fill="#22c55e" xml:space="preserve">[ok] POLY_SIG_TYPE=3 matches the wallet type</text>
+<text x="18" y="206" fill="#22c55e" xml:space="preserve">[ok] CLOB sees collateral with sig_type=3: 39.42 USDC</text>
+<text x="18" y="225" fill="#22c55e" xml:space="preserve">[ok] market btc-updown-15m-1783081800: bid=0.48 ask=0.49 min_order_size=5.0 tick=0.01</text>
+<text x="18" y="244" fill="#c3c2b7" xml:space="preserve">     taker fee at ask: 0.0175$/share (crypto table; authoritative per-market rate via executor.fee_rate)</text>
+<text x="18" y="263" fill="#eab308" xml:space="preserve">verdict: everything green, orders should work</text>
+</svg>

pmquant-0.4.0/docs/recipes.md

@@ -0,0 +1,93 @@
+# Recipes
+
+Copy-paste starting points. Everything below is Python against `pip install
+pmquant` (`import pmq`); execution snippets read `POLY_PRIVATE_KEY`,
+`POLY_FUNDER`, `POLY_SIG_TYPE` from the environment and never print them.
+
+## Trade a political market in 20 lines
+
+```python
+import pmq
+
+# discover: any gamma slug works (politics, sports, crypto)
+pm = pmq.parse_market(pmq.get_market("mississippi-gubernatorial-election-presley-d-vs-reeves-r"))
+book = pmq.get_book(pm["token_a"])                    # real-time, trustable
+bid, bid_sz, ask, ask_sz = pmq.best_bid_ask(book)
+rules = pmq.book_meta(book)                            # min_order_size, tick_size
+
+ex = pmq.PolymarketExecutor()                          # sig_type 3 = app wallet
+ex.require_collateral(10)
+if ask and ask * rules["min_order_size"] <= 10:
+    fill = ex.buy_fak(pm["token_a"], price_cap=ask, usd=10.0)
+    if fill:                                           # book ONLY what matched
+        print(f"bought {fill.matched_shares} {pm['outcome_a']} at {fill.price:.3f}")
+```
+
+## Scan a multi-outcome event (election, tournament)
+
+```python
+import pmq
+
+total_asks = 0.0
+for pm in pmq.event_markets("world-cup-winner"):
+    _, _, ask, _ = pmq.best_bid_ask(pmq.get_book(pm["token_a"]))
+    if ask is None:
+        print(f"{pm['outcome_a']:24s} unquoted (basket incomplete)")
+        continue
+    total_asks += ask
+    print(f"{pm['outcome_a']:24s} ask {ask}")
+print("sum of asks:", round(total_asks, 4), "(a full basket below 1 - fees pays 1)")
+```
+
+## What do I hold?
+
+```python
+import os
+import pmq
+
+for p in pmq.positions(os.environ["POLY_FUNDER"]):
+    print(p["slug"], p["outcome"], p["size"], "avg", p["avgPrice"],
+          "now", p.get("curPrice"), "value", p.get("currentValue"))
+```
+
+## Paper-test a strategy on any market
+
+Use [bot-template/](../bot-template/): implement `watchlist()` and
+`decide()` in `strategy.py`, run `python bot.py 24`, read
+`bot_runs/windows.csv`. Paper fills execute against the REAL ask, capped by
+displayed size and the per-market exchange minimum, and are scored with the
+real fee at resolution: if it does not survive paper, it will not survive
+live.
+
+## Budget with the real fee
+
+```python
+import pmq
+
+ex = pmq.PolymarketExecutor()
+rate = ex.fee_rate(pm["condition_id"])       # authoritative, from the exchange
+cost_per_share = ask + pmq.fee(ask, 1.0, rate)
+shares_affordable = budget_usd / cost_per_share
+```
+
+## Verify builder attribution on-chain
+
+```python
+import pmq
+
+sh, usd, fees = ex.trades_totals(pm["condition_id"])   # your fills, exchange truth
+# every matched order settles on the CTF Exchange V2; the bytes32 builder
+# code rides in the calldata. Grep any of your settlement transactions:
+# https://polygonscan.com/tx/<transactionHash from get_trades>
+# and search the input data for your builder code (without the 0x prefix).
+```
+
+## After a timeout or 5xx
+
+```python
+try:
+    fill = ex.buy_fak(token, cap, usd)
+except pmq.OrderUncertain:
+    sh, usd_spent, fees = ex.reconcile(pm["condition_id"], token)
+    # book sh/usd_spent, nothing else, and only now place new orders
+```

{pmquant-0.2.0 → pmquant-0.4.0}/docs/rounding-study.md

@@ -36,10 +36,17 @@ amounts against requested size, cross-checked with `get_trades`.
    unrounded size or price, it diverges from what the exchange signed. Book
    from the response's matched amounts (what pmq's `Fill` does), never from
    your request.
-3. Limit-path fills never exceeded the signed size in these tests. The
-   overfill reports (filled 5.051 on a size-5 order) are consistent with the
-   MARKET-order path instead, where the contract is "spend this amount" and
-   the share count is the division remainder of amount by price.
+3. Limit-path fills never exceeded the signed size in these tests because
+   they matched AT the limit price. The mechanism behind the overfill
+   reports (credit to gmoutsin in
+   [#89](https://github.com/Polymarket/py-clob-client-v2/issues/89)): the
+   signed V2 order is an amounts PAIR (makerAmount USDC, takerAmount
+   tokens), a ratio with a worst-case bound, not a (price, size) tuple.
+   Under price improvement the engine preserves your dollars and returns
+   proportionally MORE tokens (4.95 at a 0.98 ask = 5.051 tokens on a
+   "size 5" order at 0.99). Strictly favorable, but it breaks size-based
+   accounting: book from the matched amounts, and never rely on a
+   marketable limit to cap token count exactly.
 4. The per-market minimum size is enforced server-side with a clean 400, and
    is readable in advance from the book response (`min_order_size`, exposed
    by `pmq.book_meta`).

{pmquant-0.2.0 → pmquant-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pmquant"
-version = "0.2.0"
+version = "0.4.0"
 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,14 +37,25 @@ 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"
+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.2.0 → pmquant-0.4.0}/src/pmq/__init__.py

@@ -25,7 +25,7 @@ from .data import (
 )
 from .exceptions import IntrospectionMismatch, OrderUncertain, PmqError
 
-__version__ = "0.2.0"
+__version__ = "0.4.0"
 __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