# Options flow API

2 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-flow-api

| Endpoint | Plan | What it answers |
|---|---|---|
| `GET /flow/{ticker}` | Premium | What are the largest NVDA option trades today, and are they bullish or bearish? |
| `GET /smart-money/{ticker}` | Premium | Which NVDA trades look institutional today? |

## GET /flow/{ticker}

Returns the largest flows, the unusual activity (volume far above open interest), the full flow list, the most active strikes and expirations, and a summary with net premium and a sentiment label. Compact detail caps the row lists.

- **Units:** premium in dollars; volume and oi in contracts; volume_oi_ratio unitless.
- **Basis:** Aggregated from today's cumulative volume by contract; is_market_hours and data_freshness say how live the data is.
- **Markdown:** https://apexvol.com/developers/options-flow-api/flow.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `detail` | query | full for REST, compact for MCP clients | compact or full | Capped lists or everything. |
| `limit` | query | 25 | rows in all_flow under compact | Row cap. |

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/flow/NVDA?detail=compact&limit=5"
```

- `summary.sentiment, net_premium, call_put_ratio`: The read in three numbers.
- `largest_flows[].strike, expiration, type, premium, volume, oi`: The biggest tickets.
- `unusual_activity[]`: Contracts where volume dwarfs open interest.
- `top_strikes, top_expirations`: Where the activity clusters.
- `window`: What compact detail trimmed.

## GET /smart-money/{ticker}

Filters today's flow for large premium, likely opening positions and out-of-the-money contracts with time, returns each with the criteria it met and a score.

- **Units:** premium in dollars; smart_money_score is a 0 to 100 heuristic.
- **Basis:** Heuristic filters on the same flow data as /flow; not attributed to any counterparty.
- **Markdown:** https://apexvol.com/developers/options-flow-api/smart-money.md

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |

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

- `smart_money_trades[].strike, expiration, type, premium, volume, oi`: The trade.
- `smart_money_trades[].criteria, smart_money_score`: Why it qualified.
- `total_smart_trades`: Count.

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