---
title: "Options Overlay"
description: "Synthetic options from prediction market prices. Implied volatility, Greeks, vol surfaces, and spread strategies (butterfly, straddle, calendar spread)."
icon: "layer-group"
---

<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
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
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
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
# 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
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
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
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
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>
