\n $\"MAG7$ \n
\n _{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}\n

\n\n### Macro sensitivity\n\n

\n $\"MAG7$ \n
\n _{Pearson correlations of L3 residual returns vs macro factors — POST /correlation}\n

\n\n### Cross-sectional rankings\n\n

\n $\"Ticker$ \n
\n _{Universe rank percentile from get_rankings}\n

\n\n

\n $\"Ranking$ \n
\n _{Universe / sector / subsector rank percentile breakdown}\n

\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- **SSE Endpoint:** `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](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/docs/ANTHROPIC_CLOUD_AGENTS.md).\n\n---\n\n## ⌨️ Command-line CLI (`riskmodels`)\n\nThe npm package in [`cli/`](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/README_API.md) | Complete API overview, endpoints, key concepts |\n| [API_TERMS.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/API_TERMS.md) | API Terms of Service ([riskmodels.net/terms/api](https://riskmodels.net/terms/api)) |\n| [PLAID_HOLDINGS_UX.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/PLAID_HOLDINGS_UX.md) | Plaid connection flow and holdings API user experience |\n| [AUTHENTICATION_GUIDE.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/AUTHENTICATION_GUIDE.md) | Bearer token, OAuth2, Supabase JWT, rate limits |\n| [DOCS_PROCESS.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/DOCS_PROCESS.md) | Process for adding new documentation |\n| [SEMANTIC_ALIASES.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/SEMANTIC_ALIASES.md) | Field definitions, units, formulas |\n| [RESPONSE_METADATA.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/RESPONSE_METADATA.md) | `_agent` block, response headers, pricing |\n| [ERROR_SCHEMA.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/ERROR_SCHEMA.md) | Error codes and recovery patterns |\n| [OPENAPI_SPEC.yaml](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/OPENAPI_SPEC.yaml) | OpenAPI 3.0.3 specification (v3.0.0-agent) |\n| [docs/SNAPSHOT_ROADMAP.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/docs/SNAPSHOT_ROADMAP.md) | Snapshot suite roadmap, ADRs, and implementation phases |\n| [docs/SNAPSHOT_CONTENT_MAP.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/docs/SNAPSHOT_CONTENT_MAP.md) | 8-page content spec with wireframes and JSON schemas |\n| [docs/SNAPSHOT_FRONTEND_ARCH.md](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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)\n\n---\n\n## 📜 License\n\nSee [LICENSE](https://github.com/BlueWaterCorp/RiskModels_API/blob/main/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","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays","categoryDisplayName","Developer Tools","upstream",{"_94":95,"_96":97,"_98":99,"_100":101,"_102":103},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_92":57,"_93":57},"ratingAvg","reviewCount","topics",[],"license","Apache-2.0","language","TypeScript","registryName","io.github.BlueWaterCorp/riskmodels","homepage","https://riskmodels-api.vercel.app","ENV",{"_106":107,"_108":109,"_110":111},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]