RiskModels API Documentation

This repository is the authoritative reference for the ERM3 hierarchical equity risk model API—built for quant developers and AI agents who need residual risk, hedge ratios, and explained risk with production-grade fidelity. POST /decompose returns variance shares and ETF hedge ratios for any US equity, separating factor exposure from the residual bet so you can hedge what you don't want.

Live API snapshots

MAG7 macro correlations (L3 residual) and a cross-sectional rank snapshot — produced by scripts/generate_readme_assets.py with your API key, same assets as the GitHub README.

Macro sensitivity (VIX, Gold, BTC)

Rank percentile (get_rankings)

Overview

The RiskModels API provides institutional-grade equity risk analysis for AI agents and quantitative applications:

• Daily factor decompositions — market, sector, and subsector explained-risk fractions for ~3,000 US equities
• Hedge ratios — dollar-denominated ETF hedge amounts at three precision levels (L1 market-only, L2 market+sector, L3 full three-ETF)
• Historical time series — split- and dividend-adjusted daily returns plus rolling hedge ratios going back to 2006
• AI-agent ready — machine-readable manifest at /.well-known/agent-manifest, per-request billing via prepaid balance

Data coverage: Universe uni_mc_3000 (~3,000 top US stocks), date range 2006-01-04 to present, updated daily.

Why The Engine Matters

• Built to be time-safe — the engine is designed to avoid common sources of forward contamination such as recycled tickers, snapshot shares, and retroactive universe contraction
• Backed by a real Security Master — point-in-time identity, classification, and shares logic support more stable ticker-level outputs
• Hierarchical by design — market, sector, and subsector structure are modeled explicitly rather than compressed into a flat beta view
• Tradeable in practice — hedge ratios are designed to remain executable with liquid raw ETFs, not just synthetic factors
• Built on adjusted returns — split- and dividend-adjusted return series improve consistency through corporate actions and long horizons

For the mathematical detail behind L1/L2/L3 decomposition and hedge construction, see Methodology. For the design choices behind time safety, identity continuity, and tradeable hedge outputs, see ERM3 Engine.

Choose Your Workflow

Risk Metrics

Beyond static HR/ER snapshots, RiskModels exposes on-demand correlation of equity returns against daily macro factor returns (cross-asset context for regimes and crowding).

Core Endpoints

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_ticker_returns("NVDA", years=5)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_metrics("NVDA", as_dataframe=True)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().decompose("NVDA")

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_lstar("NFLX", years=5)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_l3_decomposition("NVDA")

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_factor_correlation_single("NVDA", factors=["vix","bitcoin"])

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().batch_analyze(["NVDA","AAPL"], ["returns","full_metrics"], years=2)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_returns_decomposition("AAPL", years=5, include_lstar=True)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_industry_panel(level="subsector")

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().screen_rankings(metric="subsector_residual", cohort="subsector", window="21d", min_percentile=95)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().batch_lstar(["AAPL","MSFT","NVDA"], years=5)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_universe_members("uni_mc_3000")

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().get_residual_signal_basket(["AAPL","MSFT","NVDA"], signal_quality_min_quintile=4)

from riskmodels import RiskModelsClient; RiskModelsClient.from_env().search_tickers(search="NVDA")

from riskmodels import RiskModelsClient; RiskModelsClient.from_env()._transport.request("GET", "/balance")[0]

from riskmodels import RiskModelsClient; RiskModelsClient.from_env()._transport.request("GET", "/invoices")[0]

from riskmodels import RiskModelsClient; RiskModelsClient.from_env()._transport.request("GET", "/health")[0]

import httpx; httpx.get("https://riskmodels.app/.well-known/agent-manifest", timeout=30).json()

MCP coverage note: riskmodels_list_endpoints returns capability bundles, not a 1:1 mirror of every route above. Account routes (/balance, /invoices) and the agent manifest ( /.well-known/agent-manifest) are documented here but do not appear as separate MCP tool IDs.

Pricing model: prepaid balance (Stripe). Cached responses are free. Minimum top-up: 10.

POST /decompose — one call, four bets

POST /decompose is a semantic wrapper over the same L3 fields exposed by GET /metrics/{'{ticker}'}. It returns four additive layers — market, sector, subsector, and residual — each tradable layer carrying an er (explained-risk variance fraction), an hr (dollar-ratio hedge ratio), and a hedge_etf. A top-level hedge map flips the sign (negative of each layer hr) and sums across any duplicate ETFs, so you get ready-to-short notionals per instrument.

Billing is identical to GET /metrics/{'{ticker}'} (0.001/call, billing_code: metrics_v3). For the full L1/L2/L3 snapshot (all six HR names), keep using GET /metrics/{'{ticker}'}. For the plain-language intuition behind the four bets — and a worked NVIDIA example — see the four-bets primer on riskmodels.org.

Request

curl -X POST https://riskmodels.app/api/decompose \
  -H "Authorization: Bearer $RISKMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ticker":"NVDA"}'

Response

{
  "ticker": "NVDA",
  "data_as_of": "2026-04-21",
  "exposure": {
    "market":    { "er": 0.45, "hr": 1.10, "hedge_etf": "SPY" },
    "sector":    { "er": 0.22, "hr": 0.35, "hedge_etf": "XLK" },
    "subsector": { "er": 0.20, "hr": 0.60, "hedge_etf": "SMH" },
    "residual":  { "er": 0.13, "hr": null, "hedge_etf": null }
  },
  "hedge": { "SPY": -1.10, "XLK": -0.35, "SMH": -0.60 }
}

Sign convention. hedge[etf] is the negative of the layer hr. Positive stock hr → negative ETF dollar ratio (short the ETF per 1 long stock). Negative stock hr → positive ETF dollar ratio (long the ETF as the hedge leg). Residual has no tradable ETF, so its hr and hedge_etf are always null.

ER invariant. Across the four layers, market_er + sector_er + subsector_er + residual_er ≈ 1 (variance fractions). The handler emits a warning when the sum deviates by more than 0.05.

Compare cascade depth: hedge_levels

POST /decompose is the four additive L3-factor bets view (exposure / hedge). Many routes also return a parallel hedge_levels object with L1, L2, and L3 keys. Each value is a snapshot of that standalone hedge depth: semantic market_hr / sector_hr / subsector_hr, matching market_er / sector_er / subsector_er / residual_er, and hedge_etfs (market / sector / subsector tickers). L2.market_hr is always sourced from l2_mkt_hr on the flat metrics row, L3.market_hr from l3_mkt_hr — cascade levels never share prefixed HR or ER inputs across L1 / L2 / L3. Use hedge_levels when you need to choose whether to trade a one-ETF, two-ETF, or three-ETF hedge; keep using exposure for the telescoping four-layer story. See SEMANTIC_ALIASES.md and the OpenAPI HedgeLevelsBlock component.

GET /lstar — historical level dispatch + residual returns

GET /api/lstar returns daily series for one ticker: the server picks L1, L2, or L3 per date using marginal explained-return vs a threshold (default 1%, override with ?threshold=). Parallel arrays include lstar, dispatched market_hr / sector_hr / subsector_hr (nulls below the chosen level), total_er, and residual_return — the daily residual at the chosen level (l1_rr, l2_rr, or l3_rr). Raw l2_sector_er and l3_subsector_er are included for audit.

Billing: 0.02/call (billing_code: lstar_v1). MCP capability id lstar; Python SDK: client.get_lstar(ticker, years=5).

curl -sS "https://riskmodels.app/api/lstar?ticker=NFLX&years=5" \
  -H "Authorization: Bearer $RISKMODELS_API_KEY" \
  | jq '{ticker, threshold_used, last: {lstar: .lstar[-1], residual_return: .residual_return[-1]}}'

Panel path — lstar_rr + lstar_level in MetricsV3

For cross-sectional workflows ("best residual for the universe today", not "one ticker over time"), use the MetricsV3 companion pair lstar_rr + lstar_level instead of the per-ticker /api/lstar endpoint. Both are materialized in the returns zarr at the canonical 1% threshold and surfaced on GET /api/metrics/{ticker}, POST /api/batch/analyze, and the V3 history fetches — no per-ticker round-trips.

• lstar_rr — the Lstar-dispatched residual return at the level the model picked (L1 → market, L2 → sector, L3 → subsector residual).
• lstar_level — which level Lstar dispatched to: 1 = L1, 2 = L2, 3 = L3, null = no recommendation (both L2 and L3 ER missing).

Prefer lstar_rr over l3_rr when you want "the residual" — l3_rr is fixed at L3 regardless of whether subsector hedging is statistically warranted, so it overstates cleanness for names where lstar_level is 1 or 2. For a non-default threshold, fall back to the per-ticker /api/lstar?threshold=… path above.

curl -sS "https://riskmodels.app/api/metrics/AAPL" \
  -H "Authorization: Bearer $RISKMODELS_API_KEY" \
  | jq '.metrics | {lstar_rr, lstar_level}'

GET /returns-decomposition — full daily decomposition in one call

GET /api/returns-decomposition returns the daily gross return plus the L1/L2/L3 factor return, combined-factor return, and residual return series for one ticker — everything from the returns-decomposition zarr in a single response. Use this instead of pulling l1_cfr, l1_fr, l1_rr, l2_cfr, … one key at a time. Add ?include_lstar=true (or ?dispatch=lstar) to append the Lstar level per date and the Lstar-dispatched residual return.

Billing: 0.02/call (billing_code: returns_decomposition_v1). Python SDK: client.get_returns_decomposition(ticker, years=5, include_lstar=True).

curl -sS "https://riskmodels.app/api/returns-decomposition?ticker=AAPL&years=5&include_lstar=true" \
  -H "Authorization: Bearer $RISKMODELS_API_KEY" \
  | jq '{ticker, last: {gross: .gross[-1], l3_rr: .l3_rr[-1], lstar: .lstar[-1], lstar_rr: .lstar_residual_return[-1]}}'

See returns-decomposition-metrics for the per-key cheatsheet and the "Which residual?" guidance.

GET /industry-panel — Vasicek peer-β cross-section

GET /api/industry-panel returns the industry × level peer-β cross-section from the ds_erm3_industry zarr at one trading day (latest by default). Each row is one EODHD 4-digit industry at one cascade level (market / sector / subsector) with beta_mean, beta_variance, n_companies, and total_log_mcap_weight. This is the macro / sector-rotation surface — what the model thinks an industry's "typical" β is across its cap-weighted peer group.

Filter with ?level= (single level), ?teo=YYYY-MM-DD (single day), or ?min_peers= (drop thin industries). Billing: 0.02/call (billing_code: industry_panel_v1). Python SDK: client.get_industry_panel(level="subsector").

curl -sS "https://riskmodels.app/api/industry-panel?level=subsector&min_peers=20" \
  -H "Authorization: Bearer $RISKMODELS_API_KEY" \
  | jq '.industries | sort_by(.beta_variance) | reverse | .[:5]'

The full panel is small (~72 industries × 3 levels × 4 metrics) — a 1 KB response that answers "which industries dispersed the most in β this period?" without any per-ticker round-trips.

POST /rankings/screen — universe-wide rank filter

POST /api/rankings/screen runs a server-side filter over the full ds_rankings cross-section at one teo (latest by default). Pick a metric (mkt_cap / gross_return / sector_residual / subsector_residual / er_l1 / er_l2 / er_l3), a cohort (universe / sector / subsector), and a window (1d / 21d / 63d / 252d); then filter by min_percentile, decile (1 = best), or sector_filter (sector-ETF ticker). Returns up to 500 rows sorted by rank_ordinal (1 = best, rank_percentile 100 = best).

The stat-arb cross-section in one call — replaces N per-ticker /rankings round-trips. Billing: 0.02/call (billing_code: rankings_screen_v1). Python SDK: client.screen_rankings(metric=..., cohort=..., window=..., min_percentile=95).

curl -sS -X POST "https://riskmodels.app/api/rankings/screen" \
  -H "Authorization: Bearer $RISKMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"metric":"subsector_residual","cohort":"subsector","window":"21d","min_percentile":95,"limit":50}' \
  | jq '{teo, count: (.rows | length), top3: .rows[:3]}'

POST /batch/lstar — multi-ticker Lstar history

POST /api/batch/lstar is the panel-friendly Lstar surface: up to 100 tickers in one call, each returning the same daily series as GET /lstar (per-date lstar level, dispatched HRs, total ER, residual return). Pair with lstar_rr / lstar_level in MetricsV3 — that's the single-name latest snapshot; this is per-ticker history across a panel.

JSON returns a results map keyed by ticker; parquet/csv returns one long DataFrame ready for cross-sectional analysis. 0.005/ticker, min 0.01/call (25% cheaper than repeated GET /lstar). Python SDK: client.batch_lstar(tickers, years=5) + batch_lstar_to_dataframes() to split into per-ticker frames.

curl -sS -X POST "https://riskmodels.app/api/batch/lstar" \
  -H "Authorization: Bearer $RISKMODELS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tickers":["AAPL","MSFT","NVDA","META","GOOG","AMZN","TSLA"],"years":5}' \
  | jq '.results | to_entries | map({ticker:.key, last_lstar: .value.lstar[-1], last_rr: .value.residual_return[-1]})'

🤖 Agent-Native Helpers (Python SDK)

The riskmodels-py package includes methods and metadata designed for agent workflows and LLM reasoning:

Grounding wire keys in docs: to_llm_context() pulls legend, lineage, and riskmodels_semantic_cheatsheet from object attrs — aligned with the same wire↔semantic definitions as

. Treat that file as narrative ground truth when explaining API JSON: e.g. wire l3_res_er → idiosyncratic variance share ( l3_residual_er in SDK output) so agents self-correct instead of guessing meanings.

Install from PyPI (riskmodels-py). With xarray support for multi-dimensional portfolio math:

pip install riskmodels-py[xarray]

Minimal patterns

from riskmodels import RiskModelsClient

# Credentials from env (see Quickstart for variable names)
client = RiskModelsClient.from_env()

df = client.get_metrics("NVDA", as_dataframe=True)  # attrs: legend, cheatsheet, lineage
pa = client.analyze({"NVDA": 0.5, "AAPL": 0.5})     # portfolio hedge ratios + per-name tables

# Requires the [xarray] extra — batch long table → labeled dimensions
ds = client.get_dataset(["NVDA", "AAPL", "MSFT"], years=2)
# ds is suitable for to_llm_context(ds) and broadcasted portfolio math (see Methodology)

See the package README for complete method signatures and examples.

Support

• Issues & feature requests: github.com/BlueWaterCorp/RiskModels_API/issues
• Email: service@riskmodels.app

Related