Polymarket Liquidity Bot

Educational bot for monitoring and responding to liquidity events on Polymarket prediction markets.

WARNING: This bot is for educational purposes only. Trading on prediction markets involves significant risk of financial loss. Never trade with funds you cannot afford to lose.

Features

• Real-time Market Monitoring: WebSocket-based order book and trade feed monitoring
• Liquidity Event Detection:
  • Thin order book depth detection
  • Price impact from large trades
  • Volume spike detection
  • Trade flow imbalance detection
• Automated Order Execution: Fast limit order placement with configurable strategies
• Market Discovery: Automatic discovery of low-liquidity markets via Gamma API
• Risk Management: Position limits, daily loss limits, and circuit breakers
• Simulation Mode: Test strategies without real trades

Architecture

┌─────────────────┐     ┌─────────────────┐
│ Market          │────▶│ WebSocket       │
│ Discoverer      │     │ Monitor         │
└─────────────────┘     └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │ Liquidity       │
                        │ Detector        │
                        └────────┬────────┘
                                 │ Signals
                                 ▼
                        ┌─────────────────┐
                        │ Order           │
                        │ Executor        │
                        └────────┬────────┘
                                 │
                                 ▼
                        ┌─────────────────┐
                        │ CLOB            │
                        │ Client          │
                        └─────────────────┘

Installation

1. Clone and setup:

   cd predictor
   python -m venv venv
   source venv/bin/activate  # or `venv\Scripts\activate` on Windows
   pip install -r requirements.txt

2. Configure:

   cp .env.example .env
   # Edit .env with your private key and settings

3. Run:

   python main.py --dry-run  # Test mode (recommended first)
   python main.py            # Live mode

Configuration

Environment Variables (.env)

Variable	Description	Default
PRIVATE_KEY	Ethereum private key (required)	-
DRY_RUN	Simulate trades without execution	true
DEFAULT_TRADE_SIZE	Default order size in USDC	50
MAX_DAILY_LOSS	Maximum daily loss limit	100
MIN_DEPTH_THRESHOLD	Thin depth trigger threshold	500
PRICE_IMPACT_THRESHOLD	Price impact % trigger	0.02

See .env.example for all options.

YAML Configuration (config.yaml)

Advanced settings for detection strategies, risk management, and execution parameters.

Detection Strategies

Thin Depth

Triggers when order book depth on one side falls below threshold.

• Suggests providing liquidity on the thin side
• Configurable depth levels and thresholds

Price Impact

Detects large trades causing significant price movement.

• Tracks recent price history
• Signals potential mean reversion opportunities

Volume Spike

Identifies unusual trading activity.

• Compares current volume to rolling average
• May indicate informed trading or news

Trade Imbalance

Monitors buy/sell volume ratio.

• Detects one-sided order flow
• Can signal short-term momentum

Usage Examples

Basic Run (Dry Run)

python main.py --dry-run --log-level INFO

Live Trading

# Make sure DRY_RUN=false in .env or:
python main.py  # Uses .env settings

Custom Configuration

python main.py --config my_config.yaml --env my.env

Simulation Mode

python -m src.simulator

Project Structure

predictor/
├── main.py                 # Main entry point
├── requirements.txt        # Python dependencies
├── config.yaml            # YAML configuration
├── .env.example           # Environment template
├── src/
│   ├── __init__.py
│   ├── config.py          # Configuration management
│   ├── models.py          # Data models
│   ├── clob_wrapper.py    # Polymarket CLOB client
│   ├── websocket_monitor.py # WebSocket handler
│   ├── detector.py        # Liquidity detection
│   ├── executor.py        # Order execution
│   ├── market_discoverer.py # Market discovery
│   ├── simulator.py       # Simulation mode
│   └── utils.py           # Utilities
├── tests/                 # Test files
├── data/                  # Data storage
└── logs/                  # Log files

Risk Warnings

1. Financial Risk: Prediction market trading can result in complete loss of funds
2. Technical Risk: Software bugs, network issues, or API changes can cause unexpected behavior
3. Regulatory Risk: Prediction markets may be restricted in your jurisdiction
4. Latency Risk: Other participants may have faster infrastructure
5. Liquidity Risk: Low-liquidity markets can have extreme price swings

Safety Features

• Dry Run Mode: Test without real orders
• Position Limits: Maximum exposure per market and total
• Daily Loss Limits: Automatic shutdown on excessive losses
• Circuit Breakers: Pause trading on consecutive losses
• Order Timeouts: Auto-cancel stale orders

Latency Considerations

Target latency: <200ms signal-to-order

Optimizations implemented:

• Async/await throughout
• WebSocket for real-time data
• Pre-computed order parameters
• Connection pooling
• Efficient data structures

Contributing

This is an educational project. Contributions welcome for:

• Bug fixes
• Documentation improvements
• New detection strategies
• Performance optimizations

Disclaimer

This software is provided "as is" without warranty. The authors are not responsible for any financial losses incurred through use of this software. Always understand the code before running it with real funds.

License

MIT License - See LICENSE file