Risk Metrics

(internal/legacy) Decompose a position into four additive bets with hedge ratios

Per Snapshot Architecture v3, prefer POST /snapshot with type: "ticker" for new clients. This endpoint remains callable as an internal building block. Returns the simplified four-layer ERM3 exposure for a single ticker: market, sector, subsector, and residual. Each tradable layer (market / sector / subsector) maps to a hedge ETF from ticker_metadata; residual is stock-specific and not tradable. The response also includes a top-level hedge map of ETF → dollar ratio. Each value is the layer hedge ratio itself: the ETF dollar position per $1 long stock, negative = short the ETF. A stock with positive market beta carries a negative market hr (e.g. l1_mkt_hr ≈ -l1_mkt_beta), so the hedge shorts SPY.

The response also carries style and stock_specific: a diagnostic FF2 (SMB + HML) split of exposure.residual into a non-tradable style share and the doubly-cleaned stock-selection residual, on the hedge_levels basis. See POST /v4/decompose for the same split expressed as named blocks.

Same billing profile as GET /metrics/{ticker} — this is a thin semantic wrapper that flattens the L3 metrics into an agent-friendly shape. For the full L1/L2/L3 snapshot (all six HR names), use GET /metrics/{ticker}.

Authentication: Required (API Key or OAuth2) Billing: $0.005 per request Rate Limit: 120 requests/minute (default)

post/decompose

Request

  • Base URL: https://riskmodels.app/api
  • URL: https://riskmodels.app/api/decompose
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://riskmodels.app/oauth/authorize, token URL https://riskmodels.app/api/oauth/token, scopes: mcp:read)

Request body

tickerstring required

Stock ticker symbol (case-insensitive; trimmed and upper-cased).

Example request

{
  "ticker": "NVDA"
}

Response

Four-layer decomposition with hedge map.

tickerstring required
symbolstring required

Canonical symbol key in V3 registry.

data_as_ofstring date required

Latest trading day the metrics apply to.

teostring date required

V3 observation date (time-end) for this row.

hedgeobject required

Map of hedge-ETF → dollar ratio (= the layer hr: ETF dollars per $1 long stock, negative = short the ETF). If two layers share the same ETF (e.g. subsector falls back to the sector ETF), the values are summed so each ETF appears once.

_metadataobject

Lineage, billing code, and freshness (same shape as /metrics).

Example response

{
  "ticker": "NVDA",
  "exposure": {
    "market": {
      "er": 0.22,
      "hr": 0.35,
      "hedge_etf": "XLK"
    },
    "sector": {
      "er": 0.22,
      "hr": 0.35,
      "hedge_etf": "XLK"
    },
    "subsector": {
      "er": 0.22,
      "hr": 0.35,
      "hedge_etf": "XLK"
    },
    "residual": {
      "er": 0.22,
      "hr": 0.35,
      "hedge_etf": "XLK"
    }
  },
  "hedge": {
    "SPY": -1.1,
    "XLK": -0.35,
    "SMH": -0.6
  },
  "hedge_levels": {
    "L1": {
      "hedge_etfs": {
        "market": "SPY"
      }
    },
    "L2": {
      "hedge_etfs": {
        "market": "SPY"
      }
    },
    "L3": {
      "hedge_etfs": {
        "market": "SPY"
      }
    }
  },
  "style": {
    "explained_variance": 0.102,
    "role": "diagnostic"
  },
  "stock_specific": {
    "explained_variance": 0.475
  }
}

Changes

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