RiskModels provides clean dividend-adjusted total returns, factor risk decomposition, return attribution, and ETF-executable hedge ratios for US equities — over REST, a typed SDK, and a built-in MCP server. The dataset is simulation-grade: it covers on the order of 16,000 US stocks across the full historical panel, while at each month end the model’s headline universe is the largest ~3,000 by market cap—the set the API surfaces for everyday returns, risk, and hedging.

Post-regression outputs (hedge ratios, explained-risk decompositions, and related L1–L3 series) are on daily history from 2007 through present; split- and dividend-adjusted returns (the inputs to the rolling regressions) begin 2006-01-04. The API is AI-agent ready, including a built-in Model Context Protocol (MCP) server for seamless integration with LLMs.

RiskModels API Developer Portal

This repository is the authoritative public API reference for the RiskModels equity risk model API, featuring:

• 📖 Model methodology — ERM3 overview (canonical; also mirrored on riskmodels.net)
• 📚 Comprehensive API Documentation — OpenAPI 3.0.3 specification, guides, and examples
• 🌐 Developer Portal — Beautiful Next.js site (this repo) deployed at riskmodels.app
• 🐍 Python & TypeScript Examples — Production-ready code in examples/
• 🤖 AI Agent Integration — MCP server, OAuth2, and agent manifest

🚀 Quick Links

• Python SDK — AOM quickstart (Google Colab): Open notebook · source: sdk/notebooks/riskmodels_aom_colab.ipynb
• Developer Portal: riskmodels.app
• Live API Docs: riskmodels.net/docs/api/erm3
• ERM3 methodology: riskmodels.app/docs/methodology
• Get API Key: riskmodels.app/get-key
• API Terms: riskmodels.net/terms/api
• Issues: github.com/BlueWaterCorp/RiskModels_API/issues
• PyPI (Python SDK): riskmodels-py

Canonical URLs (REST, OpenAPI, and docs)

Use these only for integrations and tooling:

Important: The hostname api.riskmodels.app is not used for the public API or machine-readable docs. Older links or docs that mention it should be treated as obsolete; use riskmodels.app (apex) as above.

📖 API Overview

The RiskModels API provides institutional-grade equity risk analysis:

• Daily factor decompositions — market, sector, subsector explained-risk fractions for the headline ~3,000 largest US stocks by market cap (month-end universe)
• Hedge ratios — dollar-denominated ETF hedge amounts (L1/L2/L3) designed to remain executable with liquid raw ETFs
• Historical time series — split- and dividend-adjusted returns (2006–present) plus rolling hedge ratios and ER (2007–present; factor outputs need a full regression window)
• AI-agent ready — OAuth2, per-request billing, machine-readable manifests

Data coverage: ~16,000 US stocks in the historical panel; ~3,000 largest by market cap at each month end for headline outputs. Updated daily. Factor outputs (HR/ER): 2007 through present. Adjusted return series: 2006-01-04 through present.

Why The Engine Matters

RiskModels is designed to be useful for real portfolio work, not just descriptive analytics:

• 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
• Grounded in a real Security Master — ticker-level outputs sit on top of a point-in-time identity layer built for identifier continuity, symbol changes, and historically defensible shares data
• Hierarchical by design — the model separates market, sector, and subsector structure rather than collapsing everything into a flat beta view
• Tradeable in practice — the published hedge ratios are designed to work with liquid ETFs at execution time, not only with synthetic or orthogonalized factors
• Built on adjusted return series — split- and dividend-adjusted returns make the decomposition and hedge ratios more economically consistent over long horizons

For a deeper explanation of the engine design choices behind these claims, see the methodology docs and API reference.

🐍 Python SDK (riskmodels-py)

Prefer the Python SDK over raw REST for agent-native workflows — ticker resolution, semantic field normalization, validation with instructional errors, and LLM-ready context formatting are built in.

Install (PyPI):

pip install riskmodels-py
# Optional — xarray cube from batch Parquet/CSV:
# pip install riskmodels-py[xarray]
# Optional — snapshot PDF rendering:
# pip install riskmodels-py[pdf]

Quickstart:

from riskmodels import RiskModelsClient, to_llm_context

client = RiskModelsClient.from_env()
pa = client.analyze({"NVDA": 0.4, "AAPL": 0.6})
print(to_llm_context(pa))

Snapshot generation (institutional PDF reports):

from riskmodels.snapshots import get_data_for_r1, render_r1_to_pdf

client = RiskModelsClient.from_env()
data = get_data_for_r1("NVDA", client)       # fetch → R1Data (caches to JSON)
render_r1_to_pdf(data, "NVDA_R1_Risk.pdf")   # render → PDF (~0.3s, no API)

Documentation:

• Package README — install, methods, agent-native helpers
• Quickstart — 60-second setup path
• API Docs — agent-native helpers reference table

Risk intelligence

Charts below are generated from live API data (get_rankings + MAG7 L3 batch metrics) via scripts/generate_readme_assets.py. Set RISKMODELS_API_KEY (free tier is sufficient), run the script from the repo root, then commit ./assets/ and ./public/docs/readme/.

MAG7 — L3 σ-scaled decomposition

_{Same “tech” label, different subsector DNA — bar length ∝ annualized σ; segments = σ × L3 market/sector/subsector risk ratios + residual (HR share). POST /batch/analyze via SDK save_mag7_l3_sigma_rr_png}

Cross-sectional rankings

_{Universe / sector / subsector rank percentile breakdown}

🤖 MCP Server (v3.0.0-agent)

RiskModels includes a first-class MCP (Model Context Protocol) server, enabling AI agents to directly query risk data and perform factor analysis.

MCP Connection (hosted API):

• Endpoint (Streamable HTTP, POST): https://riskmodels.app/api/mcp/sse
• Authentication: Bearer token (API key or OAuth2 JWT)
• Discovery: https://riskmodels.app/.well-known/mcp.json (see OPENAPI_SPEC.yaml)

Local MCP server (mcp/ in this repo) — stdio transport for Cursor / Claude Desktop / Zed: discovers capabilities, schemas, OpenAPI, and SDK-backed live-paper risk tools. Tools shipped here include:

• riskmodels_list_endpoints — List API capabilities (id, method, endpoint, short description)
• riskmodels_get_capability — Full capability record by id (parameters, pricing, examples)
• riskmodels_get_schema — JSON Schema for a response type (e.g. ticker-returns-v2.json)
• riskmodels_decompose, riskmodels_compare, riskmodels_hedge_position, riskmodels_portfolio_decompose, riskmodels_whitepaper_example — Agent-ready SDK outputs with chart_data, suggested_chart, and plain-English summaries

For live risk data and portfolio math, call the REST API (e.g. GET /api/metrics/{ticker}, POST /api/batch/analyze, GET /api/l3-decomposition), the Python SDK (riskmodels-py), or the listed MCP tools.

See mcp/README.md for install and config.

Anthropic Claude (Managed Agents vs Messages API): internal engineering design for optional cloud-hosted agents, billing, and compliance — see docs/ANTHROPIC_CLOUD_AGENTS.md.

⌨️ Command-line CLI (riskmodels)