Fair Value Gap Detection

A Fair Value Gap is a 3-candle pattern where price moves so aggressively that it leaves an unfilled zone between candle 1 and candle 3. The middle candle's body blows right past, and that gap becomes a magnet for price to revisit later. This is core Smart Money Concepts stuff. The function scans a DataFrame of candles and returns every bullish and bearish FVG it finds.

When to Use

• Screening for SMC-based trade setups in automated systems
• Building a charting tool that annotates liquidity imbalances
• Backtesting FVG fill rates across different timeframes

The Code

import pandas as pd

def find_fair_value_gaps(candles: pd.DataFrame) -> list:
    """
    Detect FVGs: 3-candle patterns showing liquidity imbalance.
    
    Bullish FVG: Low of candle 3 > High of candle 1
    Bearish FVG: High of candle 3 < Low of candle 1
    """
    fvgs = []
    for i in range(2, len(candles)):
        c1, c2, c3 = candles.iloc[i-2], candles.iloc[i-1], candles.iloc[i]
        
        # Bullish FVG
        if c3['low'] > c1['high']:
            fvgs.append({
                'type': 'BULLISH',
                'top': c3['low'],
                'bottom': c1['high'],
                'gap_size': c3['low'] - c1['high'],
                'index': i
            })
        # Bearish FVG
        elif c3['high'] < c1['low']:
            fvgs.append({
                'type': 'BEARISH',
                'top': c1['low'],
                'bottom': c3['high'],
                'gap_size': c1['low'] - c3['high'],
                'index': i
            })
    return fvgs

Notes

This only detects the gap. It doesn't tell you whether it's been filled yet or whether it's in a premium/discount zone. Layer those filters on top for actual trade signals.