tomasz dobrowolski

Posted on Sep 14 Originally published at flashalpha.com

Trading Gamma Flip Crosses Without Getting Faked Out: regime, unknown, and a Reference Detector in Python

#python #api #finance #tutorial

TL;DR: regime is spot versus the same snapshot's gamma_flip, and only when that level is certified. unknown means one of three things: no level, an unverified level, or spot sitting on the flip. Classify a cross by the regime after it, and only once the label has committed to a side with the level still where it was. Code at the bottom.

Three fields, read as a unit

`gamma_flip`	`gamma_flip_status`	`regime`	Meaning
number	`available`	`positive_gamma` / `negative_gamma`	Certified level, certified side. The only row you build a regime rule on.
number	`available`	`unknown`	Certified level, spot inside the certified window around it. You are at the flip.
number	`sensitive_root`, `uncertain_root_path`, `quality_budget`, `uncertain_gamma_variance`, `insufficient_local_coverage`, `insufficient_quote_quality`	`unknown`	Unverified level. Root exists but failed the named check. Context only, never a side.
null	`no_boundary`, `stored_sign_mismatch`, others	`unknown`	No supportable boundary. Nothing to trade against.

Reading gamma_flip alone is the easiest mistake to make.

How regime is computed

Within one response, spot and the flip come from the same snapshot: same chain, same underlying_price, same as_of. If the level is certified, spot at or above it is positive_gamma, below it is negative_gamma. No smoothing, no carry-forward, no inference from an unverified level.

Which chain depends on the endpoint:

Endpoint	Chain	Carries
`/v1/exposure/zero-dte/{symbol}`	Selected expiry only (today by default; `expiry=` for 1DTE/2DTE)	flip, status, regime, positional fields
`/v1/stock/{symbol}/summary` (`exposure` block)	Every live expiry	flip, status, regime
`/v1/exposure/levels/{symbol}`	Every live expiry	flip, status (no regime label)
`POST /v1/screener`	Every live expiry	`gamma_flip_status` as a filter, e.g. `eq available`
Same routes on `historical.flashalpha.com` with `?at=`	Same as live, point-in-time	Same as live

The 0DTE label and the whole-book label can legitimately disagree at the same instant. Pick the one that matches what you trade and stay on it. Taking the level from one endpoint and the regime from another compares two different books.

Certified means: at least 75% of OI on the path from spot to the level carries usable gamma, expiry-day quotes carry more time value than spread, and scaling any single strike's gamma by 0.75 or 1.25 leaves the zero-crossing within 0.1% of spot (0.25% on a bounded retry). Levels that fail are still shown with the failing check and regime unknown.

The three meanings of unknown

No level (gamma_flip null). Aggregate gamma keeps one sign across the search band, or the reconstruction disagrees with stored net-GEX sign. Stand down from any flip-based rule. net_gex still gives a coarse read of aggregate exposure sign.

Unverified level (status is a check name). Root exists but failed coverage, quote-quality or single-strike stress. Use it as a level to watch (median unverified root in the validation set is ~0.5% from spot). Do not compare it with spot yourself to manufacture a regime.

At the flip (status available, regime unknown). Certified level, spot inside the certified window, one strike's quote could put it either side. This is the transition zone where crosses happen. Wait. On the 0DTE endpoint, distance_to_flip_sigmas and spot_to_flip_pct show how deep in the zone you are.

Downstream fields follow the same rule: when regime is unknown, everything conditioned on regime returns null (GEX and vanna conditioned blocks, VRP regime label, short-put-spread, short-strangle, iron-condor and net harvest scores). Positional fields on the 0DTE endpoint (spot_vs_flip, spot_to_flip_pct, distance_to_flip_dollars, distance_to_flip_sigmas) stay populated for unverified levels because they describe where the root is, not which side dealers are on.

Pre-cross or post-cross regime?

Post-cross. The label describes the hedging environment you are entering, which governs how price behaves from here. Above the flip dealers are long gamma and dampen moves; below it they are short gamma and amplify them. A positive-to-negative cross is a breakout because the post-cross environment amplifies. The pre-cross regime tells you what you left.

A naive "label changed between two polls" rule fails for two reasons.

The level can cross spot. The flip is recomputed from the live book every snapshot. OI or gamma shifting at a nearby strike moves the level across a stationary price and the label flips with no breakout. Compare gamma_flip on both snapshots, require available on both, and treat a level move above ~0.25% of spot as a relocation. In validation replay, certified levels moved at most 0.32% of spot between consecutive minutes while spot moved under 0.1%.

unknown is the transition zone. Around the level the label reads unknown for one or more snapshots before committing. A cross is confirmed only when the post-cross label is a side and differs from the last committed side. For hysteresis, distance_to_flip_sigmas gives a band in units of remaining expected move. 0.3 sigma of follow-through is a reasonable starting point; tune to your holding period.

Reference cross detector

State machine against the 0DTE endpoint. Keeps last committed side, ignores unverified levels, treats unknown as waiting, rejects relocations, requires sigma follow-through.

import requests, time

API = "https://lab.flashalpha.com"
HEADERS = {"X-Api-Key": "YOUR_KEY"}

def snapshot(symbol):
    r = requests.get(f"{API}/v1/exposure/zero-dte/{symbol}", headers=HEADERS, timeout=10)
    r.raise_for_status()
    d = r.json()
    reg = d["regime"]
    return {
        "as_of": d["as_of"],
        "spot": d["underlying_price"],
        "flip": reg["gamma_flip"],
        "status": reg["gamma_flip_status"],
        "label": reg["label"],
        "sigmas": reg.get("distance_to_flip_sigmas"),
    }

class CrossDetector:
    MAX_LEVEL_MOVE = 0.0025   # rule of thumb: larger = the level moved, not spot
    MIN_FOLLOW_THROUGH = 0.3  # sigma beyond the level before we call it

    def __init__(self):
        self.last_side = None     # last committed regime
        self.last_flip = None     # flip at that commit
        self.last_flip_spot = None

    def update(self, s):
        # Only certified levels participate. Unverified: watch, never classify.
        if s["flip"] is None or s["status"] != "available":
            return "no_certified_level"

        if s["label"] == "unknown":
            return "at_flip_waiting"   # transition zone: spot inside the certified window

        side = s["label"]
        if self.last_side is None:
            self.last_side, self.last_flip, self.last_flip_spot = side, s["flip"], s["spot"]
            return "initialised"

        if side == self.last_side:
            self.last_flip, self.last_flip_spot = s["flip"], s["spot"]
            return "no_change"

        # The label committed to the other side. Did spot cross, or did the level move?
        if abs(s["flip"] - self.last_flip) / s["spot"] > self.MAX_LEVEL_MOVE:
            self.last_side, self.last_flip, self.last_flip_spot = side, s["flip"], s["spot"]
            return "level_relocated"

        if s["sigmas"] is not None and s["sigmas"] < self.MIN_FOLLOW_THROUGH:
            return "cross_pending_follow_through"

        self.last_side, self.last_flip, self.last_flip_spot = side, s["flip"], s["spot"]
        return "breakout_down" if side == "negative_gamma" else "breakout_up"

det = CrossDetector()
while True:
    s = snapshot("SPY")
    event = det.update(s)
    if event.startswith("breakout"):
        print(s["as_of"], event, "flip", round(s["flip"], 2), "spot", s["spot"])
    time.sleep(30)

What it never does: carry a stale level forward, compare spot with an unverified level, read unknown as a side. It classifies by the side it just committed to.

Backtesting

Point the same detector at historical.flashalpha.com with ?at=2026-09-10T14:30:00 (ET wall-clock, same clock as stored data) and step forward a minute at a time. Same calculation, same certification, same statuses. Expect the same unknown stretches and unverified levels you see live, especially in the last half hour of an expiry day. A backtest on an always-populated, always-certified level overstates signal availability.

Four anti-patterns

Carrying the last known flip forward when the current one is null.
Treating unknown as bearish.
Comparing spot with an unverified level to manufacture a regime.
Taking the level from one endpoint and the regime from another.

DEV Community