docs: Add comprehensive Smart Entry Timing status documentation
This commit is contained in:
mindesbunister
376
SMART_ENTRY_TIMING_STATUS.md
Normal file
376
SMART_ENTRY_TIMING_STATUS.md
Normal file
@@ -0,0 +1,376 @@
|
|||||||
|
# Smart Entry Timing - Implementation Status
|
||||||
|
|
||||||
|
## ✅ PHASE 2 IMPLEMENTATION COMPLETE
|
||||||
|
|
||||||
|
**Date:** November 26, 2025
|
||||||
|
**Status:** Code complete, TypeScript compilation clean (0 errors)
|
||||||
|
**Expected Value:** $1,600-4,000 improvement over 100 trades (0.2-0.5% per trade)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Summary
|
||||||
|
|
||||||
|
### Core Service: `lib/trading/smart-entry-timer.ts` (616 lines)
|
||||||
|
|
||||||
|
**Architecture:**
|
||||||
|
- Singleton pattern via `getSmartEntryTimer()` getter
|
||||||
|
- Queue-based signal management (Map of QueuedSignal objects)
|
||||||
|
- Monitoring loop runs every 15 seconds when queue active
|
||||||
|
- Automatic cleanup of expired/executed signals
|
||||||
|
|
||||||
|
**Key Features:**
|
||||||
|
|
||||||
|
1. **Queue Management**
|
||||||
|
- `queueSignal(signalData)` - Adds signal to queue with pullback targets
|
||||||
|
- `startMonitoring()` - Begins 15s interval checks
|
||||||
|
- `stopMonitoring()` - Stops when queue empty
|
||||||
|
- `getQueueStatus()` - Debug/monitoring endpoint
|
||||||
|
|
||||||
|
2. **Smart Entry Logic**
|
||||||
|
- LONG: Wait for 0.15-0.5% dip below signal price
|
||||||
|
- SHORT: Wait for 0.15-0.5% bounce above signal price
|
||||||
|
- ADX validation: Trend strength hasn't degraded >2 points
|
||||||
|
- Timeout: 2 minutes → execute at current price regardless
|
||||||
|
|
||||||
|
3. **Execution Flow**
|
||||||
|
- Gets fresh market data from cache (1-min updates)
|
||||||
|
- Gets real-time price from Pyth oracle
|
||||||
|
- Calculates pullback magnitude
|
||||||
|
- Validates ADX via fresh TradingView data
|
||||||
|
- Opens position via Drift SDK
|
||||||
|
- Places ATR-based exit orders (TP1/TP2/SL)
|
||||||
|
- Saves to database with smart entry metadata
|
||||||
|
- Adds to Position Manager for monitoring
|
||||||
|
|
||||||
|
4. **Configuration** (.env variables)
|
||||||
|
```bash
|
||||||
|
SMART_ENTRY_ENABLED=false # Disabled by default
|
||||||
|
SMART_ENTRY_MAX_WAIT_MS=120000 # 2 minutes
|
||||||
|
SMART_ENTRY_PULLBACK_MIN=0.15 # 0.15% minimum
|
||||||
|
SMART_ENTRY_PULLBACK_MAX=0.50 # 0.50% maximum
|
||||||
|
SMART_ENTRY_ADX_TOLERANCE=2 # 2 points max drop
|
||||||
|
```
|
||||||
|
|
||||||
|
### Integration: `app/api/trading/execute/route.ts`
|
||||||
|
|
||||||
|
**Smart Entry Decision Tree** (lines 422-478):
|
||||||
|
```
|
||||||
|
Signal arrives → Check if smart entry enabled
|
||||||
|
↓ NO: Execute immediately (existing flow)
|
||||||
|
↓ YES: Get current price from Pyth
|
||||||
|
↓ Calculate pullback from signal price
|
||||||
|
↓ Already at favorable level? (0.15-0.5% pullback achieved)
|
||||||
|
↓ YES: Execute immediately
|
||||||
|
↓ NO: Queue signal for monitoring
|
||||||
|
↓ Return HTTP 200 to n8n (workflow continues)
|
||||||
|
↓ Background monitoring every 15s
|
||||||
|
↓ Execute when:
|
||||||
|
- Pullback target hit + ADX valid
|
||||||
|
- OR timeout (2 minutes)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Behaviors:**
|
||||||
|
- Preserves existing immediate execution when smart entry disabled
|
||||||
|
- Returns success to n8n even when queued (workflow completes)
|
||||||
|
- No blocking waits - fully asynchronous monitoring
|
||||||
|
- Works with both 5-minute signals (production) and multi-timeframe data collection
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Database Tracking
|
||||||
|
|
||||||
|
**Smart Entry Metadata** (saved in `configSnapshot.smartEntry`):
|
||||||
|
```typescript
|
||||||
|
{
|
||||||
|
used: boolean, // Was smart entry used?
|
||||||
|
improvement: number, // % improvement (positive = better entry)
|
||||||
|
waitTime: number, // Seconds waited before execution
|
||||||
|
reason: string, // 'pullback_confirmed' | 'timeout' | 'manual_override'
|
||||||
|
checksPerformed: number // How many 15s checks ran
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Purpose:** Enable post-trade analysis to measure actual improvement vs immediate entry.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Testing Plan
|
||||||
|
|
||||||
|
### Phase 1: TypeScript Compilation ✅
|
||||||
|
- [x] Zero TypeScript errors
|
||||||
|
- [x] All interfaces correctly matched
|
||||||
|
- [x] Dependencies properly imported
|
||||||
|
- [x] Git committed and pushed
|
||||||
|
|
||||||
|
### Phase 2: Development Testing (TODO)
|
||||||
|
1. **Enable smart entry:**
|
||||||
|
```bash
|
||||||
|
echo "SMART_ENTRY_ENABLED=true" >> .env
|
||||||
|
docker restart trading-bot-v4
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Send test signal via n8n or manual API:**
|
||||||
|
```bash
|
||||||
|
curl -X POST http://localhost:3001/api/trading/execute \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-H "Authorization: Bearer $API_SECRET_KEY" \
|
||||||
|
-d '{
|
||||||
|
"symbol": "SOL-PERP",
|
||||||
|
"direction": "long",
|
||||||
|
"signalPrice": 142.50,
|
||||||
|
"atr": 0.43,
|
||||||
|
"adx": 26,
|
||||||
|
"rsi": 58,
|
||||||
|
"volumeRatio": 1.2,
|
||||||
|
"pricePosition": 45,
|
||||||
|
"qualityScore": 95
|
||||||
|
}'
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Verify logs:**
|
||||||
|
```bash
|
||||||
|
docker logs -f trading-bot-v4 | grep "Smart Entry"
|
||||||
|
```
|
||||||
|
Expected log sequence:
|
||||||
|
- `📥 Smart Entry: Queued signal SOL-PERP-{timestamp}`
|
||||||
|
- `🔍 Smart Entry: Checking 1 queued signals...`
|
||||||
|
- `✅ Smart Entry: Pullback confirmed!` (if price dipped)
|
||||||
|
- OR `⏰ Smart Entry: Timeout - executing at current price` (after 2 min)
|
||||||
|
|
||||||
|
4. **Test scenarios:**
|
||||||
|
- Signal arrives when price already at favorable level → immediate execution
|
||||||
|
- Signal arrives when price unfavorable → queued → pullback detected → execution
|
||||||
|
- Signal arrives when price unfavorable → queued → timeout → execution at current
|
||||||
|
- ADX degrades >2 points during wait → signal cancelled
|
||||||
|
|
||||||
|
### Phase 3: Production Deployment (TODO)
|
||||||
|
1. **Docker build:**
|
||||||
|
```bash
|
||||||
|
cd /home/icke/traderv4
|
||||||
|
docker compose build trading-bot
|
||||||
|
docker compose up -d --force-recreate trading-bot
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Verify container timestamp:**
|
||||||
|
```bash
|
||||||
|
docker logs trading-bot-v4 | grep "Server starting" | head -1
|
||||||
|
# Must be AFTER commit timestamp: a8c1b2c (Nov 26, 2025)
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Monitor first 5-10 signals:**
|
||||||
|
- Watch for "Smart Entry" logs
|
||||||
|
- Verify queuing behavior
|
||||||
|
- Confirm execution timing (pullback vs timeout)
|
||||||
|
- Check database `configSnapshot.smartEntry` fields
|
||||||
|
|
||||||
|
4. **Compare entry prices:**
|
||||||
|
- Query last 20 trades: 10 with smart entry ON, 10 with smart entry OFF
|
||||||
|
- Calculate average entry improvement
|
||||||
|
- Expected: 0.2-0.5% better entries with smart entry
|
||||||
|
|
||||||
|
### Phase 4: Performance Analysis (TODO - After 50+ trades)
|
||||||
|
```sql
|
||||||
|
-- Compare smart entry vs immediate entry performance
|
||||||
|
SELECT
|
||||||
|
CASE
|
||||||
|
WHEN "configSnapshot"::jsonb->'smartEntry'->>'used' = 'true'
|
||||||
|
THEN 'Smart Entry'
|
||||||
|
ELSE 'Immediate Entry'
|
||||||
|
END as entry_type,
|
||||||
|
COUNT(*) as trades,
|
||||||
|
ROUND(AVG("realizedPnL")::numeric, 2) as avg_pnl,
|
||||||
|
ROUND(100.0 * SUM(CASE WHEN "realizedPnL" > 0 THEN 1 ELSE 0 END) / COUNT(*), 1) as win_rate,
|
||||||
|
ROUND(AVG(("configSnapshot"::jsonb->'smartEntry'->>'improvement')::float), 3) as avg_improvement
|
||||||
|
FROM "Trade"
|
||||||
|
WHERE "exitReason" IS NOT NULL
|
||||||
|
AND "createdAt" > NOW() - INTERVAL '30 days'
|
||||||
|
GROUP BY entry_type;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Expected Results:**
|
||||||
|
- Smart Entry avg_improvement: +0.2% to +0.5%
|
||||||
|
- Smart Entry win_rate: 2-3% higher than immediate (due to better entries)
|
||||||
|
- Smart Entry avg_pnl: $16-40 more per trade
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Configuration Tuning
|
||||||
|
|
||||||
|
### Pullback Range
|
||||||
|
Current: 0.15-0.5%
|
||||||
|
- Too narrow: Misses opportunities, high timeout rate
|
||||||
|
- Too wide: Risks reversal, delays entry
|
||||||
|
- Optimal: Market-dependent, analyze timeout vs pullback hit rate
|
||||||
|
|
||||||
|
### Wait Time
|
||||||
|
Current: 2 minutes (120,000ms)
|
||||||
|
- Too short: Misses pullbacks that take longer
|
||||||
|
- Too long: Delays entry, risks missed moves
|
||||||
|
- Optimal: 90-180 seconds based on 5min candle timing
|
||||||
|
|
||||||
|
### ADX Tolerance
|
||||||
|
Current: 2 points
|
||||||
|
- Too strict: High cancellation rate, misses valid entries
|
||||||
|
- Too loose: Enters weak trends
|
||||||
|
- Optimal: 2-3 points based on ADX volatility during pullbacks
|
||||||
|
|
||||||
|
**Tuning Process:**
|
||||||
|
1. Collect 50+ smart entry trades
|
||||||
|
2. Analyze:
|
||||||
|
- Timeout rate vs pullback hit rate
|
||||||
|
- Cancelled signals (ADX degraded) - were they correct cancellations?
|
||||||
|
- Entry improvement distribution (0.15%, 0.30%, 0.50%)
|
||||||
|
3. Adjust parameters based on data
|
||||||
|
4. Re-test for 50 more trades
|
||||||
|
5. Compare performance
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Monitoring & Debugging
|
||||||
|
|
||||||
|
### Queue Status Endpoint
|
||||||
|
```typescript
|
||||||
|
const smartEntryTimer = getSmartEntryTimer()
|
||||||
|
const queueStatus = smartEntryTimer.getQueueStatus()
|
||||||
|
console.log('Queued signals:', queueStatus)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Key Log Messages
|
||||||
|
- `💡 Smart Entry Timer initialized: {enabled, maxWait, pullback, adxTolerance}`
|
||||||
|
- `📥 Smart Entry: Queued signal {id}` - Signal added to queue
|
||||||
|
- `🔍 Smart Entry: Checking {count} queued signals...` - Monitoring loop running
|
||||||
|
- `✅ Smart Entry: Pullback confirmed! {direction} {symbol}` - Optimal entry detected
|
||||||
|
- `⏰ Smart Entry: Timeout - executing at current price` - 2min timeout reached
|
||||||
|
- `❌ Smart Entry: ADX degraded from {start} to {current}` - Signal cancelled
|
||||||
|
- `💰 Smart Entry: Improvement: {percent}%` - Entry vs signal price comparison
|
||||||
|
|
||||||
|
### Common Issues
|
||||||
|
|
||||||
|
**Issue: Signals timeout frequently (>50% timeout rate)**
|
||||||
|
- Cause: Pullback targets too tight for market volatility
|
||||||
|
- Solution: Widen SMART_ENTRY_PULLBACK_MAX from 0.50% to 0.75%
|
||||||
|
|
||||||
|
**Issue: Signals cancelled due to ADX degradation**
|
||||||
|
- Cause: ADX tolerance too strict for natural fluctuations
|
||||||
|
- Solution: Increase SMART_ENTRY_ADX_TOLERANCE from 2 to 3
|
||||||
|
|
||||||
|
**Issue: Smart entry improves price but trades still lose**
|
||||||
|
- Cause: Entry improvement doesn't fix bad signal quality
|
||||||
|
- Solution: Focus on improving signal quality thresholds first
|
||||||
|
- Note: Smart entry optimizes entry on GOOD signals, doesn't fix BAD signals
|
||||||
|
|
||||||
|
**Issue: Monitoring loop not running (no "Checking" logs)**
|
||||||
|
- Cause: Queue empty or monitoring interval not started
|
||||||
|
- Solution: Check queueSignal() was called, verify enabled=true
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Success Criteria
|
||||||
|
|
||||||
|
### Phase 2 Complete ✅
|
||||||
|
- [x] Zero TypeScript compilation errors
|
||||||
|
- [x] Smart entry service implemented (616 lines)
|
||||||
|
- [x] Execute endpoint integrated
|
||||||
|
- [x] Configuration variables added to .env
|
||||||
|
- [x] Git committed and pushed
|
||||||
|
- [x] Ready for testing
|
||||||
|
|
||||||
|
### Phase 3 Success (Development Testing)
|
||||||
|
- [ ] Smart entry queues signals correctly
|
||||||
|
- [ ] Monitoring loop detects pullbacks
|
||||||
|
- [ ] Timeout execution works after 2 minutes
|
||||||
|
- [ ] ADX degradation cancels signals
|
||||||
|
- [ ] Database records smart entry metadata
|
||||||
|
- [ ] No TypeScript runtime errors
|
||||||
|
|
||||||
|
### Phase 4 Success (Production Validation)
|
||||||
|
- [ ] 50+ trades executed with smart entry enabled
|
||||||
|
- [ ] Average entry improvement: 0.2-0.5% measured
|
||||||
|
- [ ] No adverse effects on win rate
|
||||||
|
- [ ] No system stability issues
|
||||||
|
- [ ] User satisfied with results
|
||||||
|
|
||||||
|
### Phase 5 Success (Performance Analysis)
|
||||||
|
- [ ] 100+ trades analyzed
|
||||||
|
- [ ] $1,600-4,000 cumulative profit improvement confirmed
|
||||||
|
- [ ] Optimal configuration parameters determined
|
||||||
|
- [ ] Documentation updated with tuning recommendations
|
||||||
|
- [ ] Feature declared production-ready
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Financial Impact Projection
|
||||||
|
|
||||||
|
**Based on 100 trades at $8,000 average position size:**
|
||||||
|
|
||||||
|
| Entry Improvement | Profit per Trade | Total Improvement |
|
||||||
|
|-------------------|------------------|-------------------|
|
||||||
|
| 0.2% (conservative) | +$16 | +$1,600 |
|
||||||
|
| 0.35% (expected) | +$28 | +$2,800 |
|
||||||
|
| 0.5% (optimistic) | +$40 | +$4,000 |
|
||||||
|
|
||||||
|
**Assumptions:**
|
||||||
|
- Position size: $8,000 (current capital $540 × 15x leverage)
|
||||||
|
- Pullback hit rate: 40-60% (rest timeout at current price)
|
||||||
|
- ADX cancellation rate: <10% (mostly valid cancellations)
|
||||||
|
- Win rate maintained or slightly improved (better entries)
|
||||||
|
|
||||||
|
**Comparison to Phase 1:**
|
||||||
|
- Phase 1: 1-minute data collection (infrastructure)
|
||||||
|
- Phase 2: Smart entry timing (CURRENT - profit generation)
|
||||||
|
- Phase 3: ATR-based dynamic targets (planned - further optimization)
|
||||||
|
|
||||||
|
**Cumulative Impact:**
|
||||||
|
- Phase 2 alone: +$1,600-4,000 over 100 trades
|
||||||
|
- Phase 2 + Phase 3: +$3,000-7,000 expected (combined improvements)
|
||||||
|
- All phases complete: +35-40% P&L improvement (per master roadmap)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
|
||||||
|
1. **Immediate (Today):**
|
||||||
|
- Enable SMART_ENTRY_ENABLED=true in development .env
|
||||||
|
- Send test signal via n8n or manual API call
|
||||||
|
- Verify logs show queuing and monitoring behavior
|
||||||
|
- Test timeout scenario (wait 2+ minutes)
|
||||||
|
|
||||||
|
2. **This Week:**
|
||||||
|
- Execute 5-10 test trades with smart entry enabled
|
||||||
|
- Monitor for errors, crashes, unexpected behavior
|
||||||
|
- Measure entry improvement on test trades
|
||||||
|
- Fix any bugs discovered during testing
|
||||||
|
|
||||||
|
3. **Next Week:**
|
||||||
|
- Deploy to production if testing successful
|
||||||
|
- Monitor first 20 production trades closely
|
||||||
|
- Compare smart entry vs immediate entry performance
|
||||||
|
- Adjust configuration parameters if needed
|
||||||
|
|
||||||
|
4. **Month 1:**
|
||||||
|
- Collect 50+ smart entry trades
|
||||||
|
- Run SQL analysis comparing entry types
|
||||||
|
- Calculate actual profit improvement
|
||||||
|
- Tune pullback range, wait time, ADX tolerance
|
||||||
|
|
||||||
|
5. **Month 2:**
|
||||||
|
- Collect 100+ trades total
|
||||||
|
- Confirm $1,600-4,000 improvement achieved
|
||||||
|
- Document optimal configuration
|
||||||
|
- Proceed to Phase 3: ATR-based dynamic targets
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- **Roadmap:** `1MIN_DATA_ENHANCEMENTS_ROADMAP.md`
|
||||||
|
- **Master Plan:** `OPTIMIZATION_MASTER_ROADMAP.md`
|
||||||
|
- **Phase 1 Status:** Complete (1-min data collection working)
|
||||||
|
- **Phase 3 Roadmap:** `ATR_BASED_TP_ROADMAP.md`
|
||||||
|
- **Git Commit:** a8c1b2c (Nov 26, 2025)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Status:** ✅ READY FOR TESTING
|
||||||
|
**Next Action:** Enable in development and execute first test trade
|
||||||
|
**Expected Result:** 0.2-0.5% entry improvement per trade = $16-40 additional profit
|
||||||
Reference in New Issue
Block a user