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 エージェント対応で、LLM とシームレスに統合できる組み込みの 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 エージェントとの統合 — MCP サーバー、OAuth2、エージェントマニフェスト

---

Cursor での利用（エージェントプラグイン）

このリポジトリは Agent Plugins パッケージです。リポジトリのルートに plugin.json と mcp.json があります。このプラグインは Cursor をホスト型 RiskModels MCP サーバーに接続します。お使いのマシンで実行されるコードや認証情報は含まれていません。

ファイル	宣言される内容
plugin.json	プラグイン riskmodels 1.0.0、Apache-2.0
mcp.json	1 つのサーバー 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の設定で証券口座（Alpaca、Connect Trade、Plaid）を連携すると、riskmodels_get_my_positionsでその口座のポジションを読み取れます。

例：NVDA

Cursor のエージェントチャットで、次のように尋ねます。

RiskModels で NVDA のリスクを分解し、10 万ドルのポジションに対する ETF ヘッジを提示してください。

エージェントは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.riskmodels.appは、公開 API や機械可読ドキュメントでは使用されません。このホスト名が記載された古いリンクやドキュメントは廃止済みとして扱い、上記のriskmodels.app**（apex ドメイン）を使用してください。

---

📖 API の概要

RiskModels API は、機関投資家向けの株式リスク分析を提供します。

• 日次ファクター分解 — 時価総額上位の主要な米国株約 3,000 銘柄（月末時点の対象銘柄群）について、市場、セクター、サブセクターの説明済みリスク比率を提供
• ヘッジ比率 — 流動性の高い現物 ETF で執行できるよう設計された、ドル建て ETF ヘッジ金額（L1/L2/L3）
• 過去の時系列データ — 株式分割と配当を調整したリターン（2006-01-04–現在）、ローリングヘッジ比率（2010-12-08–現在）、ER（2011-12-07–現在。ファクター出力には完全な回帰ウィンドウが必要）
• AI エージェント対応 — OAuth2、リクエストごとの課金、機械可読マニフェスト

データ範囲： 過去データパネルには米国株約 16,000 銘柄を収録し、主要な出力では各月末時点の時価総額上位約 3,000 銘柄を対象としています。毎日更新されます。ヘッジ比率： 2010-12-08から現在まで。説明済みリスク： 2011-12-07から現在まで。L* レベル： 2013-01-01から現在まで。調整済みリターン系列： 2006-01-04から現在まで。

---

エンジンが重要な理由

RiskModels は、単なる記述的な分析ではなく、実際のポートフォリオ業務で役立つよう設計されています。

• 時間整合性を確保する設計 — リサイクルされたティッカー、スナップショット時点の株式数、遡及的なユニバースの縮小など、先読み汚染の一般的な原因を避けるようエンジンを設計しています
• 実際の証券マスターを基盤としています — ティッカーレベルの出力は、識別子の継続性、シンボル変更、過去のデータとして妥当性を説明できる株式数データに対応する、ポイント・イン・タイムの識別レイヤーに基づいています
• 階層構造を前提に設計 — 市場、セクター、サブセクターの構造を分離し、すべてを単一のベータビューにまとめることはありません
• 実運用で取引可能 — 公開されるヘッジ比率は、合成ファクターや直交化ファクターだけでなく、執行時に流動性の高い ETF で機能するよう設計されています
• 調整後リターン系列を基盤としています — 株式分割と配当を調整したリターンにより、長期的に見て分解とヘッジ比率の経済的な一貫性が高まります

これらの主張の背景にあるエンジンの設計方針について詳しくは、方法論ドキュメントと API リファレンスをご覧ください。

---

🐍 Python SDK (riskmodels-py)

エージェントネイティブなワークフローでは、生の REST より Python SDK をご利用ください。ティッカーの解決、セマンティックなフィールドの正規化、説明的なエラーメッセージによる検証、LLM 向けのコンテキスト形式への変換が組み込まれています。

インストール（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 — インストール、メソッド、エージェントネイティブなヘルパー
• クイックスタート — 60 秒でセットアップ
• API ドキュメント — エージェントネイティブなヘルパーのリファレンス表

---

リスクインテリジェンス

以下のチャートは、scripts/generate_readme_assets.py を使ってライブ API データ（get_rankings と MAG7 L3 バッチ指標）から生成されています。RISKMODELS_API_KEY を設定し（無料枠で十分です）、リポジトリのルートからスクリプトを実行した後、./assets/ と ./public/docs/readme/ をコミットしてください。

MAG7 — L3 σ スケーリング分解

_{同じ「テック」というラベルでも、サブセクターの特性は異なります — 棒の長さ ∝ 年率換算 σ、各セグメント = σ × L3 の市場／セクター／サブセクターのリスク比率 + 残余（HR の割合）。SDK 経由の POST /batch/analyze save_mag7_l3_sigma_rr_png}

横断的なランキング

_{ユニバース／セクター／サブセクターの順位パーセンタイルの内訳}

---

🤖 MCP サーバー（v3.0.0-agent）

RiskModels には、第一級の MCP（Model Context Protocol） サーバーが含まれており、AI エージェントがリスクデータを直接照会し、ファクター分析を実行できます。

MCP 接続（ホスト型 API）：

• エンドポイント（ストリーミング可能 HTTP、POST）： https://riskmodels.app/api/mcp
• 名前付きエンドポイント： /api/mcp/openai と /api/mcp/sse も引き続きサポートされています
• 認証： Bearer トークン（API キーまたは OAuth2 JWT）
• ディスカバリー： https://riskmodels.app/.well-known/mcp.json（OPENAPI_SPEC.yaml を参照）

ローカル MCP サーバー（このリポジトリ内の mcp/、@riskmodels/mcp 2.0.0） — Cursor／Claude Desktop／Zed 向けの stdio トランスポートです。ツールセット 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 の比較）： オプションのクラウドホスト型エージェント、課金、コンプライアンスに関する社内エンジニアリング設計については、docs/ANTHROPIC_CLOUD_AGENTS.md を参照してください。

---

⌨️ コマンドライン CLI（riskmodels）

cli/ 内の npm パッケージをインストールすると、設定、SQL クエリ（課金対象の API または Supabase への直接接続）、スキーマのイントロスペクション、残高、静的エージェントマニフェストに対応した riskmodels バイナリがインストールされます。

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 開発者ポータルが追加されました。

• ✨ 機能のハイライトを備えたヒーローランディングページ
• 📚 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	Pure-Matplotlib レンダリングパイプラインのアーキテクチャ

---

🔗 関連項目

• ERM3 — Python 製のリスクモデル計算エンジン（オープンソース）

---

🤝 貢献

プルリクエストを歓迎します。特に OpenAPI 仕様の改善をお待ちしています。説明の明確化、スキーマの改善、サンプルの追加は、すべての利用者に役立ちます。

1. OpenAPI 仕様： CONTRIBUTING.md — OPENAPI_SPEC.yaml への PR を歓迎します
2. 課題： バグ報告や機能リクエストは、課題を作成してください
3. サンプル： examples/ への PR で新しいサンプルを提出してください
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. All rights reserved.

Deploy trigger: Tue Jun 9 16:13:22 PDT 2026