From 76040fa82bf55bab8149f639f971e7f7606ed5d6 Mon Sep 17 00:00:00 2001 From: mindesbunister Date: Thu, 4 Dec 2025 14:06:05 +0100 Subject: [PATCH] docs: Add New Agent Quick Start section to copilot instructions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added explicit onboarding workflow at top of file - 4-step sequence: copilot-instructions → docs/README → README → explore - Lists all 8 documentation subdirectories with descriptions - Emphasizes 'NOTHING gets lost' principle - Ensures new agents have clear entry point without manual explanation --- .github/copilot-instructions.md | 265 ++++---------------------------- 1 file changed, 34 insertions(+), 231 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b5fc2e9..d1d7d0e 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,5 +1,39 @@ # AI Agent Instructions for Trading Bot v4 +## 🚀 NEW AGENT QUICK START + +**First Time Here?** Follow this sequence to get up to speed: + +1. **Read this file first** (`.github/copilot-instructions.md`) + - Contains all AI agent guidelines and development standards + - Common Pitfalls section (#1-71) documents every bug and fix in detail + - Financial system verification requirements (MANDATORY reading) + +2. **Navigate with** `docs/README.md` (Documentation Hub) + - Comprehensive documentation structure with 8 organized categories + - Multiple navigation methods: by topic, date, or file type + - Quick Start workflows for different development tasks + - Links to all subdirectories: setup, architecture, bugs, roadmaps, etc. + +3. **Get project context** from main `README.md` + - Live system status and configuration + - Architecture overview and key features + - File structure and deployment information + +4. **Explore specific topics** via category subdirectories as needed + - `docs/setup/` - Configuration and environment setup + - `docs/architecture/` - Technical design and system overview + - `docs/bugs/` - Known issues and critical fixes + - `docs/roadmaps/` - Planned features and optimization phases + - `docs/guides/` - Step-by-step implementation guides + - `docs/deployments/` - Deployment procedures and verification + - `docs/analysis/` - Performance analysis and data studies + - `docs/history/` - Project evolution and milestones + +**Key Principle:** "NOTHING gets lost" - all documentation is cross-referenced, interconnected, and comprehensive. + +--- + ## ⚠️ CRITICAL: VERIFICATION MANDATE - READ THIS FIRST ⚠️ **THIS IS A REAL MONEY TRADING SYSTEM - EVERY CHANGE AFFECTS USER'S FINANCIAL FUTURE** @@ -1997,237 +2031,6 @@ const { size, leverage } = getActualPositionSizeForSymbol(driftSymbol, config, q // leverage is now 15x for quality ≥95, or 10x for quality 90-94 ``` -## Environment Variable Reference - -**Purpose:** Centralized reference for all environment variables used in the trading bot system. This table provides quick lookup for AI agents and developers without needing to read the entire 482-line .env file or search multiple documentation sections. - -**Source:** `.env` file with comprehensive inline documentation. Variables organized by functional category matching .env structure. - -**Configuration Priority:** -1. **Per-symbol ENV vars** (highest priority): `SOLANA_*`, `ETHEREUM_*` -2. **Market-specific config**: From `MARKET_CONFIGS` in config/trading.ts -3. **Global ENV vars**: Fallback for BTC and other symbols -4. **Default config**: Lowest priority in `DEFAULT_TRADING_CONFIG` - -### Required - Drift Protocol Trading - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `DRIFT_WALLET_PRIVATE_KEY` | - | Private key for Drift Protocol wallet | String (JSON array or base58) | **REQUIRED** - Supports both formats from Phantom wallet | -| `API_SECRET_KEY` | - | Authentication token for trading endpoints | String | **REQUIRED** - Used in `Authorization: Bearer` header | - -### Required - Solana RPC Endpoint - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `SOLANA_RPC_URL` | - | Primary Solana RPC endpoint URL | URL | **REQUIRED** - Use Helius for reliability (NOT Alchemy - see Common Pitfall #2) | -| `BACKUP_RPC_URL` | - | Fallback RPC endpoint | URL | Optional - Used if primary fails | - -### Required - Pyth Network - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `PYTH_HERMES_URL` | `https://hermes.pyth.network` | Pyth price feed endpoint | URL | **REQUIRED** - Real-time price data for position monitoring | - -### Trading Configuration - Signal Quality - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `MIN_SIGNAL_QUALITY_SCORE` | `60` | Global minimum quality threshold | Integer (0-100) | **DEPRECATED** - Use direction-specific thresholds | -| `MIN_SIGNAL_QUALITY_SCORE_LONG` | `90` | Minimum quality for LONG signals | Integer (0-100) | **PRODUCTION** - Raised Nov 28, 2025 | -| `MIN_SIGNAL_QUALITY_SCORE_SHORT` | `80` | Minimum quality for SHORT signals | Integer (0-100) | **PRODUCTION** - Lower threshold due to baseline difficulty | - -### Trading Configuration - Adaptive Leverage - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `USE_ADAPTIVE_LEVERAGE` | `true` | Enable quality-based leverage adjustment | Boolean | **ACTIVE** - Dec 1, 2025 production config | -| `HIGH_QUALITY_LEVERAGE` | `10` | Leverage for high-quality signals | Integer | Applied when quality ≥ threshold | -| `LOW_QUALITY_LEVERAGE` | `5` | Leverage for borderline signals | Integer | Applied when quality < threshold but ≥ minimum | -| `QUALITY_LEVERAGE_THRESHOLD` | `95` | Global quality threshold for high leverage | Integer (0-100) | **DEPRECATED** - Use direction-specific | -| `QUALITY_LEVERAGE_THRESHOLD_LONG` | `95` | LONG quality threshold for 10x leverage | Integer (0-100) | **PRODUCTION** - Independent control | -| `QUALITY_LEVERAGE_THRESHOLD_SHORT` | `90` | SHORT quality threshold for 10x leverage | Integer (0-100) | **PRODUCTION** - Lower threshold for SHORTs | - -### Trading Configuration - Position Sizing - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `MAX_POSITION_SIZE_USD` | `100` | Global position size fallback | Integer (USD) | Used for BTC and other symbols | -| `LEVERAGE` | `1` | Global leverage fallback | Integer | Used for BTC and other symbols | -| `SOLANA_ENABLED` | `true` | Enable SOL-PERP trading | Boolean | Independent on/off toggle | -| `SOLANA_POSITION_SIZE` | `100` | SOL position size percentage | Integer (1-100) | 100% = use all free collateral | -| `SOLANA_LEVERAGE` | `15` | SOL leverage multiplier | Integer | **PRODUCTION** - Higher risk, higher reward | -| `ETHEREUM_ENABLED` | `false` | Enable ETH-PERP trading | Boolean | Typically disabled (SOL primary) | -| `ETHEREUM_POSITION_SIZE` | `100` | ETH position size percentage | Integer (1-100) | | -| `ETHEREUM_LEVERAGE` | `1` | ETH leverage multiplier | Integer | Lower leverage for data collection | - -### ATR-Based TP/SL System - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `USE_ATR_BASED_TARGETS` | `true` | Enable ATR-based TP/SL calculation | Boolean | **ACTIVE** - Regime-agnostic system | -| `ATR_MULTIPLIER_TP1` | `2.0` | ATR multiplier for TP1 target | Float | Typically ~0.86% for SOL (ATR 0.43) | -| `ATR_MULTIPLIER_TP2` | `4.0` | ATR multiplier for TP2 target | Float | Typically ~1.72% for SOL | -| `ATR_MULTIPLIER_SL` | `3.0` | ATR multiplier for stop loss | Float | Typically ~1.29% for SOL | -| `MIN_TP1_PERCENT` | `0.5` | Safety floor for TP1 | Float (%) | Prevents too-tight targets | -| `MAX_TP1_PERCENT` | `1.5` | Safety ceiling for TP1 | Float (%) | Prevents extreme targets | -| `MIN_TP2_PERCENT` | `1.0` | Safety floor for TP2 | Float (%) | | -| `MAX_TP2_PERCENT` | `3.0` | Safety ceiling for TP2 | Float (%) | | -| `MIN_SL_PERCENT` | `0.8` | Safety floor for SL | Float (%) | | -| `MAX_SL_PERCENT` | `2.0` | Safety ceiling for SL | Float (%) | | -| `TRAILING_STOP_ATR_MULTIPLIER` | `1.5` | ATR multiplier for trailing stop distance | Float | **Phase 7.3** - Adaptive with ADX | -| `MIN_TRAILING_STOP_PERCENT` | `0.25` | Minimum trailing distance | Float (%) | Prevents too-tight trailing | -| `MAX_TRAILING_STOP_PERCENT` | `0.9` | Maximum trailing distance | Float (%) | | - -### ATR-Based TP/SL - Legacy Fallback - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `STOP_LOSS_PERCENT` | `-1.5` | Fixed stop loss (when ATR unavailable) | Float (%) | Legacy fallback only | -| `TAKE_PROFIT_1_PERCENT` | `0.8` | Fixed TP1 (when ATR unavailable) | Float (%) | Less optimal than ATR-based | -| `TAKE_PROFIT_2_PERCENT` | `0.7` | Fixed TP2 (when ATR unavailable) | Float (%) | | - -### Trading Configuration - Runner System - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `TAKE_PROFIT_1_SIZE_PERCENT` | `60` | Percentage to close at TP1 | Integer (1-100) | Runner = 100 - this value (40% default) | -| `TRAILING_STOP_PERCENT` | `0.3` | Fixed trailing stop distance | Float (%) | **DEPRECATED** - Use ATR-based | -| `PROFIT_LOCK_TRIGGER_PERCENT` | `1.2` | Profit level to move SL to breakeven | Float (%) | Risk-free point | -| `PROFIT_LOCK_SL_PERCENT` | `0.5` | Where to move SL after profit lock | Float (%) | Small profit protection | -| `TRAILING_STOP_ACTIVATION_PERCENT` | `0.5` | When to start trailing stop | Float (%) | After TP2 trigger | -| `SOFT_STOP_PERCENT` | `-1.5` | Dual stop system - trigger limit | Float (%) | Avoids wicks | -| `HARD_STOP_PERCENT` | `-2.5` | Dual stop system - trigger market | Float (%) | Guarantees exit | - -### Trading Configuration - Dual Stop System - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `USE_DUAL_STOPS` | `true` | Enable dual stop loss orders | Boolean | Soft (limit) + hard (market) | -| `SOFT_STOP_PERCENT` | `-1.5` | Soft stop trigger (limit order) | Float (%) | Avoids wick stops | -| `HARD_STOP_PERCENT` | `-2.5` | Hard stop trigger (market order) | Float (%) | Guarantees exit | - -### Smart Entry Timing System - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `SMART_ENTRY_ENABLED` | `true` | Enable pullback detection system | Boolean | Wait for better entry prices | -| `SMART_ENTRY_MAX_WAIT_MS` | `300000` | Maximum wait time for pullback | Integer (ms) | 5 minutes default | -| `SMART_ENTRY_PULLBACK_MIN` | `0.5` | Minimum pullback to wait for | Float (%) | | -| `SMART_ENTRY_PULLBACK_MAX` | `2.0` | Maximum pullback to wait for | Float (%) | | - -### Risk Limits & Execution - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `EMERGENCY_STOP_PERCENT` | `-2.0` | Emergency market close trigger | Float (%) | Immediate exit at any price | -| `MAX_DAILY_DRAWDOWN` | `-5.0` | Daily loss limit | Float (%) | Stops trading for 24h | -| `MAX_TRADES_PER_HOUR` | `10` | Hourly trade limit | Integer | Prevents overtrading | -| `COOLDOWN_PERIOD_MS` | `300000` | Cooldown between trades | Integer (ms) | Per-symbol, 5 minutes default | - -### N8N Workflow Integration - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `N8N_WEBHOOK_URL` | - | N8N workflow webhook endpoint | URL | Optional - For workflow automation | -| `N8N_ENABLED` | `false` | Enable n8n integration | Boolean | | - -### Notifications - Telegram - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `TELEGRAM_BOT_TOKEN` | - | Telegram bot authentication token | String | **REQUIRED** for notifications | -| `TELEGRAM_CHAT_ID` | - | Telegram chat ID for notifications | String | **REQUIRED** - Get from @userinfobot | - -### Database Configuration - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `DATABASE_URL` | - | PostgreSQL connection string | String | **REQUIRED** - Format: postgresql://user:pass@host:port/db | -| `POSTGRES_USER` | `postgres` | Database username | String | Used in docker-compose | -| `POSTGRES_PASSWORD` | - | Database password | String | **REQUIRED** - Generate secure password | -| `POSTGRES_DB` | `trading_bot_v4` | Database name | String | | - -### Security & Access Control - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `JWT_SECRET` | - | JWT token signing secret | String | **REQUIRED** - Generate random string | -| `ENCRYPTION_KEY` | - | Data encryption key | String | **REQUIRED** - For sensitive data | - -### Development & Debugging - -| Variable | Default | Purpose | Type | Notes | -|----------|---------|---------|------|-------| -| `NODE_ENV` | `production` | Runtime environment | String | `development` \| `production` \| `test` | -| `LOG_LEVEL` | `info` | Logging verbosity | String | `debug` \| `info` \| `warn` \| `error` | -| `DRY_RUN` | `false` | Test mode without real trades | Boolean | **CRITICAL** - Test changes safely | -| `PORT` | `3000` | Internal Next.js port | Integer | Container port, not exposed | -| `NEXT_PUBLIC_API_URL` | `http://localhost:3001` | Public API base URL | URL | For frontend API calls | - -### Usage Examples - -**CORRECT: Use merged config (always)** -```typescript -import { getMergedConfig } from '@/config/trading' -const config = getMergedConfig() - -// Access values through config object -const minQuality = config.minSignalQualityScore -const leverage = config.leverage -``` - -**WRONG: Never read ENV directly in business logic** -```typescript -// ❌ DON'T DO THIS -const minQuality = process.env.MIN_SIGNAL_QUALITY_SCORE -const leverage = parseInt(process.env.LEVERAGE || '1') -``` - -**Per-Symbol Position Sizing:** -```typescript -import { getPositionSizeForSymbol } from '@/config/trading' - -// Returns { size, leverage, enabled } for symbol -const { size, leverage, enabled } = getPositionSizeForSymbol('SOL-PERP', config) - -if (!enabled) { - return NextResponse.json({ error: 'Symbol trading disabled' }, { status: 400 }) -} - -// Use symbol-specific values -console.log(`Opening ${size} USD position at ${leverage}x leverage`) -``` - -**Adaptive Leverage Integration:** -```typescript -import { getLeverageForQualityScore } from '@/config/trading' - -// Calculate quality score first -const qualityResult = scoreSignalQuality({ atr, adx, rsi, volumeRatio, pricePosition, timeframe }) - -// Get adaptive leverage based on quality -const leverage = getLeverageForQualityScore(qualityResult.score, config) -// Returns: 10x for quality ≥95 (LONG) or ≥90 (SHORT), 5x for borderline - -// Use in position sizing -const { size } = getActualPositionSizeForSymbol(driftSymbol, config, qualityResult.score) -``` - -**Symbol Normalization:** -```typescript -import { normalizeTradingViewSymbol } from '@/config/trading' - -// TradingView sends: "SOLUSDT", "ETHUSDT", "BTCUSDT" -const tvSymbol = body.symbol // "SOLUSDT" - -// Normalize to Drift format -const driftSymbol = normalizeTradingViewSymbol(tvSymbol) // Returns: "SOL-PERP" - -// Use Drift format in all trading operations -const position = await driftService.getPosition(driftSymbol) -``` - ## API Endpoints Architecture **Authentication:** All `/api/trading/*` endpoints (except `/test`) require `Authorization: Bearer API_SECRET_KEY`