Skip to content
StatAlphaDocumentation

FVG — Fair Value Gap

The Fair Value Gap (FVG) measures inefficiencies between candles — zones where price moved too quickly and left an untested imbalance.
Each FVG is defined using 3-candle logic:

  • Bullish FVG: low[i] > high[i-2] → gap between candle i-2 high and i low
  • Bearish FVG: high[i] < low[i-2] → gap between candle i-2 low and i high

StatAlpha tracks how these gaps behave afterward — whether price revisits (touches) or completely fills them, and how strong the initial move was before retracement.


  • Identifies inefficient price moves based on candle gaps
  • Quantifies revisit probability (partial or full fill)
  • Measures time-to-fill and move-away strength (impulse before retrace)
  • Provides both raw events and aggregated summaries (direction split, hourly buckets)

Parameter Type Description
symbol string Target symbol (e.g., AAPL, BTCUSD)
timeframe string Candle resolution (1m, 5m, 15m, 1H, 1D, 1W, …). Default: 15m
time_window string Predefined range such as 6M, 12M, 24M, 5Y
start_date / end_date string Optional custom range (YYYY-MM-DD)
start_time / end_time string Optional intraday filter (HH:MM UTC)
include_extended_hours bool Include pre/post-market data
max_bars_to_close int Cap for bars analyzed after formation (default 50; 0 = unlimited)
use_close_prices bool If true, uses close prices instead of wicks for fill detection
limit int Used in /top and /multi_top to define number of results
symbols string (Multi-symbol only) Comma-separated list like AAPL,TSLA,MSFT

Endpoint Description
GET /stats/fvg Returns all detected FVGs for a symbol and range
GET /stats/fvg/summary Aggregated statistics by direction and hourly buckets
GET /stats/fvg/top Largest gaps by gap_size, filtered by direction
GET /stats/fvg/multi_top Strongest (most advanced/filled) FVGs across multiple symbols
GET /stats/fvg/doc Returns the endpoint/field documentation used in this API

Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/fvg/summary?symbol=AAPL&timeframe=15m&time_window=12M"
Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/fvg/top?symbol=TSLA&timeframe=1H&direction=bearish&limit=5"
Terminal window
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
"https://api.statalpha.io/stats/fvg/multi_top?symbols=AAPL,TSLA,MSFT&timeframe=15m&limit=20"

{
"symbol": "AAPL",
"timeframe": "15m",
"summary": {
"overall": {
"count": 512,
"closure_rate_full_pct": 47.1,
"closure_rate_any_touch_pct": 71.5,
"avg_gap_size": 0.58,
"avg_bars_to_full_fill": 26.3,
"avg_move_away_pct_before_touch": 1.42,
"partial_fill_distribution": {
"0%": {"count": 32, "pct": 6.25},
"1-25%": {"count": 88, "pct": 17.2},
"26-50%": {"count": 134, "pct": 26.2},
"51-75%": {"count": 92, "pct": 18.0},
"76-99%": {"count": 60, "pct": 11.7},
"100%": {"count": 106, "pct": 20.7}
}
}
},
"time_window": "12M"
}

Metric Meaning
closure_rate_full_pct / closure_rate_any_touch_pct Probability of full or partial fill
avg/median_bars/minutes_to_full_fill Average time required until full fill
avg_move_away_pct_before_touch Average impulse distance before the first retracement
partial_fill_distribution Distribution of fill ratios (0%–100%) across all detected gaps
bullish / bearish split Separate stats for upward vs. downward inefficiencies

  • Query flexibility (e.g. start_date, end_date, start_time, end_time) depends on your plan.