Plugin

Fair Value Gaps

Three bar fair value gaps with a minimum size in ATR: the nearest open gap on each side, how far each is filled, and an event when one is filled.

IndicatorNo networkDesktop onlyv1.0.0

Get early access Plugin API documentation Built in indicators

About

A fair value gap is a price range three bars in a row leave untraded. Bullish: the third bar's low is above the first bar's high, and the gap runs from that high (bottom) to that low (top). Bearish: the third bar's high is below the first bar's low, from that high (bottom) to that low (top). A gap counts only when its height is at least min_atr times the ATR at the third bar: Wilder's ATR over atr_period bars, the engine's own (the same as ctx.ind("atr")). Nothing is detected while the ATR warms up.

Filling starts with the bar after the third, and wicks count. A bullish gap fills as price trades down into it: fill = (top - lowest low since) / (top - bottom). A bearish gap fills as price trades up: fill = (highest high since - bottom) / (top - bottom). When the fill reaches fill_threshold (1.0: price has traded through the whole gap; 0.5: to its middle) the gap counts as filled, is reported on that bar and is no longer tracked. The nearest open bullish gap is the one with the highest top, the nearest bearish one the one with the lowest bottom.

The plugin setting max_open_gaps caps how many open gaps are kept per side; past it the oldest is dropped without a fill event. This plugin follows the public three bar definition and is not a copy of any charting script.

Configuration

Field	Type	Default	Description
`max_open_gaps`Open gaps kept per side	numbermin 1, max 1000	`50`	How many open gaps are kept per side. When a new one would pass the limit, the oldest open gap on that side is dropped without a fill event.

Parameters

Name	Type	Default	Range or options	Description
`min_atr`	float	`0.25`	min 0, max 10	The smallest gap that counts, in multiples of the ATR at the gap's third bar. 0 counts every gap.
`atr_period`	int	`14`	min 1, max 500	Bars in Wilder's ATR. Nothing is detected before it is known.
`fill_threshold`	float	`1`	min 0.01, max 1	The fill at which a gap counts as filled: 1.0 when price has traded through the whole gap, 0.5 at its middle.

Use it in a strategy

pythonfvg = ctx.plugin_indicator("fair_value_gaps", "fvg", {"min_atr": 0.25, "fill_threshold": 0.5})
if fvg is not None and fvg.value is not None:
    close = ctx.bars(1)[-1].close
    for gap in fvg.filled_gaps:
        # Price came back to the middle of a bullish gap and closed above its bottom.
        if gap["side"] == 1 and close > gap["bottom"]:
            ctx.signal("LONG")
        # The same for a bearish gap: out.
        elif gap["side"] == -1 and close < gap["top"]:
            ctx.signal("EXIT")

What it provides

`value`Value	1 when a bullish gap formed on this bar, -1 for a bearish one, else 0 (the same as `new_gap`). None during warm up.
`gap_top`Value	Top and `gap_bottom` of the gap formed on this bar. None when none formed.
`bull_top`Value	Top, `bull_bottom` and `bull_fill` (0 to 1) of the nearest open bullish gap. None when there is none.
`bear_top`Value	Top, `bear_bottom` and `bear_fill` (0 to 1) of the nearest open bearish gap. None when there is none.
`filled_gaps`Value	The gaps this bar filled, as dicts like `open_gaps` ([] for none): read their levels here, since a filled gap is no longer tracked. None during warm up.
`bull_filled`Value	How many of them were bullish, and `bear_filled` how many bearish; 0 for none. None during warm up.
`open_bull`Value	How many bullish gaps are open, and `open_bear` how many bearish ones. None during warm up.
`open_gaps`Value	Every open gap as a dict with side, top, bottom, fill and formed_at (the time of its third bar): bullish first, then bearish, each oldest first. None during warm up.
`atr`Value	The ATR the minimum size is measured with. None during warm up.

When values are known

A gap is known at the close of its third bar; a fill is known at the close of the bar that reaches it. Nothing reported changes with later bars. Warm up: None until the ATR is known (atr_period + 1 bars).

Limits

Fills are measured with bar highs and lows: inside one bar the plugin cannot tell whether price touched the gap before or after the bar's other extreme.
Gaps depend on the timeframe and on the data's bar times: the same market shows different gaps on M5 and H1, and on data with other session hours.
Only open gaps up to the cap per side are tracked; a dropped gap never reports a fill.
A plugin indicator is not drawn on the chart and is not available in Blocks, Pine, Rust or C#; it runs on the run's own instrument only.

Preview

json{
  "atr": 0.0011,
  "bear_bottom": 1.0917,
  "bear_fill": 0,
  "bear_filled": 0,
  "bear_top": 1.0932,
  "bull_bottom": 1.0871,
  "bull_fill": 0.38,
  "bull_filled": 0,
  "bull_top": 1.0884,
  "open_bear": 2,
  "open_bull": 3,
  "value": 0
}

A made-up sample that shows the shape of the output. Not vendor data and not a result.

The code

main.py, the file the app installs.

python"""Fair value gaps: three bar price gaps, how far each is filled, and when.

The definition this plugin uses, for three bars in a row, the third being the
bar that just closed:

- Bullish gap: the third bar's low is above the first bar's high. The gap is
  the price range between them: bottom = first high, top = third low.
- Bearish gap: the third bar's high is below the first bar's low: bottom =
  third high, top = first low.
- A gap counts only when its height is at least min_atr times the ATR at the
  third bar. The ATR is Wilder's over atr_period bars, the engine's own (the
  same as ctx.ind("atr")); nothing is detected before it is known.

Filling starts with the bar after the third. A bullish gap fills as price
trades down into it: fill = (top - lowest low since) / (top - bottom). A
bearish gap fills as price trades up: fill = (highest high since - bottom) /
(top - bottom). Wicks count. Once the fill reaches fill_threshold (1.0: price
has traded through the whole gap) the gap is filled: it is listed in
filled_gaps on that bar, with its levels, and no longer tracked. At most
max_open_gaps open gaps are kept per side (plugin setting); past that the
oldest is dropped without a fill event.

A strategy reads it through
ctx.plugin_indicator("fair_value_gaps", "fvg", {"min_atr": 0.25}).
"""

from collections import deque

from orionquant_engine.indicators.core import ATR


def _bar(bar):
    """high, low and time of an engine Bar or of a plain dict."""
    if isinstance(bar, dict):
        return float(bar["high"]), float(bar["low"]), bar.get("ts")
    return float(bar.high), float(bar.low), bar.ts


class Gap:
    """One open gap. side is 1 (bullish) or -1 (bearish); extreme is the lowest
    low (bullish) or highest high (bearish) since the gap formed."""

    def __init__(self, side, top, bottom, formed_at):
        self.side = side
        self.top = top
        self.bottom = bottom
        self.formed_at = formed_at
        self.extreme = bottom if side == -1 else top
        self.fill = 0.0

    def touch(self, high, low):
        """Take one later bar into account and update the fill fraction."""
        if self.side == 1:
            self.extreme = min(self.extreme, low)
            filled = self.top - self.extreme
        else:
            self.extreme = max(self.extreme, high)
            filled = self.extreme - self.bottom
        self.fill = min(1.0, max(0.0, filled / (self.top - self.bottom)))

    def as_dict(self):
        return {"side": self.side, "top": self.top, "bottom": self.bottom, "fill": self.fill,
                "formed_at": self.formed_at}


class FairValueGaps:
    """update(bar) then read value (a gap formed this bar: 1, -1 or 0), the
    nearest open gap on each side, this bar's fill events and the open gaps."""

    def __init__(self, min_atr=0.25, atr_period=14, fill_threshold=1.0, max_open=50):
        self.min_atr = max(0.0, float(min_atr))
        self.fill_threshold = min(1.0, max(0.01, float(fill_threshold)))
        self.max_open = max(1, int(max_open))
        self._atr = ATR(max(1, int(atr_period)))
        self._last3 = deque(maxlen=3)  # (high, low) of the last three bars
        self._bull = []  # open gaps, oldest first
        self._bear = []

        self.atr = None
        self.new_gap = None
        self.gap_top = None
        self.gap_bottom = None
        self.filled_gaps = None

    def update(self, bar):
        high, low, ts = _bar(bar)
        self._atr.update(bar)
        self._last3.append((high, low))
        self.atr = self._atr.value
        if self.atr is None:
            return  # warm up

        # 1. This bar fills the gaps that were open before it.
        self.filled_gaps = self._touch(self._bull, high, low) + self._touch(self._bear, high, low)

        # 2. A gap between the first and this (third) bar.
        self.new_gap, self.gap_top, self.gap_bottom = 0, None, None
        if len(self._last3) < 3:
            return
        first_high, first_low = self._last3[0]
        least = self.min_atr * self.atr
        if low > first_high and low - first_high >= least:
            self._open(Gap(1, low, first_high, ts), self._bull)
        elif high < first_low and first_low - high >= least:
            self._open(Gap(-1, first_low, high, ts), self._bear)

    def _touch(self, gaps, high, low):
        """Update every open gap of one side with this bar; drop the filled ones
        and return them as dicts."""
        filled = []
        for gap in list(gaps):
            gap.touch(high, low)
            if gap.fill >= self.fill_threshold:
                gaps.remove(gap)
                filled.append(gap.as_dict())
        return filled

    def _open(self, gap, gaps):
        gaps.append(gap)
        if len(gaps) > self.max_open:
            del gaps[0]  # the cap: forget the oldest
        self.new_gap, self.gap_top, self.gap_bottom = gap.side, gap.top, gap.bottom

    # --- what a strategy reads ------------------------------------------------------

    @property
    def value(self):
        """1 when a bullish gap formed on this bar, -1 for a bearish one, else 0."""
        return self.new_gap

    def _nearest_bull(self):
        # The highest top: the first gap price meets on the way down. Newest wins a tie.
        best = None
        for gap in self._bull:
            if best is None or gap.top >= best.top:
                best = gap
        return best

    def _nearest_bear(self):
        # The lowest bottom: the first gap price meets on the way up. Newest wins a tie.
        best = None
        for gap in self._bear:
            if best is None or gap.bottom <= best.bottom:
                best = gap
        return best

    @property
    def bull_top(self):
        gap = self._nearest_bull()
        return gap.top if gap else None

    @property
    def bull_bottom(self):
        gap = self._nearest_bull()
        return gap.bottom if gap else None

    @property
    def bull_fill(self):
        gap = self._nearest_bull()
        return gap.fill if gap else None

    @property
    def bear_top(self):
        gap = self._nearest_bear()
        return gap.top if gap else None

    @property
    def bear_bottom(self):
        gap = self._nearest_bear()
        return gap.bottom if gap else None

    @property
    def bear_fill(self):
        gap = self._nearest_bear()
        return gap.fill if gap else None

    @property
    def bull_filled(self):
        """How many bullish gaps this bar filled."""
        return None if self.filled_gaps is None else sum(1 for g in self.filled_gaps if g["side"] == 1)

    @property
    def bear_filled(self):
        """How many bearish gaps this bar filled."""
        return None if self.filled_gaps is None else sum(1 for g in self.filled_gaps if g["side"] == -1)

    @property
    def open_bull(self):
        return None if self.atr is None else len(self._bull)

    @property
    def open_bear(self):
        return None if self.atr is None else len(self._bear)

    @property
    def open_gaps(self):
        """Every open gap as a dict (side, top, bottom, fill, formed_at): the
        bullish ones, then the bearish ones, each oldest first. A copy: changing
        it changes nothing here."""
        if self.atr is None:
            return None
        return [g.as_dict() for g in self._bull + self._bear]


def register(api):
    def make(params):
        params = params or {}
        return FairValueGaps(
            min_atr=params.get("min_atr", 0.25),
            atr_period=params.get("atr_period", 14),
            fill_threshold=params.get("fill_threshold", 1.0),
            max_open=api.get_config("max_open_gaps", 50),
        )

    api.register_indicator(
        "fvg",
        "Fair value gaps",
        make,
        [
            {"key": "min_atr", "label": "Minimum size (ATR)", "type": "float", "default": 0.25, "min": 0.0, "max": 10.0},
            {"key": "atr_period", "label": "ATR period", "type": "int", "default": 14, "min": 1, "max": 500},
            {"key": "fill_threshold", "label": "Filled at", "type": "float", "default": 1.0, "min": 0.01, "max": 1.0},
        ],
    )
    api.log("Fair value gaps indicator registered")