# Alphagbm Vol Surface

> >

- **Type:** Skill
- **Install:** `agentstack add skill-alphagbm-skills-alphagbm-vol-surface`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [AlphaGBM](https://agentstack.voostack.com/s/alphagbm)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [AlphaGBM](https://github.com/AlphaGBM)
- **Source:** https://github.com/AlphaGBM/skills/tree/main/skills/alphagbm-vol-surface
- **Website:** https://www.alphagbm.com/skills

## Install

```sh
agentstack add skill-alphagbm-skills-alphagbm-vol-surface
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# AlphaGBM Volatility Surface

## Prerequisites

- **API Key**: Set env `ALPHAGBM_API_KEY` (format `agbm_xxxx...`).
- **Base URL**: Default `https://alphagbm.zeabur.app`. Override with env `ALPHAGBM_BASE_URL`.

## What This Skill Does

Builds a **3D volatility surface** for any optionable ticker, mapping implied volatility across two dimensions -- strike price (moneyness) and time to expiration. Identifies where options are cheap, expensive, or anomalous relative to the surface.

### Key Outputs

| Output | What It Shows |
|--------|--------------|
| **Surface Grid** | IV at each (strike, expiry) coordinate -- the full 3D map |
| **ATM Term Structure** | How at-the-money IV changes across expirations (front-month vs. back-month) |
| **Skew by Expiry** | Put-call IV differential at each expiration -- measures fear/complacency |
| **Surface Anomalies** | Points where IV deviates significantly from the fitted surface -- potential mispricings |
| **Surface Shape** | Classification: contango, backwardation, flat, inverted, event-driven |

### What the Surface Tells You

- **Contango** (front IV  back IV): Near-term event expected (earnings, FDA, etc.)
- **Steep skew**: Market pricing tail risk in puts -- hedging demand is high
- **Flat skew**: Balanced sentiment -- no strong directional fear
- **Anomaly detected**: A specific contract is mispriced vs. neighbors -- potential opportunity

### Volatility Risk Premium (VRP)

```
VRP = Implied Vol - Historical Vol
```

| VRP Level | Seller | Buyer |
|-----------|--------|-------|
| very_high (>=15%) | Very favorable | Unfavorable |
| high (5-15%) | Favorable | Slightly unfavorable |
| normal (+/-5%) | Neutral | Neutral |
| low (-15% to -5%) | Unfavorable | Favorable |
| very_low (
```

Returns the full 3D volatility surface with moneyness axis, expiry axis, and IV grid.

### IV Snapshot (quick check, no quota cost)

For a fast ATM IV / IV Rank / HV / VRP check without pulling the full surface:

```
GET /api/options/snapshot/
```

Returns: ATM IV, IV Rank, HV 30d, VRP, VRP level.

## How to Use

### Input
- **Required**: Ticker symbol
- **Optional**: Moneyness range (e.g., 0.8-1.2), expiration range (e.g., 7-90 days)

### Output Structure

```json
{
  "ticker": "AAPL",
  "price": 218.45,
  "surface": {
    "moneyness_axis": [0.85, 0.90, 0.95, 1.00, 1.05, 1.10, 1.15],
    "expiry_axis": ["2026-04-04", "2026-04-18", "2026-05-16", "2026-06-20"],
    "iv_grid": [
      [38.2, 34.5, 31.0, 28.5, 30.2, 33.1, 36.8],
      [36.1, 33.0, 29.8, 27.2, 28.9, 31.5, 34.9],
      [34.5, 31.8, 28.5, 26.0, 27.5, 30.0, 33.2],
      [33.0, 30.5, 27.8, 25.5, 26.8, 29.0, 31.8]
    ]
  },
  "atm_term_structure": {
    "2026-04-04": 28.5,
    "2026-04-18": 27.2,
    "2026-05-16": 26.0,
    "2026-06-20": 25.5
  },
  "skew": {
    "2026-04-18": {"25d_put_iv": 33.0, "25d_call_iv": 28.9, "skew": -4.1}
  },
  "shape": "contango",
  "anomalies": [
    {
      "strike": 200,
      "expiry": "2026-04-18",
      "iv": 38.5,
      "expected_iv": 34.2,
      "deviation_sigma": 2.3,
      "signal": "overpriced"
    }
  ]
}
```

### Example Queries

| User Says | What Happens |
|-----------|-------------|
| "Vol surface AAPL" | Full 3D surface with term structure, skew, anomalies |
| "Is NVDA IV expensive?" | Compares current surface to 30-day historical average |
| "Volatility term structure SPY" | ATM IV across all expirations with shape classification |
| "Surface analysis TSLA" | Full surface + anomaly detection for mispriced contracts |
| "Front-month vs back-month IV for META" | Term structure with contango/backwardation call |

### Mock Data

Demo tickers available without API key: AAPL, NVDA, SPY, TSLA, META. Surface data uses realistic IV snapshots from `mock-data/`.

### Related Skills
- **alphagbm-vol-smile** -- Zoom into a single expiration's smile/skew curve
- **alphagbm-iv-rank** -- Is IV high or low vs. its own history?
- **alphagbm-options-score** -- Use surface insights to find the best-scored contracts
- **alphagbm-options-strategy** -- High IV surface suggests selling premium; low IV suggests buying

---

*Powered by [AlphaGBM](https://alphagbm.com) -- Real-data options & research intelligence for traders and AI agents. 10K+ users.*

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [AlphaGBM](https://github.com/AlphaGBM)
- **Source:** [AlphaGBM/skills](https://github.com/AlphaGBM/skills)
- **License:** MIT
- **Homepage:** https://www.alphagbm.com/skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-alphagbm-skills-alphagbm-vol-surface
- Seller: https://agentstack.voostack.com/s/alphagbm
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.