institutional-trader/README/QUICK_INTEGRATION_GUIDE.md

Quick Integration Guide

Add Momentum Score & Moneyness Context (15 minutes)

---

Step 1: Add to Options Flow Route

File: backend/src/routes/optionsFlow.js

Add these imports at the top:

import { calculateFlowMomentum, getMomentumLabel } from '../services/momentumScore.js';
import { getMoneynessContext, isGammaSqueezeSetup, getMoneynessLabel } from '../utils/moneynessHelper.js';

Then, in the dataWithFlowInfo mapping (around line 218), add:

const dataWithFlowInfo = sorted.map(row => {
  const symbol = row.Symbol || row.symbol_norm;
  const decay = flowDecay[symbol];
  const reversal = flowReversals[symbol];
  const trend = flowTrends[symbol];
  
  // ADD: Moneyness context
  const moneyness = getMoneynessContext(row);
  const isGamma = isGammaSqueezeSetup(row);
  
  // ADD: Momentum score
  const momentumScore = calculateFlowMomentum(row, trend);
  const momentumLabel = getMomentumLabel(momentumScore);
  
  const rowWithFlowInfo = {
    ...row,
    flowDecayRaw: decay,
    flowReversalRaw: reversal,
    flowTrendRaw: trend,
    // NEW: Add these fields
    moneynessContext: moneyness,
    moneynessLabel: getMoneynessLabel(moneyness),
    isGammaSqueezeSetup: isGamma,
    momentumScore: momentumScore,
    momentumLabel: momentumLabel.label,
    momentumColor: momentumLabel.color,
    momentumIcon: momentumLabel.icon
  };
  
  // Regenerate trade signal with flow trend data
  const tradeSignal = generateTradeSignal(rowWithFlowInfo);
  rowWithFlowInfo.tradeSignal = tradeSignal;
  rowWithFlowInfo.tradeSignalDisplay = formatTradeSignal(tradeSignal);
  
  return {
    ...rowWithFlowInfo,
    flowDecay: decay ? formatFlowDecay(decay) : null,
    flowReversal: reversal && reversal.hasReversal ? formatFlowReversal(reversal) : null,
    flowTrend: trend ? formatFlowTrend(trend) : null
  };
});

---

Step 2: Update Trade Signal Generator to Use Moneyness

File: backend/src/services/tradeSignalGenerator.js

Add import at top:

import { getMoneynessContext, isGammaSqueezeSetup } from '../utils/moneynessHelper.js';

Then update Pattern 1 (around line 27) to check for gamma squeeze:

// Pattern 1: 🟢 + 💎 + ⭐ + 💰 + ⚡ = BUY SIGNAL
if (round === '🟢' && hasDiamond && hasStar && hasMoney && hasFlash) {
  // CHECK: Is this a gamma squeeze setup?
  const moneyness = getMoneynessContext(row);
  const isGamma = isGammaSqueezeSetup(row);
  
  if (isGamma || (moneyness.category === 'DEEP_OTM' && row.cp_norm === 'CALL')) {
    return {
      signal: 'BUY',
      type: 'GAMMA_SQUEEZE_SETUP', // NEW TYPE
      confidence: Math.min(calculateConfidence(row, 'BUY') + 10, 95), // Boost confidence
      entry: generateEntryStrategy(row, 'BUY'),
      stop: generateStopLoss(row, 'BUY'),
      target: generateTarget(row, 'BUY'),
      reasoning: `Gamma squeeze setup: Deep OTM calls (${moneyness.distancePct}% OTM) + full institutional flow`,
      timeHorizon: 'INTRADAY',
      invalidation: generateInvalidation(row, 'BUY')
    };
  }
  
  // Regular institutional FOMO
  return {
    signal: 'BUY',
    type: 'INSTITUTIONAL_FOMO',
    confidence: calculateConfidence(row, 'BUY'),
    // ... rest stays the same
  };
}

---

Step 3: Add Momentum Column to Frontend

File: frontend/src/components/dashboard/OptionsFlowPanel.jsx

Add to allColumns array (around line 250):

{
  accessorKey: 'Momentum',
  header: 'Momentum',
  group: 'core',
  cell: ({ row }) => {
    const momentum = row.original.momentumScore || 0;
    const label = row.original.momentumLabel || 'MODERATE';
    const color = row.original.momentumColor || 'yellow';
    const icon = row.original.momentumIcon || '🟡';
    
    const colorClasses = {
      green: 'text-green-400 bg-green-500/20',
      yellow: 'text-yellow-400 bg-yellow-500/20',
      orange: 'text-orange-400 bg-orange-500/20',
      red: 'text-red-400 bg-red-500/20'
    };
    
    return (
      <div className="flex items-center gap-2">
        <div className="flex-1 bg-slate-700 rounded-full h-2">
          <div 
            className={`bg-${color}-500 h-2 rounded-full transition-all`}
            style={{ width: `${momentum}%` }}
          />
        </div>
        <div className={`px-2 py-1 rounded text-xs font-medium ${colorClasses[color]}`}>
          <span className="mr-1">{icon}</span>
          {momentum}
        </div>
      </div>
    );
  }
},

Add to DEFAULT_VISIBLE_COLUMNS:

const DEFAULT_VISIBLE_COLUMNS = [
  'Symbol', 'badges', 'Rocket', 'Momentum', 'TradeSignal', 'NetPremium', 
  'FlowTrend', 'Premium', 'CallPut', 'Strike', 'TapeAlign', 'LastFlow', 
  'PctVsRthOpen', 'CreatedTime'
];

---

Step 4: Add Moneyness Badge

Add to columns (optional, but helpful):

{
  accessorKey: 'Moneyness',
  header: 'Moneyness',
  group: 'option',
  cell: ({ row }) => {
    const moneyness = row.original.moneynessLabel || 'Unknown';
    const isGamma = row.original.isGammaSqueezeSetup;
    
    return (
      <div className="flex items-center gap-1">
        <Badge variant="outline" className="text-xs">
          {moneyness}
        </Badge>
        {isGamma && (
          <Badge className="bg-purple-500/20 text-purple-400 text-xs border-purple-500/50">
            ⚡ GAMMA
          </Badge>
        )}
      </div>
    );
  }
}

---

Step 5: Add Momentum Filter

Add to quick filters in OptionsFlowPanel.jsx:

// In the quick filter chips section
{quickFilters.has('HighMomentum') && (
  filtered = filtered.filter(row => (row.momentumScore || 0) >= 70);
)}

Add button:

<button
  onClick={() => toggleQuickFilter('HighMomentum')}
  className={`px-3 py-1 rounded text-xs ${
    quickFilters.has('HighMomentum')
      ? 'bg-green-500/20 text-green-400 border border-green-500/50'
      : 'bg-slate-800 text-slate-400 border border-slate-700'
  }`}
>
  🔥 High Momentum (70+)
</button>

---

Testing

After making changes:

1. Restart backend - npm run dev in backend folder
2. Refresh frontend - Should see new columns
3. Check data - Look for:
   • Momentum scores (0-100) in Momentum column
   • Moneyness labels (ITM/OTM/etc) if you added that column
   • Gamma squeeze signals showing as GAMMA_SQUEEZE_SETUP type

---

Expected Results

• ✅ Momentum Score - Single number (0-100) showing flow strength
• ✅ Gamma Squeeze Detection - Deep OTM calls with full badges = special signal type
• ✅ Better Signal Accuracy - Moneyness context improves signal quality
• ✅ Easier Filtering - Filter by momentum to find strongest signals

---

Time: ~15 minutes to implement all changes

Impact:

• More accurate signals (gamma squeeze detection)
• Easier to spot opportunities (momentum score)
• Better trade selection (filter by momentum)

Ready to implement? Start with Step 1!