⚠️ DISCLAIMER: This is a TEST/DEMO PROJECTThis is research and educational software demonstrating autonomous AI trading concepts. NOT suitable for production use or real financial trading. Use for learning and testing only. No warranty provided.
An autonomous trading agent for Polymarket prediction markets, powered by Claude AI and multi-source data analysis.
Status: 🚀 MVP Phase (Foundation & Configuration) - Educational/Test Purpose
- ✅ Project structure & configuration management
- ✅ Claude Tool-Use integration (decision engine)
- 🔄 Multi-source data collection (Polls, Sports, Crypto, News)
- 🔄 Semi-autonomous execution with confidence thresholds
- 🔄 Memory system for trade history & performance tracking
- Phase 2: Full data collectors for all market categories
- Phase 3: Real-time Polymarket API integration
- Phase 4: Advanced risk management (Kelly Criterion)
- Phase 5: Backtesting framework
┌─────────────────────────────────────────────┐
│ DATA LAYER (Collectors) │
├─────────────────────────────────────────────┤
│ • Polls (FiveThirtyEight) │
│ • Sports (ESPN) │
│ • Crypto (Binance, Whale Alert) │
│ • News (NewsAPI, Twitter/X) │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ CLAUDE DECISION ENGINE (Tool-Use) │
├──────────────────────────────────────────────┤
│ • Sentiment Analysis │
│ • Expected Value Calculation │
│ • Risk Management │
│ • Arbitrage Detection │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ EXECUTION (Semi-Autonomous) │
├──────────────────────────────────────────────┤
│ IF confidence > 75% + size < $50: │
│ → AUTO-EXECUTE │
│ IF 60-75% confidence: │
│ → QUEUE FOR APPROVAL │
│ ELSE: │
│ → HUMAN REVIEW │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ MEMORY (Tracking & Performance) │
├──────────────────────────────────────────────┤
│ • Trade History │
│ • Win Rate by Category │
│ • Claude Calibration │
│ • Risk Metrics │
└──────────────────────────────────────────────┘
cd PolymarketAgent
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txtcp .env.example .env.local
# Edit .env.local with your API keys:
# - ANTHROPIC_API_KEY (Claude)
# - POLYMARKET credentials
# - WALLET address & PRIVATE_KEY
# - Data source APIs (NewsAPI, Twitter, etc.)python -m src.main- Anthropic Claude: https://console.anthropic.com (free tier available)
- Polymarket CLOB: https://clob.polymarket.com (free, only gas)
- News API: https://newsapi.org (free: 100 req/day)
- Twitter/X API v2: $100/month (Essential tier) for tweet analysis
- FiveThirtyEight: Free polls (read-only)
- ESPN API: Free sports data
- Pinnacle: Bookmaker odds API ($200-500/month)
| Category | Strategy | Target ROI | Risk |
|---|---|---|---|
| Politics | Polling + sentiment | +3-5% / week | 🟢 Low |
| Sports | Historical + injuries | +5-10% / week | 🟡 Medium |
| Crypto | Arbitrage + news | +2-4% / week | 🔴 High |
| Arbitrage | Cross-market spreads | +1-2% / week | 🟢 Low |
The agent uses Claude's tool-use capability to:
- Sentiment Analysis - Extract market signals from news/tweets
- Expected Value Calc - Compare market odds vs. model probability
- Risk Calculator - Determine position size (Kelly Criterion)
- Arbitrage Detection - Spot cross-market inefficiencies
Example decision flow:
Market: "Will Bitcoin exceed $50k by April 2026?"
Current odds: 0.38 (38% probability)
Claude thinks: 42% probability (based on data)
Edge: +4.2%
Confidence: 82%
Decision: BUY 0.38 odds (underpriced)
Position Size: $100 (1% of balance)
Key settings in .env.local:
# Risk Parameters
INITIAL_BALANCE=500 # Starting USDC
MAX_POSITION_SIZE=0.02 # 2% per trade
MIN_CONFIDENCE_AUTO=0.75 # Auto-execute threshold
MIN_CONFIDENCE_APPROVAL=0.60 # Needs human review
# Execution Mode
EXECUTION_MODE=APPROVAL # PAPER | APPROVAL | AUTOSee .env.example for all options.
polymarket-agent/
├── src/
│ ├── main.py # Entry point
│ ├── config.py # Configuration & constants
│ ├── data/
│ │ ├── collectors/ # Market data sources
│ │ └── datastore.py # Data caching
│ ├── agents/
│ │ ├── claude_agent.py # Decision engine (Tool-Use)
│ │ └── tools/ # Claude tools
│ ├── execution/
│ │ ├── executor.py # Trade executor
│ │ ├── polymarket_client.py
│ │ └── approval_queue.py
│ └── memory/
│ ├── trades_history.py
│ └── performance_tracker.py
├── tests/
├── logs/
├── .env.local # Your secrets (GITIGNORE)
├── .env.example # Template
└── requirements.txt
- This is NOT production software. This is a proof-of-concept for educational purposes only.
- Real financial risk: Do not use with real money, real private keys, or production accounts.
- For production deployment, you would need:
- Hardware security module (HSM) for key management
- Professional security audit
- Compliance review (securities regulation)
- Institutional-grade monitoring & alerting
- Insurance & liability coverage
- Never commit
.env.local(private key stored here!) - Use
.env.exampleas template only - Test in
PAPERmode first (simulated trades)
💡 Best Practices (For Learning):
- Start in
PAPERmode (simulation only) - Graduate to
APPROVAL(human review of each trade) - Only then move to
AUTO(fully automatic) - Never use real credentials or significant amounts while learning
Agent logs all trades to memory/:
trades_history.json- All trades with PnLcategory_performance.json- Win rate by market typeclaude_calibration.json- Confidence accuracy metrics
# View performance
python -c "from src.memory import PerformanceTracker; \
p = PerformanceTracker(); p.print_summary()"pytest tests/ -v
pytest tests/ --cov=src # Coverage reportCurrent contributors: 1 Focus area: Core agent loop & Claude integration
This project is licensed under the MIT License - see LICENSE file for details.
All use is strictly for educational and testing purposes only.
- ✅ Phase 1 (NOW): Configure & validate API connections
- 🔄 Phase 2: Build data collectors
- 🔄 Phase 3: Claude decision engine
- 🔄 Phase 4: Trade execution
- 🔄 Phase 5: Memory & performance tracking
Let's get this agent trading! 🚀