# GET /api/mcp/data/term-structure/{ticker}

> Is SPY's IV curve in contango or inverted, and what move does each expiration price?

One row per expiration with the ATM strike, ATM IV, straddle price and the one and two sigma bounds, so the shape of the curve and the priced move at each date come back in a single array.

- **Family:** Implied volatility (https://apexvol.com/developers/implied-volatility-api)
- **Plan:** Premium and above. Every call needs `Authorization: Bearer avmcp_<token>`; tokens are issued to paid and trial accounts under Account, then API Access.
- **Units:** atm_iv is annualised percentage points. expected_move_dollar is dollars, expected_move_pct is percent of spot. straddle_* are option prices in dollars.
- **Basis:** ATM IV is the chain IV at the strike nearest spot. expected_move comes from the straddle price; iv_expected_move is the sigma-based figure from IV and time.
- **MCP tools:** `get_term_structure`
- **Background:** https://apexvol.com/learn/volatility-surface

## Parameters

| Name | In | Default | Range | Meaning |
|---|---|---|---|---|
| `ticker` (required) | path |  | any covered symbol | The underlying, upper case. Use /search to check coverage. |
| `num_expirations` | query | 8 | 1 to 20 | How many expirations to return, nearest first. |

## Request

```bash
curl -H "Authorization: Bearer avmcp_YOUR_TOKEN" \
     "https://apexvol.com/api/mcp/data/term-structure/SPY"
```

## Response (captured 2026-09-08)

Real response, lists cut to the rows nearest the money. The envelope is `{"success": true, "data": ...}`.

```json
{
  "success": true,
  "data": {
    "as_of": "2026-09-08T07:48:58.063902",
    "iv_units": "percentage_points",
    "stock_price": 770.25,
    "term_structure": [
      {
        "atm_iv": 5.92,
        "atm_strike": 770.0,
        "dte": 0,
        "expected_move_dollar": 3.82,
        "expected_move_pct": 0.5,
        "expiration": "2026-09-08",
        "iv_expected_move_dollar": 0.0,
        "iv_expected_move_pct": 0.0,
        "lower_1sigma": 766.43,
        "lower_2sigma": 762.61,
        "straddle_call": 1.98,
        "straddle_price": 3.82,
        "straddle_put": 1.84,
        "upper_1sigma": 774.07,
        "upper_2sigma": 777.89
      },
      {
        "atm_iv": 7.09,
        "atm_strike": 770.0,
        "dte": 1,
        "expected_move_dollar": 5.12,
        "expected_move_pct": 0.66,
        "expiration": "2026-09-09",
        "iv_expected_move_dollar": 2.86,
        "iv_expected_move_pct": 0.37,
        "lower_1sigma": 765.14,
        "lower_2sigma": 760.02,
        "straddle_call": 2.66,
        "straddle_price": 5.12,
        "straddle_put": 2.45,
        "upper_1sigma": 775.36,
        "upper_2sigma": 780.48
      },
      {
        "atm_iv": 8.06,
        "atm_strike": 770.0,
        "dte": 2,
        "expected_move_dollar": 6.38,
        "expected_move_pct": 0.83,
        "expiration": "2026-09-10",
        "iv_expected_move_dollar": 4.6,
        "iv_expected_move_pct": 0.6,
        "lower_1sigma": 763.88,
        "lower_2sigma": 757.5,
        "straddle_call": 3.3,
        "straddle_price": 6.38,
        "straddle_put": 3.08,
        "upper_1sigma": 776.62,
        "upper_2sigma": 783.0
      }
    ],
    "ticker": "SPY"
  }
}
```

## Fields

- `term_structure[].expiration, dte`: The expiration and days to it.
- `term_structure[].atm_iv`: At-the-money implied vol for that expiration.
- `term_structure[].straddle_price`: ATM call plus put, the market's price for the move.
- `term_structure[].expected_move_pct, expected_move_dollar`: The priced move to that date.
- `term_structure[].upper_1sigma, lower_1sigma`: The one-sigma range from the straddle.
- `as_of`: Trade date of the chain.

## Errors

- `401`: no or revoked token
- `429`: Retry-After seconds
- `403`: Premium plan required
- `424`: data feed unavailable, retry
- Full list: https://apexvol.com/developers/errors

## Ask it in an MCP client

- Is SPY's term structure in contango or backwardation right now?
- What move is priced into NVDA for each of the next 6 expirations?
- Show the IV term structure for AAPL and flag any inversion.

Conventions for units, bases and timestamps: https://apexvol.com/developers/conventions