pmquant 0.2.0__tar.gz → 0.3.0__tar.gz

{pmquant-0.2.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.2.0 → pmquant-0.3.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # 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`

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.2.0 → pmquant-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pmquant
-Version: 0.2.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
@@ -80,6 +80,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.3.0}/README.md

@@ -54,6 +54,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.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.2.0 → pmquant-0.3.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.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pmquant"
-version = "0.2.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" }
@@ -35,6 +35,7 @@ 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"]

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

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

pmquant-0.3.0/src/pmq/doctor.py

@@ -0,0 +1,191 @@
+"""pmq-doctor: one command that diagnoses the classic Polymarket V2 setup
+failures (the ones behind a dozen open issues on the official client):
+wrong signature_type for a deposit wallet, api key confusion, CLOB balance 0
+while funds sit on-chain, drifted client surface, per-market minimums.
+
+Read-only: derives addresses, calls public RPC and CLOB endpoints. Never
+prints or transmits the private key. Exit code 0 when everything is green.
+"""
+import inspect
+import json
+import os
+import sys
+import urllib.request
+
+from .data import best_bid_ask, book_meta, fee, get_book, get_market, parse_market
+
+PUSD = "0xC011a7E12a19f7B1f670d46F03B03f3342E82DFB"
+RPCS = ["https://polygon-rpc.com", "https://polygon-bor-rpc.publicnode.com",
+        "https://1rpc.io/matic", "https://polygon.drpc.org"]
+GREEN, RED, WARN = "[ok]", "[!!]", "[??]"
+
+
+def _rpc(method, params):
+    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method,
+                       "params": params}).encode()
+    last = None
+    for rpc in RPCS:
+        try:
+            req = urllib.request.Request(rpc, data=body, headers={
+                "Content-Type": "application/json", "User-Agent": "Mozilla/5.0"})
+            with urllib.request.urlopen(req, timeout=12) as r:
+                out = json.loads(r.read().decode())
+            if "error" in out:
+                raise RuntimeError(out["error"])
+            return out["result"]
+        except Exception as e:
+            last = e
+    raise last
+
+
+def looks_like_minimal_proxy(bytecode):
+    """ERC-1167 minimal proxies (Polymarket deposit wallets included) are a
+    tiny stub; a bare EOA has no code at all."""
+    return bytecode not in (None, "", "0x") and len(bytecode) < 400
+
+
+def advise_sig_type(funder_is_contract, owner_is_eoa, funder_equals_eoa):
+    """One sentence of advice from the on-chain facts."""
+    if funder_equals_eoa:
+        return 0, "funder IS the EOA: signature_type=0"
+    if funder_is_contract and owner_is_eoa:
+        return 3, ("funder is a contract owned by your EOA: a deposit wallet, "
+                   "signature_type=3 (POLY_1271)")
+    if funder_is_contract:
+        return None, ("funder is a contract NOT owned by this EOA: wrong "
+                      "POLY_PRIVATE_KEY, or someone else's wallet")
+    return None, "funder has no code on-chain: not a deployed wallet"
+
+
+def check(ok, label, detail=""):
+    print(f"{GREEN if ok else RED} {label}" + (f": {detail}" if detail else ""))
+    return bool(ok)
+
+
+def main(argv=None):
+    argv = sys.argv[1:] if argv is None else argv
+    market_arg = None
+    if "--market" in argv:
+        i = argv.index("--market")
+        if i + 1 >= len(argv):
+            print("usage: pmq-doctor [--market <gamma-slug>]")
+            return 2
+        market_arg = argv[i + 1]
+    all_ok = True
+    print("pmq-doctor: Polymarket V2 setup diagnosis (read-only, no key ever printed)\n")
+
+    # 1. installed surface
+    try:
+        from py_clob_client_v2.client import ClobClient
+        from py_clob_client_v2.clob_types import MarketOrderArgsV2, OrderType
+
+        from .executor import _EXPECTED_MARKET_ARGS, _EXPECTED_METHODS
+        drifts = []
+        for name, params in _EXPECTED_METHODS.items():
+            fn = getattr(ClobClient, name, None)
+            have = set(inspect.signature(fn).parameters) if fn else set()
+            drifts += [f"{name}.{p}" for p in params if p not in have]
+        have = set(inspect.signature(MarketOrderArgsV2).parameters)
+        drifts += [f"MarketOrderArgsV2.{p}" for p in _EXPECTED_MARKET_ARGS if p not in have]
+        if not hasattr(OrderType, "FAK"):
+            drifts.append("OrderType.FAK")
+        all_ok &= check(not drifts, "installed py-clob-client-v2 matches the verified surface",
+                        "drifted: " + ", ".join(drifts) if drifts else "")
+    except ImportError as e:
+        all_ok &= check(False, "py-clob-client-v2 installed", str(e))
+        print("\nverdict: pip install py-clob-client-v2")
+        return 1
+
+    # 2. environment and identities
+    key = os.environ.get("POLY_PRIVATE_KEY")
+    funder = os.environ.get("POLY_FUNDER")
+    sig = os.environ.get("POLY_SIG_TYPE", "0")
+    if not key:
+        check(False, "POLY_PRIVATE_KEY present in the environment")
+        print("\nverdict: export POLY_PRIVATE_KEY (data-layer usage needs no key)")
+        return 1
+    check(True, "POLY_PRIVATE_KEY present (never printed)")
+    from eth_account import Account
+    eoa = Account.from_key(key).address
+    print(f"     derived EOA: {eoa}")
+    print(f"     POLY_FUNDER: {funder or '(unset)'}   POLY_SIG_TYPE: {sig}")
+
+    # 3. on-chain truth about the funder
+    expected_sig = 0
+    if funder and funder.lower() != eoa.lower():
+        try:
+            code = _rpc("eth_getCode", [funder, "latest"])
+            is_contract = code not in (None, "", "0x")
+            owner = None
+            try:
+                res = _rpc("eth_call", [{"to": funder, "data": "0x8da5cb5b"}, "latest"])
+                if isinstance(res, str) and len(res) >= 42:
+                    owner = "0x" + res[-40:]
+            except Exception:
+                pass
+            owner_is_eoa = bool(owner) and owner.lower() == eoa.lower()
+            expected_sig, advice = advise_sig_type(is_contract, owner_is_eoa, False)
+            all_ok &= check(expected_sig is not None, "funder wallet on-chain", advice)
+            bal = int(_rpc("eth_call", [{"to": PUSD, "data":
+                      "0x70a08231" + funder.lower()[2:].rjust(64, "0")}, "latest"]), 16) / 1e6
+            print(f"     on-chain pUSD at funder: {bal:.2f}")
+        except Exception as e:
+            check(False, "on-chain funder checks (RPC)", str(e)[:120])
+    else:
+        expected_sig, advice = advise_sig_type(False, False, True)
+        check(True, "funder", advice)
+
+    if expected_sig is not None:
+        good = int(sig) == expected_sig
+        all_ok &= check(good, f"POLY_SIG_TYPE={sig} matches the wallet type",
+                        "" if good else f"set POLY_SIG_TYPE={expected_sig}")
+
+    # 4. CLOB view with the configured identity
+    try:
+        from .executor import PolymarketExecutor
+        ex = PolymarketExecutor()
+        usdc = ex.collateral()
+        seen = check(usdc > 0, f"CLOB sees collateral with sig_type={sig}", f"{usdc:.2f} USDC")
+        all_ok &= seen
+        if not seen:
+            for st in (0, 1, 2, 3):
+                if st == int(sig):
+                    continue
+                try:
+                    alt = PolymarketExecutor(signature_type=st).collateral()
+                    if alt > 0:
+                        print(f"     but sig_type={st} sees {alt:.2f} USDC: "
+                              f"set POLY_SIG_TYPE={st}")
+                        break
+                except Exception:
+                    continue
+    except Exception as e:
+        all_ok &= check(False, "CLOB auth/collateral", str(e)[:160])
+
+    # 5. optional market checks
+    if market_arg:
+        pm = parse_market(get_market(market_arg))
+        if pm:
+            b = get_book(pm["token_a"])
+            meta = book_meta(b)
+            bid, _, ask, _ = best_bid_ask(b)
+            print(f"{GREEN} market {market_arg}: bid={bid} ask={ask} "
+                  f"min_order_size={meta['min_order_size']} tick={meta['tick_size']}")
+            if ask is not None:
+                print(f"     taker fee at ask: {fee(ask, 1.0):.4f}$/share (crypto table; "
+                      f"authoritative per-market rate via executor.fee_rate)")
+            if meta["min_order_size"] and ask:
+                print(f"     smallest possible order here: about "
+                      f"{meta['min_order_size'] * ask:.2f}$")
+        else:
+            all_ok &= check(False, f"market {market_arg} resolvable",
+                            "expired or wrong slug; recurring families need the window "
+                            "start suffix, e.g. btc-updown-15m-<unix_ts>")
+
+    print("\nverdict:", "everything green, orders should work" if all_ok else
+          "fix the [!!] lines above, in order")
+    return 0 if all_ok else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{pmquant-0.2.0 → pmquant-0.3.0}/tests/test_data.py

@@ -84,3 +84,14 @@ def test_book_inferred_winner():
     assert book_inferred_winner(0.02, 0.91) == "b"
     assert book_inferred_winner(0.60, 0.35) is None
     assert book_inferred_winner(None, None) is None
+
+
+def test_doctor_pure_logic():
+    from pmq.doctor import advise_sig_type, looks_like_minimal_proxy
+    assert looks_like_minimal_proxy("0x363d3d373d3d363d6020366004")
+    assert not looks_like_minimal_proxy("0x")
+    assert not looks_like_minimal_proxy(None)
+    assert advise_sig_type(False, False, True)[0] == 0
+    assert advise_sig_type(True, True, False)[0] == 3
+    assert advise_sig_type(True, False, False)[0] is None
+    assert advise_sig_type(False, False, False)[0] is None

pmquant-0.3.0/tests/test_doctor.py

@@ -0,0 +1,26 @@
+import pmq.doctor as doctor
+
+
+def test_advise_sig_type_matrix():
+    assert doctor.advise_sig_type(False, False, True)[0] == 0
+    assert doctor.advise_sig_type(True, True, False)[0] == 3
+    assert doctor.advise_sig_type(True, False, False)[0] is None
+    assert doctor.advise_sig_type(False, False, False)[0] is None
+
+
+def test_minimal_proxy_detector():
+    assert doctor.looks_like_minimal_proxy("0x363d3d373d3d363d6020" + "ab" * 60)
+    assert not doctor.looks_like_minimal_proxy("0x")
+    assert not doctor.looks_like_minimal_proxy(None)
+    assert not doctor.looks_like_minimal_proxy("0x" + "ab" * 300)
+
+
+def test_main_without_key_exits_1(monkeypatch, capsys):
+    monkeypatch.delenv("POLY_PRIVATE_KEY", raising=False)
+    assert doctor.main([]) == 1
+    assert "POLY_PRIVATE_KEY" in capsys.readouterr().out
+
+
+def test_main_market_flag_without_value_exits_2(capsys):
+    assert doctor.main(["--market"]) == 2
+    assert "usage" in capsys.readouterr().out