This project provides a paper trading simulator for Polymarket, specifically designed for AI agents. It allows users to test trading strategies on real Polymarket order books with simulated funds, offering a zero-risk environment to track performance, backtest strategies, and compete on a leaderboard. The tool is beneficial for AI researchers and traders looking to validate strategies against live market conditions without financial risk.

How It Works

The simulator meticulously replicates Polymarket's exchange mechanics to ensure realistic trading conditions. It features level-by-level order book execution, accurately consuming liquidity at each price level. The exact fee model and slippage tracking are implemented, allowing paper trading P&L to closely mirror potential real-world P&L within the spread. It supports complex multi-outcome markets beyond simple binary YES/NO and includes a limit order state machine with Good-Til-Cancelled (GTC) and Good-Til-Date (GTD) capabilities.

Quick Start & Requirements

• Installation: Install via pip (pip install polymarket-paper-trader), ClawHub (npx clawhub install polymarket-paper-trader), or from source (uv pip install -e ".[dev]").
• Prerequisites: Requires Python 3.10+.
• Demo: A 60-second demo is available. Example strategies are provided in the examples/ directory.

Highlighted Details

• Provides 26 tools via the Model Context Protocol (MCP) server for AI agent integration.
• Supports strategy backtesting against historical price snapshots.
• Enables multi-account support for A/B testing different strategies.
• Generates shareable stats cards (for X/Twitter, Telegram/Discord) and leaderboard entries.
• Includes features for head-to-head strategy battles and comparisons.

Maintenance & Community

This project is part of agent-next, an open research lab for autonomous agents. Specific community links (e.g., Discord, Slack) are not detailed in the README.

Licensing & Compatibility

The project is released under the MIT license, which is permissive for commercial use and integration into closed-source projects.

Limitations & Caveats

This is a paper trading simulator and does not involve real money. It specifically simulates the Polymarket exchange and its associated mechanics. Live API integration tests require network connectivity.