# ORATS Field Map

This is the short in-repo version of the full ORATS mapping spec. The goal is to wire ORATS rows into the existing GammaDesk response models without changing the frontend.

## Main endpoints

| GammaDesk need | ORATS endpoint family | Key fields |
|---|---|---|
| Symbol list | `/tickers` | `ticker`, `min`, `max` |
| Expiration list | `/live/expirations` | `expiration`, `strikes` |
| Option chain and Greeks | `/live/strikes`, `/live/strikes/monthly` | `ticker`, `tradeDate`, `expirDate`, `dte`, `strike`, `stockPrice`, `spotPrice`, `gamma`, `callOpenInterest`, `putOpenInterest`, `callVolume`, `putVolume`, `smvVol`, `updatedAt` |
| Volatility surface | `/live/monies/implied` | `ticker`, `tradeDate`, `expirDate`, `stockPrice`, `vol25`, `vol50`, `vol75`, `atmiv`, `slope`, `deriv`, `calVol`, `unadjVol`, `earnEffect`, `updatedAt` |
| Summary IV and term structure | `/live/summaries` | `ticker`, `tradeDate`, `stockPrice`, `iv10d`, `iv20d`, `iv30d`, `iv60d`, `iv90d`, `iv6m`, `iv1y`, `impliedMove`, `skewing`, `rSlp30`, `rDrv30`, `contango`, `confidence`, `updatedAt` |
| IV rank | IV Rank endpoint or historical-derived fallback | `ticker`, `tradeDate`, `iv`, `ivRank1m`, `ivPct1m`, `ivRank1y`, `ivPct1y`, `updatedAt` |

## Field mapping

### `MarketSummary`

| GammaDesk field | Preferred ORATS source |
|---|---|
| `ticker` | `ticker` |
| `spot` | `spotPrice`, fallback `stockPrice` |
| `netGex` | derived from strike rows |
| `gammaRegime` | derived from `netGex` and HVL relation |
| `hvl` | derived zero-gamma / cumulative net-GEX crossing |
| `callWall` | strike with largest positive call-side GEX |
| `putWall` | strike with largest absolute negative put-side GEX |
| `ivRank` | `ivRank1y` |
| `ivx` | `iv30d`, fallback `iv`, fallback nearest `atmiv` |
| `expectedMove` | `impliedMove`, fallback `spot * atmiv * sqrt(dte / 365)` |
| `skew` | `skewing`, fallback `vol25 - vol75` |
| `asOf` | latest `updatedAt` or `quoteDate` |

### `GexProfile`

| GammaDesk field | Preferred ORATS source |
|---|---|
| `bars[].strike` | `strike` |
| `bars[].callGex` | `gamma`, `callOpenInterest`, normalized spot |
| `bars[].putGex` | `gamma`, `putOpenInterest`, normalized spot |
| `bars[].netGex` | `callGex + putGex` |
| `hvl` | derived from grouped net GEX |
| `callWall` | max grouped call GEX |
| `putWall` | min grouped put GEX |

### `ExpirationRow`

| GammaDesk field | Preferred ORATS source |
|---|---|
| `expirDate` | `expirDate` |
| `dte` | `dte` |
| `netGex` | sum by expiration |
| `callWall` | max call GEX by expiration |
| `putWall` | min put GEX by expiration |
| `ivx` | `atmiv`, fallback `vol50` |
| `skew` | `vol25 - vol75` |
| `expectedMove` | `stockPrice * atmiv * sqrt(max(dte, 1) / 365)` |

## Default clean-room GEX convention

```ts
const contractMultiplier = 100;
const moveScalar = 0.01;

const callGex = +gamma * callOpenInterest * contractMultiplier * spot ** 2 * moveScalar;
const putGex = -gamma * putOpenInterest * contractMultiplier * spot ** 2 * moveScalar;
const netGex = callGex + putGex;
```

Keep this sign convention configurable internally.