pmquant 0.1.0__tar.gz → 0.3.0__tar.gz

pmquant-0.3.0/.github/workflows/canary.yml

@@ -0,0 +1,34 @@
+name: canary
+on:
+  schedule:
+    - cron: "17 6 * * 1"        # weekly, monday 06:17 UTC
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  canary:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - name: Live canary against real Polymarket endpoints
+        env:
+          PMQ_CANARY: "1"
+        run: pytest tests/test_canary_live.py -q
+      - name: Open an issue if Polymarket drifted
+        if: failure()
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          existing=$(gh issue list --label canary --state open --json number --jq length)
+          if [ "$existing" = "0" ]; then
+            gh issue create --label canary \
+              --title "Canary: Polymarket surface drifted ($(date -u +%F))" \
+              --body "The weekly live canary failed: an endpoint shape or the installed py-clob-client-v2 surface no longer matches what pmq was verified against. See the failed run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
+          fi

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

@@ -18,6 +18,17 @@ jobs:
         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.1.0 → pmquant-0.3.0}/.github/workflows/test.yml

@@ -14,4 +14,5 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: pip install -e ".[dev]"
+      - run: ruff check .
       - run: pytest -q

pmquant-0.3.0/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## 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.3.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.3.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.1.0 → pmquant-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pmquant
-Version: 0.1.0
+Version: 0.3.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
@@ -19,12 +19,18 @@ 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'
+Requires-Dist: ruff>=0.6; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.2; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # 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)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 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
@@ -63,6 +69,35 @@ a real error in live trading:
 
 The full write-up with reproduction details: [docs/war-story.md](docs/war-story.md).
 
+## Runs in production
+
+The maintainer's own bot trades through this exact executor 24/7 with real
+money. Example receipt (2026-07-03): settlement transaction
+[`0x387f5f09...100d88a8`](https://polygonscan.com/tx/0x387f5f09c031bb36a71c54adc978b1ed4d50c67f6dd3f0c2c8068391100d88a8)
+on the CTF Exchange V2: a FAK market buy built by this library, matched and
+settled, with the builder code visible in the calldata. Additionally, a weekly
+[canary workflow](.github/workflows/canary.yml) exercises the real endpoints
+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.1.0 → pmquant-0.3.0}/README.md

@@ -1,5 +1,10 @@
 # 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)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
 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
@@ -38,6 +43,35 @@ a real error in live trading:
 
 The full write-up with reproduction details: [docs/war-story.md](docs/war-story.md).
 
+## Runs in production
+
+The maintainer's own bot trades through this exact executor 24/7 with real
+money. Example receipt (2026-07-03): settlement transaction
+[`0x387f5f09...100d88a8`](https://polygonscan.com/tx/0x387f5f09c031bb36a71c54adc978b1ed4d50c67f6dd3f0c2c8068391100d88a8)
+on the CTF Exchange V2: a FAK market buy built by this library, matched and
+settled, with the builder code visible in the calldata. Additionally, a weekly
+[canary workflow](.github/workflows/canary.yml) exercises the real endpoints
+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.3.0/SECURITY.md

@@ -0,0 +1,29 @@
+# Security
+
+## Posture
+
+* Your private key is read from the environment, used to instantiate the
+  local signer, and never logged, transmitted or stored by pmq. There is no
+  backend, no telemetry, no custody. The only hosts contacted are Polymarket
+  endpoints (clob/gamma/data-api) and, for the on-chain debug helpers you run
+  yourself, the RPC you choose.
+* The builder code embedded by default is attribution metadata inside the
+  signed order (public on-chain either way). It carries 0/0 commission and is
+  disabled with `builder_code=None`. It cannot access funds.
+* The executor refuses to trade if the installed py-clob-client-v2 no longer
+  matches the API surface pmq was verified against (introspection at startup),
+  rather than signing through changed semantics.
+
+## Reading the source before trusting it
+
+A documented wave of fake "polymarket bot" repositories steals private keys.
+pmq is deliberately small (five modules) so you can audit the entire execution
+path in minutes. Grep targets that settle the important questions fast:
+`POLY_PRIVATE_KEY` (read once, passed to the official client), `builder_code`
+(the disclosure and the opt-out), `http` (every host contacted).
+
+## Reporting a vulnerability
+
+Open a GitHub security advisory on this repository (Security tab, "Report a
+vulnerability") or an issue with the `security` label if it is not sensitive.
+You will get an answer within a few days.

{pmquant-0.1.0 → pmquant-0.3.0}/bot-template/bot.py

@@ -86,6 +86,39 @@ def write_halt_flag(utc_day, pnl):
         log(f"halt flag write failed ({e}); halt still enforced in-process")
 
 
+def recover_orphans(tracked):
+    """Markets that got a fill but no scoring row (a restart between fill and
+    resolution wipes in-memory state) are rebuilt so the scoring loop settles
+    them. Live scoring re-pulls exchange truth, so numbers cannot drift."""
+    try:
+        scored = set()
+        if os.path.exists(WINDOWS_CSV):
+            for r in csv.DictReader(open(WINDOWS_CSV)):
+                scored.add((r["family"], r["mode"]))
+        if not os.path.exists(FILLS_CSV):
+            return
+        now, orphans = time.time(), {}
+        for r in csv.DictReader(open(FILLS_CSV)):
+            if r["mode"] != MODE or (r["family"], MODE) in scored:
+                continue
+            o = orphans.setdefault(r["family"], {"side": r["side"], "fills": []})
+            o["fills"].append((float(r["price"]), float(r["shares"])))
+        for slug, o in orphans.items():
+            pm = pmq.parse_market(pmq.get_market(slug, log))
+            if not pm:
+                log(f"orphan {slug}: market unresolvable, skipped")
+                continue
+            spent = sum(p * s for p, s in o["fills"])
+            fees = sum(pmq.fee(p, s, FEE_RATE) for p, s in o["fills"])
+            tracked[slug] = {"pm": pm, "first_seen": now - MAX_TRACK_H * 1800,
+                             "fills": o["fills"], "spent": spent, "fees": fees,
+                             "side": o["side"], "winner": None, "src": "",
+                             "resolved": False, "poisoned": False, "sstate": {}}
+            log(f"orphan recovered: {slug} ({len(o['fills'])} fill(s)), will be scored")
+    except Exception as e:
+        log(f"orphan recovery failed (continuing without): {e}")
+
+
 def main(run_hours):
     t_end = time.time() + run_hours * 3600
     ex = None
@@ -109,6 +142,7 @@ def main(run_hours):
         f"daily_halt={DAILY_HALT_USD}$ strategy={strategy.NAME}")
 
     tracked, day_pnl, halted_day = {}, {}, None
+    recover_orphans(tracked)
     last_score_poll = 0.0
 
     while time.time() < t_end:
@@ -251,6 +285,12 @@ def main(run_hours):
                     log(f"{slug}: SCORED {st['side']} net={net:+.2f}$ "
                         f"winner={winner} day={day_pnl[d]:+.2f}$")
                     st["resolved"] = True
+                    if ex:
+                        # republish the CLOB-visible balance so the dashboard
+                        # tracks exchange truth without ever holding keys
+                        c = ex.collateral()
+                        if c > 0:
+                            log(f"collateral {c:.2f} USDC")
 
         except SystemExit:
             raise

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

@@ -94,7 +94,8 @@ def service_state():
                  "-n", "1500", "--no-pager", "-q"])
     lines = jout.splitlines()
     for line in reversed(lines):
-        if "live executor ready" in line and "collateral" in line:
+        # matches both the startup line and the per-scoring republication
+        if "collateral" in line:
             try:
                 collateral = float(line.split("collateral", 1)[1].split()[0])
                 collateral_ts = float(line.split(" ", 1)[0])

{pmquant-0.1.0 → pmquant-0.3.0}/bot-template/dash/dash.html

@@ -97,7 +97,7 @@ footer .stale{color:var(--warn);font-weight:600}
   </div>
 
   <div class="tiles">
-    <div class="tile"><div class="lbl">Balance estimée</div><div class="val" id="tBal">…</div><div class="hint" id="tBalH"></div></div>
+    <div class="tile"><div class="lbl">Balance</div><div class="val" id="tBal">…</div><div class="hint" id="tBalH"></div></div>
     <div class="tile"><div class="lbl">Win rate</div><div class="val" id="tWr">…</div><div class="hint" id="tWrH"></div></div>
     <div class="tile"><div class="lbl">PnL période</div><div class="val" id="tPnl">…</div><div class="hint" id="tPnlH"></div></div>
     <div class="tile"><div class="lbl">Frais payés</div><div class="val" id="tFee">…</div><div class="hint" id="tFeeH"></div></div>
@@ -186,7 +186,9 @@ function renderTiles(){
     const extra = d.windows.filter(w => w.mode === "live" && (w.scored_ts||0) > (s.collateral_ts||0))
                            .reduce((a,w) => a + (w.net_pnl||0), 0);
     $("tBal").textContent = "~" + (s.collateral + extra).toFixed(2) + "$";
-    $("tBalH").textContent = "collatéral vu au démarrage " + (extra ? "+ scoré depuis" : "");
+    $("tBalH").textContent = "vue exchange, maj il y a "
+      + (s.collateral_ts ? ago(d.now - s.collateral_ts) : "?")
+      + (extra ? " + scoré depuis" : "");
   } else { $("tBal").textContent = "?"; $("tBalH").textContent = "visible en mode live"; }
   $("tWr").textContent = rows.length ? Math.round(100*wins/rows.length) + "%" : "…";
   $("tWrH").textContent = rows.length ? wins + "W/" + (rows.length-wins) + "L · " + state.mode + " " + per : "aucune fenêtre";

pmquant-0.3.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.3.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.3.0/docs/rounding-study.md

@@ -0,0 +1,52 @@
+# CLOB V2 order rounding, measured
+
+*Controlled experiment against production, 2026-07-03, py-clob-client-v2
+1.0.2, total risk budget 10 USD (net result of the run: +0.39). Raw data
+posted on the client's issues
+[#89](https://github.com/Polymarket/py-clob-client-v2/issues/89#issuecomment-4875871905)
+and [#66](https://github.com/Polymarket/py-clob-client-v2/issues/66#issuecomment-4875871996).*
+
+## Method
+
+Phase A: resting GTC bids far below the touch (cannot fill, cancelled after
+each case, zero cost), submitted with adversarial sizes and prices, then read
+back through `get_open_orders` to see what the server actually recorded.
+Phase B: two marketable limit buys on a liquid market to observe matched
+amounts against requested size, cross-checked with `get_trades`.
+
+## Results
+
+| Case | Requested | Server-side view |
+|---|---|---|
+| Baseline 2-decimal size | 5.25 @ 0.05 | 5.25, exact |
+| 4-decimal size | 5.2537 | **5.25, silently rounded down** |
+| Float drift | 5.100000000000001 | 5.1, normalized |
+| Price finer than tick | 0.0515 (tick 0.01) | **0.05, silently rounded down** |
+| Sub-cent notional | 5.007 @ 0.03 | accepted, size recorded as 5.00 |
+| Below minimum size | size 4 (min 5) | HTTP 400: `Size (4) lower than the minimum: 5` |
+| Marketable fill, odd size | 5.1234 @ 0.96 | signed as 5.12; matched **exactly 5.12** shares for 4.9152 USDC (0.96 x 5.12 to the cent) |
+| Marketable fill, control | 5.0 @ 0.96 | matched exactly 5.00 for 4.80 USDC |
+
+## What this means
+
+1. On 1.0.2, every input is normalized CLIENT-side (rounded DOWN to the
+   allowed decimals per the tick's RoundConfig) before signing. Float-drift
+   artifacts never reach the wire.
+2. The normalization is **silent**. If your own accounting keeps the
+   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 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.1.0 → pmquant-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pmquant"
-version = "0.1.0"
+version = "0.3.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" }
@@ -31,10 +31,19 @@ Issues = "https://github.com/crp4222/pmq/issues"
 
 [project.optional-dependencies]
 mcp = ["mcp>=1.2"]
-dev = ["pytest>=8", "mcp>=1.2"]
+dev = ["pytest>=8", "mcp>=1.2", "ruff>=0.6"]
 
 [project.scripts]
 pmq-mcp = "pmq.mcp:main"
+pmq-doctor = "pmq.doctor:main"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/pmq"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I"]
+ignore = ["E501"]