pmq

Fail-closed execution and market data for Polymarket CLOB V2, in Python, built agent-first. Local signing (your keys never leave your process), exchange-confirmed fills only, fee-correct math, deposit-wallet (POLY_1271) support that actually works in production, order-attribution registries (several bots can share one wallet, each with its own exchange-truth accounting), and a bundled MCP server: plug any LLM or agent framework that speaks MCP (Claude, ChatGPT, LangChain, your own loop) on top and it can read every market and, if and only if the operator enables it, trade under hard rails: tools that do not exist until you create them, a cap per order, a daily buy budget. The model cannot widen any of this from inside a session.

pip install pmquant        # Python >= 3.10; distribution pmquant, import pmq

(PyPI's similarity check reserves the bare name; the module you import is pmq, same pattern as beautifulsoup4/bs4.)

Try it in 30 seconds, no keys

Point any MCP client at uvx; it installs the MCP extra in an isolated environment and starts pmq-mcp with one environment variable:

{
  "mcpServers": {
    "pmq": {
      "command": "uvx",
      "args": ["--from", "pmquant[mcp]", "pmq-mcp"],
      "env": { "PMQ_MCP_PAPER": "1" }
    }
  }
}

PMQ_MCP_PAPER=1 registers the same trading tools as live, but fills are simulated against the real live order books using the displayed best quote, venue minimums, and a documented crypto-rate fee estimate. The first paper ledger starts at 1000 USD, configurable with PMQ_MCP_PAPER_USD; it then persists locally across server restarts. No keys are needed and no order can reach the exchange. A real session, captured 2026-07-04, quoted verbatim:

> find_markets(query="fed decision july")
    12 markets, among them "How many dissent at the July Fed meeting?"
> market(slug="will-no-one-dissent-the-july-fed-decision-20260616001928666")
    condition_id 0x50ba...7967, token ids for Yes and No, closes 2026-07-29
> book(token_id=<Yes>)
    bid 0.54 x 592.75 | ask 0.56 x 21 | min order 5 shares | tick 0.01
> fak_buy(token_id=<Yes>, price_cap=0.58, usd=10)
    paper fill: 17.8571 shares at 0.56 (the real ask, not the cap),
    fee 0.308, cash left 989.69
> account_collateral()
    989.69 paper USD

Five calls: discover, resolve, read the live book, buy with simulated money at the real ask, check the balance. The same session rendered as a step-by-step page: docs/demo.html (one self-contained HTML file, no JavaScript, no external requests; download and open it). Trading real money additionally requires keys and an explicit PMQ_MCP_LIVE=1, under the rails in the agents section.

As of 2026-07-03 this is, to our knowledge, the only maintained Python layer combining local CLOB V2 signing, an exchange-confirmed fill contract, and working deposit-wallet (POLY_1271) auth. That claim is dated and falsifiable: docs/comparison.md names the alternatives and what each does instead; open an issue if it goes stale.

Quickstart

Market data needs no keys:

import pmq

m = pmq.parse_market(pmq.get_market("btc-updown-15m-1783062000"))
book = pmq.get_book(m["token_a"])
bid, bid_sz, ask, ask_sz = pmq.best_bid_ask(book)
print(ask, pmq.band_ask_depth_usd(book, 0.90, 0.97))
print(pmq.fee(price=0.95, shares=100))          # taker fee in $, crypto rate

Execution (reads POLY_PRIVATE_KEY, POLY_FUNDER, POLY_SIG_TYPE from the environment):

from pmq import PolymarketExecutor, OrderUncertain

ex = PolymarketExecutor()                        # signature_type=3 for the app's deposit wallet
ex.require_collateral(5.0)                       # fail fast, with a diagnostic that names sig_type

try:
    fill = ex.buy_fak(token_id=m["token_a"], price_cap=0.95, usd=5.00)
except OrderUncertain:
    ex.reconcile(m["condition_id"], m["token_a"])   # exchange truth before anything else
else:
    if fill:                                     # book ONLY what matched
        print(fill.matched_shares, "shares at", fill.price, "order", fill.order_id)

sell_fak and limit_gtc follow the same contract, and all three paths have carried production volume: a FAK round trip (buy 5.149 @ 0.94, sell back 5.14 @ 0.94, cross-checked via get_trades, 2026-07-03) and a GTC maker fill (posted above the bid, matched as MAKER at zero fee, 2026-07-04, settlement tx in the production section below).

Scope, latency, requirements

Python 3.10 to 3.14 (the CI matrix runs all five). Plain REST round trips, measured 2026-07-04 (medians of 5, residential fiber, Western Europe): resolve a market 76 ms, fetch a book 85 ms, sign + POST an order and get the exchange's answer 73 ms. Sub-second everywhere, built for second-scale strategies (the maintainer's bot polls 15-minute windows every 2.5 s); it is not a microsecond market-making stack: no websockets, no co-location, one HTTP call per action.

Why this exists

Polymarket cut over to CLOB V2 on 2026-04-28. V1-signed orders are rejected in production, the fee schedule is decided at match time, and the official client examples leave several traps undocumented. Every line of pmq was paid for with a real error in live trading:

• invalid amounts, the market buy orders maker amount supports a max accuracy of 2 decimals, taker amount a max of 4 decimals: the CLOB treats FAK/FOK buys as market orders and caps their signed amounts at 2 decimals (maker) / 4 decimals (taker) whatever the tick size. The official client's rounding table allows 5-6 taker decimals on markets whose tick is finer than 0.01 (any book trading past 0.96 or under 0.04), so market orders there are rejected wholesale (reported upstream: py-clob-client-v2#99). pmq clamps the signed pair to the exchange caps before signing and refuses at startup any client build that would still sign a rejectable pair, so the trap cannot reach your orders. Measurements in docs/rounding-study.md.
• no orders found to match with FAK order (HTTP 400, yet with an orderID): a clean no-fill, not an error. pmq returns an empty Fill instead of crashing or, worse, retrying blindly.
• CLOB shows balance: 0 while your pUSD sits on-chain: the balance endpoint ignores your funder parameter and derives the wallet from your EOA and signature_type. Funds in the Polymarket app's default wallet (an ERC-1271 deposit wallet) are only visible with signature_type=3.

The full write-up with reproduction details: docs/war-story.md.

Runs in production: my own money, daily

I built pmq for my own trading. It executes real volume with my funds every day, and it has never booked a fill the exchange did not confirm. If you want to see it on-chain, here is a settlement from one of my wallets (2026-07-03): 0x387f5f09...100d88a8 on the CTF Exchange V2: a FAK market buy built by this library, matched and settled, with the builder code visible in the calldata. The maker path has its own receipt (2026-07-04): a limit_gtc posted one tick above the bid, matched as MAKER at zero fee and settled in 0x1b60f19a...c35d09, where the maker_orders slice accounting that release 0.4.6 encodes is visible in the raw trade record. A weekly canary workflow 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

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:

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