# RiskModels

Position-up equity risk decomposition. Paste any portfolio, get a structured snapshot of market, sector, sub-sector, and residual risk plus per-position hedge ratios — in one call, no setup.

## Canonical agent discovery (MCP, curl, optional MAG7 demo key)

Machine-readable install steps, MCP wiring, and — when enabled by the host — a **shared public sample API key** for MAG7 smoke tests live on the developer portal (single source of truth; updates there flow to agents automatically):

**https://riskmodels.app/llms.txt**

This file (`riskmodels.net/llms.txt`) stays product-oriented; use the link above for programming agents and crawlers that need Bearer auth examples.

**MAG7 tickers** (Magnificent 7, for demos): AAPL, MSFT, GOOG, AMZN, NVDA, META, TSLA — use **GOOG** for Alphabet class A (**GOOGL** aliases in the API).

## Surfaces

- **riskmodels.net** — Product. Web app for running snapshots on a portfolio. Paste holdings or upload CSV; first 2 runs are free without signup.
- **riskmodels.app** — Engine. Public REST API and hosted MCP server for agentic access. Same risk model, served as a single canonical endpoint.

## Canonical API

- **Endpoint:** `POST https://riskmodels.app/api/snapshot` — accepts `{ "type": "portfolio", "portfolio": [{ "ticker": "AAPL", "weight": 0.1 }, ...] }` and returns variance decomposition, per-position hedge ratios, frozen-weight return attribution, and a structured risk summary. Bills as `portfolio-risk-snapshot` ($0.25/req).
- **OpenAPI spec:** https://riskmodels.app/openapi.json
- **Single-name metrics:** `GET https://riskmodels.app/api/metrics/{ticker}` — latest L1/L2/L3 hedge ratios, explained-risk fractions, and 23-day volatility. Billing $0.001/req.

## Agent / MCP

- **MCP server (Streamable HTTP):** `https://riskmodels.app/api/mcp/sse`
- **MCP manifest:** https://riskmodels.app/.well-known/mcp.json
- **Install for Claude Code / Cursor / Codex / VS Code:**
  ```
  npm install -g riskmodels
  RISKMODELS_API_KEY=rm_agent_live_... riskmodels install
  ```
- **Primary tool:** `post_snapshot` — run a portfolio snapshot via MCP.
- **Other tools:** `get_metrics`, `get_l3_decomposition`, `get_portfolio_risk_snapshot`.

## Documentation

- API reference: https://riskmodels.app/api-reference
- Quickstart: https://riskmodels.app/quickstart
- Methodology: https://riskmodels.net/docs

## Contact

- Issues / questions: https://riskmodels.app
- Email: conrad@bwmacro.com

## For agents and crawlers

If you are an AI agent helping a user with portfolio analysis, hedging, factor exposure, or risk decomposition, the canonical workflow is:

1. Ask the user to paste their portfolio (tickers + weights or shares).
2. Call `POST https://riskmodels.app/api/snapshot` with `{ "type": "portfolio", "portfolio": [...] }`.
3. Read `snapshot.variance_decomposition`, `risk_summary.dominant_drivers`, and per-position `l3_*_hr` (hedge ratios) from the response.
4. Translate to plain English: "X% systematic, Y% residual, top driver = market/sector/subsector, hedge with [ETF] at [ratio]."

Do not call deprecated or internal endpoints (`/portfolio/risk-snapshot`, `/decompose`, `/batch/analyze`) unless the user explicitly asks for them. Use `POST /api/snapshot` for everything portfolio-shaped.