Sign up
OverviewProductsPrivate MarketsTengu BrainAPI Reference

Products

Quant Signals

Quant Signals exposes stored model predictions, feature attributions, voter

Live API

evidence, and research candidates. Coverage and freshness depend on the available source snapshot; a returned row does not guarantee usable numerical evidence.

What's inside#

Read each route's availability and source fields before using its output.

LayerReturned evidenceAvailability limit
ML predictionsPoint estimate, score, rank, and source dateavailable means a row exists; also check prediction_evidence_available
Prediction intervalsBounds, half-width, method, and statusMissing or inconsistent intervals have null numerical fields
Feature driversFeature attributions where the export is availableInspect returned source and coverage
Voter decompositionAvailable per-voter scores and diagnosticsA configured voter is not evidence that it supplied a usable signal
Research candidatesCandidate scores and contextual gatesA research score is not trade authorization

The interval's available flag means its numbers are compatible with the reported method. Adaptive intervals can be asymmetric: half_width is the maximum absolute residual offset from a bias-corrected center, not necessarily half the span or a radius around the raw prediction. Read geometry_status and half_width_semantics; the stored row does not retain every calibration input.

Numerical compatibility does not verify calibration. calibrated_and_coherent remains false and stated_coverage remains null without the matching calibration artifact. A method name containing "conformal" is not proof of 90% coverage.

Recent realized coverage is unavailable: realised_coverage_recent and coverage_as_of are null, and realised_coverage_status is unavailable_migration_pending. Legacy coverage used an incompatible horizon. Neither a stored method name nor a stated coverage target proves measured 30-day performance. Respect capital_authorized, capital_authorization_reasons, and use when integrating the research output.

Access#

3 credits per call · Starter and up

Quant Signals is included in Starter ($99/mo) and all paid plans. Each call to the ML stack (predictions, drivers, intervals, voters, trade setups) costs 3 credits from your monthly wallet. See Pricing & credits for plan limits and per-product breakdowns.

Endpoints#

MethodPathDescription
GET/api/v3/intel/ml_prediction/{ticker}Stored prediction, nullable return estimate and interval, voter evidence, and universe rank. Interpret blended_score using score_semantics. Takes ?asset_class=equity|crypto. Optional (defaults to equity), but pass it explicitly for the nine colliding tickers so the namespace is never inferred (see below).
GET/api/v3/intel/ml_drivers/{ticker}Top-N SHAP feature attributions: which features pushed the score bullish/bearish and by how much.
GET/api/v3/intel/factor_importanceFama-French 5-factor loadings + Bayesian voter posteriors: "what drives the strategy's returns?"
GET/api/v3/intel/voter_coverage/{ticker}Per-voter scores, weights, availability status, and freshness where supplied.
GET/api/v3/intel/voter_ic_driftVoter health dashboard: IC (information coefficient) per voter over trailing 30–60 days; flags degrading confidence.
GET/api/v3/intel/voter_attribution/{ticker}Attribution: which voters drive consensus, their thresholds, and interaction effects on the final score.
GET/api/v3/intel/model_calibrationCalibration availability and diagnostics; recent realized coverage is withheld while compatible outcomes are unavailable.
GET/api/v3/decision/trade_setupsResearch candidates with scores and regime context; availability and authorization gates still apply.
GET/api/v3/signals/fusionFused signal score (consensus across all layers).
GET/api/v3/signals/mtf/{ticker}Multi-timeframe signals: daily/weekly/monthly consensus alignment.
GET/api/v3/signals/veto_stateCircuit-breaker state: when ensemble enters "all-same-direction" veto mode.
GET/api/v3/factors/predictors/{ticker}Chen–Zimmermann open-source predictor panel: 13 replicated accounting anomalies (Sloan accruals, Cooper–Gulen–Schill asset growth, Titman capital investment, Novy-Marx gross profitability, Fama–French operating profitability, net share issuance, …) at month-end grain, permno-keyed (the ticker is resolved automatically — the panel has no ticker column). ?latest=true returns the single most-recent row as a name→value map; otherwise the newest-last time series (?start/?end). Lagged academic archive — latest-available if no dates. Returns {ticker, permno, series | predictors, predictor_glossary}.
GET/api/ml/predict/{ticker}Alternative endpoint (legacy route): latest prediction envelope.

Examples#

Example 1: Read a prediction and handle unavailable intervals#

Request an explicit asset class. The response excerpt below is illustrative, not a live result or a measured performance claim.

Shell
1curl -H "Authorization: Bearer $TENGU_API_KEY" \2  "https://firm.wealthnow.io/api/v3/intel/ml_prediction/AAPL?asset_class=equity"
JSON
1{2  "ok": true,3  "ticker": "AAPL",4  "available": true,5  "prediction_evidence_available": true,6  "use": "research_only_prediction",7  "capital_authorized": false,8  "prediction": {9    "predicted_return_pct": 2.15,10    "blended_score": 0.642,11    "conviction": null12  },13  "conformal_interval": {14    "available": false,15    "status": "unavailable_invalid_or_missing_interval",16    "reason": "Interval bounds, half-width, and point estimate are missing, non-finite, or inconsistent; numeric interval withheld.",17    "lo": null,18    "hi": null,19    "half_width": null,20    "method": null,21    "calibrated_and_coherent": false,22    "stated_coverage": null,23    "realised_coverage_recent": null,24    "coverage_as_of": null,25    "realised_coverage_status": "unavailable_migration_pending"26  }27}
Python
1import math2import os3import requests4 5 6def finite_number(value):7    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)8 9 10r = requests.get(11    "https://firm.wealthnow.io/api/v3/intel/ml_prediction/AAPL",12    params={"asset_class": "equity"},13    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},14    timeout=30,15)16r.raise_for_status()17data = r.json()18 19if data.get("ok") and data.get("prediction_evidence_available"):20    pred = data.get("prediction") or {}21    interval = data.get("conformal_interval") or {}22    print(f"Ticker: {data['ticker']}")23    estimate = pred.get("predicted_return_pct")24    if finite_number(estimate):25        print(f"Predicted return: {estimate:.2f}%")26    else:27        print("Predicted return unavailable.")28    lo, hi = interval.get("lo"), interval.get("hi")29    if interval.get("available") is True and finite_number(lo) and finite_number(hi):30        print(f"Stored research interval: [{lo:.2f}%, {hi:.2f}%]")31        coverage = interval.get("stated_coverage")32        if interval.get("calibrated_and_coherent") is True and finite_number(coverage):33            print(f"Stated coverage target: {coverage:.0%}")34        else:35            print("Interval is uncalibrated; no coverage target is established.")36    else:37        print(f"Forecast interval unavailable: {interval.get('reason') or interval.get('status') or 'no interval supplied'}")38    realized = interval.get("realised_coverage_recent")39    if finite_number(realized):40        print(f"Reported realized coverage: {realized:.1%}")41    else:42        print("Recent realized coverage unavailable.")43    if data.get("capital_authorized") is not True:44        print("Research only; capital authorization is not established.")45else:46    print("Numerical prediction evidence unavailable.")

Example 2: Get SHAP feature drivers and top trade setups#

Pull the top bullish/bearish features for a ticker and the current highest-conviction trade picks.

Shell
1# Top SHAP drivers for AAPL2curl -H "Authorization: Bearer $TENGU_API_KEY" \3  "https://firm.wealthnow.io/api/v3/intel/ml_drivers/AAPL?top=5"4 5# Illustrative response structure, not a live sample:6# {7#   "ok": true,8#   "timestamp": "2026-07-05T10:30:15Z",9#   "ticker": "AAPL",10#   "available": true,11#   "tier": "tier_2",12#   "n_features_returned": 5,13#   "drivers": [14#     {15#       "rank": 1,16#       "feature": "price_momentum_20d",17#       "shap_value": 0.287453,18#       "direction": "bullish"19#     },20#     {21#       "rank": 2,22#       "feature": "earnings_surprise_pct",23#       "shap_value": 0.156240,24#       "direction": "bullish"25#     },26#     {27#       "rank": 3,28#       "feature": "short_interest_change",29#       "shap_value": -0.082150,30#       "direction": "bearish"31#     },32#     {33#       "rank": 4,34#       "feature": "insider_net_transactions",35#       "shap_value": 0.058640,36#       "direction": "bullish"37#     },38#     {39#       "rank": 5,40#       "feature": "options_iv_percentile",41#       "shap_value": -0.031240,42#       "direction": "bearish"43#     }44#   ],45#   "interpretation": "Top-5 SHAP attributions for the tier_2-tier ensemble model's score on AAPL. Positive shap_value = the feature pushed the score higher (bullish), negative = lower (bearish).",46#   "source": "reports/ml_drivers/latest.parquet (S3 firm-runtime sidecar)"47# }48 49# Top trade setups (LONG/SHORT picks with conviction)50curl -H "Authorization: Bearer $TENGU_API_KEY" \51  "https://firm.wealthnow.io/api/v3/decision/trade_setups?limit=10&min_conviction=0.5"52 53# Illustrative partial structure, not a live sample:54# {55#   "ok": true,56#   "timestamp": "2026-07-05T10:30:30Z",57#   "setups": [58#     {59#       "ticker": "AAPL",60#       "direction": "LONG",61#       "conviction": 0.642,62#       "blended_score": 0.642,63#       "predicted_return_pct": 2.15,64#       "interval_lo": -4.32,65#       "interval_hi": 8.62,66#       "decile": 7,67#       "rank": 185068#     },69#     {70#       "ticker": "TSM",71#       "direction": "SHORT",72#       "conviction": 0.534,73#       "blended_score": -0.534,74#       "predicted_return_pct": -1.82,75#       "interval_lo": -6.54,76#       "interval_hi": 2.90,77#       "decile": 2,78#       "rank": 1238879#     }80#   ],81#   "universe_skew": "bullish",82#   "regime_warranted_alternative": {83#     "strategy": "defensive",84#     "candidates": [85#       { "ticker": "JNJ", "name": "Johnson & Johnson", "expected_role": "hedge" }86#     ],87#     "rationale": "70% of picks are LONG; defensive alternatives loaded."88#   },89#   "filter": { "min_conviction": 0.5 },90#   "count": 1091# }
Python
1import os, requests2 3# Fetch SHAP drivers4r = requests.get(5    "https://firm.wealthnow.io/api/v3/intel/ml_drivers/AAPL",6    params={"top": 5},7    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},8    timeout=30,9)10r.raise_for_status()11drivers = r.json()12 13if drivers["ok"]:14    for d in drivers["drivers"]:15        print(f"{d['rank']}. {d['feature']:30} | SHAP: {d['shap_value']:+.6f} ({d['direction']})")16 17# Fetch trade setups18r = requests.get(19    "https://firm.wealthnow.io/api/v3/decision/trade_setups",20    params={"limit": 10, "min_conviction": 0.5},21    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},22    timeout=30,23)24r.raise_for_status()25setups = r.json()26 27for s in setups["setups"]:28    print(s.get("ticker"), s.get("direction"),29          "conviction:", s.get("conviction"),30          "return estimate:", s.get("predicted_return_pct"))

Example 3: Chen–Zimmermann predictor vector for a ticker#

Pull the compact academic characteristic vector for a name — 13 replicated accounting anomalies — without loading the full ~460-column GKX panel. The panel is a lagged quarterly archive keyed by CRSP permno; the exchange symbol is resolved automatically. Use latest=true for the single most-recent row.

Shell
1curl -H "Authorization: Bearer $TENGU_API_KEY" \2  "https://firm.wealthnow.io/api/v3/factors/predictors/AAPL?latest=true"3 4# Illustrative response structure, not a live sample:5# {6#   "ok": true,7#   "timestamp": "2026-07-05T10:31:00Z",8#   "ticker": "AAPL",9#   "permno": 14593,10#   "mode": "latest",11#   "as_of": "2026-02-28",12#   "n_predictors": 13,13#   "predictors": {14#     "accruals": -0.031,15#     "asset_growth": 0.084,16#     "investment": 0.052,17#     "gross_profit_at": 0.412,18#     "oper_prof": 0.318,19#     "cash_at": 0.089,20#     "leverage_change": -0.014,21#     "earnings_consistency": 0.91,22#     "revenue_growth": 0.021,23#     "positive_ni": 1,24#     "positive_cfo": 1,25#     "current_ratio": 1.04,26#     "share_issuance": -0.00827#   },28#   "predictor_glossary": {29#     "accruals": "Sloan (1996) balance-sheet accruals anomaly",30#     "gross_profit_at": "Novy-Marx gross profitability (GP/assets)",31#     ...32#   },33#   "note": "cz_predictors has NO ticker column — the symbol is resolved to a CRSP permno via the live universe registry",34#   "source": "warehouse:factor-predictors-archive"35# }
Python
1import os, requests2 3# Latest predictor vector for a name4r = requests.get(5    "https://firm.wealthnow.io/api/v3/factors/predictors/AAPL",6    params={"latest": "true"},7    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},8    timeout=30,9)10r.raise_for_status()11data = r.json()12print(f"{data['ticker']} (permno {data['permno']}) as of {data['as_of']}")13for name, val in data["predictors"].items():14    print(f"  {name:22} {val}")15 16# ...or the full monthly time series (newest last)17r = requests.get(18    "https://firm.wealthnow.io/api/v3/factors/predictors/AAPL",19    params={"start": "2024-01-01", "limit": 24},20    headers={"Authorization": f"Bearer {os.environ['TENGU_API_KEY']}"},21    timeout=30,22)23r.raise_for_status()24series = r.json()25print(f"\n{series['n']} monthly rows, {series['start']} → {series['end']}")

Ticker collisions: crypto vs equity#

Nine tickers name both a crypto asset and a US-listed equity: BTC, ETH, LINK, LTC, COMP, ARB, NEAR, APT, ATOM.

asset_class defaults to equity; pass it explicitly so the namespace is never inferred:

Shell
1# the US-listed equity, not Bitcoin2curl -H "X-API-Key: $TENGU_API_KEY" \3  "https://firm.wealthnow.io/api/v3/intel/ml_prediction/BTC?asset_class=equity"

Responses for those nine carry a disambiguation note:

JSON
1{2  "ticker_collision": {3    "note": "This is the US-listed equity 'BTC'. For the crypto asset, pass asset_class=crypto.",4    "crypto_available": false,5    "asset_class": "equity"6  }7}

Requesting the crypto side fails closed with 404 crypto_model_unavailable rather than silently returning the equity. That error never means "use the equity instead." Non-colliding tickers are unaffected.

Related#

Previous

Macro, Rates & FX

Next

Funds & Institutional