---
name: impliedoptions
description: Options market data, flow, IV, GEX, and P&L tools via REST or MCP.
---

# ImpliedOptions

## When to use

Use when a task needs US equity options data: unusual flow (blocks, sweeps, strategies), option chains and quotes, implied volatility context, expected moves, gamma exposure and max pain, multi-leg P&L modeling, or the user’s positions, watchlist and flow alerts.

## Auth

Every call sends `Authorization: Bearer io_live_…`. Export the key once: `export IMPLIEDOPTIONS_API_KEY=io_live_…` (create one at https://impliedoptions.com/account). OAuth 2.1 access tokens (`io_at_…`) work in the same header.

## Base URL

`https://impliedoptions.com/api/v1` — call `POST /tools/{name}` with a JSON body of the arguments; read tools also accept `GET /tools/{name}?arg=value` (arrays as CSV). MCP endpoint: `https://impliedoptions.com/mcp`. Full list: `GET https://impliedoptions.com/api/v1/tools`.

Responses: `{ "data": …, "meta": { "tool", "args", "freshness", "as_of", "truncated?", "total?", "next_cursor?", "duration_ms" } }`. Write tools accept `Idempotency-Key` (replays within 24h return the first result) and `X-Dry-Run: true` (returns the would-be change without persisting).

## Recipes

### Scan options flow — `flow.search`

Unusual options prints (blocks, sweeps, complex, strategies) filtered by ticker, type, side, premium and DTE. Free callers get 15-minute delayed prints capped at 50 rows.

```bash
curl -X POST https://impliedoptions.com/api/v1/tools/flow.search \
  -H "Authorization: Bearer $IMPLIEDOPTIONS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"tickers":["SPY","QQQ"],"min_premium":1000000,"limit":20}'
```

### Pull an option chain — `chain.get`

Option chain for one expiration with bid/ask, volume, open interest, IV and greeks per contract. Defaults to the nearest expiration; free callers are 15-minute delayed and capped at 50 contracts.

```bash
curl -X POST https://impliedoptions.com/api/v1/tools/chain.get \
  -H "Authorization: Bearer $IMPLIEDOPTIONS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"symbol":"SPY","strikes_around":10}'
```

### Model a multi-leg P&L — `pnl.model`

Black-Scholes P&L for a 1–8 leg option position: P&L grid now and at expiration, per-leg and net Greeks, break-evens, max profit/loss and probability of profit. Missing prices, IVs and spot are marked from the live chain.

```bash
curl -X POST https://impliedoptions.com/api/v1/tools/pnl.model \
  -H "Authorization: Bearer $IMPLIEDOPTIONS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"legs":[{"occ":"SPY260918C00620000","qty":1},{"occ":"SPY260918C00640000","qty":-1}]}'
```

### Add symbols to the watchlist — `watchlist.add`

Adds symbols to the watchlist; symbols already present are ignored.

```bash
curl -X POST https://impliedoptions.com/api/v1/tools/watchlist.add \
  -H "Authorization: Bearer $IMPLIEDOPTIONS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"symbols":["SPY","NVDA"]}'
```

### Create a flow alert — `alerts.create`

Creates a flow alert that fires when new options flow matches the filters. Free accounts may hold one alert.

```bash
curl -X POST https://impliedoptions.com/api/v1/tools/alerts.create \
  -H "Authorization: Bearer $IMPLIEDOPTIONS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"name":"NVDA big call sweeps","filters":{"tickers":["NVDA"],"rights":["C"],"min_premium":500000}}'
```

## Errors

Failures are `application/problem+json` (RFC 9457): `{ "type": "https://impliedoptions.com/docs/errors#<code>", "title", "status", "detail", "tool", "retry_after?", "errors?" }`.

| type | status | meaning |
|---|---|---|
| unauthorized | 401 | Missing or invalid credentials |
| forbidden | 403 | Credential lacks the required scope |
| tier_required | 403 | Tool needs the Paid plan |
| quota_exceeded | 429 | Daily call limit hit; `retry_after` is seconds until reset |
| invalid_args | 400 | Arguments failed validation; see `errors[]` (`path`, `message`) |
| symbol_unknown | 404 | Ticker not found |
| not_found | 404 | Tool or record not found |
| conflict | 409 | Write conflicts with existing state |
| upstream_unavailable | 502 | Data source unreachable; retry with backoff |
| internal | 500 | Unexpected failure |

## Limits

- Free: 15-minute delayed data, 50 rows per response, 500 calls/day. Anonymous runs share a smaller per-IP quota.
- Paid: realtime data, up to 2000 rows per response, unlimited calls. Responses report meta.truncated and meta.total when capped.