docs: Major documentation reorganization + ENV variable reference
**Documentation Structure:** - Created docs/ subdirectory organization (analysis/, architecture/, bugs/, cluster/, deployments/, roadmaps/, setup/, archived/) - Moved 68 root markdown files to appropriate categories - Root directory now clean (only README.md remains) - Total: 83 markdown files now organized by purpose **New Content:** - Added comprehensive Environment Variable Reference to copilot-instructions.md - 100+ ENV variables documented with types, defaults, purpose, notes - Organized by category: Required (Drift/RPC/Pyth), Trading Config (quality/ leverage/sizing), ATR System, Runner System, Risk Limits, Notifications, etc. - Includes usage examples (correct vs wrong patterns) **File Distribution:** - docs/analysis/ - Performance analyses, blocked signals, profit projections - docs/architecture/ - Adaptive leverage, ATR trailing, indicator tracking - docs/bugs/ - CRITICAL_*.md, FIXES_*.md bug reports (7 files) - docs/cluster/ - EPYC setup, distributed computing docs (3 files) - docs/deployments/ - *_COMPLETE.md, DEPLOYMENT_*.md status (12 files) - docs/roadmaps/ - All *ROADMAP*.md strategic planning files (7 files) - docs/setup/ - TradingView guides, signal quality, n8n setup (8 files) - docs/archived/2025_pre_nov/ - Obsolete verification checklist (1 file) **Key Improvements:** - ENV variable reference: Single source of truth for all configuration - Common Pitfalls #68-71: Already complete, verified during audit - Better findability: Category-based navigation vs 68 files in root - Preserves history: All files git mv (rename), not copy/delete - Zero broken functionality: Only documentation moved, no code changes **Verification:** - 83 markdown files now in docs/ subdirectories - Root directory cleaned: 68 files → 0 files (except README.md) - Git history preserved for all moved files - Container running: trading-bot-v4 (no restart needed) **Next Steps:** - Create README.md files in each docs subdirectory - Add navigation index - Update main README.md with new structure - Consolidate duplicate deployment docs - Archive truly obsolete files (old SQL backups) See: docs/analysis/CLEANUP_PLAN.md for complete reorganization strategy
This commit is contained in:
mindesbunister
164
docs/architecture/ATR_TRAILING_STOP_FIX.md
Normal file
164
docs/architecture/ATR_TRAILING_STOP_FIX.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# ATR-Based Trailing Stop Fix - Nov 11, 2025
|
||||
|
||||
## Problem Identified
|
||||
|
||||
**Critical Bug:** Runner system was using FIXED 0.3% trailing stop, causing profitable runners to exit immediately.
|
||||
|
||||
**Evidence:**
|
||||
- Recent trades showing MFE of +7-9% but exiting for losses or minimal gains
|
||||
- Example: Entry $167.82, MFE +7.01%, exit $168.91 for **-$2.68 loss**
|
||||
- At $168 SOL price: 0.3% = only **$0.50 wiggle room** before stop hits
|
||||
- Normal price volatility easily triggers 0.3% retracement
|
||||
|
||||
**Documentation Claim vs Reality:**
|
||||
- Docs claimed "ATR-based trailing stop"
|
||||
- Code was using `this.config.trailingStopPercent` (fixed 0.3%)
|
||||
- Config already had `trailingStopAtrMultiplier` parameter but it wasn't being used!
|
||||
|
||||
## Solution Implemented
|
||||
|
||||
### 1. Position Manager Update (`lib/trading/position-manager.ts`)
|
||||
**Changed trailing stop calculation from fixed to ATR-based:**
|
||||
|
||||
```typescript
|
||||
// OLD (BROKEN):
|
||||
const trailingStopPrice = this.calculatePrice(
|
||||
trade.peakPrice,
|
||||
-this.config.trailingStopPercent, // Fixed 0.3%
|
||||
trade.direction
|
||||
)
|
||||
|
||||
// NEW (FIXED):
|
||||
if (trade.atrAtEntry && trade.atrAtEntry > 0) {
|
||||
// ATR-based: Use ATR% * multiplier
|
||||
const atrPercent = (trade.atrAtEntry / currentPrice) * 100
|
||||
const rawDistance = atrPercent * this.config.trailingStopAtrMultiplier
|
||||
|
||||
// Clamp between min and max
|
||||
trailingDistancePercent = Math.max(
|
||||
this.config.trailingStopMinPercent,
|
||||
Math.min(this.config.trailingStopMaxPercent, rawDistance)
|
||||
)
|
||||
} else {
|
||||
// Fallback to configured percent with clamping
|
||||
trailingDistancePercent = Math.max(
|
||||
this.config.trailingStopMinPercent,
|
||||
Math.min(this.config.trailingStopMaxPercent, this.config.trailingStopPercent)
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Added `atrAtEntry` to ActiveTrade Interface
|
||||
```typescript
|
||||
export interface ActiveTrade {
|
||||
// Entry details
|
||||
entryPrice: number
|
||||
entryTime: number
|
||||
positionSize: number
|
||||
leverage: number
|
||||
atrAtEntry?: number // NEW: ATR value at entry for ATR-based trailing stop
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Settings UI Updates (`app/settings/page.tsx`)
|
||||
Added new fields for ATR trailing configuration:
|
||||
- **ATR Trailing Multiplier** (1.0-3.0x, default 1.5x)
|
||||
- **Min Trailing Distance** (0.1-1.0%, default 0.25%)
|
||||
- **Max Trailing Distance** (0.5-2.0%, default 0.9%)
|
||||
- Changed "Trailing Stop Distance" label to "[FALLBACK]"
|
||||
|
||||
### 4. Environment Variables (`.env.example`)
|
||||
```bash
|
||||
# ATR-based Trailing Stop (for 25% runner after TP2)
|
||||
# Trailing distance = (ATR × multiplier)
|
||||
# Example: 0.5% ATR × 1.5 = 0.75% trailing (more room than fixed 0.3%)
|
||||
TRAILING_STOP_ATR_MULTIPLIER=1.5
|
||||
TRAILING_STOP_MIN_PERCENT=0.25
|
||||
TRAILING_STOP_MAX_PERCENT=0.9
|
||||
TRAILING_STOP_ACTIVATION=0.5
|
||||
```
|
||||
|
||||
## Expected Impact
|
||||
|
||||
### Before Fix (0.3% Fixed)
|
||||
- SOL at $168: 0.3% = $0.50 wiggle room
|
||||
- Normal 2-minute oscillation kills runner immediately
|
||||
- Runners with +7-9% MFE captured minimal profit or even lost money
|
||||
|
||||
### After Fix (ATR-based)
|
||||
**Recent ATR distribution from database:**
|
||||
```sql
|
||||
-- Most common ATR values: 0.25-0.52%
|
||||
-- At 1.5x multiplier:
|
||||
0.25% ATR × 1.5 = 0.375% trail
|
||||
0.37% ATR × 1.5 = 0.555% trail
|
||||
0.45% ATR × 1.5 = 0.675% trail
|
||||
0.52% ATR × 1.5 = 0.780% trail
|
||||
```
|
||||
|
||||
**Typical improvement:**
|
||||
- Old: $0.50 wiggle room ($168 × 0.3%)
|
||||
- New: $1.12 wiggle room ($168 × 0.67% avg)
|
||||
- **2.24x more room for runner to breathe!**
|
||||
|
||||
**Volatility adaptation:**
|
||||
- Low ATR (0.25%): 0.375% trail = $0.63 @ $168
|
||||
- High ATR (0.72%): 0.9% trail cap = $1.51 @ $168 (max cap)
|
||||
- Automatically adjusts to market conditions
|
||||
|
||||
## Verification Logs
|
||||
|
||||
When runner activates, you'll now see:
|
||||
```
|
||||
🎯 Trailing stop activated at +0.65%
|
||||
📊 ATR-based trailing: 0.0045 (0.52%) × 1.5x = 0.78%
|
||||
📈 Trailing SL updated: 168.50 → 167.20 (0.78% below peak $168.91)
|
||||
```
|
||||
|
||||
Instead of:
|
||||
```
|
||||
⚠️ No ATR data, using fallback: 0.30%
|
||||
📈 Trailing SL updated: 168.50 → 168.41 (0.30% below peak $168.91)
|
||||
```
|
||||
|
||||
## Testing
|
||||
|
||||
1. **Existing open trades:** Will use fallback 0.3% (no atrAtEntry yet)
|
||||
2. **New trades:** Will capture ATR at entry and use ATR-based trailing
|
||||
3. **Settings UI:** Update multiplier at http://localhost:3001/settings
|
||||
4. **Log verification:** Check for "📊 ATR-based trailing" messages
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. ✅ `lib/trading/position-manager.ts` - ATR-based trailing calculation + interface
|
||||
2. ✅ `app/settings/page.tsx` - UI for ATR multiplier controls
|
||||
3. ✅ `.env.example` - Documentation for new variables
|
||||
4. ✅ `config/trading.ts` - Already had the config (wasn't being used!)
|
||||
|
||||
## Deployment
|
||||
|
||||
```bash
|
||||
docker compose build trading-bot
|
||||
docker compose up -d --force-recreate trading-bot
|
||||
docker logs -f trading-bot-v4
|
||||
```
|
||||
|
||||
**Status:** ✅ **DEPLOYED AND RUNNING**
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Monitor next runner:** Watch for "📊 ATR-based trailing" in logs
|
||||
2. **Compare MFE vs realized P&L:** Should capture 50%+ of MFE (vs current 5-10%)
|
||||
3. **Adjust multiplier if needed:** May increase to 2.0x after seeing results
|
||||
4. **Update copilot-instructions.md:** Document this fix after validation
|
||||
|
||||
## Related Issues
|
||||
|
||||
- Fixes the morning's missed opportunity: $172→$162 drop would have been captured
|
||||
- Addresses "trades showing +7% MFE but -$2 loss" pattern
|
||||
- Makes the 25% runner system actually useful (vs broken 5% system)
|
||||
|
||||
## Key Insight
|
||||
|
||||
**The config system was already built for this!** The `trailingStopAtrMultiplier` parameter existed in DEFAULT_TRADING_CONFIG and getConfigFromEnv() since the TP2-as-runner redesign. The Position Manager just wasn't using it. This was a "90% done but not wired up" situation.
|
||||
Reference in New Issue
Block a user