polymarket-sdk 0.2.0__tar.gz

polymarket_sdk-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+polymarket_data/
+.github/workflows/

polymarket_sdk-0.2.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## [0.6.0] — 2026-06-05
+
+### Added
+- **Market snapshot validation** (`market_snapshot.py`): Polymarket-specific CLOB
+  sanity checks — prices in (0,1), crossed-book detection, spread limits, mid-price
+  divergence guard. Raises `MarketDataError` on degenerate/stale snapshots.
+- **Drawdown metrics** (`metrics.py`): venue-agnostic `drawdown_series`,
+  `max_drawdown`, `rank_drawdown_leaderboard` for equity-curve analysis.
+
+## [0.1.0] — 2026-05-23
+
+### Added
+- Market data fetcher: 25+ endpoints covering Gamma, CLOB, and Data APIs
+- Event/market browsing with pagination, filtering, and search
+- Price history (OHLCV), orderbook depth, spreads, and midpoints
+- Order execution: limit orders with EIP-712 signing (optional eth-account)
+- Position tracking, order management, and balance queries
+- Strategy framework: mean-reversion, momentum, convergence
+- Zero-dependency core (trading extra is opt-in)
+- 15 tests covering fetcher, trading, models, and error handling
+- GitHub Actions CI (Python 3.10, 3.11, 3.12)
+- MIT License
+
+[0.1.0]: https://github.com/counterfactual5/polymarket-autopilot/releases/tag/v0.1.0

polymarket_sdk-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing to polymarket-autopilot
+
+## Setup
+
+```bash
+git clone https://github.com/counterfactual5/polymarket-autopilot.git
+cd polymarket-autopilot
+uv pip install -e ".[dev,trading]"
+```
+
+## Running Tests
+
+```bash
+uv run pytest tests/ -v
+```
+
+15 tests covering fetcher API, trading, order/position models, error handling, and pagination.
+
+## Code Style
+
+- Python 3.10+ compatible
+- 120-char line length
+- Public functions have docstrings
+- Core package has zero dependencies (trading needs only eth-account)
+
+## Project Structure
+
+```
+src/polymarket_autopilot/
+├── fetcher/          # Market data: Gamma, CLOB, and Data APIs
+│   └── fetcher.py    # 25+ endpoints
+└── trading/          # Authenticated trading
+    └── trading.py    # EIP-712 signing, order execution
+```
+
+## Pull Requests
+
+1. Fork → feature branch → changes + tests → PR to `master`
+2. Keep PRs focused — one concern per PR

polymarket_sdk-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 counterfactual5
+
+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.

polymarket_sdk-0.2.0/PKG-INFO

@@ -0,0 +1,388 @@
+Metadata-Version: 2.4
+Name: polymarket-sdk
+Version: 0.2.0
+Summary: Polymarket trading client and market data fetcher
+Project-URL: Repository, https://github.com/counterfactual5/polymarket-sdk
+Project-URL: Issues, https://github.com/counterfactual5/polymarket-sdk/issues
+Author: counterfactual5
+License-Expression: MIT
+License-File: LICENSE
+Keywords: clob,polymarket,prediction-market,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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 :: Investment
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: trading
+Requires-Dist: eth-account>=0.10; extra == 'trading'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 🎯 Polymarket Autopilot
+
+### The Python SDK Polymarket never shipped.
+
+**Fetch markets. Place orders. Track positions.** All in pure Python.
+
+Zero Dependencies* · Polymarket CLOB API · EIP-191 Signing · 25+ API Endpoints
+
+<sub>*Market data: zero deps. Trading: `eth-account` only, for message signing.</sub>
+
+[![Test](https://github.com/counterfactual5/polymarket-autopilot/actions/workflows/test.yml/badge.svg)](https://github.com/counterfactual5/polymarket-autopilot/actions)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![Zero Deps](https://img.shields.io/badge/dependencies-zero-brightgreen.svg)](pyproject.toml)
+
+[Installation](#installation) · [Market Data](#-fetch-market-data) · [Trading](#-place--manage-orders) · [API Reference](#api-reference)
+
+</div>
+
+---
+
+> [!IMPORTANT]
+> **Trading safety.** Order paths run through a shared risk-control policy
+> (amount caps, price range, max position value, chain allow-list) evaluated
+> between the `PREFLIGHT` and `SIGNED` states. Read **[RISK_POLICY.md](RISK_POLICY.md)**
+> and copy `policy.yaml` to `~/.stageforge/policy.yaml` before going live.
+
+## The Problem
+
+Polymarket is the world's largest prediction market — but they don't offer a Python SDK. Their [official docs](https://docs.polymarket.com) show raw `curl` commands and JavaScript examples. If you want to build trading bots, analyze markets, or automate strategies in Python, you're on your own.
+
+**polymarket-autopilot fills that gap.** One `pip install` gives you 25+ endpoints covering market data, trading, and portfolio management — pure Python, zero dependencies.
+
+```
+  Without this library:                    With this library:
+
+  1. Read Polymarket API docs              1. pip install polymarket-autopilot
+  2. Write HTTP client from scratch        2. from polymarket_autopilot.fetcher import search
+  3. Implement message signing             3. results = search("US election")
+  4. Debug authentication headers
+  5. Handle pagination manually            ✅ Done.
+```
+
+---
+
+## Features
+
+### 📊 Market Data (no auth required)
+
+- **Events** — browse active, closed, featured events by volume and recency
+- **Markets** — full market details or simplified lightweight listings
+- **Search** — fuzzy search across all events and markets
+- **Price History** — OHLCV candles at any interval (1m, 1h, 1d)
+- **Orderbook** — full bid/ask depth for any outcome token
+- **Spreads & Midpoints** — real-time pricing data
+- **Open Interest** — market-wide position statistics
+- **Leaderboard** — top traders by PnL
+- **Tags & Series** — browse by category (politics, crypto, sports, etc.)
+- **Trades** — recent fills filtered by market, maker, or taker
+
+### ⚡ Trading (auth required)
+
+- **Place Orders** — limit orders on any outcome with personal-sign (EIP-191)
+- **Cancel Orders** — cancel single or all orders
+- **View Positions** — current holdings across all markets
+- **View Open Orders** — pending orders with optional market filter
+- **Balance Check** — USDC balance query
+
+### 🔧 Engineering
+
+- **Zero dependencies** — pure Python stdlib (urllib, json, hashlib)
+- **Pagination handled** — automatic offset-based pagination for large result sets
+- **Retry logic** — built-in retry with exponential backoff
+- **Gzip support** — automatic decompression for faster responses
+- **Type-annotated** — full type hints for IDE autocomplete
+
+---
+
+## Installation
+
+```bash
+# Market data only (zero deps)
+pip install polymarket-autopilot
+
+# Add trading support (eth-account for signing)
+pip install "polymarket-autopilot[trading]"
+```
+
+That's it. No Node.js. No curl. No web3.py. Pure Python.
+
+---
+
+## Quick Start
+
+### 📊 Fetch Market Data
+
+```python
+from polymarket_autopilot.fetcher import (
+    fetch_events, search, fetch_price_history,
+    fetch_orderbook, fetch_spread, resolve_market_token_id,
+)
+```
+
+**Browse trending events:**
+
+```python
+events = fetch_events(limit=5)
+for ev in events:
+    print(f"  {ev['title']}")
+    print(f"    Volume: ${ev.get('volume', 0):,.0f}")
+    print(f"    Markets: {len(ev.get('markets', []))}")
+```
+
+```
+  Will Bitcoin reach $150K by end of 2026?
+    Volume: $12,450,000
+    Markets: 2
+  US Presidential Election 2028
+    Volume: $8,320,000
+    Markets: 5
+  Will ETH flip BTC in market cap?
+    Volume: $3,100,000
+    Markets: 1
+```
+
+**Search for a market:**
+
+```python
+results = search("bitcoin 100k")
+for market in results.get("markets", [])[:3]:
+    print(f"  {market['question']}")
+    print(f"    YES: {market.get('outcomePrices', ['?'])[0]}")
+```
+
+```
+  Will Bitcoin reach $100,000 by December 2026?
+    YES: 0.452
+  Will Bitcoin be above $100K on June 1?
+    YES: 0.381
+  Bitcoin $100K end of year?
+    YES: 0.417
+```
+
+**Get price history:**
+
+```python
+history = fetch_price_history("will-bitcoin-hit-100k", interval="1d")
+for candle in history[-5:]:
+    print(f"  {candle['timestamp']}  O:{candle['open']} H:{candle['high']} L:{candle['low']} C:{candle['close']}")
+```
+
+**Check the orderbook:**
+
+```python
+token_id = resolve_market_token_id("will-bitcoin-hit-100k", outcome_index=0)  # YES
+book = fetch_orderbook(token_id)
+spread = fetch_spread(token_id)
+print(f"  Bid: {book['bids'][0]['price']}  Ask: {book['asks'][0]['price']}")
+print(f"  Spread: {spread['spread']}")
+```
+
+### ⚡ Place & Manage Orders
+
+```python
+import os
+from polymarket_autopilot.trading import PolymarketTrader, Order
+
+# Configure via environment variables
+# export POLYMARKET_API_KEY="..."
+# export POLYMARKET_ADDRESS="0x..."
+# export POLYMARKET_PRIVATE_KEY="..."  # via env var, never on disk
+
+trader = PolymarketTrader.from_env()
+```
+
+**Buy YES on a market:**
+
+```python
+token_id = resolve_market_token_id("will-bitcoin-hit-100k", outcome_index=0)
+
+order = Order(
+    token_id=token_id,
+    side="buy",       # "buy" or "sell"
+    price=0.45,       # price in USDC (0-1 range for binary options)
+    size=10,          # quantity in USDC
+)
+
+result = trader.place_order(order)
+print(f"  Order ID: {result['orderID']}")
+print(f"  Status: {result['status']}")
+```
+
+```
+  Order ID: 12345678
+  Status: LIVE
+```
+
+**Check your positions:**
+
+```python
+positions = trader.get_positions()
+for pos in positions:
+    print(f"  {pos.token_id[:10]}...  {pos.side} {pos.size} @ avg {pos.avg_price}")
+```
+
+**Manage open orders:**
+
+```python
+# View open orders
+orders = trader.get_orders()
+for o in orders:
+    print(f"  {o['id']}: {o['side']} {o['original_size']} @ {o['price']}")
+
+# Cancel a specific order
+trader.cancel_order("12345678")
+
+# Cancel all orders for a token
+trader.cancel_all_orders(token_id=token_id)
+```
+
+---
+
+## API Reference
+
+### Market Data (no auth)
+
+| Function | Endpoint | Description |
+|---|---|---|
+| `fetch_events()` | Gamma API | Browse events with filters (active, closed, featured) |
+| `fetch_event_by_id()` | Gamma API | Get single event by ID |
+| `fetch_event_by_slug()` | Gamma API | Get single event by URL slug |
+| `fetch_markets()` | Gamma API | Browse markets with full details |
+| `fetch_market_by_id()` | Gamma API | Get single market by ID |
+| `fetch_market_by_slug()` | Gamma API | Get single market by URL slug |
+| `fetch_simplified_markets()` | Gamma API | Lightweight market list (faster) |
+| `search()` | Gamma API | Fuzzy search across events and markets |
+| `fetch_event_tags()` | Gamma API | Tags for an event |
+| `fetch_tags()` | Gamma API | All available tags/categories |
+| `fetch_series()` | Gamma API | Market series/collections |
+| `fetch_price_history()` | CLOB API | OHLCV price candles |
+| `fetch_orderbook()` | CLOB API | Full bid/ask order book |
+| `fetch_midpoint()` | CLOB API | Midpoint price for a token |
+| `fetch_spread()` | CLOB API | Bid-ask spread |
+| `fetch_trades()` | CLOB API | Recent trade fills |
+| `fetch_open_interest()` | Data API | Open interest statistics |
+| `fetch_leaderboard()` | Data API | Top traders by PnL |
+| `resolve_market_token_id()` | — | Convert market slug → CLOB token ID |
+| `fetch_all_snapshot()` | Multiple | Bulk snapshot of events + markets |
+
+### Trading (auth required)
+
+| Method | Description |
+|---|---|
+| `PolymarketTrader.from_env()` | Create trader from environment variables |
+| `trader.place_order(order)` | Place a limit order (signed) |
+| `trader.cancel_order(order_id)` | Cancel a specific order |
+| `trader.cancel_all_orders(token_id?)` | Cancel all orders (optionally filtered) |
+| `trader.get_orders(token_id?)` | List open orders |
+| `trader.get_positions()` | List current positions |
+| `trader.get_balance()` | Check USDC balance |
+
+---
+
+## Architecture
+
+```
+polymarket_autopilot/
+├── fetcher/              Market data (no auth)
+│   └── fetcher.py          25 endpoints — Gamma, CLOB, Data APIs
+│       ├── Gamma API       Events, markets, tags, series, search
+│       ├── CLOB API        Prices, orderbook, spreads, trades
+│       └── Data API        Leaderboard, open interest
+│
+└── trading/              Authenticated trading
+    └── trading.py          Order execution + portfolio management
+        ├── Order           Limit order dataclass
+        ├── Position        Position dataclass
+        └── PolymarketTrader  Main trading client
+            ├── Message signing (eth-account, optional)
+            ├── Place / cancel orders
+            └── Position & balance queries
+```
+
+```
+Data Flow:
+
+  User Code
+     │
+     ├── fetcher.search() ──────────→ Polymarket Gamma API ──→ events, markets, tags
+     │
+     ├── fetcher.fetch_orderbook() ──→ Polymarket CLOB API ──→ prices, spreads, trades
+     │
+     ├── fetcher.fetch_leaderboard() → Polymarket Data API ──→ leaderboard, open interest
+     │
+     └── trader.place_order(order) ──→ Sign ──→ Polymarket CLOB ──→ ✅ Order placed
+                                          ↑
+                                     eth-account
+                                   (trading extra)
+```
+
+## Security
+
+| Concern | How we handle it |
+|---|---|
+| Private keys | Environment variable only — never on disk, never logged |
+| Order signing | In-process via eth-account — no external CLI, no IPC |
+| API keys | Passed via env vars, not hardcoded or stored in config files |
+| HTTP requests | urllib with gzip + retry — no third-party HTTP libraries |
+
+```bash
+# Required for trading
+export POLYMARKET_API_KEY="your-api-key"
+export POLYMARKET_ADDRESS="0x..."
+export POLYMARKET_PRIVATE_KEY="0x..."  # via env var, never written to a file
+```
+
+## For AI Agent Developers
+
+This library is designed as the execution backend for AI trading agents:
+
+```python
+# 1. Research   →  search markets, check prices and spreads
+# 2. Analyze    →  fetch orderbook depth, price history, open interest
+# 3. Decide     →  your model / strategy logic
+# 4. Execute    →  place_order() with message signing
+# 5. Monitor    →  get_positions(), get_orders()
+```
+
+Works with [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Cursor](https://cursor.sh), [Codex](https://github.com/openai/codex), or any Python-capable agent.
+
+## Development
+
+```bash
+git clone https://github.com/counterfactual5/polymarket-autopilot.git
+cd polymarket-autopilot
+
+# Install with dev + trading deps
+uv pip install -e ".[dev,trading]"
+
+# Run tests
+uv run pytest tests/ -v
+```
+
+## Roadmap
+
+- [x] Strategy framework (mean-reversion, momentum, convergence)
+- [ ] Market analysis (probability trends, volume anomalies)
+- [ ] Backtesting engine with historical data
+- [ ] Arbitrage scanner (spread + cross-market)
+- [ ] WebSocket support for real-time price feeds
+- [ ] Async support (async/await)
+
+## License
+
+[MIT](LICENSE) — use it however you want.
+
+---
+
+If this project helped you, please ⭐ star this repo — it helps others find it!