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
310
docs/architecture/ADAPTIVE_LEVERAGE_SYSTEM.md
Normal file
310
docs/architecture/ADAPTIVE_LEVERAGE_SYSTEM.md
Normal file
@@ -0,0 +1,310 @@
|
||||
# Adaptive Leverage System
|
||||
|
||||
**Implementation Date:** November 24, 2025
|
||||
**Status:** ✅ DEPLOYED - Container rebuilt and running
|
||||
**Commit:** bfdb0ba
|
||||
|
||||
## Overview
|
||||
|
||||
Adaptive leverage automatically adjusts position leverage based on signal quality score, providing risk-adjusted position sizing. High-confidence signals (quality 95+) use maximum leverage, while borderline signals (quality 90-94) use reduced leverage to preserve capital.
|
||||
|
||||
## Motivation
|
||||
|
||||
**Data-Driven Decision (Nov 24, 2025):**
|
||||
- v8 Money Line indicator shows perfect quality separation
|
||||
- Quality 95+ signals: 100% win rate (4/4 wins, +$253.35)
|
||||
- Quality 90-94 signals: More volatile performance
|
||||
- User requested: "adaptive leverage per quality score? like for every trade below the 95 threshold we only use a 10x and for every trade with 95 and more we use the full blast 15x?"
|
||||
- **Goal:** Maximize profits on best setups while reducing risk on borderline signals
|
||||
|
||||
## Configuration
|
||||
|
||||
### Quality-Based Leverage Tiers
|
||||
|
||||
```typescript
|
||||
// Default configuration (config/trading.ts)
|
||||
useAdaptiveLeverage: true // Enable adaptive leverage system
|
||||
highQualityLeverage: 15 // For signals >= 95 quality
|
||||
lowQualityLeverage: 10 // For signals 90-94 quality
|
||||
qualityLeverageThreshold: 95 // Threshold for high vs low leverage
|
||||
```
|
||||
|
||||
### ENV Variables
|
||||
|
||||
```bash
|
||||
# Adaptive Leverage Settings (Nov 24, 2025)
|
||||
USE_ADAPTIVE_LEVERAGE=true # Enable quality-based leverage tiers
|
||||
HIGH_QUALITY_LEVERAGE=15 # Maximum leverage for quality 95+
|
||||
LOW_QUALITY_LEVERAGE=10 # Reduced leverage for quality 90-94
|
||||
QUALITY_LEVERAGE_THRESHOLD=95 # Quality score threshold
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
### 1. Quality Score Calculation (Early in Execute Endpoint)
|
||||
|
||||
Quality score is now calculated **before position sizing** (moved from line 755 to line 172 in execute route):
|
||||
|
||||
```typescript
|
||||
// app/api/trading/execute/route.ts (lines 172-192)
|
||||
const qualityResult = await scoreSignalQuality({
|
||||
atr: body.atr || 0,
|
||||
adx: body.adx || 0,
|
||||
rsi: body.rsi || 0,
|
||||
volumeRatio: body.volumeRatio || 0,
|
||||
pricePosition: body.pricePosition || 0,
|
||||
direction: body.direction,
|
||||
symbol: driftSymbol,
|
||||
currentPrice: body.signalPrice || 0,
|
||||
timeframe: body.timeframe,
|
||||
})
|
||||
console.log(`📊 Signal quality score: ${qualityResult.score} (calculated early for adaptive leverage)`)
|
||||
```
|
||||
|
||||
### 2. Leverage Determination (Helper Function)
|
||||
|
||||
```typescript
|
||||
// config/trading.ts (lines 653-673)
|
||||
export function getLeverageForQualityScore(
|
||||
qualityScore: number,
|
||||
config: TradingConfig
|
||||
): number {
|
||||
// If adaptive leverage disabled, use fixed leverage
|
||||
if (!config.useAdaptiveLeverage) {
|
||||
return config.leverage
|
||||
}
|
||||
|
||||
// High quality signals get maximum leverage
|
||||
if (qualityScore >= config.qualityLeverageThreshold) {
|
||||
return config.highQualityLeverage // 15x for quality 95+
|
||||
}
|
||||
|
||||
// Lower quality signals get reduced leverage
|
||||
return config.lowQualityLeverage // 10x for quality 90-94
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Position Sizing Integration
|
||||
|
||||
```typescript
|
||||
// config/trading.ts (lines 327-384)
|
||||
export async function getActualPositionSizeForSymbol(
|
||||
symbol: string,
|
||||
baseConfig: TradingConfig,
|
||||
freeCollateral: number,
|
||||
qualityScore?: number // NEW: Optional quality score parameter
|
||||
): Promise<{ size: number; leverage: number; enabled: boolean; usePercentage: boolean }> {
|
||||
// ... symbol-specific size calculation ...
|
||||
|
||||
// NEW (Nov 24, 2025): Apply adaptive leverage based on quality score
|
||||
let finalLeverage = symbolSettings.leverage
|
||||
if (qualityScore !== undefined && baseConfig.useAdaptiveLeverage) {
|
||||
finalLeverage = getLeverageForQualityScore(qualityScore, baseConfig)
|
||||
console.log(`📊 Adaptive leverage: Quality ${qualityScore} → ${finalLeverage}x leverage (threshold: ${baseConfig.qualityLeverageThreshold})`)
|
||||
}
|
||||
|
||||
return {
|
||||
size: actualSize,
|
||||
leverage: finalLeverage, // Use adaptive leverage
|
||||
enabled: symbolSettings.enabled,
|
||||
usePercentage,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### High Quality Signal (Quality 95+)
|
||||
|
||||
```
|
||||
📊 Signal quality score: 100 (calculated early for adaptive leverage)
|
||||
📊 Adaptive leverage: Quality 100 → 15x leverage (threshold: 95)
|
||||
💰 Position: $540 × 15x = $8,100 notional
|
||||
✅ Maximum firepower for high-confidence setup
|
||||
```
|
||||
|
||||
### Borderline Quality Signal (Quality 90-94)
|
||||
|
||||
```
|
||||
📊 Signal quality score: 92 (calculated early for adaptive leverage)
|
||||
📊 Adaptive leverage: Quality 92 → 10x leverage (threshold: 95)
|
||||
💰 Position: $540 × 10x = $5,400 notional
|
||||
⚠️ Reduced exposure by $2,700 (33% less risk)
|
||||
```
|
||||
|
||||
### Below Threshold (Quality <90)
|
||||
|
||||
```
|
||||
📊 Signal quality score: 85
|
||||
❌ Blocked by direction-specific quality filter
|
||||
LONG threshold: 90
|
||||
SHORT threshold: 95
|
||||
🛑 Trade not executed
|
||||
```
|
||||
|
||||
## Risk Impact Analysis
|
||||
|
||||
### Capital Preservation on Borderline Signals
|
||||
|
||||
**Example: Quality 90 LONG signal**
|
||||
- Without adaptive: $540 × 15x = $8,100 position
|
||||
- With adaptive: $540 × 10x = $5,400 position
|
||||
- Risk reduction: $2,700 (33% less exposure)
|
||||
|
||||
**Profit trade-off:**
|
||||
- Hypothetical win at +0.77%: $62.37 vs $41.58
|
||||
- Profit reduction: $20.79 (33% less profit)
|
||||
- **But:** Borderline signals more likely to stop out
|
||||
- Net effect: Less painful losses on volatile setups
|
||||
|
||||
**Data-driven expectation:**
|
||||
- Quality 95+ signals: Proven 100% WR in v8 → deserve full leverage
|
||||
- Quality 90-94 signals: Volatile results → reduced leverage appropriate
|
||||
- Quality <90 signals: Blocked by filters (not executed)
|
||||
|
||||
## Integration Points
|
||||
|
||||
### Execute Endpoint
|
||||
|
||||
1. Quality score calculated early (line 172)
|
||||
2. Passed to `getActualPositionSizeForSymbol()` (line 196)
|
||||
3. Leverage determined by quality tier
|
||||
4. Position opened with adaptive leverage
|
||||
|
||||
### Test Endpoint
|
||||
|
||||
Test trades always use quality score 100 for maximum leverage:
|
||||
|
||||
```typescript
|
||||
const { size: positionSize, leverage, enabled, usePercentage } = await getActualPositionSizeForSymbol(
|
||||
driftSymbol,
|
||||
config,
|
||||
health.freeCollateral,
|
||||
100 // Test trades always use max leverage
|
||||
)
|
||||
```
|
||||
|
||||
## Monitoring
|
||||
|
||||
### Log Messages
|
||||
|
||||
**Adaptive leverage determination:**
|
||||
```
|
||||
📊 Adaptive leverage: Quality 95 → 15x leverage (threshold: 95)
|
||||
📊 Adaptive leverage: Quality 92 → 10x leverage (threshold: 95)
|
||||
```
|
||||
|
||||
**Trade execution:**
|
||||
```
|
||||
💰 Opening LONG position:
|
||||
Symbol: SOL-PERP
|
||||
Base size: $534.60
|
||||
Leverage: 15x (adaptive - quality 100)
|
||||
Requested notional: $8,019.00
|
||||
```
|
||||
|
||||
### Analytics Dashboard
|
||||
|
||||
Future enhancement: Add "Leverage Tier" column to analytics showing which leverage was used per trade.
|
||||
|
||||
## Validation & Testing
|
||||
|
||||
### Pre-Deployment Checks
|
||||
|
||||
✅ TypeScript compilation: No errors
|
||||
✅ Docker build: Successful in 71.8s
|
||||
✅ Container startup: Clean, no errors
|
||||
✅ Log messages: Showing "Adaptive leverage: Quality X → Yx leverage"
|
||||
|
||||
### Post-Deployment Monitoring
|
||||
|
||||
**Track first 10 trades with adaptive leverage:**
|
||||
- Quality 95+ trades → Verify using 15x leverage
|
||||
- Quality 90-94 trades → Verify using 10x leverage
|
||||
- Compare P&L impact vs historical 15x-only results
|
||||
- Assess if risk reduction > profit reduction
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Additional Leverage Tiers
|
||||
|
||||
```typescript
|
||||
// Potential multi-tier system
|
||||
qualityScore >= 97: 20x leverage // Ultra-high confidence
|
||||
qualityScore >= 95: 15x leverage // High confidence (current)
|
||||
qualityScore >= 90: 10x leverage // Borderline (current)
|
||||
qualityScore >= 85: 5x leverage // Low confidence (currently blocked)
|
||||
qualityScore < 85: Blocked // Too low quality
|
||||
```
|
||||
|
||||
### Per-Direction Multipliers
|
||||
|
||||
```typescript
|
||||
// Example: SHORTS more conservative
|
||||
if (direction === 'short') {
|
||||
finalLeverage = finalLeverage * 0.8 // 15x → 12x, 10x → 8x
|
||||
}
|
||||
```
|
||||
|
||||
### Dynamic Adjustment Based on Streak
|
||||
|
||||
```typescript
|
||||
// Reduce leverage after losing streak
|
||||
if (lastThreeTradesLost()) {
|
||||
finalLeverage = Math.min(finalLeverage, 10) // Cap at 10x
|
||||
}
|
||||
```
|
||||
|
||||
## Files Changed
|
||||
|
||||
### Core Configuration
|
||||
- **config/trading.ts** (105 lines modified)
|
||||
- Added interface fields: `useAdaptiveLeverage`, `highQualityLeverage`, `lowQualityLeverage`, `qualityLeverageThreshold`
|
||||
- Added ENV variable parsing for adaptive leverage
|
||||
- Created helper function: `getLeverageForQualityScore()`
|
||||
- Modified `getActualPositionSizeForSymbol()` to accept optional `qualityScore` parameter
|
||||
|
||||
### API Endpoints
|
||||
- **app/api/trading/execute/route.ts** (32 lines modified)
|
||||
- Moved quality score calculation earlier (before position sizing)
|
||||
- Pass quality score to `getActualPositionSizeForSymbol()`
|
||||
- Removed duplicate quality scoring later in function
|
||||
|
||||
- **app/api/trading/test/route.ts** (3 lines modified)
|
||||
- Test trades use quality score 100 for maximum leverage
|
||||
|
||||
## Deployment Timeline
|
||||
|
||||
- **Nov 24, 2025 08:00 UTC:** User requested adaptive leverage
|
||||
- **Nov 24, 2025 08:15 UTC:** Implementation complete
|
||||
- **Nov 24, 2025 08:25 UTC:** Docker build successful (71.8s)
|
||||
- **Nov 24, 2025 08:28 UTC:** Container deployed and running
|
||||
- **Nov 24, 2025 08:30 UTC:** Git commit bfdb0ba pushed
|
||||
- **Status:** ✅ LIVE in production
|
||||
|
||||
## Expected Impact
|
||||
|
||||
### Capital Efficiency
|
||||
- Quality 95+ signals: Maximum leverage (15x) = maximum profit potential
|
||||
- Quality 90-94 signals: Reduced leverage (10x) = 33% less risk exposure
|
||||
- Net effect: Better risk-adjusted returns
|
||||
|
||||
### System Behavior Changes
|
||||
- Before: All signals used same leverage (15x fixed or per-symbol override)
|
||||
- After: Leverage adapts to signal confidence automatically
|
||||
- Trade-off: Slightly lower profits on borderline wins, significantly lower losses on borderline losses
|
||||
|
||||
### Success Metrics (After 50+ Trades)
|
||||
- Compare quality 95+ win rate and avg P&L (should be similar to before)
|
||||
- Compare quality 90-94 win rate and avg P&L (should be better risk-adjusted)
|
||||
- Calculate: (risk reduction on 90-94) > (profit reduction on 90-94 wins)?
|
||||
- If yes: System is net positive
|
||||
- If no: Adjust thresholds or disable adaptive leverage
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Adaptive leverage provides intelligent risk management by matching position size to signal confidence. High-quality signals (95+) earn full leverage for maximum profit, while borderline signals (90-94) use reduced leverage to preserve capital during volatile periods. This data-driven approach aligns position sizing with the proven performance characteristics of the v8 Money Line indicator, where quality 95+ signals have demonstrated 100% win rate.
|
||||
|
||||
**Next steps:** Monitor first 10-20 adaptive trades, validate leverage tiers are working as expected, collect performance data for threshold optimization.
|
||||
Reference in New Issue
Block a user