Polymarket_Copy_Bot/.context/README.md

Polymarket Copy Trading Bot - Context Documentation

This folder contains comprehensive documentation about the Polymarket Copy Trading Bot project.

📋 Documents

1. PROJECT_OVERVIEW.md (Main Reference)

Complete architectural overview of the entire project including:

• Project structure and file organization
• All 12 core components with detailed descriptions
• Configuration guide
• Trade execution flow diagram
• Key metrics and current state
• Bug fixes applied

Best for: Understanding how the bot works, architecture decisions, component interactions

2. FIXES_APPLIED.md (Recent Changes)

Detailed documentation of all fixes applied to the bot:

• Fix #1: DOWN orders not showing in TUI (panel overflow)
• Fix #2: Window summary showing order count instead of total shares
• Fix #3: Missing API pagination (only fetching first 100 trades)

Includes before/after code, root cause analysis, and verification steps.

Best for: Understanding what was fixed, why, and how the changes work

🎯 Quick Start

1. Rebuild the Project

npm run build

2. Run the Bot

npm start

3. Check Logs

tail -f bot.log

📊 Key Improvements Made

Issue	Status	File	Impact
DOWN orders not visible in TUI	✅ Fixed	src/tui-dashboard.ts	Now displays both UP and DOWN
Window summary shows order count	✅ Fixed	src/storage.ts	Now shows total shares
Missing API pagination	✅ Fixed	src/account-monitor.ts	Now fetches ALL trades
Rate limiting missing	✅ Added	src/account-monitor.ts	Prevents API throttling
Error handling weak	✅ Improved	src/account-monitor.ts	Exponential backoff added

🔧 Files Modified

1. src/tui-dashboard.ts - Fixed window panel overflow
2. src/storage.ts - Changed to sum shares instead of counting orders
3. src/account-monitor.ts - Added pagination, rate limiting, error handling
4. .context/PROJECT_OVERVIEW.md - Updated documentation
5. .context/FIXES_APPLIED.md - Detailed fix documentation

📈 Current Status

✅ Compilation: Successful
✅ Pagination: Implemented
✅ Rate Limiting: Implemented
✅ Error Handling: Robust
✅ TUI Display: Fixed
✅ Data Accuracy: Complete

🚀 Next Steps

1. Monitor logs after deployment:

   tail -f bot.log | grep -E "Total trades fetched|Down|Window"
   

2. Verify TUI displays:

   • Both UP and DOWN values should be visible
   • Numbers should be total shares, not order counts
   • No content should be cut off

3. Adjust poll interval if needed:

   • Current: 5000ms (5 seconds between full fetches)
   • If you have many trades, may need to increase to 10000ms

4. Monitor API errors:

   • Watch for backoff messages in logs
   • Indicates API rate limiting issues

📝 Configuration

Key environment variables:

# Trade monitoring
POLL_INTERVAL_MS=5000          # Time between API polls
FILTER_BTC_15M_ONLY=true       # Only 15-min Bitcoin markets

# Bot behavior
EXECUTE_TRADES_ENABLED=false   # Dry-run mode (set to true to execute)
MATCH_EXACT_AMOUNT=false       # Use volume ratio vs exact matching

# UI
USE_TUI=true                   # Enable terminal UI dashboard

📚 Architecture Overview

┌─ Account Monitor (REST polling with pagination)
│  └─ API calls with limit/offset for all trades
├─ Storage Layer (SQLite with 15-min aggregation)
│  └─ Persists trades with outcome/share totals
├─ Market Detector (15-min Bitcoin market identification)
│  └─ Filters markets by type and time
├─ Trade Copier (Volume ratio calculations)
│  └─ Sizes trades based on account balance ratio
├─ Trade Executor (CLOB API order placement)
│  └─ Places limit orders on Polymarket
└─ TUI Dashboard (Terminal UI visualization)
   └─ Real-time monitoring of all activity

🐛 Known Limitations

1. Initial Fetch: First poll fetches ALL historical trades (may take time)
2. Rate Limiting: API may throttle if too many requests
3. Window Size: Shows current + previous window (30 minutes)

💡 Troubleshooting

"Fetched 100 trades" - stuck at same number?

• Old build - rebuild with npm run build

DOWN orders still not showing?

• Restart bot: npm start
• Check terminal height is sufficient

API errors in logs?

• Automatic backoff after 5 errors (30 seconds)
• Check API rate limits

📞 Support

Refer to:

1. PROJECT_OVERVIEW.md - Component documentation
2. FIXES_APPLIED.md - Fix details
3. bot.log - Runtime logs
4. trades.db - Historical data

---

Last Updated: 2025-12-06 All Fixes Applied: ✅ Build Status: ✅ Successful