# RiskModels (riskmodels.app)

RiskModels is an agent-friendly US equity risk API: hierarchical (L3) variance decomposition,
ETF hedge ratios, metrics, portfolio snapshots, and a hosted MCP surface.

**No sign-in yet?** If this host publishes a shared demo key, you will find it under **Public sample API key** below — use it as `RISKMODELS_API_KEY` / `Authorization: Bearer …` for MAG7 examples. That path is meant for browser agents that cannot run `POST /api/auth/provision-free`.

## Magnificent 7 (MAG7)

These seven US equities are the usual demo / smoke-test set (landing charts, optional public sample key, `mag7=true` on tickers):

- AAPL
- MSFT
- GOOG
- AMZN
- NVDA
- META
- TSLA

One-line form: **AAPL, MSFT, GOOG, AMZN, NVDA, META, TSLA**. For Alphabet use **GOOG** in examples; **GOOGL** aliases to the same name in the API. The public JSON from `GET /api/tickers?mag7=true` may list **GOOGL**; both work with `GET /api/metrics/{ticker}` and related routes.

## First-time setup (human runs once in a terminal)

- Install Node.js LTS (https://nodejs.org).
- Get an API key: https://riskmodels.app/get-key
- Run (pins the CLI so `npx` does not use a stale cache):

  RISKMODELS_API_KEY=… npx -y riskmodels@latest install

  Optional: add --dry-run first. The installer stores the key in ~/.config/riskmodels/config.json
  and merges the RiskModels MCP server into supported clients (Cursor, Claude Desktop, Codex, etc.).

## Claude Code (terminal `claude`) vs Claude Desktop

`riskmodels install` updates Claude Desktop and Cursor configs. The **Claude Code** CLI uses a
separate MCP store. After install, register RiskModels for Claude Code:

  claude mcp add --scope user --transport stdio riskmodels -- npx -y @riskmodels/mcp

Then restart `claude` and check `claude mcp list`. If the server does not connect, use the hosted
MCP URL with `mcp-remote` and AUTHORIZATION=Bearer … (see Quickstart / MCP README).

## Where to integrate without a local install

- Hosted MCP (Streamable HTTP): https://riskmodels.app/api/mcp/sse — use with an MCP client and
  Bearer token; discovery tools need no key; data tools bill per underlying REST route.
- OpenAPI: https://riskmodels.app/openapi (or /api-docs in the portal)
- Python SDK (PyPI): riskmodels-py — see https://riskmodels.app/docs/python-sdk

## Agent prompts

- Compare tickers: "Compare AAPL and NVDA using RiskModels. What am I really betting on?"
- Do not paste **private** API keys into LLM chats; use env vars or local config. When this file
  includes a **Public sample API key** section, that token is intentionally published for agents.

Canonical site: https://riskmodels.app  |  Terms: https://riskmodels.net/terms/api

## Public sample API key (LLM agents)

When this block appears, the host has enabled a **shared** demo credential (Doppler / Vercel: `LLMS_TXT_PUBLIC_AGENT_KEY`). It is intended for documentation and agent smoke tests on the **Magnificent 7** listed above (**AAPL, MSFT, GOOG, AMZN, NVDA, META, TSLA**). It is rate-limited and may be rotated without notice; for production or the full ~3k universe, use a personal key from https://riskmodels.app/get-key .

Public MAG7 ticker array from the API (no auth; symbols may show GOOGL):

curl -sS "https://riskmodels.app/api/tickers?mag7=true"

RISKMODELS_API_KEY=rm_agent_live_hcZs1KUiVgprAocQ003n6RpbWMoDpS9L_UQPDOofC

bash — latest L3 metrics for all seven (same symbols as the bullet list):

for t in AAPL MSFT GOOG AMZN NVDA META TSLA; do curl -sS -H "Authorization: Bearer $RISKMODELS_API_KEY" "https://riskmodels.app/api/metrics/$t"; done

bash — 5y returns + hedge-ratio / ER history (adjust `years`):

for t in AAPL MSFT GOOG AMZN NVDA META TSLA; do curl -sS -H "Authorization: Bearer $RISKMODELS_API_KEY" "https://riskmodels.app/api/ticker-returns?ticker=$t&years=5"; done

Python (riskmodels-py) after exporting `RISKMODELS_API_KEY`:

from riskmodels import RiskModelsClient, to_llm_context
client = RiskModelsClient.from_env()
for t in ("AAPL", "MSFT", "GOOG", "AMZN", "NVDA", "META", "TSLA"):
    print(to_llm_context(client.get_metrics(t)))