Riskmodels

RiskModels 为美国股票提供经过分红调整的总回报、因子风险分解、回报归因，以及可通过 ETF 执行的对冲比率，支持 REST、类型化 SDK 和内置 MCP 服务。数据集达到模拟级：完整历史面板涵盖约 16,000 只美国股票，而模型的核心股票池在每个月末取市值最大的约 3,000 只——这是 API 在日常回报、风险和对冲场景中提供的股票集合。

回归后的输出（对冲比率、已解释风险分解及相关 L1–L3 序列）从完整估计窗口所覆盖的首个日期开始提供：对冲比率从 2010-12-08 开始，已解释风险占比和股票方差从 2011-12-07 开始，L* 残差水平从 2013-01-01 开始。经过拆股和分红调整的回报（滚动回归的输入）从 2006-01-04 开始。该 API 已为 AI Agent 做好准备，内置 Model Context Protocol（MCP）服务，可与大模型无缝集成。

RiskModels API 开发者门户

此代码仓库是 RiskModels 股票风险模型 API 的权威公开 API 参考，包含：

• 📖 模型方法论 — ERM3 概览（权威版本；也镜像发布于 riskmodels.net）
• 📚 全面的 API 文档 — OpenAPI 3.0.3 规范、指南和示例
• 🌐 开发者门户 — 美观的 Next.js 网站（即本代码仓库），部署于 riskmodels.app
• 🐍 Python 和 TypeScript 示例 — examples/ 中可用于生产环境的代码
• 🤖 AI Agent 集成 — MCP 服务、OAuth2 和 Agent 清单

---

在 Cursor 中使用（Agent 插件）

此代码仓库是一个 Agent Plugins 软件包：仓库根目录中包含 plugin.json 和 mcp.json。该插件将 Cursor 连接到托管的 RiskModels MCP 服务。它不包含任何会在你的计算机上运行的代码，也不包含凭据。

文件	声明内容
plugin.json	插件 riskmodels 1.0.0，Apache-2.0
mcp.json	一个服务 riskmodels：位于 https://riskmodels.app/api/mcp/openai 的 Streamable HTTP

安装

1. 在 Cursor 中打开 Marketplace 并搜索 RiskModels。
2. 为你的用户或当前项目安装。
3. Cursor 会添加 riskmodels MCP 服务。登录后即可使用其中的工具。

登录

该服务使用带 PKCE 的 OAuth 2.1。登录流程由 Cursor 处理，插件文件中无需填写任何内容：

1. Cursor 首次连接 riskmodels 服务时，该服务会请求登录，Cursor 随后会在浏览器中打开 riskmodels.app。
2. 使用 Google 或电子邮件链接登录，或者选择 改用密码登录。
3. 同意页面会显示 登录身份：<email>。如果账号不正确，请先点击 使用其他账号，然后点击 允许。
4. Cursor 会保存令牌。这些工具为只读工具：它们只返回数据，不会下单或更改你的账号。

定价和账户

• 需要 RiskModels 账户。新账户会获得 20 美元预付额度。注册时会收集付款方式用于验证，只有在充值时才会扣款。
• 按使用量付费，每次工具调用从余额中扣费。大多数单只股票调用的费用为 0.005 美元；基本面数据为 0.02 美元，完整的投资组合敞口报告为 0.25 美元。费率和套餐：riskmodels.app/pricing。
• 可选：在 riskmodels.net 的 Settings 中关联经纪账户（Alpaca、Connect Trade 或 Plaid），之后 riskmodels_get_my_positions 会读取该账户的持仓。

示例：NVDA

在 Cursor 的 Agent 聊天中提问：

使用 RiskModels 分解 NVDA 的风险，并为 100,000 美元的持仓提供 ETF 对冲方案。

Agent 会调用 riskmodels_decompose，获取 NVDA 的方差在市场、行业、子行业和个股特有风险层面的拆分，以及每个层级的对冲比率。随后，它会再次调用 riskmodels_decompose 并传入金额，将这些比率转换为 SPY 以及行业和子行业 ETF 的美元交易金额。数据为截至最近一个交易日的实时模型输出。

Claude 插件（claude-plugin/）和本地开发者 MCP 服务（.cursor/mcp.json、mcp/）是彼此独立的，且均未更改。

---

🚀 快速链接

• Python SDK — AOM 快速入门（Google Colab）：打开笔记本 · 源文件：sdk/notebooks/riskmodels_aom_colab.ipynb
• 开发者门户：riskmodels.app
• 实时 API 文档：riskmodels.net/docs/api/erm3
• ERM3 方法论：riskmodels.app/docs/methodology
• 获取 API 密钥：riskmodels.app/get-key
• API 条款：riskmodels.net/terms/api
• 问题反馈：github.com/BlueWaterCorp/RiskModels_API/issues
• PyPI（Python SDK）：riskmodels-py

规范 URL（REST、OpenAPI 和文档）

仅将以下地址用于集成和工具：

内容	URL
REST 基础 URL（OpenAPI servers）	https://riskmodels.app/api
已部署的 OpenAPI JSON（与 OPENAPI_SPEC.yaml 中的规范相同）	https://riskmodels.app/openapi.json
交互式 API 参考（本门户）	/api-reference

**重要提示：**公共 API 和机器可读文档均不使用主机名 api.riskmodels.app。提及该地址的旧链接或文档均已过时；请使用上文中的主域名 riskmodels.app。

---

📖 API 概述

RiskModels API 提供机构级股票风险分析：

• 每日因子分解 — 覆盖市值最大的约 3,000 只美国股票（按月末确定范围），提供市场、行业和子行业的风险解释比例
• 对冲比率 — 以美元计价的 ETF 对冲金额（L1/L2/L3），旨在使用流动性良好的原始 ETF，确保交易可执行
• 历史时间序列 — 经拆股和股息调整的收益率（2006-01-04 至今），以及滚动对冲比率（2010-12-08 至今）和 ER（2011-12-07 至今；因子输出需要完整的回归窗口）
• 适用于 AI Agent — OAuth2、按请求计费、机器可读清单

数据覆盖范围：历史面板包含约 16,000 只美国股票；核心输出覆盖每个月末市值最大的约 3,000 只股票。每日更新。**对冲比率：**从 2010-12-08 至今。**风险解释：**从 2011-12-07 至今。**L* 层级：**从 2013-01-01 至今。**调整后收益率序列：**从 2006-01-04 至今。

---

引擎为何重要

RiskModels 旨在服务于真实的投资组合工作，而不只是提供描述性分析：

• 为确保时间安全而构建 — 引擎旨在避免常见的前视污染来源，例如重复使用的代码、快照股数以及追溯性收缩股票池
• 基于真实的证券主数据 — 代码级输出建立在时点身份层之上，该层专为标识符连续性、代码变更和历史可辩护的股数数据而构建
• 采用分层设计 — 模型将市场、行业和子行业结构分开处理，而不是将所有内容压平为单一的 Beta 视图
• 在实践中可交易 — 发布的对冲比率旨在执行时适用于流动性良好的 ETF，而不只是适用于合成或正交化因子
• 基于调整后收益序列构建 — 经拆股和股息调整后的收益，可使长期范围内的分解和对冲比率在经济意义上更加一致

有关这些设计主张背后的引擎设计选择，请参阅方法文档和 API 参考。

---

🐍 Python SDK（riskmodels-py）

对于原生支持 Agent 工作流的场景，建议优先使用 Python SDK，而不是直接调用 REST — 代码解析、语义字段规范化、带指导性错误信息的验证，以及适用于大模型的上下文格式化均已内置。

安装（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]

快速入门：

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))

快照生成（机构级 PDF 报告）：

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)

文档：

• 软件包 README — 安装、方法、原生支持 Agent 的辅助工具
• 快速入门 — 60 秒即可完成的设置流程
• API 文档 — 原生支持 Agent 的辅助工具参考表

---

风险智能

下方图表通过 scripts/generate_readme_assets.py 由实时 API 数据（get_rankings + MAG7 L3 批量指标）生成。设置 RISKMODELS_API_KEY（免费套餐即可），从仓库根目录运行脚本，然后提交 ./assets/ 和 ./public/docs/readme/。

MAG7 — L3 σ 缩放分解

_{相同的“科技”标签，不同的子行业特征 — 柱长 ∝ 年化 σ；各部分 = σ × L3 市场／行业／子行业风险比率 + 残差（HR 份额）。通过 SDK save_mag7_l3_sigma_rr_png 调用 POST /batch/analyze}

横截面排名

_{股票池／行业／子行业排名百分位细分}

---

🤖 MCP 服务端（v3.0.0-agent）

RiskModels 内置了 MCP（Model Context Protocol） 服务，可让 AI Agent 直接查询风险数据并执行因子分析。

MCP 连接（托管 API）：

• 端点（Streamable HTTP，POST）： https://riskmodels.app/api/mcp
• 命名端点： 仍支持 /api/mcp/openai 和 /api/mcp/sse
• 身份验证： Bearer token（API 密钥或 OAuth2 JWT）
• 发现： https://riskmodels.app/.well-known/mcp.json（参见 OPENAPI_SPEC.yaml）

本地 MCP 服务（本仓库中的 mcp/，@riskmodels/mcp 2.0.0）——通过 stdio 传输，适用于 Cursor / Claude Desktop / Zed。工具集 2.0 是与托管端点共用的注册表：本地有 25 个工具，托管端有 26 个（增加了 riskmodels_render_artifact）：

riskmodels_get_stock_snapshot、riskmodels_decompose、riskmodels_compare、riskmodels_get_returns、riskmodels_get_return_attribution、riskmodels_get_residual_returns、riskmodels_get_residual_signal、riskmodels_get_macro_correlation、riskmodels_get_fundamentals、riskmodels_analyze_portfolio、riskmodels_get_portfolio_risk_snapshot、riskmodels_portfolio_exposure、riskmodels_decompose_selection_vs_drift、riskmodels_get_my_positions、riskmodels_get_rankings、riskmodels_screen_rankings、riskmodels_get_cohorts、riskmodels_get_peers、riskmodels_search、riskmodels_resolve_security_identity、riskmodels_get_filer、riskmodels_get_fund、riskmodels_get_etf、riskmodels_get_benchmark_fit、riskmodels_get_factor_returns。

REST 目录、响应架构和 OpenAPI 规范均作为 MCP 资源提供（riskmodels:///capabilities、riskmodels:///schemas/{path}、riskmodels:///openapi）。工具列表、价格和 1.x → 2.0 迁移表：mcp/README.md。在 MCP 之外，可调用 REST API 或 Python SDK（riskmodels-py）。

有关安装和配置，请参阅 mcp/README.md。

Anthropic Claude（Managed Agents 与 Messages API）： 关于可选云托管 Agent、计费和合规性的内部工程设计，请参阅 docs/ANTHROPIC_CLOUD_AGENTS.md。

---

⌨️ 命令行 CLI（riskmodels）

cli/ 中的 npm 包会安装 riskmodels 二进制文件，提供配置、SQL 查询（计费 API 或直接连接 Supabase）、架构内省、余额查询和静态 Agent 清单。

从 npm 安装：

npm install -g riskmodels
riskmodels --help

从本仓库开发：

cd cli
npm ci
npm run build
npm run install:global   # optional: npm link for local testing

发布到 npm（维护者）：相关流程记录在私有的 BWMACRO 单体仓库中（docs/RISKMODELS_CLI_NPM_PUBLISHING.md），此处不作说明。只能从 cli/ 目录发布——仓库根目录的 Next.js 应用不会发布到 npm。

---

💻 开发者门户（本仓库）

本仓库现已包含一个 Next.js 开发者门户，提供：

• ✨ 带有功能亮点的首页 Hero 区块
• 📚 由 MDX 驱动的文档（README_API.md、AUTHENTICATION_GUIDE.md）
• 🔍 交互式 API 参考（Redoc OpenAPI 查看器）
• 💡 带语法高亮和复制按钮的代码示例
• 🎯 分步快速入门指南

本地开发

# Install dependencies
npm install

# Option A: Copy env template and fill in Supabase/Stripe keys manually
cp .env.example .env.local

# Option B: Use Doppler (recommended for team consistency)
# Ensure `doppler login` is done, then:
doppler secrets download --no-file --format env > .env.local

# Generate OpenAPI JSON for Redoc
npm run build:openapi

# Run dev server
npm run dev

截图采集规范：

为审计或文档采集网站截图时：

1. 先确保构建通过： npm run build 必须无错误地完成
2. 确认开发服务器返回 HTTP 200： 访问 http://localhost:3000 并确认页面正常渲染（而非“Internal Server Error”）
3. 运行采集脚本： python3 capture_site.py（需要 Playwright）

脚本会跳过返回 HTTP 500 或内容包含“Internal Server Error”的页面。请勿将包含服务器错误的截图提交到代码库。

使用 Doppler 管理环境变量：

此代码库使用 Doppler 管理密钥。doppler.yaml 已预先配置为使用 erm3 项目：

# Verify setup (should show project: erm3, config: dev)
doppler setup

# List all secrets
doppler secrets

# Get a specific secret
doppler secrets get STRIPE_SECRET_KEY

# Export dev secrets to .env.local for curl testing and local dev
npm run doppler:env

# Push production secrets to Vercel (requires vercel login + project link)
npm run vercel:sync-env:doppler

使用 Doppler 密钥进行 curl/API 测试：

# 1. Export secrets to .env.local
npm run doppler:env

# 2. Source them for your shell session
source .env.local

# 3. Use in curl commands
curl -H "Authorization: Bearer $RISKMODELS_API_SERVICE_KEY" \
  https://riskmodels.app/api/health

详细的 Vercel/Doppler 集成信息，请参阅 DEPLOYMENT.md。

访问 http://localhost:3000

构建与部署

# Build for production
npm run build

# Start production server
npm start

部署： 有关 Vercel 设置、环境变量以及 Supabase/Stripe 配置，请参阅 DEPLOYMENT.md。

---

📂 代码库结构

RiskModels_API/
├── app/                      # Next.js app
│   ├── api/                  # API routes (REST)
│   ├── page.tsx              # Hero landing page
│   ├── layout.tsx            # Root layout with Navbar/Footer
│   ├── docs/[[...slug]]/     # MDX docs renderer
│   ├── api-reference/        # Redoc OpenAPI viewer
│   ├── examples/             # Code examples showcase
│   └── quickstart/           # Quickstart guide
├── components/               # React components (new)
│   ├── Navbar.tsx
│   ├── Footer.tsx
│   ├── Hero.tsx
│   ├── CodeBlock.tsx
│   └── Logo.tsx
├── content/docs/             # MDX content (new)
│   ├── api.mdx
│   └── authentication.mdx
├── cli/                      # Command-line CLI (`riskmodels`)
├── sdk/                      # Python SDK (`riskmodels-py`) source
│   └── riskmodels/snapshots/ # Snapshot PDF pipeline (R1 shipped, R2–P4 planned)
├── examples/                 # Runnable examples
│   ├── python/
│   └── typescript/
├── mcp/                      # MCP (Model Context Protocol) server
├── public/                   # Static assets (new)
│   ├── transparent_logo.svg
│   └── openapi.json          # Generated from OPENAPI_SPEC.yaml
├── styles/                   # Global styles (new)
├── lib/                      # Utilities (new)
├── OPENAPI_SPEC.yaml         # Canonical OpenAPI spec
├── README_API.md             # API reference (source for content/docs/api.mdx)
├── AUTHENTICATION_GUIDE.md   # Auth guide (source for content/docs/authentication.mdx)
├── SEMANTIC_ALIASES.md       # Field definitions
└── package.json              # Next.js deps (new)

---

🛠️ 技术栈（开发者门户）

• 框架： Next.js 15（App Router）
• 样式： Tailwind CSS 3.4，默认启用深色模式
• MDX： 使用 @next/mdx 编写文档
• API 参考： Redoc（OpenAPI 3.0 查看器）
• 代码高亮： 带复制按钮的自定义 CodeBlock
• 字体： Inter（回退到 system-ui）
• 颜色： 蓝色主色（hsl(217, 91%, 60%)），深色 zinc/slate 调色板

---

📄 文档文件

文档	说明
README_API.md	完整的 API 概述、端点和关键概念
API_TERMS.md	API 服务条款（riskmodels.net/terms/api）
PLAID_HOLDINGS_UX.md	Plaid 连接流程和持仓 API 用户体验
AUTHENTICATION_GUIDE.md	Bearer 令牌、OAuth2、Supabase JWT、速率限制
DOCS_PROCESS.md	添加新文档的流程
SEMANTIC_ALIASES.md	字段定义、单位、公式
RESPONSE_METADATA.md	_agent 块、响应标头、定价
ERROR_SCHEMA.md	错误代码和恢复模式
OPENAPI_SPEC.yaml	OpenAPI 3.0.3 规范（v3.0.0-agent）
docs/SNAPSHOT_ROADMAP.md	快照套件路线图、ADR 和实施阶段
docs/SNAPSHOT_CONTENT_MAP.md	包含线框图和 JSON 架构的 8 页内容规范
docs/SNAPSHOT_FRONTEND_ARCH.md	纯 Matplotlib 渲染流水线架构

---

🔗 相关项目

• ERM3 — Python 风险模型计算引擎（开源）

---

🤝 贡献

欢迎提交拉取请求，尤其欢迎改进 OpenAPI 规范——更清晰的描述、更完善的架构和更多示例都有助于所有人。

1. OpenAPI 规范： CONTRIBUTING.md — 欢迎提交针对 OPENAPI_SPEC.yaml 的 PR
2. 问题： 如需报告错误或提出功能请求，请提交问题
3. 示例： 通过 PR 向 examples/ 提交新示例
4. 文档： 编辑 content/docs/ 中的 MDX 文件来改进文档

---

📧 支持

• API 支持： [email protected]
• 问题： github.com/BlueWaterCorp/RiskModels_API/issues
• 状态： riskmodels.net/status · API 指标 riskmodels.app/api/status

---

📜 许可证

详情请参阅 LICENSE。

© 2026 Blue Water Macro Corp. 保留所有权利。

部署触发时间：Tue Jun 9 16:13:22 PDT 2026