# 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.