- API Reference
- Volatility Analytics
- Dispersion
Lab API
Dispersion
Dispersion API
Demeterfi-Derman-Kani implied correlation between an index and a user-supplied basket of constituents, paired with a 1-factor realized correlation, plus correlation premium and per-constituent vol contribution.
Endpoint
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);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 − realizedpositive) to put on an index-vs-constituents dispersion trade - short index vol, long single-name vol - Compare
implied_correlationagainstrealized_correlationto gauge whether the market is over- or under-pricing co-movement - Rank
top_contributors[]bycontribution_to_basket_volto size or trim single-name legs around the heaviest vol contributors - Decompose
implied_vol_indexversusimplied_vol_basketto see how much of basket vol is correlation versus single-name level - Sweep
horizon_daysand alternate baskets to backtest dispersion entry signals across lookbacks - Audit
missing_symbols[]andconstituent_countso a thin or partially-dropped basket doesn't silently distort the premium
Related
Related reading
- Complete guide to volatility relative-value trading - where index-vs-constituent dispersion fits in the vol relative-value toolkit
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