Risk Metrics

Correlation vs macro factor returns

Computes Pearson or Spearman correlation between a stock return series and daily macro factor returns stored in macro_factors (e.g. bitcoin, vix). Stock series may be gross returns or ERM3 residual returns (L1/L2/L3) using the replication identity with SPY and sector/subsector ETFs. Request body accepts a single ticker or an array for batch (results array). Cost: $0.01 per request. Factor strings are normalized to lowercase canonical keys matching macro_factors.factor_key (aliases such as btc → bitcoin). JSON Schema (MCP / validation): request body https://riskmodels.app/schemas/factor-correlation-request-v1.json ; single-ticker 200 body https://riskmodels.app/schemas/factor-correlation-v1.json .

post/correlation

Request

  • Base URL: https://riskmodels.app/api
  • URL: https://riskmodels.app/api/correlation
  • Auth: HTTP bearer

Request body

factorsstring[]

Factor keys matching macro_factors.factor_key. Two sleeves share the table and endpoint; the metadata.category field on each row distinguishes them. Macro sleeve (10 keys, from ds_macro_factor.zarr): inflation (TIP), term_spread (VGIT), short_rates (BIL), credit (HYG), oil (USO), gold (GLD), usd (UUP), volatility (VXX short-term vol futures), bitcoin (BITO), vix_spot (FRED VIXCLS spot index). Note: volatility and vix_spot are DIFFERENT — VXX captures futures roll dynamics, VIXCLS is pure spot. Style sleeve (8 keys, mirrored from ds_etf.zarr): momentum (MTUM), quality (QUAL), low_vol (USMV), value (VLUE), growth (IWF), size (IWM), dividend (SCHD), moat (MOAT). History starts at each ETF's launch date (2011–2013 for MSCI factors; 2000 for IWF/IWM); pre-launch windows return null correlations. Style factors are most informative against return_type=l3_residual: because the residual is already orthogonal to SPY/sector/subsector, correlation isolates the pure style tilt. Legacy v1 aliases (dxy→usd, vix→vix_spot, ust10y2y→term_spread), common synonyms (btc, wti, xau, gld, cpi, tips), and style aliases (mtum, qual, usmv, vlue, iwf, iwm, schd, moat, minvol, small_cap) are normalized server-side. Defaults to all 18 canonical keys when omitted.

return_type'gross' | 'l1' | 'l2' | 'l3_residual'
window_daysinteger
method'pearson' | 'spearman'

Example request

{
  "ticker": "NVDA"
}

Response

Correlations per macro factor (null when insufficient overlap or missing data).

OR

Example response

{
  "_metadata": {
    "model_version": "ERM3-L3-v30",
    "data_as_of": "2026-03-17",
    "factor_set_id": "SPY_uni_mc_3000",
    "universe_size": 2987,
    "wiki_uri": "https://riskmodels.app/docs/methodology/erm3-l3",
    "factors": [
      "SPY",
      "XLK",
      "XLF",
      "XLV",
      "XLE",
      "XLI",
      "XLY",
      "XLP",
      "XLU",
      "XLB",
      "XLRE",
      "XLC"
    ],
    "range": [
      "2018-01-02",
      "2026-04-14"
    ]
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.