trading_bot_v4/docs/guides/REENTRY_ANALYTICS_QUICKSTART.md

# Re-Entry Analytics System - Quick Setup Guide

## 🎯 What You Just Got

A smart validation system for manual Telegram trades that uses fresh TradingView data to prevent bad entries.

## 📊 How It Works

### 1. Data Collection (Automatic)
- Every trade signal from TradingView auto-caches metrics
- Cache expires after 5 minutes
- Includes: ATR, ADX, RSI, volume ratio, price position

### 2. Manual Trade Flow
```
You: "long sol"
  ↓
Bot checks /api/analytics/reentry-check
  ↓
✅ Fresh TradingView data (<5min old)?
   → Use real metrics, score quality
  ↓
⚠️ Stale/no data?
   → Use historical metrics, apply penalty
  ↓
Score >= 55? → Execute trade
Score < 55?  → Block (suggest --force)
  ↓
You: "long sol --force" → Override and execute
```

### 3. Performance Modifiers
- **-20 points**: Last 3 trades lost money (avgPnL < -5%)
- **+10 points**: Last 3 trades won (avgPnL > +5%, WR >= 66%)
- **-5 points**: Using stale data
- **-10 points**: No data available

## 🚀 Setup Steps

### Step 1: Deploy Updated Code
```bash
cd /home/icke/traderv4

# Build and restart
docker compose build trading-bot
docker compose up -d trading-bot

# Restart Telegram bot
docker compose restart telegram-bot
```

### Step 2: Create TradingView Market Data Alerts

For **each symbol** (SOL, ETH, BTC), create a separate alert:

**Alert Name:** "Market Data - SOL 5min"

**Condition:** 
```
ta.change(time("1"))
```
(Fires every bar close on 1-5min chart)

**Alert Message (JSON):**
```json
{
  "action": "market_data",
  "symbol": "{{ticker}}",
  "timeframe": "{{interval}}",
  "atr": {{ta.atr(14)}},
  "adx": {{ta.dmi(14, 14)}},
  "rsi": {{ta.rsi(14)}},
  "volumeRatio": {{volume / ta.sma(volume, 20)}},
  "pricePosition": {{(close - ta.lowest(low, 100)) / (ta.highest(high, 100) - ta.lowest(low, 100)) * 100}},
  "currentPrice": {{close}}
}
```

**Webhook URL:**
```
https://your-domain.com/api/trading/market-data
```

**Frequency:** Every 1-5 minutes (recommend 5min to save alert quota)

**Repeat for:** SOL-PERP, ETH-PERP, BTC-PERP

### Step 3: Test the System

```bash
# Check if market data endpoint is accessible
curl http://localhost:3001/api/trading/market-data

# Should return available symbols and cache data
```

### Step 4: Test via Telegram

```
You: "long sol"

✅ Analytics check passed (68/100)
Data: tradingview_real (23s old)
Proceeding with LONG SOL...

✅ OPENED LONG SOL
Entry: $162.45
Size: $2100.00 @ 10x
TP1: $162.97  TP2: $163.59  SL: $160.00
```

**Or if analytics blocks:**

```
You: "long sol"

🛑 Analytics suggest NOT entering LONG SOL

Reason: Recent long trades losing (-2.4% avg)
Score: 45/100
Data: ✅ tradingview_real (23s old)

Use `long sol --force` to override
```

**Override with --force:**

```
You: "long sol --force"

⚠️ Skipping analytics check...

✅ OPENED LONG SOL (FORCED)
Entry: $162.45
...
```

## 📊 View Cached Data

```bash
# Check what's in cache
curl http://localhost:3001/api/trading/market-data

# Response shows:
{
  "success": true,
  "availableSymbols": ["SOL-PERP", "ETH-PERP"],
  "count": 2,
  "cache": {
    "SOL-PERP": {
      "atr": 0.45,
      "adx": 32.1,
      "rsi": 58.3,
      "ageSeconds": 23
    }
  }
}
```

## 🔧 Configuration

### Adjust Thresholds (if needed)

Edit `app/api/analytics/reentry-check/route.ts`:

```typescript
const MIN_REENTRY_SCORE = 55  // Lower = more permissive

// Performance modifiers
if (last3Count >= 2 && avgPnL < -5) {
  finalScore -= 20  // Penalty for losing streak
}

if (last3Count >= 2 && avgPnL > 5 && winRate >= 66) {
  finalScore += 10  // Bonus for winning streak
}
```

### Cache Expiry

Edit `lib/trading/market-data-cache.ts`:

```typescript
private readonly MAX_AGE_MS = 5 * 60 * 1000 // 5 minutes
```

## 🎯 Benefits

✅ **Prevents revenge trading** - Blocks entry after consecutive losses  
✅ **Uses real data** - Fresh TradingView metrics, not guessed  
✅ **Data-driven** - Considers recent performance, not just current signal  
✅ **Override capability** - `--force` flag for manual judgment  
✅ **Fail-open** - If analytics fails, trade proceeds (not overly restrictive)  
✅ **Transparent** - Shows data age and source in responses  

## 📈 Next Steps

1. **Monitor effectiveness:**
   - Track how many trades are blocked
   - Compare win rate of allowed vs forced trades
   - Adjust thresholds based on data

2. **Add more symbols:**
   - Create market data alerts for any new symbols
   - System auto-adapts to new cache entries

3. **Phase 2 (Future):**
   - Time-based cooldown (no re-entry within 10min of exit)
   - Trend reversal detection (check if price crossed MA)
   - Volatility spike filter (ATR expansion = risky)

## 🐛 Troubleshooting

**No fresh data available:**
- Check TradingView alerts are firing
- Verify webhook URL is correct
- Check Docker logs: `docker logs -f trading-bot-v4`

**Analytics check fails:**
- Trade proceeds anyway (fail-open design)
- Check logs for error details
- Verify Prisma database connection

**--force always needed:**
- Lower MIN_REENTRY_SCORE threshold
- Check if TradingView alerts are updating cache
- Review penalty logic (may be too aggressive)

## 📝 Files Created/Modified

**New Files:**
- `lib/trading/market-data-cache.ts` - Cache service
- `app/api/trading/market-data/route.ts` - Webhook endpoint
- `app/api/analytics/reentry-check/route.ts` - Validation logic

**Modified Files:**
- `app/api/trading/execute/route.ts` - Auto-cache metrics
- `telegram_command_bot.py` - Pre-execution analytics check
- `.github/copilot-instructions.md` - Documentation

---

**Ready to use!** Send `long sol` in Telegram to test the system.