RiskModels

Decomposição de risco de ações e portfólio dos EUA (mercado, setor, subsetor e específico de ações), índices de hedge de ETF e fundamentos pontuais do modelo de fatores RiskModels. MCP hospedado com OAuth, ou o pacote npm stdio.

GitHub

Servidor MCP hospedado

npx add-mcp 'https://riskmodels.app/api/mcp/sse'

Instala no Claude Code, Codex, Cursor e outros

Documentação

RiskModels fornece retornos totais ajustados por dividendos e desdobramentos, decomposição de risco por fatores, atribuição de retorno e índices de hedge executáveis via ETFs para ações dos EUA — via REST, um SDK tipado e um servidor MCP integrado. O conjunto de dados é de qualidade de simulação: cobre cerca de 16.000 ações dos EUA em todo o painel histórico, enquanto ao final de cada mês o universo principal do modelo é composto pelas ~3.000 maiores por capitalização de mercado — o conjunto que a API disponibiliza para retornos, risco e hedge no dia a dia.

Saídas pós-regressão (índices de hedge, decomposições de risco explicado e séries L1–L3 relacionadas) são servidas a partir da primeira data cuja janela completa de estimação é coberta: índices de hedge a partir de 2010-12-08, participações de risco explicado e variância das ações a partir de 2011-12-07, níveis residuais L* a partir de 2013-01-01. Retornos ajustados por desdobramentos e dividendos (os insumos das regressões móveis) começam em 2006-01-04. A API está pronta para agentes de IA, incluindo um servidor Model Context Protocol (MCP) integrado para integração perfeita com LLMs.

Portal do Desenvolvedor da API RiskModels

CI Live Docs OpenAPI PyPI smithery badge

Este repositório é a referência pública autoritativa da API para a API de modelo de risco de ações RiskModels, com:

  • 📖 Metodologia do modelo — Visão geral do ERM3 (canônica; também espelhada em riskmodels.net)
  • 📚 Documentação abrangente da API — Especificação OpenAPI 3.0.3, guias e exemplos
  • 🌐 Portal do Desenvolvedor — Site Next.js elegante (este repositório) implantado em riskmodels.app
  • 🐍 Exemplos em Python e TypeScript — Código pronto para produção em examples/
  • 🤖 Integração com Agentes de IA — Servidor MCP, OAuth2 e manifesto de agente

Uso no Cursor (Plugin de Agente)

Este repositório é um pacote de Agent Plugins: plugin.json e mcp.json na raiz do repositório. O plugin conecta o Cursor ao servidor MCP hospedado do RiskModels. Ele não contém código que seja executado na sua máquina nem credenciais.

ArquivoO que declara
plugin.jsonPlugin riskmodels 1.0.0, Apache-2.0
mcp.jsonUm servidor, riskmodels: HTTP Streamable em https://riskmodels.app/api/mcp/openai

Instalação

  1. No Cursor, abra o Marketplace e procure por RiskModels.
  2. Instale-o para o seu usuário ou para o projeto atual.
  3. O Cursor adiciona o servidor MCP riskmodels. As ferramentas aparecem depois que você faz login.

Login

O servidor usa OAuth 2.1 com PKCE. O Cursor gerencia o fluxo, e nada é armazenado nos arquivos do plugin:

  1. Quando o Cursor se conecta pela primeira vez ao servidor riskmodels, o servidor solicita o login e o Cursor abre um navegador em riskmodels.app.
  2. Faça login com o Google ou um link de e-mail, ou escolha Entrar com senha.
  3. A tela de consentimento mostra Conectado como <email>. Se essa for a conta errada, clique em Usar uma conta diferente primeiro e depois em Permitir.
  4. O Cursor armazena o token. As ferramentas são somente leitura: elas retornam dados e nunca fazem ordens ou alteram sua conta.

Preços e conta

  • Uma conta RiskModels é necessária. Novas contas começam com US$ 20 de crédito pré-pago. Um método de pagamento é coletado no cadastro para verificação e não é cobrado até você fazer uma recarga.
  • O uso é pré-pago e cobrado por chamada de ferramenta contra esse saldo. A maioria das chamadas de ação individual custa US$ 0,005; fundamentos custam US$ 0,02, e um relatório completo de exposição de portfólio custa US$ 0,25. Tarifas e planos: riskmodels.app/pricing.
  • Opcional: vincule uma conta de corretora (Alpaca, Connect Trade ou Plaid) em riskmodels.net Configurações, e riskmodels_get_my_positions lê esse livro.

Exemplo: NVDA

Pergunte no chat de agente do Cursor:

Decomponha o risco da NVDA com o RiskModels e me dê o hedge de ETF para uma posição de US$ 100.000.

O agente chama riskmodels_decompose para a divisão de mercado / setor / subsetor / específica da ação da variância da NVDA e o índice de hedge em cada nível. Em seguida, ele chama riskmodels_hedge_position para transformar esses índices em negociações em dólares em SPY e nos ETFs de setor e subsetor. Os números são saída de modelo ao vivo do último dia de negociação.

O plugin do Claude (claude-plugin/) e o servidor MCP local do desenvolvedor (.cursor/mcp.json, mcp/) são separados e inalterados.

🚀 Links Rápidos

URLs canônicas (REST, OpenAPI e documentação)

Use estas apenas para integrações e ferramentas:

O quêURL
Base REST (OpenAPI servers)https://riskmodels.app/api
JSON OpenAPI implantado (mesma especificação de OPENAPI_SPEC.yaml)https://riskmodels.app/openapi.json
Referência interativa da API (este portal)/api-reference

Importante: O nome de host api.riskmodels.app não é usado para a API pública ou documentação legível por máquina. Links antigos ou documentação que o mencionem devem ser tratados como obsoletos; use riskmodels.app (apex) como acima.

📖 Visão Geral da API

A API RiskModels fornece análise de risco de ações de nível institucional:

  • Decomposições diárias de fatores — frações de risco explicado de mercado, setor e subsetor para as ~3.000 maiores ações dos EUA por capitalização de mercado (universo de fim de mês)
  • Índices de hedge — valores de hedge em dólares por ETF (L1/L2/L3) projetados para permanecerem executáveis com ETFs líquidos brutos
  • Séries temporais históricas — retornos ajustados por desdobramentos e dividendos (2006-01-04–presente) além de índices de hedge móveis (2010-12-08–presente) e ER (2011-12-07–presente; saídas de fatores precisam de uma janela de regressão completa)
  • Pronto para agentes de IA — OAuth2, cobrança por solicitação, manifestos legíveis por máquina

Cobertura de dados: ~16.000 ações dos EUA no painel histórico; ~3.000 maiores por capitalização de mercado ao final de cada mês para saídas principais. Atualizado diariamente. Índices de hedge: 2010-12-08 até o presente. Risco explicado: 2011-12-07 até o presente. Níveis L*: 2013-01-01 até o presente. Séries de retornos ajustados: 2006-01-04 até o presente.

Por Que o Motor Importa

O RiskModels é projetado para ser útil para trabalho real de portfólio, não apenas análises descritivas:

  • Construído para ser seguro em relação ao tempo — o motor é projetado para evitar fontes comuns de contaminação futura, como tickers reciclados, ações instantâneas e contração retroativa do universo
  • Fundamentado em um Security Master real — saídas em nível de ticker ficam sobre uma camada de identidade pontual construída para continuidade de identificadores, mudanças de símbolos e dados de ações historicamente defensáveis
  • Hierárquico por design — o modelo separa a estrutura de mercado, setor e subsetor em vez de colapsar tudo em uma visão beta plana
  • Negociável na prática — os índices de hedge publicados são projetados para funcionar com ETFs líquidos no momento da execução, não apenas com fatores sintéticos ou ortogonalizados
  • Construído sobre séries de retornos ajustados — retornos ajustados por desdobramentos e dividendos tornam a decomposição e os índices de hedge mais consistentes economicamente em horizontes longos

Para uma explicação mais profunda das escolhas de design do motor por trás dessas afirmações, consulte a documentação de metodologia e a referência da API.

🐍 SDK Python (riskmodels-py)

Prefira o SDK Python em vez de REST bruto para fluxos de trabalho nativos de agente — resolução de tickers, normalização semântica de campos, validação com erros instrutivos e formatação de contexto pronta para LLM estão integrados.

Instalação (PyPI):

PyPI version

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]

Início rápido:

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

Geração de instantâneos (relatórios PDF institucionais):

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)

Documentação:

Inteligência de risco

Os gráficos abaixo são gerados a partir de dados ao vivo da API (get_rankings + métricas de lote L3 do MAG7) via scripts/generate_readme_assets.py. Defina RISKMODELS_API_KEY (o nível gratuito é suficiente), execute o script a partir da raiz do repositório e depois faça commit de ./assets/ e ./public/docs/readme/.

MAG7 — Decomposição L3 escalada por σ

MAG7 L3 sigma-scaled risk ratios and residual HR share
Mesmo rótulo de “tech”, DNA de subsetor diferente — comprimento da barra ∝ σ anualizado; segmentos = σ × índices de risco L3 de mercado/setor/subsetor + residual (participação do HR). POST /batch/analyze via SDK save_mag7_l3_sigma_rr_png

Rankings transversais

Ranking by cohort
Detalhamento do percentil de classificação por universo / setor / subsetor

🤖 Servidor MCP (v3.0.0-agent)

O RiskModels inclui um servidor MCP (Model Context Protocol) de primeira classe, permitindo que agentes de IA consultem diretamente dados de risco e realizem análise de fatores.

Conexão MCP (API hospedada):

  • Endpoint (HTTP Streamable, POST): https://riskmodels.app/api/mcp/sse
  • Autenticação: Token Bearer (chave de API ou JWT OAuth2)
  • Descoberta: https://riskmodels.app/.well-known/mcp.json (veja OPENAPI_SPEC.yaml)

Servidor MCP local (mcp/ neste repositório) — transporte stdio para Cursor / Claude Desktop / Zed: descobre capacidades, esquemas, OpenAPI e ferramentas de risco de papel ao vivo com suporte do SDK. As ferramentas incluídas aqui são:

  • riskmodels_list_endpoints — Lista capacidades da API (id, método, endpoint, descrição curta)
  • riskmodels_get_capability — Registro completo de capacidade por id (parâmetros, preços, exemplos)
  • riskmodels_get_schema — JSON Schema para um tipo de resposta (ex.: ticker-returns-v2.json)
  • riskmodels_decompose, riskmodels_compare, riskmodels_hedge_position, riskmodels_portfolio_decompose, riskmodels_whitepaper_example — Saídas de SDK prontas para agente com chart_data, suggested_chart e resumos em linguagem simples

Para dados de risco ao vivo e matemática de portfólio, chame a API REST (ex.: GET /api/metrics/{ticker}, POST /api/batch/analyze, GET /api/l3-decomposition), o SDK Python (riskmodels-py) ou as ferramentas MCP listadas.

Veja mcp/README.md para instalação e configuração.

Anthropic Claude (Agentes Gerenciados vs API de Mensagens): design de engenharia interno para agentes opcionais hospedados em nuvem, cobrança e conformidade — veja docs/ANTHROPIC_CLOUD_AGENTS.md.

⌨️ CLI de linha de comando (riskmodels)

O pacote npm em cli/ instala o binário riskmodels: configuração, consulta SQL (API cobrada ou Supabase direto), introspecção de esquema, saldo e manifestos estáticos de agente.

Instalação a partir do npm:

npm install -g riskmodels
riskmodels --help

Desenvolvimento a partir deste repositório:

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

Publicação no npm (mantenedores): o procedimento está documentado no monorepo privado BWMACRO (docs/RISKMODELS_CLI_NPM_PUBLISHING.md), não aqui. Publique apenas a partir do diretório cli/ — o aplicativo Next.js na raiz do repositório não é publicado no npm.

💻 Portal do Desenvolvedor (Este Repositório)

Este repositório agora inclui um portal do desenvolvedor Next.js com:

  • ✨ Página inicial hero com destaques de recursos
  • 📚 Documentação alimentada por MDX (README_API.md, AUTHENTICATION_GUIDE.md)
  • 🔍 Referência interativa da API (visualizador OpenAPI Redoc)
  • 💡 Exemplos de código com realce de sintaxe e botões de copiar
  • 🎯 Guia de início rápido passo a passo

Desenvolvimento Local

# 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

Higiene na Captura de Screenshots:

Ao capturar screenshots do site para auditoria ou documentação:

  1. Garanta que o build passe primeiro: npm run build deve ser concluído sem erros
  2. Verifique se o servidor de desenvolvimento responde HTTP 200: Acesse http://localhost:3000 e confirme que as páginas renderizam (não "Internal Server Error")
  3. Execute o script de captura: python3 capture_site.py (requer Playwright)

O script ignorará páginas que retornarem HTTP 500 ou que contenham conteúdo "Internal Server Error". Screenshots com erros de servidor nunca devem ser commitados no repositório.

Gerenciamento de Ambiente com Doppler:

Este repositório usa Doppler para gerenciamento de segredos. O doppler.yaml está pré-configurado para o projeto 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

Para testes com curl/API usando segredos do Doppler:

# 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

Consulte DEPLOYMENT.md para integração detalhada Vercel/Doppler.

Visite http://localhost:3000

Build e Deploy

# Build for production
npm run build

# Start production server
npm start

Deploy: Consulte DEPLOYMENT.md para configuração do Vercel, variáveis de ambiente e configuração Supabase/Stripe.

📂 Estrutura do Repositório

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)

🛠️ Stack Tecnológico (Portal do Desenvolvedor)

  • Framework: Next.js 15 (App Router)
  • Estilização: Tailwind CSS 3.4, modo escuro padrão
  • MDX: @next/mdx para documentação
  • Referência da API: Redoc (visualizador OpenAPI 3.0)
  • Destaque de Código: CodeBlock personalizado com botão de copiar
  • Fontes: Inter (fallback system-ui)
  • Cores: Azul primário (hsl(217, 91%, 60%)), paleta escura zinc/slate

📄 Arquivos de Documentação

DocumentoDescrição
README_API.mdVisão geral completa da API, endpoints, conceitos-chave
API_TERMS.mdTermos de Serviço da API (riskmodels.net/terms/api)
PLAID_HOLDINGS_UX.mdFluxo de conexão Plaid e experiência do usuário na API de holdings
AUTHENTICATION_GUIDE.mdBearer token, OAuth2, Supabase JWT, limites de taxa
DOCS_PROCESS.mdProcesso para adicionar nova documentação
SEMANTIC_ALIASES.mdDefinições de campos, unidades, fórmulas
RESPONSE_METADATA.mdBloco _agent, cabeçalhos de resposta, preços
ERROR_SCHEMA.mdCódigos de erro e padrões de recuperação
OPENAPI_SPEC.yamlEspecificação OpenAPI 3.0.3 (v3.0.0-agent)
docs/SNAPSHOT_ROADMAP.mdRoadmap do conjunto de snapshots, ADRs e fases de implementação
docs/SNAPSHOT_CONTENT_MAP.mdEspecificação de conteúdo de 8 páginas com wireframes e schemas JSON
docs/SNAPSHOT_FRONTEND_ARCH.mdArquitetura do pipeline de renderização puro-Matplotlib

🔗 Relacionados

  • ERM3 — Motor de computação de modelos de risco em Python (código aberto)

🤝 Contribuindo

Aceitamos pull requests, especialmente para melhorar a especificação OpenAPI — descrições mais claras, melhores schemas e mais exemplos ajudam a todos.

  1. Especificação OpenAPI: CONTRIBUTING.md — PRs para OPENAPI_SPEC.yaml são incentivados
  2. Issues: Abra uma issue para bugs ou solicitações de recursos
  3. Exemplos: Envie novos exemplos via PR para examples/
  4. Documentação: Melhore a documentação editando arquivos MDX em content/docs/

📧 Suporte

📜 Licença

Consulte LICENSE para detalhes.

© 2026 Blue Water Macro Corp. Todos os direitos reservados.

Disparo de deploy: Ter Jun 9 16:13:22 PDT 2026