docs: Add comprehensive ATR-based risk management documentation
- Document ATR × multiplier system (2.0/4.0/3.0 for TP1/TP2/SL) - Add calculation formula and example with SOL at $140 - Document safety bounds (MIN/MAX percentages) - Include data-driven ATR values (SOL median 0.43 from 162 trades) - Document ENV configuration variables - Add regime-agnostic benefits explanation - Update Exit Strategy section with ATR-based details - Update Telegram manual trade presets with accurate ATR - Add TradingView integration requirements - Update 'When Making Changes' with ATR modification guidance - Explain performance analysis and expected improvements Why: Major system upgrade (Nov 17, 2025) requires complete documentation for future AI agents and developers. ATR-based targets solve bull/bear optimization bias by adapting to actual market volatility.
This commit is contained in:
mindesbunister
156
.github/copilot-instructions.md
vendored
156
.github/copilot-instructions.md
vendored
@@ -42,10 +42,16 @@
|
||||
|
||||
**Key Design Principle:** Dual-layer redundancy - every trade has both on-chain orders (Drift) AND software monitoring (Position Manager) as backup.
|
||||
|
||||
**Exit Strategy:** TP2-as-Runner system (CURRENT):
|
||||
- TP1 at +0.4%: Close configurable % (default 75%, adjustable via `TAKE_PROFIT_1_SIZE_PERCENT`)
|
||||
- TP2 at +0.7%: **Activates trailing stop** on full remaining % (no position close)
|
||||
- Runner: Remaining % after TP1 with ATR-based trailing stop (default 25%, configurable)
|
||||
**Exit Strategy:** ATR-Based TP2-as-Runner system (CURRENT - Nov 17, 2025):
|
||||
- **ATR-BASED TP/SL** (PRIMARY): TP1/TP2/SL calculated from ATR × multipliers
|
||||
- TP1: ATR × 2.0 (typically ~0.86%, closes 60% default)
|
||||
- TP2: ATR × 4.0 (typically ~1.72%, activates trailing stop)
|
||||
- SL: ATR × 3.0 (typically ~1.29%)
|
||||
- Safety bounds: MIN/MAX caps prevent extremes
|
||||
- Falls back to fixed % if ATR unavailable
|
||||
- **Runner:** 40% remaining after TP1 (configurable via `TAKE_PROFIT_1_SIZE_PERCENT=60`)
|
||||
- **Trailing Stop:** ATR-based (1.3-1.5x ATR multiplier), activates after TP2 trigger
|
||||
- **Benefits:** Regime-agnostic (adapts to bull/bear automatically), asset-agnostic (SOL vs BTC different ATR)
|
||||
- **Note:** All UI displays dynamically calculate runner% as `100 - TAKE_PROFIT_1_SIZE_PERCENT`
|
||||
|
||||
**Per-Symbol Configuration:** SOL and ETH have independent enable/disable toggles and position sizing:
|
||||
@@ -65,6 +71,15 @@
|
||||
|
||||
**Manual Trading via Telegram:** Send plain-text messages like `long sol`, `short eth`, `long btc` to open positions instantly (bypasses n8n, calls `/api/trading/execute` directly with preset healthy metrics). **CRITICAL:** Manual trades are marked with `signalSource='manual'` and excluded from TradingView indicator analysis (prevents data contamination).
|
||||
|
||||
**Telegram Manual Trade Presets (Nov 17, 2025 - Data-Driven):**
|
||||
- ATR: 0.43 (median from 162 SOL trades, Nov 2024-Nov 2025)
|
||||
- ADX: 32 (strong trend assumption)
|
||||
- RSI: 58 long / 42 short (neutral-favorable)
|
||||
- Volume: 1.2x average (healthy)
|
||||
- Price Position: 45 long / 55 short (mid-range)
|
||||
- Purpose: Enables quick manual entries when TradingView signals unavailable
|
||||
- Note: Re-entry analytics validate against fresh TradingView data when cached (<5min)
|
||||
|
||||
**Re-Entry Analytics System:** Manual trades are validated before execution using fresh TradingView data:
|
||||
- Market data cached from TradingView signals (5min expiry)
|
||||
- `/api/analytics/reentry-check` scores re-entry based on fresh metrics + recent performance
|
||||
@@ -695,6 +710,126 @@ Without this, order cancellations fail silently during TP1→breakeven order upd
|
||||
- `getLastTradeTimeForSymbol(symbol)` - Get last trade time for specific coin (enables per-symbol cooldown)
|
||||
- Each coin (SOL/ETH/BTC) has independent cooldown timer to avoid missed opportunities
|
||||
|
||||
## ATR-Based Risk Management (Nov 17, 2025)
|
||||
|
||||
**Purpose:** Regime-agnostic TP/SL system that adapts to market volatility automatically instead of using fixed percentages that work in one market regime but fail in another.
|
||||
|
||||
**Core Concept:** ATR (Average True Range) measures actual market volatility - when volatility increases (trending markets), targets expand proportionally. When volatility decreases (choppy markets), targets tighten. This solves the "bull/bear optimization bias" problem where fixed % targets optimized in bearish markets underperform in bullish conditions.
|
||||
|
||||
**Calculation Formula:**
|
||||
```typescript
|
||||
function calculatePercentFromAtr(
|
||||
atrValue: number, // Absolute ATR value (e.g., 0.43 for SOL)
|
||||
entryPrice: number, // Position entry price (e.g., $140)
|
||||
multiplier: number, // ATR multiplier (2.0, 4.0, 3.0)
|
||||
minPercent: number, // Safety floor (e.g., 0.5%)
|
||||
maxPercent: number // Safety ceiling (e.g., 1.5%)
|
||||
): number {
|
||||
// Convert absolute ATR to percentage of price
|
||||
const atrPercent = (atrValue / entryPrice) * 100
|
||||
|
||||
// Apply multiplier (TP1=2x, TP2=4x, SL=3x)
|
||||
const targetPercent = atrPercent * multiplier
|
||||
|
||||
// Clamp between min/max bounds for safety
|
||||
return Math.max(minPercent, Math.min(maxPercent, targetPercent))
|
||||
}
|
||||
```
|
||||
|
||||
**Example Calculation (SOL at $140 with ATR 0.43):**
|
||||
```typescript
|
||||
// ATR as percentage: 0.43 / 140 = 0.00307 = 0.307%
|
||||
|
||||
// TP1 (close 60%):
|
||||
// 0.307% × 2.0 = 0.614% → clamped to [0.5%, 1.5%] = 0.614%
|
||||
// Price target: $140 × 1.00614 = $140.86
|
||||
|
||||
// TP2 (activate trailing):
|
||||
// 0.307% × 4.0 = 1.228% → clamped to [1.0%, 3.0%] = 1.228%
|
||||
// Price target: $140 × 1.01228 = $141.72
|
||||
|
||||
// SL (emergency exit):
|
||||
// 0.307% × 3.0 = 0.921% → clamped to [0.8%, 2.0%] = 0.921%
|
||||
// Price target: $140 × 0.99079 = $138.71
|
||||
```
|
||||
|
||||
**Configuration (ENV variables):**
|
||||
```bash
|
||||
# Enable ATR-based system
|
||||
USE_ATR_BASED_TARGETS=true
|
||||
|
||||
# ATR multipliers (tuned for SOL volatility)
|
||||
ATR_MULTIPLIER_TP1=2.0 # TP1: 2× ATR (first target)
|
||||
ATR_MULTIPLIER_TP2=4.0 # TP2: 4× ATR (trailing stop activation)
|
||||
ATR_MULTIPLIER_SL=3.0 # SL: 3× ATR (stop loss)
|
||||
|
||||
# Safety bounds (prevent extreme targets)
|
||||
MIN_TP1_PERCENT=0.5 # Don't go below 0.5% for TP1
|
||||
MAX_TP1_PERCENT=1.5 # Don't go above 1.5% for TP1
|
||||
MIN_TP2_PERCENT=1.0 # Don't go below 1.0% for TP2
|
||||
MAX_TP2_PERCENT=3.0 # Don't go above 3.0% for TP2
|
||||
MIN_SL_PERCENT=0.8 # Don't go below 0.8% for SL
|
||||
MAX_SL_PERCENT=2.0 # Don't go above 2.0% for SL
|
||||
|
||||
# Legacy fallback (used when ATR unavailable)
|
||||
STOP_LOSS_PERCENT=-1.5
|
||||
TAKE_PROFIT_1_PERCENT=0.8
|
||||
TAKE_PROFIT_2_PERCENT=0.7
|
||||
```
|
||||
|
||||
**Data-Driven ATR Values:**
|
||||
- **SOL-PERP:** Median ATR 0.43 (from 162 trades, Nov 2024-Nov 2025)
|
||||
- Range: 0.0-1.17 (extreme outliers during high volatility)
|
||||
- Typical: 0.32%-0.40% of price
|
||||
- Used in Telegram manual trade presets
|
||||
- **ETH-PERP:** TBD (collect 50+ trades with ATR tracking)
|
||||
- **BTC-PERP:** TBD (collect 50+ trades with ATR tracking)
|
||||
|
||||
**When ATR is Available:**
|
||||
- TradingView signals include `atr` field in webhook payload
|
||||
- Execute endpoint calculates dynamic TP/SL using ATR × multipliers
|
||||
- Logs show: `📊 ATR-based targets: TP1 0.86%, TP2 1.72%, SL 1.29%`
|
||||
- Database saves `atrAtEntry` for post-trade analysis
|
||||
|
||||
**When ATR is NOT Available:**
|
||||
- Falls back to fixed percentages from ENV (STOP_LOSS_PERCENT, etc.)
|
||||
- Logs show: `⚠️ No ATR data, using fixed percentages`
|
||||
- Less optimal but still functional
|
||||
|
||||
**Regime-Agnostic Benefits:**
|
||||
1. **Bull markets:** Higher volatility → ATR increases → targets expand automatically
|
||||
2. **Bear markets:** Lower volatility → ATR decreases → targets tighten automatically
|
||||
3. **Asset-agnostic:** SOL volatility ≠ BTC volatility, ATR adapts to each
|
||||
4. **No re-optimization needed:** System adapts in real-time without manual tuning
|
||||
|
||||
**Performance Analysis (Nov 17, 2025):**
|
||||
- **Old fixed targets:** v6 shorts captured 3% of avg +20.74% MFE moves (TP2 at +0.7%)
|
||||
- **New ATR targets:** TP2 at ~1.72% + 40% runner with trailing stop
|
||||
- **Expected improvement:** Capture 8-10% of move (3× better than fixed targets)
|
||||
- **Real-world validation:** Awaiting 50+ trades with ATR-based exits for statistical confirmation
|
||||
|
||||
**Code Locations:**
|
||||
- `config/trading.ts` - ATR multiplier fields in TradingConfig interface
|
||||
- `app/api/trading/execute/route.ts` - calculatePercentFromAtr() function
|
||||
- `telegram_command_bot.py` - MANUAL_METRICS with ATR 0.43
|
||||
- `.env` - ATR_MULTIPLIER_* and MIN/MAX_*_PERCENT variables
|
||||
|
||||
**Integration with TradingView:**
|
||||
Ensure alerts include ATR field:
|
||||
```json
|
||||
{
|
||||
"symbol": "{{ticker}}",
|
||||
"direction": "{{strategy.order.action}}",
|
||||
"atr": {{ta.atr(14)}}, // CRITICAL: Include 14-period ATR
|
||||
"adx": {{ta.dmi(14, 14)}},
|
||||
"rsi": {{ta.rsi(14)}},
|
||||
// ... other fields
|
||||
}
|
||||
```
|
||||
|
||||
**Lesson Learned (Nov 17, 2025):**
|
||||
Optimizing fixed % targets in one market regime (bearish Nov 2024) creates bias that fails when market shifts (bullish Dec 2024+). ATR-based targets eliminate this bias by adapting to actual volatility, not historical patterns. This is the correct long-term solution for regime-agnostic trading.
|
||||
|
||||
## Configuration System
|
||||
|
||||
**Three-layer merge:**
|
||||
@@ -2338,8 +2473,17 @@ if (!enabled) {
|
||||
5. **Docker changes:** Rebuild with `docker compose build trading-bot` then restart container
|
||||
6. **Modifying quality score logic:** Update BOTH `/api/trading/check-risk` and `/api/trading/execute` endpoints, ensure timeframe-aware thresholds are synchronized
|
||||
7. **Exit strategy changes:** Modify Position Manager logic + update on-chain order placement in `placeExitOrders()`
|
||||
8. **TradingView alert changes:** Ensure alerts pass `timeframe` field (e.g., `"timeframe": "5"`) to enable proper signal quality scoring
|
||||
9. **Position Manager changes:** ALWAYS execute test trade after deployment
|
||||
8. **TradingView alert changes:**
|
||||
- Ensure alerts pass `timeframe` field (e.g., `"timeframe": "5"`) to enable proper signal quality scoring
|
||||
- **CRITICAL:** Include `atr` field for ATR-based TP/SL system: `"atr": {{ta.atr(14)}}`
|
||||
- Without ATR, system falls back to less optimal fixed percentages
|
||||
9. **ATR-based risk management changes:**
|
||||
- Update multipliers or bounds in `.env` (ATR_MULTIPLIER_TP1/TP2/SL, MIN/MAX_*_PERCENT)
|
||||
- Test with known ATR values to verify calculation (e.g., SOL ATR 0.43)
|
||||
- Log shows: `📊 ATR-based targets: TP1 X.XX%, TP2 Y.YY%, SL Z.ZZ%`
|
||||
- Verify targets fall within safety bounds (TP1: 0.5-1.5%, TP2: 1.0-3.0%, SL: 0.8-2.0%)
|
||||
- Update Telegram manual trade presets if median ATR changes (currently 0.43 for SOL)
|
||||
10. **Position Manager changes:** ALWAYS execute test trade after deployment
|
||||
- Use `/api/trading/test` endpoint or Telegram `long sol --force`
|
||||
- Monitor `docker logs -f trading-bot-v4` for full cycle
|
||||
- Verify TP1 hit → 75% close → SL moved to breakeven
|
||||
|
||||
Reference in New Issue
Block a user