pmquant 0.1.0__tar.gz

pmquant-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: pip install -e ".[dev]"
+
+      - name: Test
+        run: python -m pytest tests/ -q
+
+      - name: Build
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pmquant-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: tests
+on:
+  push:
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e ".[dev]"
+      - run: pytest -q

pmquant-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/
+.env

pmquant-0.1.0/AGENTS.md

@@ -0,0 +1,40 @@
+# Working with pmq (agent instructions)
+
+pmq is a small Python library for Polymarket CLOB V2 with two layers.
+
+## Data layer (no credentials, safe anywhere)
+
+```python
+import pmq
+m = pmq.parse_market(pmq.get_market(slug))       # condition id + token ids
+book = pmq.get_book(m["token_a"])                # REAL TIME, trade off this
+bid, bid_sz, ask, ask_sz = pmq.best_bid_ask(book)
+pmq.fee(price, shares)                            # taker $, crypto rate 0.07
+```
+
+Never make live decisions from `get_tape` (data-api): it lags matching by 1
+to 3 minutes. It is for offline scoring at least 5 minutes after close.
+
+## Execution layer (needs POLY_PRIVATE_KEY; treat as production)
+
+Rules an agent MUST follow:
+
+1. Default to reading data, not trading. Only place orders when the user
+   explicitly asked for live execution in this session.
+2. Book only `fill.matched_shares` and `fill.matched_usd`. A falsy `Fill`
+   means nothing happened, whatever the request was.
+3. Wrap every order in `try/except OrderUncertain`; on that exception call
+   `executor.reconcile(condition_id)` and do not place new orders on that
+   market until it returns.
+4. Call `executor.require_collateral(stake)` before a session of trading.
+   If it reports 0 while the user says the account is funded, the
+   signature_type is wrong: the Polymarket app's default wallet needs
+   `signature_type=3` (deposit wallet).
+5. Budget with fees: a share at price p costs `p + pmq.fee(p, 1)`.
+6. Never print or log POLY_PRIVATE_KEY or any environment secret. Addresses
+   and builder codes are public; keys are not.
+7. FAK buys spend dollars (`buy_fak(token, price_cap, usd)`), FAK sells
+   spend shares. Amounts are rounded down internally to exchange accuracy.
+8. Builder attribution: the library defaults to the maintainer's
+   zero-commission builder code. Respect the user's choice if they set
+   `builder_code=None` or their own code; do not change it silently.

pmquant-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 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.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 crp4222
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pmquant-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: pmquant
+Version: 0.1.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
+Author: crp4222
+License: MIT
+License-File: LICENSE
+Keywords: builder-code,clob,clob-v2,deposit-wallet,execution,fak,market-order,orderbook,poly-1271,polymarket,prediction-markets,quant,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+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: pytest>=8; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# pmq
+
+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
+works in production.
+
+```bash
+pip install pmquant        # distribution name pmquant, import name pmq
+```
+
+(PyPI's similarity check reserves the bare name; the module you import is
+`pmq`, same pattern as beautifulsoup4/bs4.)
+
+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: the comparison table below names the alternatives and what each
+does instead; open an issue if it goes stale.
+
+## 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`: the CLOB treats FAK/FOK buys as **market orders**. pmq routes
+  them through the market-order builder with the correct rounding.
+* `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](docs/war-story.md).
+
+## The contract: nothing is booked without exchange confirmation
+
+| Situation | What pmq does |
+|---|---|
+| Response is a dict with `orderID`, not flagged failed | `Fill` with the **matched** size read from the response |
+| Error dict on HTTP 200, string body, `success: false` | `Fill(rejected=True)`, zero booked |
+| HTTP 4xx (incl. FAK no-match) | `Fill(rejected=True)`, zero booked |
+| Timeout, 5xx, exception after send | raises `OrderUncertain`: the order MAY exist. Call `reconcile()` before trading that market again |
+| Unparseable matched amounts | zero booked (fail closed) |
+
+`reconcile(condition_id)` cancels anything resting, verifies nothing stayed
+open, and returns `(shares, usd, fees)` from `get_trades`: the exchange truth,
+not your hopes.
+
+At startup pmq **introspects the installed py-clob-client-v2** against the API
+surface it was verified on, and refuses to trade on drift instead of sending
+orders through changed semantics.
+
+## Quickstart
+
+Market data needs no keys:
+
+```python
+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):
+
+```python
+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. The buy path has carried
+live volume; treat the sell path as following the same documented semantics
+with less battle time.
+
+## The signature_type table nobody gives you
+
+| `signature_type` | Wallet | When it is yours |
+|---|---|---|
+| 0 | the EOA itself | you trade from a bare private key |
+| 1 | `POLY_PROXY` | email/Magic accounts (legacy) |
+| 2 | `POLY_GNOSIS_SAFE` | browser-wallet proxy |
+| 3 | `POLY_1271` deposit wallet | **the Polymarket app's default wallet** |
+
+If `collateral()` returns 0 while the funds are visible on-chain on your funder
+address, your `signature_type` is wrong. Debug trick: `eth_call` `owner()`
+(`0x8da5cb5b`) on the funder; if it returns your EOA and the wallet bytecode is
+an ERC-1167 proxy, you want `signature_type=3`.
+
+## Comparison (2026-07-03, factual)
+
+| | pmq | py-clob-client-v2 (official) | pmxt | NautilusTrader | caiovicentino MCP |
+|---|---|---|---|---|---|
+| CLOB V2 signing | yes, local | yes, local | writes via its hosted backend | yes, local | V1 only (rejected in prod since 2026-04-28) |
+| Confirmed-fill contract | yes (core design) | no (raw responses) | n/a | engine-level | no |
+| Deposit wallet / POLY_1271 | yes, production-proven | open issues (#70 and others) | n/a | untested claim | no |
+| Fee math | official per-category formula | fee at match, no helper | via backend | fee model | fee-blind |
+| Reconciliation helper | yes | no | n/a | engine-level | no |
+| Footprint | one small lib | one small lib | multi-venue platform | full trading framework | MCP server |
+
+NautilusTrader is excellent if you want a full framework; pmq is the small
+library you embed in your own bot. pmxt is convenient if you accept routing
+writes through their backend; pmq exists for self-custody.
+
+## Builder code disclosure
+
+pmq ships with the maintainer's public Polymarket **builder code** as default
+attribution inside signed orders (`pmq.executor.DEFAULT_BUILDER_CODE`). Its
+commission is set to **0/0: it never adds any fee to your orders**. Attribution
+feeds Polymarket's builder program and funds this project at zero cost to you.
+
+Opt out or replace it, one line either way:
+
+```python
+PolymarketExecutor(builder_code=None)            # no attribution
+PolymarketExecutor(builder_code="0xYOURS...")    # your own code
+```
+
+or set the `POLY_BUILDER_CODE` environment variable. (Same model as
+JKorf/Polymarket.Net; the official client defaults to zero attribution.)
+
+## MCP server (agents)
+
+`pip install "pmquant[mcp]"` then run `pmq-mcp` (stdio). Read tools (market,
+book, taker_fee, account_collateral, account_trades) always exist. Trading
+tools (`fak_buy`, `fak_sell`, `cancel_and_reconcile`) are **only registered
+when the operator sets `PMQ_MCP_LIVE=1`** in the server environment: an
+agent cannot talk its way past a tool that was never created. Every order is
+capped per call by `PMQ_MCP_MAX_USD` (default 10).
+
+```json
+{
+  "mcpServers": {
+    "pmq": {
+      "command": "pmq-mcp",
+      "env": { "POLY_PRIVATE_KEY": "...", "POLY_FUNDER": "0x...", "POLY_SIG_TYPE": "3" }
+    }
+  }
+}
+```
+
+Leave the `POLY_*` variables out entirely for a read-only market-data server.
+
+## Bot template
+
+[bot-template/](bot-template/) is a complete bot minus the strategy, for ANY
+market (politics, sports, crypto, culture): paper mode against real books
+with real fees, per-market budgets with fee headroom, poisoned-market
+reconciliation, consecutive-failure halt, disk-persisted daily loss halt, a
+systemd unit with `RestartPreventExitStatus=42` so halts stay halted, and a
+lightweight phone dashboard. You implement `watchlist()` and `decide()`; the
+shipped demo strategy is an API illustration meant to be replaced.
+
+## Security posture
+
+* Keys are read from the environment, used to instantiate the signer, and
+  never logged. No custody, no backend, no telemetry, zero network calls
+  besides Polymarket endpoints.
+* Beware of the documented wave of fake "polymarket bot" repositories that
+  steal private keys. Read the source: pmq is small on purpose.
+* Fund the trading wallet with what you can afford to lose. Nothing here is
+  financial advice; prediction-market access is restricted in some
+  jurisdictions and compliance is on you.
+
+## License
+
+MIT

pmquant-0.1.0/README.md

@@ -0,0 +1,186 @@
+# pmq
+
+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
+works in production.
+
+```bash
+pip install pmquant        # distribution name pmquant, import name pmq
+```
+
+(PyPI's similarity check reserves the bare name; the module you import is
+`pmq`, same pattern as beautifulsoup4/bs4.)
+
+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: the comparison table below names the alternatives and what each
+does instead; open an issue if it goes stale.
+
+## 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`: the CLOB treats FAK/FOK buys as **market orders**. pmq routes
+  them through the market-order builder with the correct rounding.
+* `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](docs/war-story.md).
+
+## The contract: nothing is booked without exchange confirmation
+
+| Situation | What pmq does |
+|---|---|
+| Response is a dict with `orderID`, not flagged failed | `Fill` with the **matched** size read from the response |
+| Error dict on HTTP 200, string body, `success: false` | `Fill(rejected=True)`, zero booked |
+| HTTP 4xx (incl. FAK no-match) | `Fill(rejected=True)`, zero booked |
+| Timeout, 5xx, exception after send | raises `OrderUncertain`: the order MAY exist. Call `reconcile()` before trading that market again |
+| Unparseable matched amounts | zero booked (fail closed) |
+
+`reconcile(condition_id)` cancels anything resting, verifies nothing stayed
+open, and returns `(shares, usd, fees)` from `get_trades`: the exchange truth,
+not your hopes.
+
+At startup pmq **introspects the installed py-clob-client-v2** against the API
+surface it was verified on, and refuses to trade on drift instead of sending
+orders through changed semantics.
+
+## Quickstart
+
+Market data needs no keys:
+
+```python
+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):
+
+```python
+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. The buy path has carried
+live volume; treat the sell path as following the same documented semantics
+with less battle time.
+
+## The signature_type table nobody gives you
+
+| `signature_type` | Wallet | When it is yours |
+|---|---|---|
+| 0 | the EOA itself | you trade from a bare private key |
+| 1 | `POLY_PROXY` | email/Magic accounts (legacy) |
+| 2 | `POLY_GNOSIS_SAFE` | browser-wallet proxy |
+| 3 | `POLY_1271` deposit wallet | **the Polymarket app's default wallet** |
+
+If `collateral()` returns 0 while the funds are visible on-chain on your funder
+address, your `signature_type` is wrong. Debug trick: `eth_call` `owner()`
+(`0x8da5cb5b`) on the funder; if it returns your EOA and the wallet bytecode is
+an ERC-1167 proxy, you want `signature_type=3`.
+
+## Comparison (2026-07-03, factual)
+
+| | pmq | py-clob-client-v2 (official) | pmxt | NautilusTrader | caiovicentino MCP |
+|---|---|---|---|---|---|
+| CLOB V2 signing | yes, local | yes, local | writes via its hosted backend | yes, local | V1 only (rejected in prod since 2026-04-28) |
+| Confirmed-fill contract | yes (core design) | no (raw responses) | n/a | engine-level | no |
+| Deposit wallet / POLY_1271 | yes, production-proven | open issues (#70 and others) | n/a | untested claim | no |
+| Fee math | official per-category formula | fee at match, no helper | via backend | fee model | fee-blind |
+| Reconciliation helper | yes | no | n/a | engine-level | no |
+| Footprint | one small lib | one small lib | multi-venue platform | full trading framework | MCP server |
+
+NautilusTrader is excellent if you want a full framework; pmq is the small
+library you embed in your own bot. pmxt is convenient if you accept routing
+writes through their backend; pmq exists for self-custody.
+
+## Builder code disclosure
+
+pmq ships with the maintainer's public Polymarket **builder code** as default
+attribution inside signed orders (`pmq.executor.DEFAULT_BUILDER_CODE`). Its
+commission is set to **0/0: it never adds any fee to your orders**. Attribution
+feeds Polymarket's builder program and funds this project at zero cost to you.
+
+Opt out or replace it, one line either way:
+
+```python
+PolymarketExecutor(builder_code=None)            # no attribution
+PolymarketExecutor(builder_code="0xYOURS...")    # your own code
+```
+
+or set the `POLY_BUILDER_CODE` environment variable. (Same model as
+JKorf/Polymarket.Net; the official client defaults to zero attribution.)
+
+## MCP server (agents)
+
+`pip install "pmquant[mcp]"` then run `pmq-mcp` (stdio). Read tools (market,
+book, taker_fee, account_collateral, account_trades) always exist. Trading
+tools (`fak_buy`, `fak_sell`, `cancel_and_reconcile`) are **only registered
+when the operator sets `PMQ_MCP_LIVE=1`** in the server environment: an
+agent cannot talk its way past a tool that was never created. Every order is
+capped per call by `PMQ_MCP_MAX_USD` (default 10).
+
+```json
+{
+  "mcpServers": {
+    "pmq": {
+      "command": "pmq-mcp",
+      "env": { "POLY_PRIVATE_KEY": "...", "POLY_FUNDER": "0x...", "POLY_SIG_TYPE": "3" }
+    }
+  }
+}
+```
+
+Leave the `POLY_*` variables out entirely for a read-only market-data server.
+
+## Bot template
+
+[bot-template/](bot-template/) is a complete bot minus the strategy, for ANY
+market (politics, sports, crypto, culture): paper mode against real books
+with real fees, per-market budgets with fee headroom, poisoned-market
+reconciliation, consecutive-failure halt, disk-persisted daily loss halt, a
+systemd unit with `RestartPreventExitStatus=42` so halts stay halted, and a
+lightweight phone dashboard. You implement `watchlist()` and `decide()`; the
+shipped demo strategy is an API illustration meant to be replaced.
+
+## Security posture
+
+* Keys are read from the environment, used to instantiate the signer, and
+  never logged. No custody, no backend, no telemetry, zero network calls
+  besides Polymarket endpoints.
+* Beware of the documented wave of fake "polymarket bot" repositories that
+  steal private keys. Read the source: pmq is small on purpose.
+* Fund the trading wallet with what you can afford to lose. Nothing here is
+  financial advice; prediction-market access is restricted in some
+  jurisdictions and compliance is on you.
+
+## License
+
+MIT

pmquant-0.1.0/bot-template/README.md

@@ -0,0 +1,65 @@
+# pmq bot template
+
+A complete Polymarket bot minus the strategy, for ANY market: politics,
+sports, crypto, culture. The engine (`bot.py`) is market-agnostic: it tracks
+whatever slugs your `strategy.py` returns, executes your intents through the
+pmq fail-closed layer, scores at resolution, and enforces the risk rails.
+You write two small functions.
+
+## What is deliberately NOT here
+
+A trading edge, or even a direction to look for one. The shipped demo
+strategy buys 2$ of any 0.98+ favorite once per market: an API illustration
+with negative expectancy, present only so paper mode has something to show.
+The engine is the part that is the same for everyone; the strategy is the
+part that is not.
+
+## Quickstart (paper, safe anywhere)
+
+```bash
+pip install pmquant
+BOT_SLUGS="<any-gamma-market-slug>" python bot.py 24
+```
+
+Fills land in `bot_runs/fills.csv`, resolved markets in
+`bot_runs/windows.csv`, and `python dash/bot_dash.py` serves a phone
+dashboard on port 8080 reading those files.
+
+## The two functions you own (`strategy.py`)
+
+* `watchlist()` returns the gamma slugs to track right now. Static from an
+  env var, discovered via the gamma API, or generated for recurring
+  markets.
+* `decide(pm, book_a, book_b, remaining_usd, side_held, state)` returns
+  `None` or `(side_key, price_cap, usd)`. You see real-time books and the
+  market metadata (`pm['outcome_a']`, `pm['end_ts']`, ...); the engine
+  enforces budget with fee headroom, one side per market, poisoning,
+  reconciliation and halts. A buggy strategy can lose its stake; it cannot
+  un-guard the execution.
+
+## The rails (engine-enforced, whatever your strategy does)
+
+* Paper mode by default; live requires `BOT_MODE=live` AND `LIVE=1`.
+* Nothing booked without exchange confirmation; unknown outcomes poison the
+  market until reconciled from `get_trades`.
+* `BOT_MAX_CONSEC_FAILS` failed buys in a row exit with code 42, and the
+  systemd unit's `RestartPreventExitStatus=42` keeps that halt halted.
+* Daily realized loss under `BOT_DAILY_HALT` stops entries; in live it is
+  persisted to disk so a same-day restart stays stopped.
+* Collateral checked before the first live order (deposit wallets need
+  `POLY_SIG_TYPE=3`).
+
+## Env reference
+
+| Var | Default | Meaning |
+|---|---|---|
+| BOT_MODE | paper | paper or live (live also needs LIVE=1) |
+| BOT_SLUGS | empty | comma-separated slugs for the demo watchlist |
+| BOT_STAKE | 5 | $ budget per market, fees included |
+| BOT_DAILY_HALT | -25 | UTC-day realized loss that halts |
+| BOT_POLL | 2.5 | seconds between polls |
+| BOT_SCORE_POLL | 60 | seconds between resolution checks |
+| BOT_FEE_CATEGORY | crypto | fee schedule for budgeting and scoring |
+| BOT_OUT_DIR | ./bot_runs | CSV output directory |
+| BOT_MAX_CONSEC_FAILS | 10 | failed buys in a row before exit 42 |
+| BOT_MAX_TRACK_HOURS | 48 | drop unresolved markets after this long |