Metadata-Version: 2.4
Name: polymarket-execution
Version: 0.1.0a0
Summary: Execution utilities for Polymarket CLOB: stop-loss, take-profit, redeem, position reconciliation, and order lifecycle
Project-URL: Homepage, https://github.com/eduardodoege/polymarket-execution
Project-URL: Issues, https://github.com/eduardodoege/polymarket-execution/issues
Project-URL: Repository, https://github.com/eduardodoege/polymarket-execution
Project-URL: Sponsor, https://github.com/sponsors/eduardodoege
Author-email: Eduardo Doege <eduardodoege87@gmail.com>
License: MIT
License-File: LICENSE
Keywords: clob,polymarket,prediction-markets,redeem,stop-loss,take-profit,trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: py-clob-client-v2>=1.0.0
Requires-Dist: typer>=0.12.0
Requires-Dist: web3>=7.0.0
Requires-Dist: websockets>=14.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Provides-Extra: markets
Requires-Dist: polymarket-apis>=0.5.0; (python_version >= '3.12') and extra == 'markets'
Description-Content-Type: text/markdown

# polymarket-execution

Battle-tested execution utilities for [Polymarket](https://polymarket.com) 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`](https://github.com/Polymarket/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

```bash
pip install polymarket-execution
```

Optional extras:

```bash
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.

```python
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.

```python
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.

```python
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

```bash
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](./LICENSE)

## Sponsor

If this saves you time in production, [consider sponsoring](https://github.com/sponsors/eduardodoege).
