# Market Structure Quickstart

> Request an authenticated OptionData market-structure snapshot and locate GEX, walls, Max Pain, volatility context, and freshness metadata.

The Market Structure API returns a precomputed symbol-level snapshot. It combines structural GEX and open-interest levels with volatility context and a lightweight flow overlay.

## 1. Request the latest snapshot

Store your key in `OPTIONDATA_API_KEY`, then run:

```bash
curl "https://www.optiondata.io/api/v1/market-structure/SPY" \
  -H "Authorization: Bearer $OPTIONDATA_API_KEY"
```

Use the exact option root. For index products, roots such as `SPX` and `SPXW` are distinct.

![Annotated OptionData market-structure page showing the REST endpoint and full GEX documentation link](/docs/market-structure-quickstart/market-structure-page-annotated.png)

*The overview card is the starting point for the symbol-level snapshot request.*

## 2. Request a retained date

Add `date=YYYY-MM-DD` when you need a retained historical snapshot:

```bash
curl "https://www.optiondata.io/api/v1/market-structure/SPY?date=YYYY-MM-DD" \
  -H "Authorization: Bearer $OPTIONDATA_API_KEY"
```

Not every calendar date or exact root has a retained snapshot.

## 3. Find the main sections

| Response path | Purpose |
|---|---|
| `data.symbol_meta` | Underlying description, prices, IV rank/percentile, skew, and term structure |
| `data.structure` | Spot, GEX/OI totals, Gamma Flip, walls, Max Pain, and expiration aggregates |
| `data.flow` | Lightweight session-flow overlay |
| `data.intraday_gex` | Latest intraday full-chain GEX summary when available |
| `meta.effective_date` | Trading date represented by the snapshot |
| `meta.*_as_of` | Freshness timestamps for the corresponding sections |

Treat walls and Gamma Flip as market-structure context, not guaranteed price targets.

## 4. Handle missing data correctly

- `401`: bearer key is missing or invalid.
- `403`: the customer lacks active/trialing entitlement.
- `404 SYMBOL_NOT_FOUND`: the exact option root is unknown.
- `404 SNAPSHOT_NOT_FOUND`: the root exists, but no snapshot was retained for that date.
- `429`: rate limited; honor `Retry-After`.

Use [Market Structure API](/docs/market-structure-api) for the complete field definitions and nullability contract.