PolyAgent - Polymarket Trading Bot

A production-ready, modular trading bot for Polymarket prediction markets with a modern React dashboard and real-time WebSocket updates.

Quick Start

# 1. Clone and setup Python environment
cd PolyAgent
pip install -r requirements.txt

# 2. Start the backend API server
python -m src.api_server

# 3. In a new terminal, start the frontend dashboard
cd frontend
npm install
npm run dev

# 4. Open http://localhost:3000 and create your first bot!

Features

Trading Engine

Feature	Description
Real-Time WebSocket	Sub-second price updates via Polymarket WebSocket API (`wss://ws-subscriptions-clob.polymarket.com/ws/market`)
Multi-Window Spike Detection	Analyzes price spikes over configurable 10/30/60 minute windows
Volatility Filtering	Reduces false signals using coefficient of variation analysis
Spike Sam Strategy	Fade spikes - BUY on downward spikes, SELL on upward spikes
Train of Trade	Sequential target-based trading with automatic rebuy after sells
Dual Signature Modes	Support for EOA (SIGNATURE_TYPE=0) and Gnosis Proxy (SIGNATURE_TYPE=2)
Risk Controls	Take Profit, Stop Loss, Max Hold Time, Cooldown, Trade Size Limits
P&L Tracking	Realized P&L with win rate statistics, persisted to disk
State Persistence	Crash recovery via `data/position.json` and `data/bots/*.json`
Settlement Verification	Optional User WebSocket for real-time order status confirmation
Polymarket Pricing Logic	Uses official pricing: midpoint if spread ≤ $0.10, last trade price otherwise

Web Dashboard

Feature	Description
Multi-Bot Management	Create, start, stop, delete, and monitor multiple independent bots
Real-Time Updates	WebSocket-powered live price, position, activity, and target updates
Interactive Price Chart	Recharts-based chart with target lines, entry/exit markers, and live updates
Position Tracking	Live P&L, entry/exit prices, hold time, TP/SL visualization
Activity Feed	Filterable real-time feed of spikes, orders, fills, P&L, and system events
Settings Panel	Global settings, killswitch, slippage, liquidity requirements
Market Metrics	Spread, liquidity depth, bid/ask visualization
Trading Profiles	Pre-configured profiles: Normal, Live, Edge, Ultra-Conservative
Dark/Light Themes	Modern UI with theme toggle support
Responsive Design	Works on desktop and tablet viewports

Architecture

PolyAgent uses a fully decoupled architecture where the backend API server and frontend dashboard are independent.

┌─────────────────────────────────────────────────────────────────────────────┐
│                              PolyAgent System                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─── Frontend (Next.js 16) ───────────────────────────────────────────┐    │
│  │                                                                     │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌────────────┐  │    │
│  │  │   Bot       │  │   Price     │  │  Activity   │  │  Settings  │  │    │
│  │  │  Manager    │  │   Chart     │  │    Feed     │  │   Panel    │  │    │
│  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └─────┬──────┘  │    │
│  │         │                │                │               │         │    │
│  │         └────────────────┴────────────────┴───────────────┘         │    │
│  │                                   │                                 │    │
│  │                    ┌──────────────┴──────────────┐                  │    │
│  │                    │    BotStateContext (React)   │                 │    │
│  │                    │    WebSocket Connection      │                 │    │
│  │                    └──────────────┬──────────────┘                  │    │
│  └───────────────────────────────────┼─────────────────────────────────┘    │
│                                      │                                      │
│                           WebSocket (ws://localhost:8000)                   │
│                           REST API (http://localhost:8000)                  │
│                                      │                                      │
│  ┌─── Backend (FastAPI + Python) ────┼──────────────────────────────────┐   │
│  │                                   │                                  │   │
│  │                    ┌──────────────┴──────────────┐                   │   │
│  │                    │     API Server (FastAPI)    │                   │   │
│  │                    │     - REST Endpoints        │                   │   │
│  │                    │     - WebSocket Broadcast   │                   │   │
│  │                    │     - CORS Handling         │                   │   │
│  │                    └──────────────┬──────────────┘                   │   │
│  │                                   │                                  │   │
│  │         ┌─────────────────────────┼─────────────────────────┐        │   │
│  │         │                         │                         │        │   │
│  │  ┌──────┴──────┐          ┌───────┴───────┐         ┌───────┴──────┐ │   │
│  │  │ BotSession  │          │  BotSession   │         │  BotSession  │ │   │
│  │  │   (Bot 1)   │          │    (Bot 2)    │         │    (Bot N)   │ │   │
│  │  │  ┌───────┐  │          │  ┌───────┐    │         │  ┌───────┐   │ │   │
│  │  │  │ Bot   │  │          │  │ Bot   │    │         │  │ Bot   │   │ │   │
│  │  │  │Engine │  │          │  │Engine │    │         │  │Engine │   │ │   │
│  │  │  └───┬───┘  │          │  └───┬───┘    │         │  └───┬───┘   │ │   │
│  │  │      │      │          │      │        │         │      │       │ │   │
│  │  │  ┌───┴───┐  │          │  ┌───┴───┐    │         │  ┌───┴───┐   │ │   │
│  │  │  │ CLOB  │  │          │  │ CLOB  │    │         │  │ CLOB  │   │ │   │
│  │  │  │Client │  │          │  │Client │    │         │  │Client │   │ │   │
│  │  │  └───────┘  │          │  └───────┘    │         │  └───────┘   │ │   │
│  │  └─────────────┘          └───────────────┘         └──────────────┘ │   │
│  │                                                                      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│                           Polymarket APIs (External)                        │
│                                      │                                      │
│       ┌──────────────────────────────┼──────────────────────────────┐       │
│       │                              │                              │       │
│  ┌────┴─────┐              ┌─────────┴─────────┐            ┌───────┴─────┐ │
│  │ CLOB API │              │ WebSocket Market  │            │  Gamma API  │ │
│  │  (REST)  │              │   Price Updates   │            │  (Markets)  │ │
│  └──────────┘              └───────────────────┘            └─────────────┘ │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Core Components

Component	File	Purpose
API Server	`src/api_server.py`	FastAPI server exposing REST + WebSocket endpoints
Bot Session	`src/bot_session.py`	Isolated bot instance with own config, wallet, market
Bot Engine	`src/bot.py`	Core trading logic, spike detection, strategy execution
CLOB Client	`src/clob_client.py`	Polymarket py-clob-client wrapper with helpers
Config	`src/config.py`	Typed configuration with validation and trading profiles
WebSocket Client	`src/websocket_client.py`	Real-time market data from Polymarket
User WebSocket	`src/user_websocket_client.py`	Authenticated user channel for order status
Crypto	`src/crypto.py`	Fernet encryption for sensitive data (private keys)
Multi-Bot Manager	`src/multi_bot_manager.py`	Legacy multi-bot management (deprecated)
Train Bot	`src/train_bot.py`	Train-of-trade strategy implementation

Frontend Components

Component	File	Purpose
Main Page	`frontend/app/page.tsx`	Dashboard entry point
BotStateContext	`frontend/contexts/bot-state-context.tsx`	Global state management with WebSocket
Bot Manager Panel	`frontend/components/panels/bot-manager-panel.tsx`	Bot CRUD, configuration, and controls
Price Chart	`frontend/components/panels/price-chart.tsx`	Interactive Recharts price chart
Activity Feed	`frontend/components/panels/activity-feed.tsx`	Real-time activity log
Position Card	`frontend/components/panels/position-card.tsx`	Current position details
Settings Panel	`frontend/components/settings-panel.tsx`	Global settings management

Installation

Prerequisites

Python 3.10+ with pip
Node.js 18+ with npm
Polygon Wallet with USDC.e and small MATIC for gas
Polymarket Account (optional: generate API keys for User WebSocket)

Backend Setup

# Navigate to project root
cd PolyAgent

# Create virtual environment (recommended)
python -m venv venv
venv\Scripts\activate  # Windows
source venv/bin/activate  # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Verify installation
python scripts/check_setup.py

Frontend Setup

cd frontend

# Install dependencies
npm install

# Create local environment (optional, for custom API URL)
cp .env.local.example .env.local

Required Python Packages

py-clob-client>=0.18.0   # Polymarket SDK
fastapi>=0.115.0         # API framework
uvicorn>=0.34.0          # ASGI server
websockets>=13.0         # WebSocket client
cryptography>=44.0       # Encryption
python-dotenv>=1.0.0     # Environment variables
pytest>=8.3.0            # Testing

Web Dashboard

Starting the Dashboard

# Terminal 1: Start backend API (port 8000)
python -m src.api_server

# Terminal 2: Start frontend (port 3000)
cd frontend && npm run dev

# Open http://localhost:3000

Dashboard Features

Bot Manager Panel

Create Bot: Configure wallet, market, strategy, and risk parameters
Trading Profiles: Choose from Normal, Live, Edge, or Ultra-Conservative
Start/Stop/Pause: Control individual bot instances
Delete: Remove bot and its configuration

Price Chart

Live Price Line: Real-time price with color-coded movements
Target Lines: Buy/Sell targets for Train of Trade strategy
Entry Markers: Entry price shown with horizontal line
Trade Markers: Visual dots for executed trades
Timeframe Selection: 1H, 4H, 1D views

Position Card

Entry Price: Price at which position was opened
Current P&L: Unrealized profit/loss in % and USD
Hold Time: Time since position opened
TP/SL Progress: Visual progress bars to targets

Activity Feed

Filters: Spikes, Orders, Fills, Exits, P&L, Errors, System
Real-Time Updates: Instant updates via WebSocket
Auto-Scroll: Optional auto-scroll to latest activity

Settings Panel

Global Settings: Slippage, min liquidity, tick interval
Killswitch: Emergency stop all bots
Daily Loss Limit: Auto-pause on reaching limit
Persistence: Settings saved to data/settings.json

Configuration

No More .env Files!

All configuration is now managed through the frontend UI. When you create a bot, you configure:

Wallet Settings (Per Bot)

Setting	Description
`private_key`	64-character hex string (without 0x prefix)
`signature_type`	0 = EOA (direct), 2 = Gnosis Proxy
`funder_address`	Required only for Proxy mode

Market Settings (Per Bot)

Setting	Description
`market_slug`	URL slug from polymarket.com
`market_token_id`	Direct token ID (alternative to slug)
`market_index`	Which outcome to trade (0=YES, 1=NO)

Strategy Settings (Per Bot)

Setting	Default	Description
`spike_threshold_pct`	3.0	Minimum % change to detect spike
`take_profit_pct`	5.0	Exit when profit reaches this %
`stop_loss_pct`	3.0	Exit when loss reaches this %
`trade_size_usd`	5.0	Amount per trade in USD
`max_hold_seconds`	3600	Maximum position hold time
`cooldown_sec`	120	Seconds between trades
`dry_run`	true	Simulate trades (no real orders)

Trading Profiles

Profile	Spike Threshold	Take Profit	Stop Loss	Trade Size
Normal	3.0%	5.0%	3.0%	$5.00
Live	2.5%	4.0%	2.5%	$10.00
Edge	1.5%	2.5%	1.5%	$20.00
Ultra-Conservative	5.0%	10.0%	5.0%	$1.00

Configuration Storage

data/
├── bots/                    # Bot configurations (encrypted)
│   ├── bot_abc123.json
│   └── bot_def456.json
├── settings.json            # Global settings
├── .encryption_key          # Fernet encryption salt
└── position.json            # Legacy position backup

Trading Strategies

Spike Sam Strategy (Default)

The bot "fades" price spikes - betting they will reverse:

Detect Spike: Price moves more than spike_threshold_pct over time windows
Direction Analysis:
- Downward spike → BUY (expect bounce back up)
- Upward spike → SELL (expect reversion down)
Risk Controls: Apply TP/SL/time-based exits

Price drops 5% suddenly
  → Bot detects downward spike
  → Places BUY order
  → Sets Take Profit at +5%
  → Either hits TP or SL exits position

Train of Trade Strategy

Sequential target-based trading that runs continuously:

Initial State: Set BUY target below current price
Buy Trigger: When price drops to target, BUY
Sell Target: Set target above entry (entry × (1 + take_profit_pct))
Sell Trigger: When price rises to target, SELL
Repeat: Set new BUY target, continue cycle

# Cycle illustration:
# Price: $0.50 → Set BUY target at $0.485 (−3%)
# Price drops to $0.485 → BUY triggered
# Set SELL target at $0.509 (entry × 1.05)
# Price rises to $0.509 → SELL triggered (+5% profit)
# Set new BUY target at $0.494 (−3%)
# Repeat...

Multi-Window Spike Detection

Analyzes price changes over multiple time windows:

# Default windows: 10, 30, 60 minutes
# For each window:
#   1. Get prices from that window
#   2. Calculate % change from oldest to current
#   3. Check coefficient of variation (volatility filter)
#   4. Take maximum spike across all windows

API Reference

REST Endpoints

All endpoints are served from http://localhost:8000.

Bot Management

Method	Endpoint	Description
`GET`	`/api/bots`	List all bots with status
`POST`	`/api/bots`	Create new bot
`GET`	`/api/bots/{id}`	Get bot details
`PUT`	`/api/bots/{id}`	Update bot config
`DELETE`	`/api/bots/{id}`	Delete bot
`POST`	`/api/bots/{id}/start`	Start bot
`POST`	`/api/bots/{id}/stop`	Stop bot
`POST`	`/api/bots/{id}/trade`	Execute manual trade
`POST`	`/api/bots/{id}/close`	Close position
`GET`	`/api/bots/{id}/activities`	Get activity log
`GET`	`/api/bots/{id}/chart-data`	Get price chart data

Market Data

Method	Endpoint	Description
`GET`	`/api/markets/{slug}`	Get market info
`GET`	`/api/prices/{token_id}`	Get current price
`GET`	`/api/orderbook/{token_id}`	Get orderbook

Settings

Method	Endpoint	Description
`GET`	`/api/settings`	Get global settings
`POST`	`/api/settings`	Update global settings
`GET`	`/api/profiles`	List trading profiles

WebSocket Events

Connect to ws://localhost:8000/ws for real-time updates.

Incoming Events (Server → Client)

// Price update
{ type: "price", bot_id: "xxx", price: 0.55, timestamp: "..." }

// Position update
{ type: "position", bot_id: "xxx", position: {...} }

// Spike detected
{ type: "spike", bot_id: "xxx", spike_pct: 3.5, direction: "down" }

// Activity
{ type: "activity", bot_id: "xxx", activity_type: "order", message: "..." }

// Target update (Train of Trade)
{ type: "target", bot_id: "xxx", target_price: 0.52, action: "buy" }

// Error
{ type: "error", bot_id: "xxx", error: "..." }

Scripts & Utilities

Located in scripts/ directory:

Script	Purpose
`check_setup.py`	Verify wallet, credentials, and configuration
`check_status.py`	Check current positions and balances
`check_orderbook.py`	Display orderbook for configured market
`check_spreads.py`	Analyze bid-ask spreads
`easy_setup.py`	Interactive setup wizard
`approve_usdc.py`	Approve USDC.e for EOA trading
`approve_usdc_gnosis.py`	Approve USDC.e for Proxy trading
`find_best_market.py`	Find markets with good liquidity
`find_tradeable_market.py`	Find active tradeable markets
`get_market_from_url.py`	Extract token ID from Polymarket URL
`compare_prices.py`	Compare prices from different sources
`manual_trade.py`	Execute manual test trades
`sell_all_positions.py`	Emergency: sell all positions
`test_full_cycle.py`	Test complete buy→hold→sell cycle
`test_live_trade.py`	Test live trading (small amounts)
`poly_tools.py`	Various Polymarket utility functions

Usage Examples

# Check your setup
python scripts/check_setup.py

# Find a liquid market to trade
python scripts/find_best_market.py

# Test a trade cycle
python scripts/test_full_cycle.py

# Emergency: close all positions
python scripts/sell_all_positions.py

Testing

Backend Tests (pytest)

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_trading_cycle.py -v

# Run with coverage
pytest tests/ --cov=src --cov-report=html

Test Files

Test File	Coverage
`test_end_to_end.py`	Full trading flow
`test_trading_cycle.py`	Buy→Sell cycle logic
`test_midprice_and_spike.py`	Price calculation and spike detection
`test_websocket_callbacks.py`	WebSocket event handling
`test_rebuy_config.py`	Rebuy strategy configuration
`test_runtime_state.py`	State persistence
`test_market_endpoints.py`	API endpoint testing

Frontend Tests (Playwright)

cd frontend

# Run all E2E tests
npm run test:e2e

# Run with UI mode
npm run test:e2e:ui

# Run with visible browser
npm run test:e2e:headed

Operations Guide

Starting Everything

# 1. Start API server (keep running)
python -m src.api_server

# 2. Start frontend (keep running)
cd frontend && npm run dev

# 3. Access dashboard at http://localhost:3000

Creating Your First Bot

Click "Create Bot" in the Bot Manager Panel
Enter bot name and description
Paste your private key (64 hex characters, no 0x prefix)
Choose signature type (EOA for most users)
Enter market slug from Polymarket URL
Select a trading profile or customize settings
Enable Dry Run for testing
Click Create Bot

Going Live

Verify setup with dry run trades
Monitor bot for expected behavior
Edit bot configuration
Set Dry Run: false
Start with small amounts ($1-5)
Monitor continuously initially

Emergency Stop

Dashboard: Click the Killswitch button in Settings
Individual Bot: Click Stop button for that bot
Terminal: Ctrl+C to stop the API server
Script: python scripts/sell_all_positions.py

Monitoring

Dashboard: Real-time activity feed, price chart, P&L
API Logs: Check the terminal running api_server.py
Position State: Check data/bots/*.json

Troubleshooting

Common Issues

Issue	Solution
"No balance/allowance"	Approve USDC.e: `python scripts/approve_usdc.py`
"Token not found"	Check market slug or use token ID directly
"Order failed"	Check spread, liquidity; market might be thin
"WebSocket disconnected"	Normal reconnection happens automatically
"Encryption error"	Delete `data/.encryption_key` and recreate bots
"CORS error"	Ensure API runs on port 8000, frontend on 3000
"No price available"	Check if market is active and has trades

Checking Setup

# Full diagnostic
python scripts/check_setup.py

# Check wallet balance
python scripts/check_status.py

# Test market connection
python scripts/check_orderbook.py

Logs

The API server logs to stdout. Key log patterns:

INFO:     [BOT_abc123] Price: 0.55 | Target: SELL @ 0.58
INFO:     [TRADE] Executing BUY $5.00
INFO:     [ORDER] Filled: BUY $5.00 @ 0.52
WARNING:  [RISK] Stop loss triggered at -3.2%

Security

Private Key Protection

Private keys are encrypted using Fernet symmetric encryption
Encryption key derived from machine-specific data (user + home path)
Salt stored in data/.encryption_key
Only works on the machine where bot was created

Best Practices

Use a dedicated trading wallet - Never use your main wallet
Fund with small amounts - Only what you're willing to lose
Start with dry run - Test thoroughly before live trading
Secure data/ folder - Contains encrypted private keys
Don't commit .env or data/ - Already in .gitignore

File Permissions

# Restrict key file (Linux/Mac)
chmod 600 data/.encryption_key

# Restrict bot configs
chmod 600 data/bots/*

Project Structure

PolyAgent/
├── src/                       # Python backend
│   ├── api_server.py          # FastAPI server
│   ├── bot.py                 # Bot engine
│   ├── bot_session.py         # Isolated bot sessions
│   ├── clob_client.py         # Polymarket client
│   ├── config.py              # Configuration
│   ├── crypto.py              # Encryption utilities
│   ├── multi_bot_manager.py   # Legacy multi-bot
│   ├── train_bot.py           # Train strategy
│   ├── websocket_client.py    # Market WebSocket
│   └── user_websocket_client.py # User channel
│
├── frontend/                  # Next.js frontend
│   ├── app/                   # Next.js app router
│   ├── components/            # React components
│   │   ├── panels/            # Dashboard panels
│   │   └── ui/                # UI primitives (shadcn)
│   ├── contexts/              # React contexts
│   └── hooks/                 # Custom hooks
│
├── scripts/                   # CLI utilities
├── tests/                     # Python tests
├── data/                      # Runtime data
│   ├── bots/                  # Bot configs
│   └── settings.json          # Global settings
│
├── docs/                      # Documentation
│   ├── ARCHITECTURE.md        # System architecture
│   └── NOOB_GUIDE.md          # Beginner's guide
│
|
├── requirements.txt           # Python dependencies
├── conftest.py                # Pytest configuration
└── README.md                  # This file

Additional Documentation

Architecture Guide - Deep dive into system design
Beginner's Guide - Step-by-step for new users

Acknowledgments

Polymarket - The prediction market platform
py-clob-client - Official Python SDK
FastAPI - Modern API framework
Next.js - React framework
shadcn/ui - UI component library
Recharts - Charting library

Disclaimer

Trading on prediction markets involves significant risk. You can lose your entire investment. This software is provided "as is" without warranty. The authors are not responsible for any financial losses incurred. Only trade with funds you can afford to lose.

Happy Trading!

Made with ❤️ for the Polymarket community

Name		Name	Last commit message	Last commit date
Latest commit History 59 Commits
docs		docs
frontend		frontend
logs		logs
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
conftest.py		conftest.py
pytest.ini		pytest.ini
requirements.txt		requirements.txt
start_api_server.py		start_api_server.py
start_bot.py		start_bot.py

Folders and files

Latest commit

History

Repository files navigation

PolyAgent - Polymarket Trading Bot

Quick Start

Table of Contents

Features

Trading Engine

Web Dashboard

Architecture

Core Components

Frontend Components

Installation

Prerequisites

Backend Setup

Frontend Setup

Required Python Packages

Web Dashboard

Starting the Dashboard

Dashboard Features

Bot Manager Panel

Price Chart

Position Card

Activity Feed

Settings Panel

Configuration

No More .env Files!

Wallet Settings (Per Bot)

Market Settings (Per Bot)

Strategy Settings (Per Bot)

Trading Profiles

Configuration Storage

Trading Strategies

Spike Sam Strategy (Default)

Train of Trade Strategy

Multi-Window Spike Detection

API Reference

REST Endpoints

Bot Management

Market Data

Settings

WebSocket Events

Incoming Events (Server → Client)

Scripts & Utilities

Usage Examples

Testing

Backend Tests (pytest)

Test Files

Frontend Tests (Playwright)

Operations Guide

Starting Everything

Creating Your First Bot

Going Live

Emergency Stop

Monitoring

Troubleshooting

Common Issues

Checking Setup

Logs

Security

Private Key Protection

Best Practices

File Permissions

Project Structure

Additional Documentation

Acknowledgments

Disclaimer

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Packages