My portfolioManagers & fundsFund lineupHow to read results
Checking session...
Looking for the latest API reference? The canonical documentation and key management have moved to the developer platform.
Go to riskmodels.app
Live API

ERM3 Risk Metrics API

Institutional-grade equity factor data — hedge ratios, risk decomposition, and daily returns. Start with $20 free credits (valid card required for verification).

📓

Interactive Notebook

Google Colab · zero setup

Three ready-to-run examples: hedge a stock, hedge a portfolio, and build a factor risk table. Or use the CLI for faster local workflows. Paste your key in cell 2 and run all.

  • ✓CLI quickstart: npm install -g @riskmodels/cli
  • ✓Hedge a single stock (L1/L2/L3 ratios → DataFrame)
  • ✓Hedge a portfolio (weighted across positions)
  • ✓Factor risk table (market / sector / residual decomposition)
Open in Google Colab

If Colab asks to allow pop-ups, click Allow in your browser's address bar — it needs a window to complete Google Drive auth.

🔑

Demo Key

Mag 7 tickers · 5 req/min · 250 tokens/request

Try the API right now with this shared demo key — works for AAPL, MSFT, GOOGL, AMZN, META, NVDA, TSLA. Rate-limited to keep it available for everyone.
Get your own key: $20 free credits after card verification

Demo key not configured — use the email form to get your own.

Get your own key

Sign up, add a card for $20 in credits, then issue keys and connect Plaid from Settings.

Create account

RiskModels V2 API Documentation

Overview

The RiskModels API (V2) provides programmatic access to institutional-grade equity risk analysis. The system uses a long-form Entity-Attribute-Value (EAV) schema for historical time-series data, enabling maximum flexibility for financial metrics.

Base URL: https://riskmodels.net/api

Response metadata: Time-series endpoints include _metadata with data_as_of and model_version for reproducibility.


Core Endpoints

1. /api/tickers

Search and list all available symbols in the RiskModels universe.

  • GET /api/tickers?array=ticker: List all ticker symbols.
  • GET /api/tickers?search=QUERY: Search for a ticker by symbol or company name.
  • GET /api/tickers?mag7=true: Returns only Magnificent 7 tickers (high performance).

2. /api/metrics/[ticker]

Get the latest risk metrics snapshot for a specific ticker.

  • GET /api/metrics/AAPL: Latest volatility, hedge ratios, and explained risk.

3. /api/ticker-returns

Fetch historical daily returns and hierarchical hedge ratios.

  • GET /api/ticker-returns?ticker=NVDA&years=3: 3 years of daily returns with L3 market, sector, and subsector hedge ratios.
  • Format: Add ?format=parquet or ?format=csv for bulk downloads (default: JSON).
  • Response: Includes data, meta, and _metadata (model_version, data_as_of).

4. /api/returns and /api/etf-returns

Stock and ETF returns time series (daily).

  • GET /api/returns?ticker=AAPL&years=1: Daily gross returns for a stock.
  • GET /api/etf-returns?ticker=SPY&years=5: Daily gross returns for an ETF.
  • Format: ?format=parquet or ?format=csv supported.

5. /api/estimate

Pre-flight cost estimate (free to call).

  • POST /api/estimate
    { "endpoint": "ticker-returns", "params": { "ticker": "NVDA", "years": 5 } }
    
  • Returns estimated_cost_usd and related fields.

6. /api/l3-decomposition

Detailed hierarchical risk decomposition history.

  • GET /api/l3-decomposition?ticker=TSLA&from=2024-01-01: Time-series of HR and ER metrics at all three factor levels.

7. /api/batch/analyze

Efficiently analyze multiple positions in a single call.

  • POST /api/batch/analyze
    {
      "tickers": ["AAPL", "MSFT", "GOOGL"],
      "metrics": ["returns", "hedge_ratios", "full_metrics"],
      "years": 1
    }
    

8. /api/heatmap

Retrieve market-wide data for treemap visualizations.

  • GET /api/heatmap?limit=500: Top 500 stocks with latest returns and market caps.

9. /api/fundamentals/[ticker]

Retrieve point-in-time quarterly fundamentals and derived cost-of-capital fields.

  • GET /api/fundamentals/AAPL?periods=8: Returns only rows available by the request's knowledge date, including each row's period end and filing date.
  • cost_of_debt and wacc are the strict reported-data fields. They remain null when positive trusted SEC debt exists but reported interest expense cannot support a debt cost. A null strict value is a data gap, not a zero-percent debt cost.
  • cost_of_debt_imputed and wacc_imputed are separate, additive fallback fields; clients must never silently coalesce them into the strict fields.
  • When cost_of_debt_imputation.status is used, the proxy is the point-in-time 10-year Treasury rate plus the Treasury High Quality Market 10-year corporate spread. The HQM series covers the A/AA/AAA high-quality corporate market and is not an issuer-specific rating, bond yield, or reported company figure.
  • Inspect cost_of_debt_imputation for the risk-free input, spread, HQM spot rate, reference month, series identifiers (HQMCB10YR and GS10), and status. For point-in-time use, reference month M becomes eligible on day 10 of M+1; hqm_observation_date names that reference month and is not a publication or availability date.
  • Both WACC fields use book-value weights. Market-value weights remain the textbook convention and require an external market-cap input.

Data Schema (V2)

Table: symbols (Master Registry)

Stores metadata and latest cached metrics for all securities.

  • ticker: TEXT (PK)
  • asset_type: ENUM ('stock', 'etf', 'index')
  • latest_teo: DATE
  • latest_vol: REAL
  • latest_er_total: REAL
  • latest_hr_mkt: REAL
  • metadata: JSONB (company_name, sector, industry, sector_etf)
  • latest_metrics: JSONB (additional daily snapshots)

Table: security_history (Time-Series)

Stores historical values in EAV format.

  • symbol: TEXT (FK to symbols)
  • teo: DATE
  • metric_key: TEXT (e.g., 'return', 'L3_market_HR')
  • value: REAL
  • periodicity: ENUM ('daily', 'monthly')

Key Metrics Reference

| Metric Key | Description | Unit | |------------|-------------|------| | return | Daily log return | Decimal | | L3_market_HR | Market (SPY) hedge ratio | Ratio | | L3_sector_HR | Sector (GICS) hedge ratio | Ratio | | L3_subsector_HR | Subsector hedge ratio | Ratio | | L3_market_ER | Risk explained by Market | 0.0 - 1.0 | | L3_residual_risk | Idiosyncratic risk remaining | 0.0 - 1.0 |


Last Updated: October 7, 2026