# 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
```bash
npm run build
```

### 2. Run the Bot
```bash
npm start
```

### 3. Check Logs
```bash
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:
   ```bash
   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:

```bash
# 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