An automated trading system for Polymarket prediction markets featuring quantitative strategies, real-time dashboards, and comprehensive risk management.

• Market Making: Avellaneda-Stoikov model with dynamic inventory management
• Edge Detection: Kelly criterion position sizing for probability edges
• Mean Reversion: Z-score based strategy with adaptive parameters
• Hot Market Scorer: Ranks markets by exploitability using microstructure metrics

• Real-time drawdown monitoring with circuit breakers
• Position limits by market, category, and total exposure
• Daily/weekly loss limits with automatic halt
• Slippage modeling for realistic paper trading

• Unified API Client: Type-safe Polymarket API access with shared rate limiting
• Paper Trading: Full simulation with realistic order fills and P&L tracking
• Backtesting: Walk-forward testing with Brier score metrics
• Real-time Dashboard: React frontend with live updates via WebSocket
• Telegram Alerts: Trade notifications and system alerts

polypigeon/ ├── backend/ # FastAPI Python backend │ ├── app/ │ │ ├── api/ # REST API routes │ │ │ └── routes/ # Dashboard, trading, markets, analysis │ │ ├── connectors/ # Legacy Polymarket connector + WebSocket │ │ ├── core/ # Trading engine, risk manager, paper bots │ │ ├── db/ # SQLAlchemy models and schemas │ │ ├── polymarket/ # ★ NEW: Unified API module │ │ │ ├── models/ # Pydantic models (OrderBook, Market, etc.) │ │ │ ├── endpoints/ # API endpoint handlers │ │ │ ├── normalizers/ # Response format normalization │ │ │ ├── client.py # Singleton client │ │ │ └── rate_limiter.py # Token bucket rate limiting │ │ ├── services/ # Alerts, monitoring │ │ └── strategies/ # Market making, edge detection, microstructure │ └── backtesting/ # Historical backtesting engine ├── frontend/ # Vite + React dashboard │ └── src/ │ ├── components/ # Dashboard cards, charts, tables │ ├── hooks/ # React Query hooks │ └── views/ # Analysis views └── docker-compose.yml # Docker orchestration 

• Python 3.12+
• Node.js 18+
• PostgreSQL (optional, SQLite works for development)

cd backend python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt # Configure environment cp .env.example .env # Edit .env with your settings (see Configuration below)

cd frontend npm install

# Terminal 1 - Backend (starts on port 8000) cd backend uvicorn app.main:app --reload # Terminal 2 - Frontend (starts on port 5173) cd frontend npm run dev

Navigate to http://localhost:5173

docker-compose up -d

Create a .env file in the backend/ directory:

The new app.polymarket module provides type-safe, rate-limited access to all Polymarket APIs.

from app.polymarket import get_client, init_client # Initialize once at startup (done in main.py) await init_client() # Use anywhere in the application client = get_client() # Fetch markets from Gamma API markets = await client.markets.list(active=True, limit=100) market = await client.markets.get(condition_id) results = await client.markets.search("election") # Fetch orderbook from CLOB API book = await client.orderbook.get(token_id) books = await client.orderbook.get_batch(token_ids) # Partial retry on failure midpoint = await client.orderbook.get_midpoint(token_id) # Place orders (requires credentials) if client.trading_enabled: from app.polymarket import OrderSide from decimal import Decimal order = await client.trading.place_limit_order( token_id=token_id, side=OrderSide.BUY, price=Decimal("0.55"), size=Decimal("100"), ) # Historical price data history = await client.historical.get_prices(token_id, interval="1h")

All endpoints share a unified rate limiter respecting Polymarket's documented limits:

# Check rate budget before batch operations from app.polymarket import get_rate_limiter limiter = get_rate_limiter() wait_time = await limiter.acquire("books", tokens=20) if wait_time > 0: await asyncio.sleep(wait_time)

All responses are normalized to type-safe models:

from app.polymarket import ( OrderBook, OrderBookEntry, Market, MarketToken, Event, Order, Trade, OrderSide, OrderType, OrderStatus, PriceBar, PriceHistory, ) # OrderBook with typed entries book: OrderBook = await client.orderbook.get(token_id) for bid in book.bids: print(f"Price: {bid.price}, Size: {bid.size}") # Both are Decimal

The market making strategy uses a simplified Avellaneda-Stoikov model:

Reservation Price: r = s - q × γ × σ² × (T - t) Spread: base_spread + (2.5 × σ × √holding_period) + (0.02 × |inventory_ratio|) 

Where:

• s = mid price
• q = current inventory
• γ = risk aversion (0.3-0.7)
• σ = volatility
• T-t = time remaining to resolution

Uses Kelly criterion for position sizing on probability edges:

Kelly% = (p × b - q) / b Position = Capital × Kelly% × Fraction × Min(Max_Position) 

Where:

• p = your model's probability estimate
• b = implied odds from market price
• Recommended: 25% Kelly (quarter Kelly) for safety

Ranks markets by exploitability using seven microstructure signals:

Score Interpretation:

• > 1.3: HIGH_OPPORTUNITY - deploy mean reversion strategy
• 0.8-1.3: MODERATE - use conservative sizing
• < 0.8: LOW/AVOID - skip or use momentum

Polypigeon includes a comprehensive paper trading system that simulates real trading conditions:

• Realistic fills: Orders fill based on actual order book depth
• Slippage modeling: Simulates market impact and execution slippage
• P&L tracking: Real-time profit/loss calculation
• Multiple bots: Run different strategies simultaneously
• Historical price charts: Real-time price history for all scanned markets

The system initializes with these default paper trading bots:

• Conservative market maker
• Aggressive edge detector
• Balanced portfolio bot

The backtesting engine supports walk-forward analysis:

cd backend python -m backtesting.engine --strategy market_making --days 30

Metrics calculated:

• Total return and Sharpe ratio
• Maximum drawdown
• Brier score (prediction accuracy)
• Win rate and profit factor

Important Considerations:

• US residents should wait for the CFTC-regulated Polymarket US platform
• Do not use VPN to access global Polymarket from restricted jurisdictions
• Automated trading IS allowed on Polymarket (official SDK provided)
• Consult a tax professional for your jurisdiction's reporting requirements
• This software is provided as-is for educational purposes

cd backend pytest tests/ -v

cd backend mypy app/

# Backend black app/ isort app/ # Frontend npm run lint

MIT License - see LICENSE for details.

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• GitHub Issues: Report bugs or request features
• Documentation: Check the algo.md file for detailed algorithm explanations

Built with ❤️ for the Polymarket trading community