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.
Concept
Section titled “Concept”- 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)
Parameters
Section titled “Parameters”| 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 |
Endpoints
Section titled “Endpoints”| 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 |
Example Requests
Section titled “Example Requests”1. Summary for a single symbol
Section titled “1. Summary for a single symbol”curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.io/stats/fvg/summary?symbol=AAPL&timeframe=15m&time_window=12M"2. Top bearish gaps by size
Section titled “2. Top bearish gaps by size”curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.io/stats/fvg/top?symbol=TSLA&timeframe=1H&direction=bearish&limit=5"3. Multi-symbol overview
Section titled “3. Multi-symbol overview”curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ "https://api.statalpha.io/stats/fvg/multi_top?symbols=AAPL,TSLA,MSFT&timeframe=15m&limit=20"Example Response (summary excerpt)
Section titled “Example Response (summary excerpt)”{ "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"}Interpretation
Section titled “Interpretation”| 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.