{
  "markdown": "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.\n\n**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.\n\n# RiskModels API Developer Portal\n\n[![CI](https://github.com/BlueWaterCorp/RiskModels_API/actions/workflows/ci.yml/badge.svg)](https://github.com/BlueWaterCorp/RiskModels_API/actions/workflows/ci.yml)\n[![Live Docs](https://img.shields.io/badge/Live%20Docs-riskmodels.net%2Fdocs%2Fapi-6366f1)](https://riskmodels.net/docs/api/erm3)\n[![OpenAPI](https://img.shields.io/badge/OpenAPI-3.0.3-85ea2d)](OPENAPI_SPEC.yaml)\n[![PyPI](https://img.shields.io/pypi/v/riskmodels-py.svg)](https://pypi.org/project/riskmodels-py/)\n[![smithery badge](https://smithery.ai/badge/service-c09f/riskmodels)](https://smithery.ai/servers/service-c09f/riskmodels)\n\nThis repository is the **authoritative public API reference** for the [RiskModels](https://riskmodels.net) equity risk model API, featuring:\n\n- 📖 **Model methodology** — [ERM3 overview](https://riskmodels.app/docs/methodology) (canonical; also mirrored on [riskmodels.net](https://riskmodels.net/docs/methodology/erm3-l3))\n- 📚 **Comprehensive API Documentation** — OpenAPI 3.0.3 specification, guides, and examples\n- 🌐 **Developer Portal** — Beautiful Next.js site (this repo) deployed at **riskmodels.app**\n- 🐍 **Python & TypeScript Examples** — Production-ready code in `examples/`\n- 🤖 **AI Agent Integration** — MCP server, OAuth2, and agent manifest\n\n---\n\n## 🚀 Quick Links\n\n- **Python SDK — AOM quickstart (Google Colab):** [Open notebook](https://colab.research.google.com/github/BlueWaterCorp/RiskModels_API/blob/main/sdk/notebooks/riskmodels_aom_colab.ipynb) · source: [`sdk/notebooks/riskmodels_aom_colab.ipynb`](sdk/notebooks/riskmodels_aom_colab.ipynb)\n- **Developer Portal:** [riskmodels.app](https://riskmodels.app)\n- **Live API Docs:** [riskmodels.net/docs/api/erm3](https://riskmodels.net/docs/api/erm3)\n- **ERM3 methodology:** [riskmodels.app/docs/methodology](https://riskmodels.app/docs/methodology)\n- **Get API Key:** [riskmodels.app/get-key](https://riskmodels.app/get-key)\n- **API Terms:** [riskmodels.net/terms/api](https://riskmodels.net/terms/api)\n- **Issues:** [github.com/BlueWaterCorp/RiskModels_API/issues](https://github.com/BlueWaterCorp/RiskModels_API/issues)\n- **PyPI (Python SDK):** [riskmodels-py](https://pypi.org/project/riskmodels-py/)\n\n### Canonical URLs (REST, OpenAPI, and docs)\n\nUse these **only** for integrations and tooling:\n\n| What | URL |\n|------|-----|\n| **REST base** (OpenAPI `servers`) | `https://riskmodels.app/api` |\n| **Deployed OpenAPI JSON** (same spec as [`OPENAPI_SPEC.yaml`](./OPENAPI_SPEC.yaml)) | `https://riskmodels.app/openapi.json` |\n| **Interactive API reference** (this portal) | [`/api-reference`](https://riskmodels.app/api-reference) |\n\n**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.\n\n---\n\n## 📖 API Overview\n\nThe RiskModels API provides institutional-grade equity risk analysis:\n\n- **Daily factor decompositions** — market, sector, subsector explained-risk fractions for the headline **~3,000** largest US stocks by market cap (month-end universe)\n- **Hedge ratios** — dollar-denominated ETF hedge amounts (L1/L2/L3) designed to remain executable with liquid raw ETFs\n- **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)\n- **AI-agent ready** — OAuth2, per-request billing, machine-readable manifests\n\n**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.\n\n---\n\n## Why The Engine Matters\n\nRiskModels is designed to be useful for real portfolio work, not just descriptive analytics:\n\n- **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\n- **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\n- **Hierarchical by design** — the model separates market, sector, and subsector structure rather than collapsing everything into a flat beta view\n- **Tradeable in practice** — the published hedge ratios are designed to work with liquid ETFs at execution time, not only with synthetic or orthogonalized factors\n- **Built on adjusted return series** — split- and dividend-adjusted returns make the decomposition and hedge ratios more economically consistent over long horizons\n\nFor a deeper explanation of the engine design choices behind these claims, see the methodology docs and API reference.\n\n---\n\n## 🐍 Python SDK (riskmodels-py)\n\nPrefer 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.\n\n**Install** ([PyPI](https://pypi.org/project/riskmodels-py/)):\n\n[![PyPI version](https://img.shields.io/pypi/v/riskmodels-py.svg)](https://pypi.org/project/riskmodels-py/)\n\n```bash\npip install riskmodels-py\n# Optional — xarray cube from batch Parquet/CSV:\n# pip install riskmodels-py[xarray]\n# Optional — snapshot PDF rendering:\n# pip install riskmodels-py[pdf]\n```\n\n**Quickstart:**\n\n```python\nfrom riskmodels import RiskModelsClient, to_llm_context\n\nclient = RiskModelsClient.from_env()\npa = client.analyze({\"NVDA\": 0.4, \"AAPL\": 0.6})\nprint(to_llm_context(pa))\n```\n\n**Snapshot generation** (institutional PDF reports):\n\n```python\nfrom riskmodels.snapshots import get_data_for_r1, render_r1_to_pdf\n\nclient = RiskModelsClient.from_env()\ndata = get_data_for_r1(\"NVDA\", client)       # fetch → R1Data (caches to JSON)\nrender_r1_to_pdf(data, \"NVDA_R1_Risk.pdf\")   # render → PDF (~0.3s, no API)\n```\n\n**Documentation:**\n\n- [Package README](./sdk/README.md) — install, methods, agent-native helpers\n- [Quickstart](/quickstart) — 60-second setup path\n- [API Docs](/docs/api) — agent-native helpers reference table\n\n---\n\n## Risk intelligence\n\nCharts below are **generated from live API data** (`get_rankings` + MAG7 L3 batch metrics) via [`scripts/generate_readme_assets.py`](./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/`.\n\n### MAG7 — L3 σ-scaled decomposition\n\n<p align=\"center\">\n  <img src=\"./assets/mag7_l3_sigma_rr.png\" width=\"680\" alt=\"MAG7 L3 sigma-scaled risk ratios and residual HR share\" />\n  <br>\n  <sub>Same “tech” label, different subsector DNA — bar length ∝ annualized σ; segments = σ × L3 market/sector/subsector risk ratios + residual (HR share). <code>POST /batch/analyze</code> via SDK <code>save_mag7_l3_sigma_rr_png</code></sub>\n</p>\n\n### Cross-sectional rankings\n\n<p align=\"center\">\n  <img src=\"./assets/ranking_cohorts.png\" width=\"680\" alt=\"Ranking by cohort\" />\n  <br>\n  <sub>Universe / sector / subsector rank percentile breakdown</sub>\n</p>\n\n---\n\n## 🤖 MCP Server (v3.0.0-agent)\n\nRiskModels includes a first-class [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server, enabling AI agents to directly query risk data and perform factor analysis.\n\n**MCP Connection (hosted API):**\n- **Endpoint (Streamable HTTP, POST):** `https://riskmodels.app/api/mcp/sse`\n- **Authentication:** Bearer token (API key or OAuth2 JWT)\n- **Discovery:** `https://riskmodels.app/.well-known/mcp.json` (see [OPENAPI_SPEC.yaml](./OPENAPI_SPEC.yaml))\n\n**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:**\n\n- `riskmodels_list_endpoints` — List API capabilities (id, method, endpoint, short description)\n- `riskmodels_get_capability` — Full capability record by id (parameters, pricing, examples)\n- `riskmodels_get_schema` — JSON Schema for a response type (e.g. `ticker-returns-v2.json`)\n- `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\n\nFor 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.\n\nSee [mcp/README.md](./mcp/README.md) for install and config.\n\n**Anthropic Claude (Managed Agents vs Messages API):** internal engineering design for optional cloud-hosted agents, billing, and compliance — see [docs/ANTHROPIC_CLOUD_AGENTS.md](./docs/ANTHROPIC_CLOUD_AGENTS.md).\n\n---\n\n## ⌨️ Command-line CLI (`riskmodels`)\n\nThe npm package in [`cli/`](./cli/) installs the `riskmodels` binary: config, SQL query (billed API or direct Supabase), schema introspection, balance, and static agent manifests.\n\n**Install from npm:**\n\n```bash\nnpm install -g riskmodels\nriskmodels --help\n```\n\n**Develop from this repo:**\n\n```bash\ncd cli\nnpm ci\nnpm run build\nnpm run install:global   # optional: npm link for local testing\n```\n\n**Publish to npm** (maintainers): procedure is documented in the private **BWMACRO** monorepo (`docs/RISKMODELS_CLI_NPM_PUBLISHING.md`), not here. Only publish from the **`cli/`** directory — the repo root Next.js app is not published to npm.\n\n---\n\n## 💻 Developer Portal (This Repo)\n\nThis repo now includes a **Next.js developer portal** with:\n\n- ✨ Hero landing page with feature highlights\n- 📚 MDX-powered documentation (README_API.md, AUTHENTICATION_GUIDE.md)\n- 🔍 Interactive API reference (Redoc OpenAPI viewer)\n- 💡 Code examples with syntax highlighting and copy buttons\n- 🎯 Step-by-step quickstart guide\n\n### Local Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Option A: Copy env template and fill in Supabase/Stripe keys manually\ncp .env.example .env.local\n\n# Option B: Use Doppler (recommended for team consistency)\n# Ensure `doppler login` is done, then:\ndoppler secrets download --no-file --format env > .env.local\n\n# Generate OpenAPI JSON for Redoc\nnpm run build:openapi\n\n# Run dev server\nnpm run dev\n```\n\n**Screenshot Capture Hygiene:**\n\nWhen capturing site screenshots for audit or documentation:\n1. **Ensure the build passes first:** `npm run build` must complete without errors\n2. **Verify the dev server serves HTTP 200:** Visit `http://localhost:3000` and confirm pages render (not \"Internal Server Error\")\n3. **Run the capture script:** `python3 capture_site.py` (requires Playwright)\n\nThe script will skip pages returning HTTP 500 or containing \"Internal Server Error\" content. Screenshots with server errors should never be committed to the repository.\n\n**Environment Management with Doppler:**\n\nThis repo uses [Doppler](https://doppler.com) for secrets management. The `doppler.yaml` is pre-configured for the `erm3` project:\n\n```bash\n# Verify setup (should show project: erm3, config: dev)\ndoppler setup\n\n# List all secrets\ndoppler secrets\n\n# Get a specific secret\ndoppler secrets get STRIPE_SECRET_KEY\n\n# Export dev secrets to .env.local for curl testing and local dev\nnpm run doppler:env\n\n# Push production secrets to Vercel (requires vercel login + project link)\nnpm run vercel:sync-env:doppler\n```\n\n**For curl/API testing with Doppler secrets:**\n\n```bash\n# 1. Export secrets to .env.local\nnpm run doppler:env\n\n# 2. Source them for your shell session\nsource .env.local\n\n# 3. Use in curl commands\ncurl -H \"Authorization: Bearer $RISKMODELS_API_SERVICE_KEY\" \\\n  https://riskmodels.app/api/health\n```\n\nSee [DEPLOYMENT.md](DEPLOYMENT.md) for detailed Vercel/Doppler integration.\n\nVisit [http://localhost:3000](http://localhost:3000)\n\n### Build & Deploy\n\n```bash\n# Build for production\nnpm run build\n\n# Start production server\nnpm start\n```\n\n**Deployment:** See [DEPLOYMENT.md](DEPLOYMENT.md) for Vercel setup, env vars, and Supabase/Stripe config.\n\n---\n\n## 📂 Repository Structure\n\n```\nRiskModels_API/\n├── app/                      # Next.js app\n│   ├── api/                  # API routes (REST)\n│   ├── page.tsx              # Hero landing page\n│   ├── layout.tsx            # Root layout with Navbar/Footer\n│   ├── docs/[[...slug]]/     # MDX docs renderer\n│   ├── api-reference/        # Redoc OpenAPI viewer\n│   ├── examples/             # Code examples showcase\n│   └── quickstart/           # Quickstart guide\n├── components/               # React components (new)\n│   ├── Navbar.tsx\n│   ├── Footer.tsx\n│   ├── Hero.tsx\n│   ├── CodeBlock.tsx\n│   └── Logo.tsx\n├── content/docs/             # MDX content (new)\n│   ├── api.mdx\n│   └── authentication.mdx\n├── cli/                      # Command-line CLI (`riskmodels`)\n├── sdk/                      # Python SDK (`riskmodels-py`) source\n│   └── riskmodels/snapshots/ # Snapshot PDF pipeline (R1 shipped, R2–P4 planned)\n├── examples/                 # Runnable examples\n│   ├── python/\n│   └── typescript/\n├── mcp/                      # MCP (Model Context Protocol) server\n├── public/                   # Static assets (new)\n│   ├── transparent_logo.svg\n│   └── openapi.json          # Generated from OPENAPI_SPEC.yaml\n├── styles/                   # Global styles (new)\n├── lib/                      # Utilities (new)\n├── OPENAPI_SPEC.yaml         # Canonical OpenAPI spec\n├── README_API.md             # API reference (source for content/docs/api.mdx)\n├── AUTHENTICATION_GUIDE.md   # Auth guide (source for content/docs/authentication.mdx)\n├── SEMANTIC_ALIASES.md       # Field definitions\n└── package.json              # Next.js deps (new)\n```\n\n---\n\n## 🛠️ Tech Stack (Developer Portal)\n\n- **Framework:** Next.js 15 (App Router)\n- **Styling:** Tailwind CSS 3.4, dark mode default\n- **MDX:** @next/mdx for documentation\n- **API Reference:** Redoc (OpenAPI 3.0 viewer)\n- **Code Highlighting:** Custom CodeBlock with copy button\n- **Fonts:** Inter (system-ui fallback)\n- **Colors:** Blue primary (`hsl(217, 91%, 60%)`), zinc/slate dark palette\n\n---\n\n## 📄 Documentation Files\n\n| Document | Description |\n|---|---|\n| [README_API.md](README_API.md) | Complete API overview, endpoints, key concepts |\n| [API_TERMS.md](API_TERMS.md) | API Terms of Service ([riskmodels.net/terms/api](https://riskmodels.net/terms/api)) |\n| [PLAID_HOLDINGS_UX.md](PLAID_HOLDINGS_UX.md) | Plaid connection flow and holdings API user experience |\n| [AUTHENTICATION_GUIDE.md](AUTHENTICATION_GUIDE.md) | Bearer token, OAuth2, Supabase JWT, rate limits |\n| [DOCS_PROCESS.md](DOCS_PROCESS.md) | Process for adding new documentation |\n| [SEMANTIC_ALIASES.md](SEMANTIC_ALIASES.md) | Field definitions, units, formulas |\n| [RESPONSE_METADATA.md](RESPONSE_METADATA.md) | `_agent` block, response headers, pricing |\n| [ERROR_SCHEMA.md](ERROR_SCHEMA.md) | Error codes and recovery patterns |\n| [OPENAPI_SPEC.yaml](OPENAPI_SPEC.yaml) | OpenAPI 3.0.3 specification (v3.0.0-agent) |\n| [docs/SNAPSHOT_ROADMAP.md](docs/SNAPSHOT_ROADMAP.md) | Snapshot suite roadmap, ADRs, and implementation phases |\n| [docs/SNAPSHOT_CONTENT_MAP.md](docs/SNAPSHOT_CONTENT_MAP.md) | 8-page content spec with wireframes and JSON schemas |\n| [docs/SNAPSHOT_FRONTEND_ARCH.md](docs/SNAPSHOT_FRONTEND_ARCH.md) | Pure-Matplotlib rendering pipeline architecture |\n\n---\n\n## 🔗 Related\n\n- **[ERM3](https://github.com/conradgann/ERM3)** — Python risk model computation engine (open source)\n\n---\n\n## 🤝 Contributing\n\nWe welcome pull requests, especially to improve the **OpenAPI spec** — clearer descriptions, better schemas, and more examples help everyone.\n\n1. **OpenAPI spec:** [CONTRIBUTING.md](CONTRIBUTING.md) — PRs to `OPENAPI_SPEC.yaml` are encouraged\n2. **Issues:** [Open an issue](https://github.com/BlueWaterCorp/RiskModels_API/issues) for bugs or feature requests\n3. **Examples:** Submit new examples via PR to `examples/`\n4. **Docs:** Improve documentation by editing MDX files in `content/docs/`\n\n---\n\n## 📧 Support\n\n- **API Support:** [service@riskmodels.app](mailto:service@riskmodels.app)\n- **Issues:** [github.com/BlueWaterCorp/RiskModels_API/issues](https://github.com/BlueWaterCorp/RiskModels_API/issues)\n- **Status:** [riskmodels.net/status](https://riskmodels.net/status) · API metrics [riskmodels.app/api/status](https://riskmodels.app/api/status)\n\n---\n\n## 📜 License\n\nSee [LICENSE](LICENSE) for details.\n\n**© 2026 Blue Water Macro Corp. All rights reserved.**\n# Deploy trigger: Tue Jun  9 16:13:22 PDT 2026\n\n\n",
  "bytes": 17502,
  "sha": "6e8d5adec2806d8b10504205dd554c1807c692e3036fdc5190bb17f54cc39344",
  "repo_slug": "bluewatercorp/riskmodels_api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bluewatercorp_riskmodels_b2e88ad7/readme"
}