> For the complete documentation index, see [llms.txt](https://statalpha.gitbook.io/statalpha-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://statalpha.gitbook.io/statalpha-docs/stats/fvg.md).

# FVG

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

* 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

| 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

| 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

### 1. Summary for a single symbol

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/fvg/summary?symbol=AAPL&timeframe=15m&time_window=12M"
```

### 2. Top bearish gaps by size

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/fvg/top?symbol=TSLA&timeframe=1H&direction=bearish&limit=5"
```

### 3. Multi-symbol overview

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  "https://api.statalpha.market/stats/fvg/multi_top?symbols=AAPL,TSLA,MSFT&timeframe=15m&limit=20"
```

***

## Example Response (summary excerpt)

```json
{
  "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

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

***

## Notes

* FVG statistics are **plan-independent** — all users can access the same metrics.
* Query flexibility (e.g. `start_date`, `end_date`, `start_time`, `end_time`) depends on your plan.
* Data is cached automatically; repeated identical queries may return from cache for performance consistency.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://statalpha.gitbook.io/statalpha-docs/stats/fvg.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.