root/trading_bot_v4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add New Agent Quick Start section to copilot instructions

Browse Source 
- 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
2025-12-04 14:06:05 +01:00
parent 0798229582
commit 76040fa82b
1 changed files with 34 additions and 231 deletions
Download Patch File Download Diff File Expand all files Collapse all files

265
.github/copilot-instructions.md vendored
View File

@@ -1,5 +1,39 @@
# AI Agent Instructions for Trading Bot v4 # 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 ⚠️ ## ⚠️ CRITICAL: VERIFICATION MANDATE - READ THIS FIRST ⚠️
**THIS IS A REAL MONEY TRADING SYSTEM - EVERY CHANGE AFFECTS USER'S FINANCIAL FUTURE** **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 // 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 ## API Endpoints Architecture
**Authentication:** All `/api/trading/*` endpoints (except `/test`) require `Authorization: Bearer API_SECRET_KEY` **Authentication:** All `/api/trading/*` endpoints (except `/test`) require `Authorization: Bearer API_SECRET_KEY`