docs: Add New Agent Quick Start section to copilot instructions
- 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
This commit is contained in:
mindesbunister
265
.github/copilot-instructions.md
vendored
265
.github/copilot-instructions.md
vendored
@@ -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`
|
||||
|
||||
Reference in New Issue
Block a user