StoQuant — Quantitative Stock Research

The named, two-sided evidence behind a ticker's Q-Score — the 'bull case vs bear case' as concrete facts rather than scores. Returns five grids (`momentum`, `sentiment`, `earnings`, `valuation`, `risk`), each with `cells`: every cell has a human-readable `label` (e.g. 'Price above 50-day average', 'Short interest'), a formatted `value`, and a `tone` ('bullish'|'bearish'|'neutral'|'unknown'). To assemble a balanced case, collect cells with tone 'bullish' (the bull case) and 'bearish' (the bear case) across all five grids. Use this AFTER stoquant_get_qscore when the user asks WHY the score is wh…

Quote plus computed technical indicators for one ticker: RSI(14), MACD, Bollinger Bands, and moving-average context. Use when you need momentum/overbought-oversold context, not just price. Heavier than stoquant_get_quote; can occasionally time out on cold cache — retry once if so.

Undervalued small-caps with confirming signals (the 'hidden gem' screen: low valuation, healthy balance sheet, low analyst coverage, plus momentum/ML/insider confirmation). Returns `{gems:[...], totalCount, lastScanAt}`. freshness filters by how recently a gem's signals fired. Use for value-oriented idea generation distinct from momentum.

Insider-buying cluster metrics for a ticker under `data`: distinctFilers14d, officerCount14d, purchaseCount90d, totalValue90d, clusterScore, and a clusterMomentum flag. Cluster buying by multiple insiders (especially officers, large dollar value) is a strong bullish signal — this scores it. Pairs with stoquant_get_insider_trades (the raw transactions).

Recent insider (Form 4) transactions for a ticker under `data`, plus a `summary` (net buy/sell counts and dollar value). Cluster buying by officers/directors — especially large dollar buys — is a notable bullish signal. Use to check whether insiders are accumulating or distributing.

Top institutional holders for a ticker: organization name, shares held, and percent ownership. Use to gauge institutional concentration and who the big holders are.

Aggregated institutional sentiment for a ticker: holder additions vs reductions and a net `signal` direction. Use as a 'smart money' flow read distinct from analyst ratings.

Forward (~14 day) economic calendar: scheduled releases with forecast, prior value, and expected market impact. Use to flag upcoming macro events (CPI, FOMC, jobs) that could move positions.

Full top-down macro picture in one call: `regime` classification, key `indicators`, `macroStress` gauge, `sectorRotation` (which sectors are favored, with valid GICS sector names), forward `calendar`, and current `themes`. Best first call for 'what's the macro backdrop' before drilling into stocks.

Latest values for one FRED macro series under `data` (recent observations) with a `count`. Common ids: DGS10 (10y Treasury yield), DGS2 (2y), T10Y2Y (10y-2y spread), UNRATE (unemployment), CPIAUCSL (CPI), VIXCLS (VIX), FEDFUNDS (fed funds). Use for a single specific indicator; for the full picture use stoquant_get_macro_dashboard.

Current macro investment themes with their related sectors — the narrative layer (e.g. rate-cut beneficiaries, AI capex). Use for thematic idea generation that ties stocks to a macro thesis.

Current market-regime classification from the Hidden Markov Model over S&P 500 returns: regime label (e.g. Bull/Range/Bear) and the probability vector across states. Use to set top-down context before stock-level calls. If the model reports it could not fit, probabilities fall back to roughly uniform — read that as 'regime undetermined', not a confident Range call.

ML model's probability that the ticker will OUTPERFORM the S&P 500 over the horizon (NOT a buy/hold/sell call). Returns `data.prediction` with: `probability` (0-1, chance of outperformance), `classification` ('bull' = predicted to outperform, 'bear' = underperform), `modelVersion`, `modelAuc`, `plainLanguage` (headline/summary/topDrivers), and `isHeuristic` (true when the trained model is gated for distribution drift and a heuristic fallback is used — weight it less). Use stoquant_explain_ml_prediction for the feature-level 'why'. horizon is in trading days. Note: early in the US trading day (…

Small/mid-caps flagged with high (>5x) upside potential: revenue acceleration, improving fundamentals, and pre-discovery setups. Higher risk/variance than hidden gems. Use for aggressive growth idea generation.

Recent news headlines for a ticker under `items`: each with publishedAt, headline, source/provider, category, and a sentiment label. Use for the latest narrative around a stock. For news plus filings plus earnings in one combined view, use stoquant_get_news_events.

Combined event view for a ticker under `data`: `news` (headlines), `filings` (SEC), and `earnings` (calendar). The single best call for 'what is happening with this stock' — recent coverage, regulatory activity, and upcoming/just-reported earnings together.

System-wide auto-portfolio health report (subsystem statuses, degraded mode, last check time). Use to see whether the engine is healthy before trusting a last-eval snapshot. Read-only — does not trigger healing or reset the drawdown breaker.

The Q-Score is StoQuant's headline 0-100 composite for a ticker, blending fundamentals, momentum/technicals, ML, analyst, and 'hidden gem' value dimensions on SECTOR-RESIDUALIZED forward returns (sector beta removed). Returns: score (0-100), signal ('strong_buy'|'buy'|'hold'|'sell'|'strong_sell'|'unrated'), per-dimension `components` (each with rawValue, normalizedScore, weight, and an `available` flag — unavailable dims contribute 0), `confidence`/`confidenceInterval`, `dimensionContributions`, a `verdict` and `plainLanguage` summary, and `riskAlerts`. This is the best single tool for 'is thi…

Quantitative analytics for a ticker under `data`: factor exposures, correlation/quality metrics, and risk decomposition. Use for portfolio-construction and factor-tilt questions. Complements stoquant_get_qscore (verdict) with the underlying quant detail.

Real-time quote for ONE ticker: last price, day change (absolute and percent), bid/ask, day high/low, and volume. Use for a single symbol; for 2+ symbols use stoquant_get_quotes_batch (one call, far fewer requests). Prices are delayed per the data vendor, not tick-by-tick.

Current quotes for up to 50 tickers in a single call. Preferred over calling stoquant_get_quote in a loop — same data, one request, stays well under rate limits. Returns one quote object per ticker (price, change, volume).

Find peers of a ticker under `peers`, each with qScore, quote, and market cap. `by` selects the relation: 'sector' (same sector), 'tag' (shared thematic tags), 'setup' (same technical setup firing), or 'correlation' (highest 60-day return correlation). Use to build a comparison set or find alternatives to a name.

Recent SEC filings for a ticker under `items` (with `count`/`total`), unioning the whole suite: 8-K events (with item labels like 'Item 2.02 Results of Operations'), NT-10K/Q late filings, 13D/13G activist/passive ownership, S-1/S-3/424B dilution, DEF 14A / Form 25 / Form 15 governance, and Form 144/3 insider intent. Each item has accession, formType, filedDate, category, and a human-readable label. Use to read the actual regulatory record behind a thesis.

Top and bottom performing stocks within a GICS sector, by recent return. Use to find what is leading or lagging inside a sector. sector must be a full GICS name (see stoquant_get_macro_dashboard sectorRotation for valid names), e.g. 'Technology', 'Health Care', 'Financials'.

Short-interest history for a ticker: append-only `snapshots` plus a `summary` (latestFloat = % of float short, latestRatio = days-to-cover, and window deltas). Rising short interest with a price squeeze can signal a short squeeze; falling can signal covering. Use for crowded-short reads.

Historical track record per signal type: an array of records with `signalType`, `hitRate` (0-1), `totalObservations`, `avgReturnPercent`, `precision`, and `windowDays`. Use to weight how much to trust a given signal before acting on it — prefer signals with high hitRate AND large totalObservations.

Hit-rate heatmap of signals over time/ticker for a date range — which signal types worked when. Use for backtest-style 'has this signal been reliable lately' questions. Dates are YYYY-MM-DD; omit for the default recent window.

Returns both the raw Q-Score (`originalQScore`) and a `stage`/regime-adjusted variant (`adjusted`) for a ticker. Use this when you want the score adjusted for the stock's lifecycle stage and current market regime rather than the raw composite. For the full breakdown use stoquant_get_qscore.

Tickers with a sharp (2x+) surge in social mentions in the last hour vs the prior hour — the earliest social-momentum signal, with sentiment and a recent post snippet per name. Use to catch breakouts in attention before they are widely noticed.

Current social-media buzz for a ticker: `totalMentions`, `recentPostCount24h`, `sentimentBreakdown` (bullish/bearish/neutral), `topPlatforms`, and a sample of `recentPosts`. Use to read retail attention and crowd sentiment. Sources are credibility-weighted platform aggregates, not raw noise.

Daily social mention-volume and sentiment trend for a ticker over the last ~30 days. Use to see whether attention and bullishness are building or fading, not just the current snapshot.

Leaderboard of social sources ranked by true directional accuracy (Wilson lower-bound on their calls). Use to judge how much weight to give a platform or author's sentiment — high-credibility sources earn more trust than raw mention volume.

Historical price series (~90 days) for up to 50 tickers, for charting or trend/return computation. interval controls granularity (1d daily, 1wk weekly, 1mo monthly). Returns an array of close prices per ticker, not full OHLCV.

Qualitative competitive intelligence for a ticker: economic moats, structural weaknesses, upcoming catalysts, and peer comparison. Best for mid/small-caps; mega-caps and thinly-covered names may return `{data:null}` (no edges computed) — treat that as 'no data', not an error.

Read-only strategy performance for a portfolio. `view` selects the slice: `kpis` (headline returns), `equity-curve` (vs SPY, normalized to 100), `monthly-returns`, `risk-metrics` (Sharpe/Sortino/max drawdown/capture), `attribution` (P/L by signal type), `comparison` (all active portfolios). Pro-tier. Does not trade.

Current ranked candidate tickers and target-weight basket for a themed preset (`social`, `insider`, `congress`, …). Returns `{preset, appliedOptions, candidates, basket}`. This is a signal read — it does NOT create or rebalance a paper portfolio.

StoQuant's current highest-conviction names: the stocks with the strongest Q-Scores backed by multiple corroborating signals. Use as the starting point for 'what does the platform like right now'. May be empty between scans (`{stocks:{}}`).

Most-mentioned tickers across social platforms in the last few hours, each with mentionCount, prevMentionCount, deltaPercent, velocityScore, bullishPct, and platforms. Use for market-wide 'what is retail talking about right now' discovery and early momentum.

Options contracts trading far above their open interest, ranked by notional (volume x price x 100). Each row under `data.rows` has ticker, optType (call/put), strike, expiry, dte, volume, openInterest, volOi, newPosition (open interest was 0), notional, priceSource (mid/last), lastVsMid and ageHours. IMPORTANT: this is a delayed QUOTE snapshot, front-month expiry only — there is no trade tape, so no buyer/seller side and no sweep detection; `lastVsMid` is only where the last print sat between bid (0) and ask (1). Open interest is published next day, so volume/OI compares today against yesterda…

The pre-built strategy templates you can backtest (`id`, name, parameters). Known ids include `momentum`, `growth_chaser`, `value`, `insider_follower`, `gem_composite`, and `research_*` variants. Call this before stoquant_run_backtest so you pass a real strategyId. Power-tier. Read-only.

List the curated prebuilt screens with their id, name, and description. Available screens: 'undervalued-gems' (low P/E, P/B value plays), 'momentum-leaders' (strong price momentum), 'oversold-bounce' (RSI reversal setup), 'ml-outperform' (ML-predicted S&P 500 outperformance), 'hidden-gems' (small-cap value with confirmation signals), 'growth-explosion' (high-growth micro/mid-caps before discovery), 'pre-explosion' (multibagger pattern: revenue acceleration + insider + fundamentals). Call this first, then run one with stoquant_run_prebuilt_screen — it is faster and better-tuned than hand-built …

Themed strategy presets (social / insider / congress, etc.) with customization knobs. Read-only signal catalog — does not create a portfolio. Use stoquant_get_strategy_preset_candidates to see the current ranked basket for one preset.

Compute target weights via Black-Litterman (HRP blend fallback). Returns an `optimization` object with weights — it does NOT place orders, rebalance, or move cash. If `predictions` is omitted the server fills views from ML forecasts (up to 20 tickers). Pro/Power tier. Use the weights as a recommendation; call stoquant_get_accuracy_summary first and do not size into buys while excessSpreadPp is negative and dataSufficient is true.

Run a historical backtest for a strategy template over [startDate, endDate]. Returns the full run (metrics at 0% slippage plus bias disclosure: Deflated Sharpe, iteration count). This is a simulation — it does NOT place live or paper orders. It does persist a run record you can reload with stoquant_get_backtest. Power-tier; computationally expensive (this call can take tens of seconds). Prefer universe=sp500. Dates are YYYY-MM-DD.

Run one curated screen by its id (from stoquant_list_prebuilt_screens) and get the ranked matching stocks. Prefer this over stoquant_run_screener for common intents (value, momentum, oversold, ML picks, hidden gems, growth) — the filters are pre-tuned. universe defaults to sp500; use 'full' for the broadest set. Result count is fixed by the screen definition.

Run a custom stock screen. Read-only — nothing is mutated. All filters are AND-combined; returns an ARRAY of matching stocks (ticker, name, price, plus the requested metrics and overlays like valueScore/qScore/mlProbability). Valid filter fields (camelCase, case-sensitive): trailingPE, forwardPE, priceToBook, marketCap, epsTrailingTwelveMonths, dividendYield, bookValue, regularMarketPrice, fiftyDayAverage, twoHundredDayAverage, fiftyDayAverageChangePercent, twoHundredDayAverageChangePercent, regularMarketChangePercent, fiftyTwoWeekHighChangePercent, regularMarketVolume, averageDailyVolume3Mont…