poly-maker: A maker-only bot for Polymarket political markets

Why poly-maker targets Polymarket CLOB V2

poly-maker addresses the operational work involved in quoting both outcomes of a prediction market. It is intended for an operator with the repository, a `.env` file, a funded wallet, and enough knowledge to supervise market-making risk. Its declared focus is political markets on Polymarket CLOB V2, not general exchange liquidity or an automated prediction-market research platform.

The bot posts maker-only orders, meaning every order uses post-only behavior rather than crossing the spread for an immediate fill. It estimates a fair value, constructs bids for YES and NO, and adjusts those bids as inventory and market conditions change. This approach is different from simply reacting to a news feed or placing one directional bet. Its purpose is to maintain a two-sided quote set while controlling how much inventory can accumulate.

The README is direct about the economic boundary: market making is competitive and can lose money. It calls the project a reference implementation and research harness, not a product with guaranteed profitability. Operators therefore need to evaluate the strategy itself rather than treat the existence of automation, risk checks, or a backtest-like journal system as evidence of positive returns.

How market data reaches poly-maker's quoting engine

The runtime uses one asynchronous process and several data paths. Gamma supplies the political-market catalog for discovery and ranking. A market WebSocket feeds an internal `OrderBook`, while a user WebSocket updates positions, orders, and related state in a `StateStore`. SQLite holds the catalog, positions, orders, PnL, and other operational data.

The quoted architecture is a market WebSocket driving `OrderBook`, then waking a `Quoter`. The strategy itself is a pure function of the book, inventory, parameters, and clock, with a `TargetQuotes` result. That separation makes the quote calculation deterministic and suitable for unit testing. The engine owns I/O and surrounding state, while an `ExecutionGateway` handles authentication, signing, submission, cancellation, and blocking calls moved away from the hot path.

Before orders change, a reconciler compares current live orders with target quotes and uses churn tolerances. A periodic REST reconciliation supplements the streaming state. An exchange heartbeat acts as a dead-man switch. This architecture matters because strategy output is not treated as a command that can be submitted blindly. It is a target that must pass through reconciliation and risk management before reaching the execution gateway.

How poly-maker prices and sizes two-sided quotes

Fair value starts with a depth-weighted microprice from the live order book and is adjusted using an EWMA of signed trade flow. The strategy then calculates a reservation price with an inventory skew and a half-spread based on configured base width plus volatility and toxicity terms. For the outcome pair, it posts BUY-YES below the reservation value and BUY-NO below the corresponding value for the other side.

Inventory handling is more than a simple exposure limit. A net YES position lowers the YES bid and raises the NO bid, creating pressure to acquire the offsetting outcome. Position size tapers as inventory approaches a soft cap, after which the adding side is removed. The project also identifies a locked edge when both filled bids are combined, although the README does not present that relationship as a guarantee against execution losses.

Volatility and toxic fills are tracked with EWMAs. Higher values widen quotes and reduce size when the bot appears likely to be adversely selected. A per-market regime machine moves through states including `QUIET`, `TRENDING`, `EVENT`, `REDUCE_ONLY`, and `HALTED`. Sweeps or jumps can pull quotes, while stale data, resolution, an inventory cap, an approaching end date, or the kill switch can restrict or cancel activity. Named parameter profiles in `config/strategy.toml` change this behavior for markets such as long-dated and politically active events.

Installing poly-maker and preparing a paper-mode run

The project requires Python 3.12 or later and uses `uv` for dependency management. The documented development installation includes the optional test and lint tooling, after which the Typer entry point named `polymaker` can be invoked.

uv sync --extra dev
uv run polymaker --help

The second command should expose the CLI documented by the project. The README also requires local credentials in `.env`. Only two values are identified as required edits.

cp .env.example .env

After copying the file, set `PK` to the signer wallet's private key and `BROWSER_ADDRESS` to the associated Polymarket address. The rest of the operator's configuration lives in `config/config.toml`, `config/strategy.toml`, and `config/markets.toml`. Because the first value controls signing, the source repository, configuration files, state database, and journal directory should all be reviewed before handling production credentials.

Market discovery and selection are separate from execution. The scan writes ranked candidates to `state.db`, and `markets` lists them before an operator chooses what to trade.

uv run polymaker scan
uv run polymaker markets
uv run polymaker markets-add <slug> --profile political-longdated

The first command discovers and ranks political markets. The second displays the resulting catalog. The third adds a selected slug to the trade list with the `political-longdated` profile, but the README does not document a command for removing a market.

Running poly-maker without posting live orders

Paper mode is the first documented execution path. According to the README, it runs the full pipeline against the live feed while posting no orders. This makes it more useful than a disconnected simulation because market discovery, WebSocket handling, quote generation, state updates, and reconciliation still participate.

uv run polymaker run --paper
uv run polymaker status
uv run polymaker cancel-all

Paper mode should not be interpreted as a historical backtest. The project has captured journal data, but the README explicitly says a replay backtester has not been built. External poll and news feeds are also absent. The paper runner therefore tests current integration and operational behavior rather than proving profitability over historical markets.

The documented preflight command checks the wallet before live execution.

uv run polymaker doctor

The README does not enumerate every condition checked by `doctor`, so operators should not assume that it validates strategy economics, API credentials, funds, or every market-specific constraint. Two additional commands have narrower and potentially costly purposes. `livetest` places a deep post-only order and cancels it, while `moneydoctor` performs limit rest, market buy, and market sell operations before auto-flattening. The latter is described as costing cents, but it still submits real market orders.

uv run polymaker livetest
uv run polymaker moneydoctor

After those checks, the live entry point is `uv run polymaker run`. `cancel-all` is designated as the panic button, so a deployment still needs a clear operator procedure for invoking it.

Risk controls and operational limits in poly-maker

Risk is distributed across several components rather than represented by one exposure value. The README lists per-market notional limits, a worst-case cap for negative-risk event groups, a total exposure cap, a daily-loss kill switch, and a halt on stale WebSocket data. The strategy also pulls the adding side near its inventory cap and can enter `REDUCE_ONLY` near the end date or when inventory conditions require it.

These mechanisms address different failures. A per-market cap limits concentration in one question. The event-group cap addresses correlated outcomes across a negative-risk market group. Total exposure and daily-loss controls cover broader portfolio failure. WebSocket staleness prevents a process from relying on obsolete order-book data, while the heartbeat reduces the chance that orders remain active when the intended process is no longer operating.

The project captures raw WebSocket and order events under `journal/`, which can assist diagnosis, but there is no documented replay backtester. Operators also cannot assume external news-driven cancellation because polls, news, and cross-venue feeds are listed as not built. The regime machine can detect observed sweeps and jumps, yet those inputs are not equivalent to knowing an external event before the market reacts.

There is also a wallet-path limitation. Safe or proxy-wallet merging would route a transaction through a relayer, but that path is not wired. Inventory exits therefore use limit sells rather than merging. This makes operational behavior different from a deployment that can combine matched outcome positions directly through the intended Safe path.

poly-maker maintenance, dependency, and licensing costs

The repository was last pushed on 2026-07-09. It is not archived, and the repository currently has no GitHub releases, so `2.0.0` from `pyproject.toml` is a package version rather than evidence of a published release. Upgrade work must therefore include review of the source commit and changes to locked dependencies rather than rely on release notes.

The Python project pins `py-clob-client-v2==1.0.2`, uses `uv.lock`, and requires Python 3.12 or later. It also depends on Web3, HTTP, WebSocket, Pydantic, Typer, Rich, and asynchronous runtime packages. `uv sync --extra dev` installs development tools for pytest, ruff, and mypy, but optional live integration tests are separately gated.

uv run pytest
POLYMAKER_LIVE=1 uv run pytest tests/test_live_marketdata.py
uv run ruff check src tests
uv run mypy src

The README reports an offline unit suite, live WebSocket integration coverage, strict typing, and 83 tests, but this article does not claim that those checks were executed. Live tests involve market data, while `moneydoctor` is a separate wallet and order-path check rather than part of the normal test suite.

The package metadata and LICENSE identify MIT licensing. That permits use and modification under the license's conditions, but users remain responsible for reviewing the exact license text and for exchange-account, market-making, and financial compliance requirements.

Where poly-maker differs from a simpler trading bot

A simpler alternative is a manually operated pair of outcome bids with no persistent strategy state. Such an approach gives the operator direct control over every placement, but it lacks poly-maker's automated fair-value adjustment, inventory skew, toxicity estimate, regime transitions, churn controls, journal capture, and reconciliation loop.

Another alternative is a conventional directional prediction-market strategy that uses external news or polls to place orders. Its decision process depends on a separate information source. poly-maker does not currently include external news, poll, or cross-venue feeds, so it should be judged as an order-book and fill-response system rather than a complete event-prediction platform. The observable regime machine reacts to market behavior, including jumps and sweeps, which is a different input model.

The practical comparison is operational. poly-maker requires Python 3.12+, wallet configuration, a continuously supervised process, and comfort managing live exchange state. In return, it centralizes the mechanics of maintaining post-only, two-sided quotes. It is less appropriate for users seeking hosted execution, historical performance estimates, Safe-wallet merging, or a strategy backed by external event data. The absence of a replay backtester also means the repository layout alone does not provide a supported path for evaluating the captured journals against historical fills.

Editorial conclusion

poly-maker fits operators who understand Polymarket orders, can monitor an unattended process, and want to experiment with maker-only political-market quoting. It is a poor fit for passive users, custodial deployments, or strategies requiring Safe merging or external news data. Before adopting it, verify paper-mode behavior, inspect the configured wallet and risk limits, and confirm that the `doctor` checks and market-selection workflow match the intended deployment.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. warproxxx/poly-maker on GitHub