RiskModels

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 served from the first date whose full estimation window is covered: hedge ratios from 2010-12-08, explained-risk shares and stock variance from 2011-12-07, **L\* residual levels from 2013-01-01. 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

---

Use in Cursor (Agent Plugin)

This repository is an Agent Plugins package: plugin.json and mcp.json at the repository root. The plugin connects Cursor to the hosted RiskModels MCP server. It contains no code that runs on your machine and no credentials.

Install

1. In Cursor, open the Marketplace and search for RiskModels.
2. Install it for your user or for the current project.
3. Cursor adds the riskmodels MCP server. Its tools appear once you sign in.

Sign in

The server uses OAuth 2.1 with PKCE. Cursor handles the flow, and nothing goes in the plugin files:

1. When Cursor first connects to the riskmodels server, the server asks for sign-in and Cursor opens a browser at riskmodels.app.
2. Sign in with Google or an email link, or choose Sign in with a password instead.
3. The consent screen shows Signed in as <email>. If that is the wrong account, click Use a different account first, then Allow.
4. Cursor stores the token. The tools are read-only: they return data and never place orders or change your account.

Pricing and account

• A RiskModels account is required. New accounts start with $20 of prepaid credit. A payment method is collected at signup for verification and is not charged until you top up.
• Usage is pay-as-you-go and billed per tool call against that balance. Most single-stock calls cost $0.005; fundamentals cost $0.02, and a full portfolio exposure report costs $0.25. Rates and plans: riskmodels.app/pricing.
• Optional: link a brokerage account (Alpaca, Connect Trade or Plaid) in riskmodels.net Settings, and riskmodels_get_my_positions reads that book.

Example: NVDA

Ask in Cursor's agent chat:

Decompose NVDA's risk with RiskModels and give me the ETF hedge for a $100,000 position.

The agent calls riskmodels_decompose for the market / sector / subsector / stock-specific split of NVDA's variance and the hedge ratio at each level. Then it calls riskmodels_decompose again with a dollar amount to turn those ratios into dollar trades in SPY and the sector and subsector ETFs. The numbers are live model output as of the latest trading day.

The Claude plugin (claude-plugin/) and the local developer MCP server (.cursor/mcp.json, mcp/) are separate and unchanged.

---

🚀 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-01-04–present) plus rolling hedge ratios (2010-12-08–present) and ER (2011-12-07–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. Hedge ratios: 2010-12-08 through present. Explained risk: 2011-12-07 through present. **L\* levels: 2013-01-01 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
• Named endpoints: /api/mcp/openai and /api/mcp/sse remain supported
• 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, `@riskmodels/mcp` 2.0.0) — stdio transport for Cursor / Claude Desktop / Zed. Tool set 2.0 is one registry shared with the hosted endpoints: 25 tools locally, 26 hosted (adds riskmodels_render_artifact):

riskmodels_get_stock_snapshot, riskmodels_decompose, riskmodels_compare, riskmodels_get_returns, `ris