RiskModels API Documentation

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_etf_factor_returns(sleeve="all")

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