get_pretrade_risk_scan

Run a pre-trade risk scan for a single stock: the stock's own volatility/beta/VaR/drawdown set against the SPY benchmark, market regime, a forward return distribution for the stock, position-sizing checks on the stock's own metrics, and — against the user's tracked watchlist — the sector/symbol exposure impact of adding it and its correlation to existing holdings.

riskDeltas compare SPY with the stock on its own. They are NOT the risk of the user's portfolio before and after the trade; only exposure and correlation use the portfolio.

Use this tool when:

• You need a risk-first check before evaluating or placing a trade.

• You want position-sizing guardrails (volatility, drawdown, beta, liquidity) evaluated against warn/fail thresholds, not just raw numbers.

• You need to see how adding this symbol would shift sector or per-symbol concentration in the existing portfolio.

• You want the new symbol's correlation to current holdings, to judge diversification benefit vs. redundant exposure.

Do NOT use this tool for:

• A standalone price-distribution simulation with no portfolio context → use get_monte_carlo instead.

• A general bullish/bearish read on the stock → use analyze_stock.

Example

get_pretrade_risk_scan("NVDA")

Returns

dict with keys: symbol : str — normalized ticker asOf : str — ISO 8601 date the scan was computed regime : str — "bull" | "bear" | "chop" market regime regimeConfidence: float — 0–1 confidence in the regime classification riskDeltas : list — the stock's own risk metrics next to the SPY benchmark's (field names are historical; neither side is a portfolio), each a dict: label : str — e.g. "Annualized Volatility", "Beta (vs SPY)", "1-Day VaR (95%)", "Max Drawdown (1Y)" beforeValue : float — the SPY benchmark's value (beta is 1.0) afterValue : float — the scanned stock's own value unit : str — "%" or "" (unitless, e.g. beta) higherIsRiskier : bool — whether an increase in this metric is worse distribution : dict — the stock's simulated forward return distribution over methodology.monteCarlo .horizonDays trading days (10): {"bins": list, "frequencies": list, "kde_x": list, "kde_y": list} range_90 : dict — {"lower": float, "upper": float} 5th-95th percentile of that forward return (%) mean : float — mean simulated forward return (%) threshold : float — break-even line of the distribution (0.0) sizingChecks : list — pass/warn/fail guardrail checks on the stock's own metrics, each a dict: label : str — "Volatility" | "Drawdown Risk" | "Market Exposure" | "Liquidity" status : str — "pass" | "warn" | "fail" detail : str — human-readable explanation with the thresholds used. Liquidity is the 20-day average of close x volume in the ticker's quote currency (no FX conversion); the service warns below 5,000,000 and fails below 500,000, and the detail text states those limits. Services deployed before 2026-10-12 print $50M / $5M in the text; the limits applied were 5,000,000 / 500,000 throughout. exposure : dict — portfolio concentration impact: available : bool — false if the user has no watchlist symbols to compare against bySector : list of {sector, currentPct, postTradePct, deltaPct} — empty list when available is false bySymbol : list of {symbol, currentPct, postTradePct, deltaPct} — empty list when available is false concentrationFlag : str — "pass" | "warn" | "fail" | "unknown" ("unknown" when available is false) assumedPositionWeight: float | None — None when available is false weightingMethod : str — e.g. "equal_weight_proxy" reason : str — present only when available is false; human-readable explanation (e.g. "No watchlist symbols to compare against. Add symbols to your watchlist to see portfolio exposure.") — surface this to the user instead of guessing why the section is empty correlation : dict — correlation of the new symbol to holdings: available : bool — false if the user has no watchlist symbols to compare against aggregate : dict | None — None when available is false; otherwise {avgCorrelationWithPortfolio, level, mostCorrelated: {symbol, correlation}, leastCorrelated: {symbol, correlation}} matrix : dict | None — None when available is false; otherwise {"symbols": list, "values": list[list[float]]} full pairwise correlation matrix reason : str — present only when available is false; human-readable explanation (e.g. "No watchlist symbols to compare against. Add symbols to your watchlist to see correlation.") — surface this to the user instead of guessing why the section is empty methodology : dict — how the scan was computed, read from the constants the computation uses. Absent from services deployed before 2026-10-12. Includes: monteCarlo : dict — {"model": "gbm", "horizonDays": int (10), "paths": int, "seeded": bool}; horizonDays is the horizon of distribution / range_90 / mean var : dict — {"method": "historical", "confidence": 0.95, "horizonDays": 1} thresholds : dict — warn/fail limits for every check, e.g. "turnoverBelow": {"warn": 5000000, "fail": 500000} windowStart, windowEnd, lookbackCalendarDays, observations, benchmark, benchmarkFallback, returns, annualizationDays, beta, maxDrawdownDays

Notes

• Requires a valid HPSILAB_API_KEY.

• Requires a paid plan (Developer, Team, Enterprise, Pro, or Pro Lifetime). A Free account is refused with HTTP 403 (http_error, status_code 403) and is not charged.

• Each call deducts Credits from the account (x-credits in this tool's metadata). The Credits check runs first, so an empty balance is insufficient_credits (402) even on a Free account. Confirm with the user before calling it.

• Exposure and correlation sections assume the user has an existing tracked watchlist/portfolio. If none exists, "available" is false in both sections, their data fields are null/empty, and each includes a "reason" string explaining why — relay that reason to the user (e.g. suggest adding symbols to their watchlist) rather than treating the missing data as an error.