polymarket-execution 0.1.0a0

Execution utilities for Polymarket CLOB: stop-loss, take-profit, redeem, position reconciliation, and order lifecycle

polymarket-execution

Battle-tested execution utilities for Polymarket CLOB v2: stop-loss, take-profit, redeem, position reconciliation, order lifecycle, and recovery layers for masked fills.

Built on top of py-clob-client-v2. Designed to be the missing layer between the raw CLOB primitives and a production trading bot.

Status: Early development (v0.1.x alpha). API may change before 1.0.

Why this exists

The Polymarket CLOB gives you primitives like create_and_post_order and cancel_order, but doesn't help with the things you actually need to run a bot in production:

• Stop-loss / take-profit execution — CLOB has no native trigger orders
• Redeeming resolved positions — claim winnings via web3 (with the USDC.e → pUSD wrap dance that V2 introduced)
• Position reconciliation — keep CLOB and on-chain state in sync
• Order lifecycle — retry, replace, and clean up stale orders
• Recovery layers — detect masked fills when network errors / status timeouts / balance locks hide a successful order

This library provides those primitives, with no opinions about your trading strategy.

Install

pip install polymarket-execution

Optional extras:

pip install polymarket-execution[markets]   # adds polymarket-apis for category-filtered listing/search
pip install polymarket-execution[dev]       # pytest, ruff, mypy

Crypto up/down market discovery (BTC/ETH/SOL/XRP at 5m/15m/1h windows) works out of the box — the [markets] extra is only needed for general listing/search across categories.

Quick start: discover current crypto markets

Available now. Native slug-based lookup, no [markets] extra needed.

from polymarket_execution.markets import discover_current_markets

markets = discover_current_markets(window="5m")  # btc, eth, sol, xrp by default
for m in markets:
    print(m, "->", m.polymarket_url)

Quick start: redeem resolved positions

Preview API. Implementation lands in v0.1.0; the snippet below shows the target shape.

from py_clob_client_v2 import ClobClient
from polymarket_execution.redeem import RedeemClient

client = ClobClient(host="https://clob.polymarket.com", chain_id=137, key=PRIVATE_KEY, signature_type=2, funder=SAFE_ADDRESS)

redeemer = RedeemClient(clob_client=client, web3_rpc_url=POLYGON_RPC, safe_address=SAFE_ADDRESS)
result = redeemer.auto_redeem_all()  # also wraps USDC.e -> pUSD afterwards
print(result.redeemed_markets, result.wrap_tx_hash)

Quick start: stop-loss

Preview API. Implementation lands in v0.3.0; the snippet below shows the target shape.

from polymarket_execution.triggers import StopLossMonitor
from polymarket_execution.price_reference import use_mid_price

monitor = StopLossMonitor(clob_client=client, price_source=use_mid_price)
monitor.add_stop(token_id="0x...", trigger_price=0.45, size=100)
await monitor.run()

Modules

Module	Purpose
redeem	Claim USDC from resolved positions via web3 (with V2 USDC.e → pUSD wrap)
triggers.stop_loss	Monitor positions and execute market orders on trigger
triggers.take_profit	Monitor PnL and execute market orders on profit target
orders.place	Place orders with sane defaults
orders.fills	Get true VWAP fill price via get_trades (fixes a critical PnL bug)
recovery	5 recovery layers for masked fills (network/status/balance/matched_orders/suspect_drop)
position	Reconcile CLOB and on-chain positions
markets.crypto	Native slug-based discovery for crypto up/down markets (no extra)
markets.general	List/search arbitrary markets (requires [markets] extra)
order_lifecycle	Retry, replace, and clean up stale orders
price_feed.chainlink_rtds	Polymarket-aligned ChainLink price feed via WebSocket

CLI

polymarket-execution redeem auto                          # redeem all resolved positions
polymarket-execution markets crypto --window 5m           # current crypto markets (no extra)
polymarket-execution markets crypto --symbol btc          # single symbol
polymarket-execution markets list                         # general listing (requires [markets])
polymarket-execution stop-loss watch                      # interactive stop-loss monitor
polymarket-execution take-profit watch                    # interactive take-profit monitor
polymarket-execution position reconcile                   # CLOB vs chain drift report

Run polymarket-execution --help for the full command tree.

What this is NOT

• A trading framework. You decide when, what, and how much to trade.
• A strategy library. No signals, no parameters, no backtesting.
• A replacement for py-clob-client-v2. It plugs in on top.

License

MIT

Sponsor

If this saves you time in production, consider sponsoring.