diff --git a/docs/FARTCOIN_SYMBOL_FIX_DEC7_2025.md b/docs/FARTCOIN_SYMBOL_FIX_DEC7_2025.md new file mode 100644 index 0000000..bd38492 --- /dev/null +++ b/docs/FARTCOIN_SYMBOL_FIX_DEC7_2025.md @@ -0,0 +1,170 @@ +# FARTCOIN Symbol Normalization Fix (Dec 7, 2025) + +## Problem Summary + +User added FARTCOIN 1-minute and 5-minute TradingView alerts for multi-asset data collection, but all FARTCOIN signals were being stored in the database as `SOL-PERP` instead of `FARTCOIN-PERP`. + +## Root Cause Discovery + +**Initial Hypothesis (WRONG):** +- Suspected bot's symbol normalization code was checking `includes('SOL')` before FARTCOIN +- Applied fixes to `config/trading.ts` and `app/api/trading/market-data/route.ts` +- **Result:** Fixes had NO effect, logs still showed SOL-PERP + +**Actual Root Cause (Dec 7, 2025):** +- **TradingView → n8n → Bot architecture misunderstanding** +- n8n workflow normalizes symbols BEFORE sending to bot +- Bot receives symbols already in Drift format (`SOL-PERP`, `BTC-PERP`) +- Bot's normalization code is NEVER reached +- n8n workflow regex only matched `(SOL|BTC|ETH)` - FARTCOIN was missing + +## Evidence + +**Docker logs analysis:** +```bash +docker logs trading-bot-v4 --since 20m | grep "🎯 Trade execution request" +``` + +**Result:** +```json +{ + "symbol": "SOL-PERP", // Already normalized by n8n! + "direction": "long", + "timeframe": "1", + "atr": 0, + "adx": 26.9563054335 +} +``` + +**Key insight:** Symbol field was `SOL-PERP`, not `SOLUSDT` or `SOL` - normalization happened BEFORE bot received webhook. + +## Solution + +**File:** `workflows/trading/parse_signal_enhanced.json` + +**Changes:** +1. Updated symbol regex: `(SOL|BTC|ETH)` → `(FARTCOIN|FART|SOL|BTC|ETH)` +2. Added FARTCOIN-specific mapping logic: + +```javascript +const symbolMatch = body.match(/\b(FARTCOIN|FART|SOL|BTC|ETH)\b/i); +let symbol; +if (symbolMatch) { + const matched = symbolMatch[1].toUpperCase(); + // FARTCOIN and FART both map to FARTCOIN-PERP + if (matched === 'FARTCOIN' || matched === 'FART') { + symbol = 'FARTCOIN-PERP'; + } else { + symbol = matched + '-PERP'; + } +} else { + symbol = 'SOL-PERP'; // Default fallback +} +``` + +**Why order matters:** FARTCOIN checked BEFORE SOL to avoid substring match issues. + +## Deployment Steps + +### 1. Code Changes (✅ Complete) +- Updated `workflows/trading/parse_signal_enhanced.json` +- Committed and pushed (commit d3e0d20 + ebffe9a) + +### 2. n8n Workflow Import (⏳ USER ACTION REQUIRED) +**CRITICAL:** User must manually import updated workflow to n8n: + +1. Open n8n web interface +2. Navigate to workflows +3. Find "Parse Signal Enhanced" workflow +4. Import from: `/home/icke/traderv4/workflows/trading/parse_signal_enhanced.json` +5. Activate the updated workflow + +**Without this step, FARTCOIN symbols will STILL be saved as SOL-PERP** + +### 3. Verify Fix Working +After importing workflow, trigger new FARTCOIN alert and check logs: + +```bash +docker logs trading-bot-v4 --since 5m | grep -i fart +``` + +**Expected output:** +``` +📊 Normalized symbol: FARTCOIN-PERP → FARTCOIN-PERP +📊 DATA COLLECTION: 1min signal from FARTCOIN-PERP +``` + +## Architecture Clarification + +**Symbol Normalization Flow:** +``` +TradingView Alert (FARTCOIN) + ↓ +n8n Parse Signal Enhanced + ↓ (Regex match + mapping logic) +n8n HTTP POST to Bot + ↓ (Symbol already "FARTCOIN-PERP") +Bot Execute Endpoint + ↓ (normalizeTradingViewSymbol() called but does nothing - already normalized) +Database Save (FARTCOIN-PERP) +``` + +**Key Insight:** n8n is the ONLY place where raw TradingView symbols get normalized. Bot normalization code is a fallback that's rarely (never?) used in production. + +## Future Symbol Additions + +**To add new symbols (BNB, AVAX, etc.):** + +1. **Update n8n workflow** (`parse_signal_enhanced.json`): + - Add to regex: `(FARTCOIN|FART|BNB|SOL|BTC|ETH)` + - Add mapping if needed (e.g., special cases like FARTCOIN) + +2. **Import to n8n** (manual step, MANDATORY) + +3. **Bot normalization code** (optional, for non-n8n webhooks): + - Update `config/trading.ts` - `normalizeTradingViewSymbol()` + - Update `app/api/trading/market-data/route.ts` - local `normalizeTradingViewSymbol()` + +## Lessons Learned + +### 1. Verify Data Flow Before Debugging +- Spent time fixing bot code that was never executed +- Should have checked webhook payload FIRST to see pre-normalized symbol +- "Obvious" solution (bot regex order) was wrong because assumption was wrong + +### 2. Architecture Documentation Critical +- n8n symbol normalization was not documented anywhere +- Led to incorrect debugging approach +- Now documented in `.github/copilot-instructions.md` for future reference + +### 3. Test with Real Data +- Code changes looked correct but logs showed no effect +- Real production logs revealed actual data flow +- Never declare "fixed" without verification + +### 4. Manual Deployment Steps Must Be Explicit +- n8n workflow changes require manual import +- Git commit alone is NOT sufficient +- User must perform import step for fix to take effect + +## Git Commits + +- **d3e0d20** - "fix: Add FARTCOIN symbol mapping to n8n Parse Signal Enhanced" +- **ebffe9a** - "docs: Document n8n symbol normalization architecture and FARTCOIN fix" + +## Status + +- ✅ Code fixed and committed +- ✅ Documentation updated +- ⏳ **USER ACTION REQUIRED:** Import workflow to n8n +- ⏳ Waiting for verification (next FARTCOIN alert) + +## Related Issues + +- **Smart Validation Timeout Extension:** Also completed Dec 7, 2025 (separate feature) +- **Multi-Asset Data Collection:** FARTCOIN is part of broader multi-asset analysis initiative +- **BlockedSignal Analysis:** Quality-blocked signals tracked for threshold optimization + +--- + +**Dec 7, 2025 20:50 CET** - Investigation complete, fix applied, awaiting n8n import by user.