GET /v2/gex/{symbol}/reference

Fixed GEX reference book for a session's open or prior close

gex_getReference

A stored GEX book by strike and expiry, captured at a session's open or at the prior session's close. Use it as a fixed baseline to compare the live grid against.

Path parameters

symbol string required: Underlying symbol, e.g. SPY

Query parameters

date string required ISO date: Exchange session (ET), ISO YYYY-MM-DD, between 2014 and today.
basis string required: open for that session's first regular-session capture, or prev_close for the last regular-session capture of the session before it.

Details

basis=open returns the first regular-session capture of date; basis=prev_close returns the last regular-session capture of the session before it. An open book is written once and never changes; a prior-close book is frozen before the requested session starts. Sessions follow the exchange calendar, including holidays, daylight-saving changes and half-day closes. reference_session_date names the session the book was captured in. Rows are keyed by (strike, expiry) exactly as the grid's by_expiry=true rows.

Units

gex, net_gex and delta_adj are dollars of dealer hedging per $1 move in the underlying (calls positive, puts negative).
gex_shares is the same exposure in shares per $1 move: gex ÷ the book's spot.
strike is in integer thousandths of a dollar (600000 = $600.00); call_oi and put_oi are contracts.
spot is dollars; captured_at is epoch milliseconds.

GEX on this route is in dollars, and each strike also carries gex_shares in shares. For delta-adjusted figures and the conversion, see Units: dollars, shares and delta-adjusted.

Limits

No per-operation limit applies to requests with an API key.

Empty results

A session with no stored book returns 200 with captured_at: null, strikes: [] and meta.available: false, never a nearby session instead. A cell missing from strikes is unknown, not zero. complete is false when contracts without gamma prove the book is partial, and null when completeness cannot be certified.

Example

http

GET /v2/gex/SPY/reference?date=2026-09-24&basis=open

json

{
  "data": {
    "symbol": "SPY",
    "basis": "open",
    "session_date": "2026-09-24",
    "reference_session_date": "2026-09-24",
    "captured_at": 1790256713559,
    "spot": 764.18,
    "net_gex": -677777251.96,
    "complete": null,
    "contract_count": 8214,
    "gamma_absent": 0,
    "strikes": [
      {
        "strike": 785000,
        "expiry": "2026-09-25",
        "gex": 97146211.4,
        "call_oi": 122433,
        "put_oi": 8201,
        "delta_adj": 11846231.7,
        "gex_shares": 127124.8
      }
    ]
  },
  "meta": { "available": true }
}

Response

Prices are dollars, timestamps epoch milliseconds, strikes integer thousandths of a dollar; null means unknown. Units →

200application/json

Stable reference book or explicit unavailable reference

object

A successful response: the payload consumers parse plus response metadata. data shapes are the platform types — never reshaped by the envelope.

data object required

basis string required

captured_at integer · int64 nullable

complete boolean nullable

false when contracts without gamma prove the book is partial; null when completeness cannot be certified. Never inferred true from a non-empty book.

contract_count integer · int32 nullable

gamma_absent integer · int32 nullable

net_gex number · double nullable

reference_session_date string · date required ISO date

session_date string · date required ISO date

spot number · double nullable

strikes array<ReferenceStrike> required

call_oi integer · int32 nullable

Call open interest, contracts.

delta_adj number · double nullable $ per $1 move

Delta-adjusted exposure, dollars per $1 move. null on older historical rows captured before the field existed.

expiry string · date nullable ISO date

Present only with by_expiry=true.

gex number · double required $ per $1 move

Net dealer gamma exposure at this strike, dollars per $1 move (calls positive, puts negative).

gex_0dte number · double nullable

The part of gex from the nearest (0DTE) expiry, when known.

put_oi integer · int32 nullable

Put open interest, contracts.

strike integer · int64 required 1/1000 $

Strike in integer thousandths of a dollar (exact OSI unit)

gex_shares number · double required $ per $1 move

Gamma exposure in shares per $1 move: gex ÷ this capture's spot.

symbol string required

meta object required

Response metadata.

caps object nullable

meta.caps — the entitlement caps that shaped this response. applied lists the caps that actually changed it (for example range_clamped).

applied array<string> required

Which caps actually shaped this response (e.g. range_clamped). Empty = nothing was clamped.

darkpool boolean nullable

Whether this account can use Off-Exchange in the site.

flow boolean nullable

Whether the OPRA option-flow capability (flow) is granted to this principal in the app: site Pro plus a CBOE non-professional attestation (never on an itm_ key). Emitted explicitly — true and false — by the account endpoints, so the app reads the grant instead of inferring it from tier and attestation; absent on routes that do not report it.

gexDepth string nullable

GEX data depth when the route reports it. Camel-cased to match the browser capability bundle; absent on unrelated routes.

tier string required

The tier the request was served under.

cursor string nullable

Opaque continuation cursor (pass back as ?cursor=); absent when there is nothing more to read.

plane string nullable

Which serving tier answered the read (meta.plane). Informational provenance: treat it as an opaque label, because new values may appear.

Errors

Every error is the JSON error envelope; branch on error.code.

Status	Meaning
400	Invalid date or basis
401	Unauthenticated
403	Full GEX entitlement required
503	Reference storage unavailable

Request

curl -sS -G "https://api.itmatrixhq.com/v2/gex/SPY/reference" \
  -H "Authorization: Bearer $ITM_API_KEY" \
  -d "date=2026-09-25" \
  -d "basis=open"

import os
import httpx

response = httpx.get(
    "https://api.itmatrixhq.com/v2/gex/SPY/reference",
    params={"date": "2026-09-25", "basis": "open"},
    headers={"Authorization": f"Bearer {os.environ['ITM_API_KEY']}"},
    timeout=30,
)
print(response.status_code, response.json())

import os
import itmatrix as itm

with itm.ITMClient(api_key=os.environ["ITM_API_KEY"]) as client:
    result = client.get_gex_reference("SPY", date="2026-09-25", basis="open")
    print(result.status, result.data)

const url = new URL("https://api.itmatrixhq.com/v2/gex/SPY/reference");
url.search = new URLSearchParams({ date: "2026-09-25", basis: "open" }).toString();

const response = await fetch(url, {
  headers: { Authorization: `Bearer ${process.env.ITM_API_KEY}` },
});
console.log(response.status, await response.json());

import { ITMClient } from "@itmatrixhq/core";

const client = new ITMClient({ apiKey: process.env.ITM_API_KEY });
const result = await client.getGexReference("SPY", { date: "2026-09-25", basis: "open" });
console.log(result.status, result.data);