# Options Greeks API

3 endpoints under `https://apexvol.com/api/mcp/data`. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access. Web version: https://apexvol.com/developers/options-greeks-api

| Endpoint | Plan | What it answers |
|---|---|---|
| `GET /charm/{ticker}` | Pro | How much delta will dealers shed on SPY overnight from charm? |
| `GET /greeks-heatmap/{ticker}` | Basic | Where are NVDA's gamma and vega concentrated across strikes and expirations? |
| `GET /third-order-greeks/{ticker}` | Pro | How fast do SPY's gamma and vega change as spot and vol move? |

## GET /charm/{ticker}

Returns total, call and put charm exposure for the chosen expiration and the per-strike breakdown, plus the detailed rows with IV and open interest.

- **Units:** charm_exposure is delta shares per day (positive means dealers gain long delta as time passes).
- **Basis:** Dealer convention: dealers short customer positions. Computed from open interest and per-contract charm.
- **Markdown:** https://apexvol.com/developers/options-greeks-api/charm.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `expiration` | query | nearest | YYYY-MM-DD, a listed expiration | Which expiration to use. Defaults to the nearest one. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/charm/SPY"
```

- `total_charm, call_charm, put_charm`: Aggregate charm exposure.
- `charm_by_strike[].strike, charm_exposure, oi`: The per-strike profile.
- `detailed[]`: Per contract with charm, IV and OI.
- `dte, expiration, stock_price`: Context.

## GET /greeks-heatmap/{ticker}

Returns matrices of delta, gamma, theta, vega, rho, vanna, charm and IV over the strike and expiration grid, the aggregates by strike and by expiration, and the open-interest call and put walls plus max pain.

- **Units:** Greeks are per share for one contract. The iv matrix is a decimal. Strikes in dollars.
- **Basis:** Values are per-contract Greeks from the chain, not dealer exposure; for exposure use /greeks-exposure.
- **Markdown:** https://apexvol.com/developers/options-greeks-api/greeks-heatmap.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `option_type` | query | calls | calls, puts or net | Which side to grid; net is calls minus puts. |
| `greek` | query | delta | delta, gamma, theta, vega, rho, vanna, charm or iv | The Greek returned as greek_matrix and greek_type. Under compact detail only its matrix and aggregates are kept. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/greeks-heatmap/NVDA"
```

- `greek_type, greek_matrix[expiration][strike]`: The requested Greek.
- `strikes[], expirations[]`: The axes of every matrix.
- `greek_matrices.<greek>[strike][expiration]`: One matrix per Greek plus iv.
- `aggregates.<greek>.by_strike, by_expiration`: Sums along each axis.
- `levels.oi_call_wall, oi_put_wall, max_pain`: Reference levels.

## GET /third-order-greeks/{ticker}

Returns the third-order Greeks per strike and per contract for one expiration, with a definitions block so a caller can label them.

- **Units:** Per-share sensitivities for one contract; speed is gamma per dollar of spot, color is gamma per day, vomma is vega per vol point.
- **Basis:** Analytic Black-Scholes derivatives on the chain IV.
- **Markdown:** https://apexvol.com/developers/options-greeks-api/third-order-greeks.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `expiration` | query | nearest | YYYY-MM-DD, a listed expiration | Which expiration to use. Defaults to the nearest one. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/third-order-greeks/SPY"
```

- `greeks_by_strike[].speed, zomma, color, vomma, ultima, vanna, charm`: Per strike.
- `detailed[]`: Per contract with type and IV.
- `definitions`: One line per Greek.

Conventions: https://apexvol.com/developers/conventions. Errors: https://apexvol.com/developers/errors. Whole API in one file: https://apexvol.com/docs/api/apexvol-api.md