> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Options Overlay

> Synthetic options from prediction market prices. Implied volatility, Greeks, vol surfaces, and spread strategies (butterfly, straddle, calendar spread).

<Warning>
  **Ultra Feature.** Requires an Ultra subscription. [Get started at api.mathematicalcompany.com](https://api.mathematicalcompany.com)
</Warning>

# Options Overlay

Prediction markets are binary options. They have implied volatility, Greeks, and a term structure. Horizon's options overlay extracts these from market prices and builds synthetic spread strategies. All math is in Rust.

## Overview

<CardGroup cols={2}>
  <Card title="Options Chain" icon="table-list">
    `hz.build_options_chain()` computes IV, delta, gamma, theta, and vega from binary prices.
  </Card>

  <Card title="Vol Surface" icon="mountain">
    `hz.vol_surface()` maps implied vol across strikes and expiries.
  </Card>

  <Card title="Term Structure" icon="chart-line">
    `hz.term_structure()` extracts the IV term structure.
  </Card>

  <Card title="Spread Strategies" icon="arrows-left-right">
    Butterfly, straddle, and calendar spread construction.
  </Card>
</CardGroup>

***

## Core Functions

### hz.build\_options\_chain

Build a synthetic options chain with Greeks from prediction market prices.

```python theme={null}
import horizon as hz

chain = hz.build_options_chain(
    market_ids=["btc_100k", "btc_150k", "btc_200k"],
    prices=[0.60, 0.35, 0.10],
    expiry_days=[30.0, 30.0, 30.0],
)
for opt in chain:
    print(f"{opt.market_id}: IV={opt.implied_vol:.2%}, "
          f"delta={opt.delta:.4f}, gamma={opt.gamma:.4f}")
```

| Parameter     | Type          | Description           |
| ------------- | ------------- | --------------------- |
| `market_ids`  | `list[str]`   | Market identifiers    |
| `prices`      | `list[float]` | Current binary prices |
| `expiry_days` | `list[float]` | Days to expiry        |

Returns a list of `SyntheticOption` objects with fields: `market_id`, `price`, `implied_vol`, `delta`, `gamma`, `theta`, `vega`.

### hz.vol\_surface

Build a volatility surface across strikes and expiries.

```python theme={null}
surface = hz.vol_surface(
    strikes=[0.3, 0.5, 0.7],
    expiry_days=[7.0, 30.0, 90.0],
    prices=[0.60, 0.50, 0.35],
)
for point in surface:
    print(f"Strike={point.strike:.2f}, Expiry={point.expiry_days:.0f}d, IV={point.implied_vol:.2%}")
```

### hz.term\_structure

Extract the IV term structure for a single strike across different expiries.

```python theme={null}
ts = hz.term_structure(
    prices=[0.60, 0.55, 0.50],
    expiry_days=[7.0, 30.0, 90.0],
)
for point in ts:
    print(f"{point.expiry_days:.0f}d: IV={point.implied_vol:.2%}")
```

### Spread Strategies

```python theme={null}
# Butterfly spread: buy wing, sell body, buy wing
butterfly = hz.synthetic_butterfly(
    prices=[0.60, 0.50, 0.35],
    market_ids=["low", "mid", "high"],
    size=10.0,
)

# Straddle: buy both sides around fair
straddle = hz.synthetic_straddle(
    price=0.50, market_id="btc_100k", size=10.0,
)

# Calendar spread: buy far expiry, sell near expiry
legs = hz.calendar_spread_legs(
    near_price=0.55, far_price=0.50,
    near_id="btc_march", far_id="btc_june",
    size=10.0,
)
```

***

## Pipeline Functions

### hz.options\_chain

Build and track the options chain each cycle.

```python theme={null}
chain = hz.options_chain(
    market_feeds={"btc_100k": "btc_feed", "btc_150k": "btc_150k_feed"},
    default_expiry=30.0,
)
```

| Parameter        | Type               | Default  | Description                      |
| ---------------- | ------------------ | -------- | -------------------------------- |
| `market_feeds`   | `dict[str, str]`   | required | market\_id -> feed\_name mapping |
| `expiry_days`    | `dict[str, float]` | `None`   | Per-market expiry overrides      |
| `default_expiry` | `float`            | `30.0`   | Default days to expiry           |

### hz.delta\_hedge\_continuous

Continuous delta hedging. Flags when delta drift exceeds a threshold.

```python theme={null}
hedger = hz.delta_hedge_continuous(
    market_feeds={"btc_100k": "btc_feed"},
    hedge_threshold=0.1,
    default_expiry=30.0,
)
```

### hz.vol\_surface\_monitor

Track the vol surface and detect IV changes.

```python theme={null}
monitor = hz.vol_surface_monitor(
    market_feeds={"btc_100k": "btc_feed", "btc_150k": "btc_150k_feed"},
    default_expiry=30.0,
)
```

***

## Examples

### Options-Aware Trading

```python theme={null}
import horizon as hz

def vol_strategy(ctx):
    avg_iv = ctx.params.get("avg_iv", 0.0)
    iv_change = ctx.params.get("iv_change", 0.0)
    if iv_change > 0.05:  # vol spike
        return []  # stand aside
    return hz.quotes(fair=ctx.feed.price, spread=0.03, size=10)

hz.run(
    name="vol_aware",
    feeds={"btc": hz.PolymarketBook("will-btc-hit-100k")},
    pipeline=[
        hz.vol_surface_monitor(market_feeds={"btc": "btc"}),
        vol_strategy,
    ],
)
```

***

## Mathematical Background

<AccordionGroup>
  <Accordion title="Binary Option Implied Volatility">
    For a binary option paying 1 if the event occurs:

    **price = N(d2)** where **d2 = -sigma \* sqrt(T) / 2**

    IV is extracted by inverting this relationship via bisection. Prices near 0.5 have the highest vega (most sensitive to vol changes).
  </Accordion>

  <Accordion title="Binary Greeks">
    * **Delta**: dP/dS, sensitivity to underlying. For binaries, delta peaks at-the-money.
    * **Gamma**: d2P/dS2, rate of delta change.
    * **Theta**: dP/dT, time decay. Binaries gain theta as they move away from 0.5.
    * **Vega**: dP/dsigma, sensitivity to implied vol.
  </Accordion>
</AccordionGroup>