Endpoint

GET /v1/dispersion

Auth required (X-Api-Key) Rate Limited: Yes Alpha plan+

Parameters

Name	In	Required	Default	Description
`index`	query	yes	-	Index symbol (e.g. `SPX`, `NDX`, `RUT`). Must have data loaded.
`symbols`	query	yes	-	Comma-separated constituent symbols (max 50, de-duped).
`weights`	query	no	equal	Comma-separated; non-negative; normalised to sum 1.
`horizon_days`	query	no	20	Lookback window in days for realized correlation. Clamped to `[5, 252]`.

curl -H "X-Api-Key: YOUR_API_KEY" \
  "https://lab.flashalpha.com/v1/dispersion?index=SPX&symbols=AAPL,MSFT,NVDA&weights=0.5,0.3,0.2&horizon_days=20"

import requests

resp = requests.get(
    "https://lab.flashalpha.com/v1/dispersion",
    params={
        "index": "SPX",
        "symbols": "AAPL,MSFT,NVDA",
        "weights": "0.5,0.3,0.2",
        "horizon_days": 20,
    },
    headers={"X-Api-Key": "YOUR_API_KEY"}
)
data = resp.json()
print(f"Correlation premium: {data['correlation_premium']}")

const resp = await fetch(
  "https://lab.flashalpha.com/v1/dispersion?index=SPX&symbols=AAPL,MSFT,NVDA&weights=0.5,0.3,0.2&horizon_days=20",
  { headers: { "X-Api-Key": "YOUR_API_KEY" } }
);
const data = await resp.json();
console.log("Correlation premium: " + data.correlation_premium);

API Key

Response

{
  "as_of": "2026-05-29T15:30:00Z",
  "index": "SPX",
  "constituent_count": 3,
  "missing_symbols": [],
  "horizon_days": 20,
  "implied_correlation": 0.412,
  "realized_correlation": 0.385,
  "correlation_premium": 0.027,
  "implied_vol_index": 0.138,
  "implied_vol_basket": 0.224,
  "top_contributors": [
    { "symbol": "NVDA", "weight": 0.20, "iv": 0.46, "contribution_to_basket_vol": 0.092 },
    { "symbol": "AAPL", "weight": 0.50, "iv": 0.18, "contribution_to_basket_vol": 0.090 }
  ]
}

Key Response Fields

Field	Description
`constituent_count`	Number of constituents that survived to the calculator (after drops in `missing_symbols`).
`implied_correlation`	`ρ = (σ²_idx − Σ wᵢ² σᵢ²) / ((Σ wᵢ σᵢ)² − Σ wᵢ² σᵢ²)`. `null` when the denominator is non-positive (degenerate basket - e.g. single constituent or all-zero vols).
`realized_correlation`	Basket-weight-weighted average of `Pearson(log_returns(constituent), log_returns(index))` over the horizon. Weights are the supplied basket weights (renormalised across survivors), not OI weights. `null` when no constituent's Pearson is computable (flat / empty closes).
`correlation_premium`	`implied − realized`. `null` when either side is `null`. Positive ⇒ market pricing in more correlation than realized.
`implied_vol_index`	The index's ATM IV (decimal, e.g. `0.138` = 13.8%).
`implied_vol_basket`	`Σ wᵢ σᵢ` after weight renormalisation across surviving constituents.
`top_contributors[]`	Sorted descending by `contribution_to_basket_vol = wᵢ × σᵢ`. `Σ contribution == implied_vol_basket` by construction.
`missing_symbols[]`	Constituents requested but dropped at controller time (no quote, no greeks snapshots, or no computable ATM IV). Constituents whose historical-close fetch returns empty are kept - they just contribute zero to the realized term. Surviving weights are renormalised internally.

Errors

Status	Description
`400`	`missing_index` / `missing_symbols` / `too_many_symbols` / `invalid_weights` / `weight_count_mismatch`
`403`	Requires Alpha plan or higher
`404`	`index_not_found`, `no_index_iv`, or `no_data` (no constituent survived)

About

Computes the Demeterfi-Derman-Kani implied correlation between an index and a user-supplied basket of constituents, paired with a 1-factor realized correlation over a configurable lookback. It returns correlation_premium = implied − realized and each constituent's contribution to basket vol, sorted descending. This is vol-arb / dispersion-trading math for the quants, vol desks, and systematic researchers in the Alpha persona.

Index IV comes from the same StockSummaryBuilder.ComputeAtmIvFromSnapshots path as /v1/stock/{symbol}/summary - the index must already have options/greeks loaded. The 1-factor realized correlation is the weighted average of each constituent's correlation to the index, which is what's directly comparable to the implied figure. You supply the basket; the endpoint deliberately ships no hardcoded weight tables.

Common Use Cases

Screen for a rich correlation_premium (implied − realized positive) to put on an index-vs-constituents dispersion trade - short index vol, long single-name vol
Compare implied_correlation against realized_correlation to gauge whether the market is over- or under-pricing co-movement
Rank top_contributors[] by contribution_to_basket_vol to size or trim single-name legs around the heaviest vol contributors
Decompose implied_vol_index versus implied_vol_basket to see how much of basket vol is correlation versus single-name level
Sweep horizon_days and alternate baskets to backtest dispersion entry signals across lookbacks
Audit missing_symbols[] and constituent_count so a thin or partially-dropped basket doesn't silently distort the premium

Complementary endpoints

Advanced Volatility (SVI) - fitted single-name surfaces behind each constituent's ATM IV
Exposure Basket - build and weight the same constituent basket for exposure aggregation
Volatility - the per-symbol ATM IV and surface feeding the basket vol terms
Skew Term Structure - per-name wing skew when picking single-stock legs

Dispersion API