HistorySnapshot

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gammaflip-io/json-schema/gammaflip-io-history-snapshot-schema.json",
  "title": "HistorySnapshot",
  "description": "A stored snapshot: the snapshot-level fields (as `HistoryLevelsRow`, plus\n`expiration` and `dte`) and the strikes within +/- 25% of spot.\n",
  "x-generated": "2026-11-09",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gammaflip-io-openapi.yml#/components/schemas/HistorySnapshot",
  "allOf": [
    {
      "$ref": "#/$defs/HistoryLevelsRow"
    },
    {
      "type": "object",
      "properties": {
        "expiration": {
          "type": "string",
          "description": "`TOTAL` or an ISO date."
        },
        "dte": {
          "type": [
            "number",
            "null"
          ],
          "description": "Calendar days to expiration; `null` for `TOTAL`."
        },
        "strikes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/HistoryStrike"
          }
        }
      }
    }
  ],
  "$defs": {
    "HistoryLevelsRow": {
      "type": "object",
      "description": "One stored `TOTAL` snapshot. `type` is `close` only for the last capture of a\ncompleted session. `oi_date` is the session whose open interest the row used.\nThe levels fields follow the `Levels` schema (`max_pain` is `null` for `TOTAL`, so always `null` in the levels series;\na single-expiration snapshot may set it).\n",
      "allOf": [
        {
          "type": "object",
          "properties": {
            "schema_version": {
              "type": "integer"
            },
            "timestamp_utc": {
              "type": "string",
              "format": "date-time"
            },
            "session_date": {
              "type": "string",
              "format": "date",
              "description": "UTC date (crypto) or New York trading date (TradFi)."
            },
            "type": {
              "type": "string",
              "enum": [
                "intraday",
                "close"
              ]
            },
            "exchange": {
              "type": "string"
            },
            "symbol": {
              "type": "string"
            },
            "oi_date": {
              "type": [
                "string",
                "null"
              ],
              "format": "date",
              "description": "Session whose open interest was used."
            }
          }
        },
        {
          "$ref": "#/$defs/Levels"
        }
      ]
    },
    "HistoryStrike": {
      "type": "object",
      "properties": {
        "strike": {
          "type": "number"
        },
        "call_gex": {
          "type": [
            "number",
            "null"
          ],
          "description": "Non-negative."
        },
        "put_gex": {
          "type": [
            "number",
            "null"
          ],
          "description": "Non-negative."
        },
        "net_gex": {
          "type": [
            "number",
            "null"
          ],
          "description": "`call_gex - put_gex`."
        },
        "call_oi": {
          "type": [
            "number",
            "null"
          ],
          "description": "Open interest in contracts."
        },
        "put_oi": {
          "type": [
            "number",
            "null"
          ]
        }
      }
    },
    "Levels": {
      "type": "object",
      "description": "The levels of one GEX snapshot. GEX values are USD per 1% move of the\nunderlying; `call_gex` and `put_gex` are non-negative, `net_gex = call_gex - put_gex`.\nMissing values are `null`. See the data dictionary.\n",
      "properties": {
        "spot": {
          "type": [
            "number",
            "null"
          ],
          "description": "Underlying price at capture."
        },
        "flip": {
          "type": [
            "number",
            "null"
          ],
          "description": "Primary gamma-flip price (`flip_points[0]`), the net-gamma sign change nearest to spot."
        },
        "flip_count": {
          "type": "integer",
          "description": "Number of zero crossings in the profile."
        },
        "regime": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "positive",
            "negative",
            null
          ],
          "description": "`positive` if `spot >= flip`."
        },
        "net_gex": {
          "type": [
            "number",
            "null"
          ],
          "description": "Sum of call_gex minus sum of put_gex."
        },
        "abs_gex": {
          "type": [
            "number",
            "null"
          ],
          "description": "Sum of call_gex plus sum of put_gex."
        },
        "call_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "put_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "call_oi_total": {
          "type": [
            "number",
            "null"
          ],
          "description": "Sum of call open interest in contracts."
        },
        "put_oi_total": {
          "type": [
            "number",
            "null"
          ],
          "description": "Sum of put open interest in contracts."
        },
        "p1_strike": {
          "type": [
            "number",
            "null"
          ],
          "description": "Strike with the largest positive net GEX."
        },
        "p1_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "p2_strike": {
          "type": [
            "number",
            "null"
          ]
        },
        "p2_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "n1_strike": {
          "type": [
            "number",
            "null"
          ],
          "description": "Strike with the most negative net GEX."
        },
        "n1_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "n2_strike": {
          "type": [
            "number",
            "null"
          ]
        },
        "n2_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "a1_strike": {
          "type": [
            "number",
            "null"
          ],
          "description": "Strike with the largest absolute GEX (call + put)."
        },
        "a1_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "a2_strike": {
          "type": [
            "number",
            "null"
          ]
        },
        "a2_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "s_price": {
          "type": [
            "number",
            "null"
          ],
          "description": "Max-stability level, the peak of the net-gamma profile (a price)."
        },
        "s_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "v_price": {
          "type": [
            "number",
            "null"
          ],
          "description": "Max-volatility level, the trough of the net-gamma profile (a price)."
        },
        "v_gex": {
          "type": [
            "number",
            "null"
          ]
        },
        "max_pain": {
          "type": [
            "number",
            "null"
          ],
          "description": "Per-expiration max-pain strike; `null` for TOTAL."
        },
        "atm_iv": {
          "type": [
            "number",
            "null"
          ],
          "description": "ATM implied volatility as a decimal (0.18 = 18%)."
        }
      }
    }
  }
}