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

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):

{
  "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

# 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

# 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:

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:

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.