GET /v2/gex/{symbol}/grid

Gamma exposure (GEX) by strike for one underlying

gex_getGrid

Dealer gamma exposure at every strike of one capture, with the grid totals net_gex, max_abs_gex and flip_point. Use it for the current GEX profile, or with at= for a past capture.

Path parameters

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

Query parameters

at string epoch ms: Point in time to read instead of the latest capture: epoch-ms, or a YYYY-MM-DD / YYYY-MM-DDTHH:MM[:SS] string interpreted in tz. A bare date reads that session's last capture; the capture is returned exactly as stored.
tz string: IANA timezone for a string at (default America/New_York).
expiries string: Comma-separated ISO expiry dates to keep (2026-10-16,2026-10-17), or all (the default).
dte string: Days to expiry; only 0 is supported. Keeps just the nearest expiry that has not settled, resolved from the exchange calendar and echoed in meta.dte_expiry. A live read rolls to the next trading day after the close (13:00 ET on a half day) and across weekends and holidays; an at= read keeps the expiry of the session it serves. Cannot be combined with expiries.
top integer · int32: Keep only the N strikes with the largest absolute gex. The grid totals still cover every strike.
by_expiry boolean: true returns one row per (strike, expiry) instead of one net row per strike.

Details

top=N trims the rows, never the totals: net_gex and max_abs_gex always cover every strike left after expiry filtering. flip_point is the price where cumulative net GEX crosses zero, or null when it never does.

Units

gex, net_gex, max_abs_gex and delta_adj are dollars of dealer hedging per $1 move in the underlying (calls positive, puts negative).
Share-denominated GEX is dollar GEX ÷ spot, using prior_close_spot when spot is null. Delta-adjusted shares are delta_adj ÷ the same price.
strike is in integer thousandths of a dollar (600000 = $600.00).
spot, prior_close_spot and flip_point are dollars; captured_at is epoch milliseconds.

GEX on this route is in dollars. For shares or delta-adjusted figures and how to convert, see Units: dollars, shares and delta-adjusted.

Freshness

A live read (no at=) serves the latest capture of the current session; a new capture lands every 5 minutes during market hours. Before the first capture of the day, and on weekends and holidays, it serves the most recent session with data and names it in meta.date. Expiries that have already settled are never served live: after the 16:00 ET close they are dropped and counted in meta.expired_filtered. Symbols outside ITMatrixHQ's regular coverage are computed on demand from the full listed chain, cached for 10 minutes and marked meta.origin = "adhoc".

Limits

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

Empty results

A symbol with no listed options returns 200 with strikes: []; meta.date says which session was read.

Example

http

GET /v2/gex/SPY/grid?top=1

json

{
  "data": {
    "spot": 764.18,
    "prior_close_spot": 767.81,
    "captured_at": 1790256713559,
    "net_gex": -677777251.96,
    "flip_point": null,
    "max_abs_gex": 170798799.48,
    "strikes": [
      {
        "strike": 785000,
        "gex": 170798799.48,
        "call_oi": 222861,
        "put_oi": 15019,
        "delta_adj": 20825953.25
      }
    ]
  },
  "meta": {
    "date": "2026-09-24",
    "expired_filtered": 315,
    "strike_count": 1,
    "underlying": "SPY"
  }
}

Response

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

200application/jsonapplication/x-protobuf

{spot, prior_close_spot, captured_at, net_gex, flip_point, max_abs_gex, strikes} in data. Under Accept: application/x-protobuf the same grid is served as the public protobuf body (/v2/rest-protocol.proto); JSON stays the default for every other Accept.

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 $ per $1 move

The contract GEX grid. flip_point is null when there is no flip; units are dollars of dealer hedging per $1 move.

captured_at integer · int64 nullable epoch ms

Capture instant, epoch-ms.

flip_point number · double nullable USD

Gamma flip (dollar price), or null when the cumulative net never crosses zero.

max_abs_gex number · double required $ per $1 move

Largest |gex| over the same filtered curve, dollars per $1 move.

net_gex number · double required $ per $1 move

Sum of gex over every strike after expiry filtering (before any top=N trim), dollars per $1 move.

prior_close_spot number · double nullable USD

Previous session's close, dollars.

spot number · double nullable USD

Underlying price the capture was valued at, dollars.

strikes array<GexGridStrike> required

Per-strike rows (per (strike, expiry) with by_expiry=true), ascending by strike.

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)

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.

Send Accept: application/x-protobuf for a protobuf body instead of JSON — see Protobuf. Errors stay JSON.

Errors

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

Status	Meaning
400	`invalid_params` — bad `at`/`expiries`/`top`, a `dte` other than `0`, or `dte` combined with `expiries`
401	`unauthenticated` / `token_expired`
403	`not_entitled_tier` / `attestation_required`
502	`internal` — the db source failed upstream
503	`internal` — the db source is not configured here

Request

curl -sS -G "https://api.itmatrixhq.com/v2/gex/SPY/grid" \
  -H "Authorization: Bearer $ITM_API_KEY" \
  -d "top=20"

import os
import httpx

response = httpx.get(
    "https://api.itmatrixhq.com/v2/gex/SPY/grid",
    params={"top": 20},
    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("SPY", top=20)
    print(result.status, result.data)

const url = new URL("https://api.itmatrixhq.com/v2/gex/SPY/grid");
url.search = new URLSearchParams({ top: "20" }).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.getGex("SPY", { top: 20 });
console.log(result.status, result.data);