Quant Signals

What's inside#

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

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#

Quant Signals is included in Starter ($99/mo) and all paid plans. Each call to the ML stack (predictions, drivers, intervals, voters, trade setups, scans, factor data) costs 3 credits from your monthly wallet. The server-sent-event feeds for signals and decisions belong to the same product; see Real-Time Streaming, which also says which feeds carry data today. See Pricing & credits for plan limits and per-product breakdowns.

Endpoints#

Every route on this page is GET, costs 3 credits and needs Starter or above. The MCP tool column is the tool name on the Wealthnow MCP server; each tool takes the same parameters as its route.

Predictions and uncertainty#

Batch predictions across many tickers#

GET /api/v2/predict/multi_horizon (MCP multi_horizon_batch, Quant Signals, Starter and up, 3 credits per call) answers up to 200 tickers from the stored prediction book in one call:

• One horizon carries a leg. The model was trained for 1m, so only 1m gets a leg; every other horizon you ask for is null, because no forecast was trained for it. training_horizon is 1m, evaluated_horizon is 1d, and horizon_status is unknown: do not present the 1m leg as a one-month return forecast.
• What a leg holds. direction (positive, negative or flat), percentile (100 = best rank in the scored universe; null when the full ranking is not available) and source. While point_estimate_supported is false, predicted_return_pct is null and the leg carries withheld: "uncalibrated_point_estimate". The number it would have been is blended_score × 100, a scored ordering described in point_estimate, not a forecast. Legs carry no interval.
• Every ticker is accounted for. Each requested ticker appears once, in rows (keyed by ticker, then horizon) or in missing_tickers. missing_tickers means the ticker is not in the scored equity universe, never that the read failed. A fund or ADR the book scored is in missing_tickers and also in excluded_tickers, as {ticker, reason}; the response adds the book_guard block (see Funds and ADRs).
• Dates. as_of_ts is the newest prediction timestamp in the book, snapshot_age_s is how long ago this server loaded it, and stale is true when as_of_ts is more than 3 weekdays old.
• Refusals. A malformed symbol returns 400 with error: "invalid_tickers" naming them, more than 200 distinct symbols returns 400 too_many_tickers, no usable symbol returns 400 no_valid_tickers, and an unknown horizon returns 400 invalid_horizons. A server that has not loaded the book yet answers 503 with error: "snapshot_cold" and retry_after_s: 5 (also Retry-After: 5); retry after the wait. A loaded book that lacks the columns the route needs answers 503 snapshot_unusable, also with Retry-After: 5, rather than reporting every ticker missing. While the book guard loads its sources the route answers 503 snapshot_cold (Retry-After: 5), and when the guard cannot verify the book, 503 snapshot_unusable with Retry-After: 60 and the book_guard block. None of these is billed.

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/predict/multi_horizon?tickers=AAPL,MSFT,ZZZZ&horizons=1m,3m" # Response structure; values are placeholders, not live data:# {#   "ok": true,#   "contract": "firmMultiHorizonBatch.v3",#   "as_of_ts": "...",#   "snapshot_age_s": ...,#   "stale": true,#   "horizons": ["1m", "3m"],#   "horizon_status": "unknown",#   "point_estimate_supported": false,#   "point_estimate": { ... },#   "training_horizon": "1m",#   "evaluated_horizon": "1d",#   "rows": {#     "AAPL": {#       "1m": {"predicted_return_pct": null, "direction": "positive", "percentile": ...,#              "withheld": "uncalibrated_point_estimate", "source": "ensemble"},#       "3m": null#     },#     "MSFT": { "...": "..." }#   },#   "missing_tickers": ["ZZZZ"]# }

Rankings and market-wide scans#

Explaining the model#

Model health and track record#

Regimes#

Factor and characteristic data#

Price snapshot#

How old the prediction book is#

The stored prediction book has not been regenerated since 2026-09-14. The routes that serve it say how old it is in a data_freshness block, graded when you call, on the rows actually served:

A stale book is still served, with this block, so read is_stale before presenting a score, rank or pick as current. data_freshness is on ml_prediction, ml_predict, ml_top_picks, prediction_intervals, ultimate_decision, trade_setups, universe_scan, signals_fusion and the book fallback of prediction_tracker. data_staleness_days on a served prediction row is computed from the row's own as_of_ts when you call; it used to pass through a stored value that was always 0.0.

Funds and ADRs are not ranked as equities#

The equity model ranks companies on company characteristics that a fund or an ADR does not have, yet the book carries an equity-model score for several thousand of them, many on the same no-feature constant (SPY, AGG, QQQ and GLD share one). Since 2026-09-25 a fund or ADR (by security class in the security master) whose row carries an equity-model score is removed before any ranking is built or any per-ticker prediction is served. A row the pipeline's quarantine list says to refuse is removed the same way. Nothing is re-ranked: rank and decile keep the book's own values, computed over every row.

Ranking routes (ml_top_picks, trade_setups, universe_scan, ultimate_decision without a ticker, signals_fusion, the book fallback of prediction_tracker, and multi_horizon_batch) carry a book_guard block: verified, n_rows, n_served, n_excluded, excluded_by_reason (non_equity_constant_ml_score counts funds and ADRs, quarantined:<code> refused quarantine rows), checks and rank_note.

A fund or ADR you ask for by name:

An excluded block carries error_code: "excluded_from_equity_ranking", error_message, reason and ticker.

When the guard cannot load the security master it cannot verify any row. A ranking or per-ticker prediction then answers 503 with error: "upstream_unavailable", error_code: "book_guard_unavailable", the book_guard block and Retry-After: 60, not billed, instead of serving unchecked rows. multi_horizon_batch answers 503 snapshot_cold or snapshot_unusable instead (see Batch predictions), and quote_and_fundamentals keeps its quote and fundamentals and names the gap in prediction_unavailable.

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.

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/ml_prediction/AAPL?asset_class=equity"

{  "ok": true,  "ticker": "AAPL",  "available": true,  "prediction_evidence_available": true,  "use": "research_only_prediction",  "capital_authorized": false,  "prediction": {    "predicted_return_pct": null,    "blended_score": 0.027183,    "conviction": 0.2767,    "decile": 9,    "rank": 2013,    "n_universe": 13049,    "percentile_rank": 84.57,    "withheld": "uncalibrated_point_estimate"  },  "point_estimate_supported": false,  "conformal_interval": {    "available": false,    "status": "unavailable_invalid_or_missing_interval",    "reason": "Interval bounds, half-width, and point estimate are missing, non-finite, or inconsistent; numeric interval withheld.",    "lo": null,    "hi": null,    "half_width": null,    "method": null,    "calibrated_and_coherent": false,    "stated_coverage": null,    "realised_coverage_recent": null,    "coverage_as_of": null,    "realised_coverage_status": "unavailable_migration_pending"  }}

import mathimport osimport requests  def finite_number(value):    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)  r = requests.get(    "https://firm.wealthnow.io/api/v3/intel/ml_prediction/AAPL",    params={"asset_class": "equity"},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()data = r.json() if data.get("ok") and data.get("prediction_evidence_available"):    pred = data.get("prediction") or {}    interval = data.get("conformal_interval") or {}    print(f"Ticker: {data['ticker']}")    estimate = pred.get("predicted_return_pct")    if finite_number(estimate) and data.get("point_estimate_supported") is True:        print(f"Predicted return: {estimate:.2f}%")    elif pred.get("withheld"):        # Withheld on purpose: the score is a ranking, not a return forecast.        print(f"Rank {pred.get('rank')} of {pred.get('n_universe')}, "              f"decile {pred.get('decile')} (magnitude withheld: {pred['withheld']})")    else:        print("Predicted return unavailable.")    lo, hi = interval.get("lo"), interval.get("hi")    if interval.get("available") is True and finite_number(lo) and finite_number(hi):        print(f"Stored research interval: [{lo:.2f}%, {hi:.2f}%]")        coverage = interval.get("stated_coverage")        if interval.get("calibrated_and_coherent") is True and finite_number(coverage):            print(f"Stated coverage target: {coverage:.0%}")        else:            print("Interval is uncalibrated; no coverage target is established.")    else:        print(f"Forecast interval unavailable: {interval.get('reason') or interval.get('status') or 'no interval supplied'}")    realized = interval.get("realised_coverage_recent")    if finite_number(realized):        print(f"Reported realized coverage: {realized:.1%}")    else:        print("Recent realized coverage unavailable.")    if data.get("capital_authorized") is not True:        print("Research only; capital authorization is not established.")else:    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.

SHAP values explain one model, so ml_drivers serves drivers only when every row of the drivers file names the same model bundle (model_bundle_sha256) and that bundle is the one serving now. Otherwise it answers 503 with error: "upstream_unavailable" and error_code: "upstream_dead_drivers_unbound", not billed, and binding.status says why:

On 2026-09-25 the published drivers file records no bundle, so every ticker is refused with unbound. A failed read of the file is refused the same way, with error_code archive_read_timeout (the read took more than 5 seconds, Retry-After: 300), archive_read_failed (the file could not be read, 300) or upstream_dead_no_archive (the file holds no rows, 3600). None of these refusals means the ticker is outside the model's scoring universe, and none is an empty result: the drivers could not be established, so do not describe them.

A served answer carries model_bundle_sha256, as_of (when the drivers were computed), stale (true past 72 hours) and report_freshness. When the bound file has no rows for the ticker, the answer is marked available: false and carries the same fields; like any paid result marked unavailable, it reaches you as a 503 paid_data_unavailable, not billed.

# Top SHAP drivers for AAPLcurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/ml_drivers/AAPL?top=5" # The refusal on 2026-09-25 (HTTP 503, Retry-After: 3600). error, error_code and# binding.status are the values captured for AAPL; the rest shows the shape:# {#   "ok": false,#   "error": "upstream_unavailable",#   "error_code": "upstream_dead_drivers_unbound",#   "product": "ml_drivers",#   "data_available": false,#   "is_empty_result_set": false,#   "detail": "NO DRIVERS WERE SERVED for AAPL: the SHAP drivers file does not record which model bundle produced it, ... THIS DOES NOT MEAN AAPL IS OUTSIDE THE MODEL'S SCORING UNIVERSE, ...",#   "binding": {"bound": false, "status": "unbound", "drivers_bundle_sha256": null,#               "active_bundle_sha256": null, "as_of": "..."},#   "coverage": {"drivers_as_of": "..."},#   "billing": {"charged": false, "policy": "..."},#   "retry_after_s": 3600,#   "ticker": "AAPL"# } # A served answer. Illustrative response structure, not a live sample:# {#   "ok": true,#   "timestamp": "2026-07-05T10:30:15Z",#   "ticker": "AAPL",#   "available": true,#   "tier": "tier_2",#   "n_features_returned": 5,#   "drivers": [#     {#       "rank": 1,#       "feature": "price_momentum_20d",#       "shap_value": 0.287453,#       "direction": "bullish"#     },#     {#       "rank": 2,#       "feature": "earnings_surprise_pct",#       "shap_value": 0.156240,#       "direction": "bullish"#     },#     {#       "rank": 3,#       "feature": "short_interest_change",#       "shap_value": -0.082150,#       "direction": "bearish"#     },#     {#       "rank": 4,#       "feature": "insider_net_transactions",#       "shap_value": 0.058640,#       "direction": "bullish"#     },#     {#       "rank": 5,#       "feature": "options_iv_percentile",#       "shap_value": -0.031240,#       "direction": "bearish"#     }#   ],#   "model_bundle_sha256": "...",#   "as_of": "2026-07-05T02:10:00+00:00",#   "stale": false,#   "report_freshness": {"ml_drivers": {"as_of": "2026-07-05T02:10:00+00:00", "as_of_field": "as_of_ts",#                        "provenance": "payload", "report_age_hours": 8.3, "max_age_hours": 72.0, "stale": false}},#   "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).",#   "source": "reports/ml_drivers/latest.parquet (S3 firm-runtime sidecar)"# } # Top trade setups (LONG/SHORT picks with conviction)curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/decision/trade_setups?limit=10&min_conviction=0.5" # Illustrative partial structure, not a live sample:# {#   "ok": true,#   "timestamp": "2026-07-05T10:30:30Z",#   "setups": [#     {#       "ticker": "AAPL",#       "direction": "LONG",#       "conviction": 0.642,#       "blended_score": 0.642,#       "predicted_return_pct": null,#       "interval_lo": null,#       "interval_hi": null,#       "withheld": "uncalibrated_point_estimate",#       "decile": 7,#       "rank": 1850#     },#     {#       "ticker": "TSM",#       "direction": "SHORT",#       "conviction": 0.534,#       "blended_score": -0.534,#       "predicted_return_pct": null,#       "interval_lo": null,#       "interval_hi": null,#       "withheld": "uncalibrated_point_estimate",#       "decile": 2,#       "rank": 12388#     }#   ],#   "universe_skew": "bullish",#   "regime_warranted_alternative": {#     "strategy": "momentum",#     "rationale": "Screen is heavily bullish ...",#     "candidates": [#       { "ticker": "MTUM", "name": "iShares MSCI USA Momentum Factor", "thesis": "...", "expected_role": "factor_momentum" },#       { "ticker": "QUAL", "name": "iShares MSCI USA Quality Factor", "thesis": "...", "expected_role": "factor_quality" },#       { "ticker": "SPHQ", "name": "Invesco S&P 500 Quality", "thesis": "...", "expected_role": "alt_quality" }#     ]#   },#   "filter": { "min_conviction": 0.5 },#   "source": "warehouse:ensemble-scores",#   "as_of_ts": "2026-07-02T21:05:00+00:00",#   "book_age_sessions": 0,#   "is_stale": false,#   "stale_after_sessions": 2# }

Example 3: Academic predictor vector for a ticker#

Pull the compact academic characteristic vector for a name (13 replicated accounting anomalies) without reading the full characteristic panel, which factor_characteristics serves. The predictor panel is a lagged archive keyed by a security key; the exchange symbol is resolved automatically. Use latest=true for the single most-recent row.

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/factors/predictors/AAPL?latest=true" # Illustrative response structure, not a live sample:# {#   "ok": true,#   "timestamp": "2026-07-05T10:31:00Z",#   "ticker": "AAPL",#   "permno": 14593,#   "mode": "latest",#   "as_of": "2026-02-28",#   "n_predictors": 13,#   "predictors": {#     "accruals": -0.031,#     "asset_growth": 0.084,#     "investment": 0.052,#     "gross_profit_at": 0.412,#     "oper_prof": 0.318,#     "cash_at": 0.089,#     "leverage_change": -0.014,#     "earnings_consistency": 0.91,#     "revenue_growth": 0.021,#     "positive_ni": 1,#     "positive_cfo": 1,#     "current_ratio": 1.04,#     "share_issuance": -0.008#   },#   "predictor_glossary": {#     "accruals": "Sloan (1996) balance-sheet accruals anomaly",#     "gross_profit_at": "Novy-Marx gross profitability (GP/assets)",#     ...#   },#   "note": "this panel has NO ticker column ...",#   "source": "warehouse:factor-predictors-archive"# }

Example 4: Interval bounds at a chosen alpha#

prediction_intervals returns the stored interval for the latest prediction. coverage_target is 1 - alpha, computed from your request; changing alpha does not recompute the bounds. Neither alpha nor coverage_target is a measured coverage rate, and the same calibration caveats as ml_prediction apply. When you need calibrated_and_coherent, stated_coverage and the capital-authorization fields, call ml_prediction instead.

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/predict/AAPL/intervals?alpha=0.2"

Illustrative structure, not a live sample:

{  "ok": true,  "timestamp": "2026-09-24T14:05:11Z",  "ticker": "AAPL",  "alpha": 0.2,  "coverage_target": 0.8,  "interval": {    "lo": null,    "hi": null,    "half_width": null,    "withheld": "uncalibrated_point_estimate"  },  "as_of_ts": "2026-09-14T07:05:00+00:00",  "data_freshness": {"data_as_of": "2026-09-14T07:05:00+00:00", "max_sessions_behind": 2, "is_stale": true, "...": "..."},  "magnitudes_withheld": {    "fields": ["interval.lo", "interval.hi", "interval.half_width"],    "reason": "...",    "use_instead": ["rank", "percentile", "decile"],    "...": "..."  }}

Since 2026-09-25 the bounds are withheld: the band is built around predicted_return_pct, which is blended_score × 100 and not a calibrated forecast, so lo, hi and half_width are null, interval.withheld says why, and magnitudes_withheld names the fields and what to use instead. Handle the other null cases too: interval is null when the ticker has no stored prediction (with warning: "no_predictions" when no prediction table is available), and for a fund or ADR, which also carries excluded (see Funds and ADRs).

Example 5: Check model health before trusting a call#

Three reads answer "is the model still working?": directional accuracy over a window, how fast each signal's edge is decaying, and whether the voters have drifted.

# Directional hit rate over the last 90 days of resolved predictionscurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/learning/accuracy?window_days=90" # Per-signal decaycurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/features/decay" # Drift over the last 30 dayscurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/models/drift?window_days=30"

Illustrative structures; the numbers are placeholders, not measured results:

{  "ok": true,  "timestamp": "2026-09-24T14:06:02Z",  "accuracy": {    "n": 1200,    "hit_rate": 0.5,    "window_days": 90  }}

{  "ok": true,  "timestamp": "2026-09-24T14:06:03Z",  "decay": [    {      "factor": "options_flow",      "live_ic": 0.012,      "baseline_ic": 0.031,      "retention": 0.387,      "status": "yellow"    }  ],  "as_of": "2026-09-23T19:01:35+00:00",  "source": "voter_ic_drift_sidecar",  "note": "retention = live_ic/baseline_ic; <1 means the signal is decaying",  "report_freshness": {    "voter_ic_drift": {      "as_of": "2026-09-23T19:01:35+00:00",      "as_of_field": "as_of",      "provenance": "payload",      "report_age_hours": 19.1,      "max_age_hours": 80.0,      "stale": false    }  },  "stale": false}

{  "ok": true,  "timestamp": "2026-09-24T14:06:04Z",  "drift": [    // one row per voter, each with its own "stale" and "stale_at_build"  ],  "summary": {    "as_of": "2026-09-23T19:01:35+00:00",    "n_voters": 19,    "n_red": 1,    "n_yellow": 3,    "n_green": 15,    "worst_status": "red"  },  "source": "voter_ic_drift_sidecar",  "window_days": 30,  "report_freshness": { "voter_ic_drift": { "...": "as in the decay example" } },  "stale": false}

How to read them:

• hit_rate is the share of resolved predictions in the window whose predicted and realized returns had the same sign. It says nothing about magnitude or interval coverage. accuracy is null when no resolved outcomes fall in the window.
• When source is voter_ic_drift_sidecar, drift and decay come from the daily per-voter IC snapshot, so window_days is echoed rather than applied.
• A response served from a report snapshot grades it by the snapshot's own timestamp. report_freshness holds one entry per snapshot: as_of, as_of_field (the field it was read from), provenance, report_age_hours, max_age_hours and stale; the top-level stale is true when any of them is. provenance is payload, or unknown_generation_time when the snapshot carries no timestamp of its own, and then stale is true: the time a file was copied or uploaded is not taken as its age. The voter-drift snapshot's limit is 80 hours, so a Friday snapshot lasts the weekend. A stale snapshot describes the voters on its as_of date, not today.
• In drift, each voter's stale is true when its producer marked it stale or the snapshot is stale; the producer's own flag is kept as stale_at_build.
• For per-voter detail with the staleness flag, call /api/v3/intel/voter_ic_drift.
• /api/v3/learning/prediction_tracker?limit=50 lists the individual calls behind the hit rate. If the response carries source: "ensemble_predictions_fallback", the tracker table was unavailable and the rows are the latest stored predictions with no resolution state.

Example 6: Regime forecast and history#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/regime/forecast?horizon_days=21" curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/regime/history?days=180"

Illustrative structures, not live samples:

{  "ok": true,  "timestamp": "2026-09-24T14:07:00Z",  "current_regime": "normal",  "horizon_days": 21,  "forecast": [    { "regime": "normal", "probability": 1.0 }  ],  "source": "empirical_transition_matrix",  "fitted_at": "2026-06-12",  "window_days": 26,  "caveat": "Live regime has been constant over the observed window, so the empirical transition matrix is degenerate (P(stay)=1). ...",  "current_regime_as_of": "...",  "current_regime_source": "prediction_book",  "as_of": "...",  "book_age_sessions": 8,  "stale_after_sessions": 2,  "stale": true}

{  "ok": true,  "timestamp": "2026-09-24T14:07:01Z",  "history": [    { "date": "2026-06-11", "regime": "normal" },    { "date": "2026-06-12", "regime": "normal" }  ],  "source": "regime_transition_config",  "fitted_at": "2026-06-12",  "coverage_end": "2026-06-12",  "note": "daily max_by(regime) from warehouse:ensemble-scores",  "window_days": 180,  "as_of": "2026-06-12",  "stale": true,  "report_freshness": {    "regime_transition": {      "as_of": "2026-06-12",      "as_of_field": "as_of",      "provenance": "payload",      "report_age_hours": 2510.1,      "max_age_hours": 72.0,      "stale": true    }  }}

A days too short to reach coverage_end is refused. An excerpt of the refusal for days=30 on 2026-09-25: error_code, reason, coverage_end and window_days are the captured values (with Retry-After: 3600), the other fields are shown as the route builds them, and min_days_with_labels is the value it computes that day:

{  "ok": false,  "error": "upstream_unavailable",  "error_code": "dataset_unavailable",  "dataset": "regime_history",  "reason": "table_missing",  "retryable": false,  "coverage_end": "2026-06-12",  "window_days": 30,  "min_days_with_labels": 105}

The forecast starts from current_regime, which is read from the prediction book. current_regime_as_of (also as_of) is the timestamp of the book row it came from, never the time of the request, and current_regime_source names where it was read (prediction_book, or regime_forecast_table when a stored forecast exists). stale is true when that book is more than stale_after_sessions (2) US equity sessions old, counted in book_age_sessions; the forecast then projects from a past regime. A server that has not loaded the book yet answers 503 with error: "upstream_unavailable", error_code: "dataset_unavailable" (reason: "source_unreadable", cause: "snapshot_cold") and Retry-After: 5, not billed, instead of timing out or assuming a regime; retry after the wait.

When source is empirical_transition_matrix, the forecast is a Markov projection of the observed daily regime sequence, so it can only assign probability to regimes that appear in that sequence. Read fitted_at, window_days and caveat before quoting it: a sequence with one regime yields a forecast that the current regime persists, which says nothing about regime-change risk. History served from the same fitted sequence (source: "regime_transition_config") stops at coverage_end, the last date the sequence covers. days counts calendar days back from today, not entries, so it returns only the labels dated inside that window. A window that starts after coverage_end holds no label, and the call is refused: 503 with error: "upstream_unavailable" and error_code: "dataset_unavailable", not billed (Retry-After: 3600). The body names coverage_end, the window_days you asked for, and min_days_with_labels, the smallest days that reaches coverage_end. Retrying with the same days will not help; pass at least min_days_with_labels. The recorded sequence currently ends on 2026-06-12, so on 2026-09-25 any days below 105 is refused, and the default of 180 will be refused from 2026-12-10.

A served history adds window_days, and grades the sequence by its newest label, on the 72-hour limit of a daily report: as_of is coverage_end, and stale and report_freshness (fields as in Example 5) say how old it is. While the sequence ends on 2026-06-12, every served history carries stale: true.

Example 7: Scan the universe, then read one verdict#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/decision/universe_scan?limit=25" curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/decision/ultimate?ticker=AAPL"

Illustrative structures, not live samples:

{  "ok": true,  "timestamp": "2026-09-24T14:08:00Z",  "universe": [    {      "ticker": "AAPL",      "blended_score": 0.642,      "conviction": 0.642,      "decile": 7,      "adv_dollars": 11200000000.0,      "in_earnings_blackout": false    }  ],  "n": 25,  "n_filtered_illiquid": 312,  "n_filtered_unknown_adv": 1840,  "liquidity_filter": "applied",  "snapshot_age_s": 1840.0,  "snapshot_stale": false,  "min_adv_dollars": { "long": 5000000.0, "short": 10000000.0 },  "source": "warehouse:ensemble-scores"}

{  "ok": true,  "timestamp": "2026-09-24T14:08:01Z",  "ticker": "AAPL",  "decision": {    "symbol": "AAPL",    "direction": "LONG",    "blended_score": 0.642,    "predicted_return_pct": null,    "conviction": 0.642,    "decile": 7,    "rank": 1850,    "regime": "normal",    "interval_lo": null,    "interval_hi": null,    "withheld": "uncalibrated_point_estimate",    "as_of_ts": "2026-09-24T10:00:00+00:00",    "source": "ensemble_predictions"  },  "source": "ensemble_predictions"}

Scan rows are stored prediction rows plus two annotations:

• adv_dollars: average daily dollar volume, null when unknown.
• in_earnings_blackout: true or false when the blackout calendar covers the name, null when it does not. Blackout names are annotated, never removed.

When liquidity_filter is applied, rows below the default floors ($5M a day for long-signal rows, $10M for short-signal rows, which need borrow) are dropped and counted in n_filtered_illiquid. Rows with no volume data are dropped and counted separately in n_filtered_unknown_adv. If the volume data covers too little of the universe, the scan is served unfiltered with liquidity_filter: "unavailable".

The ultimate_decision verdict is the stored ensemble row in decision form. It is research output with the same authorization limits as ml_prediction, not an instruction to trade.

Withheld magnitudes. Every route that serves the prediction book withholds the same value: ml_prediction, ml_predict, ml_top_picks, trade_setups, ultimate_decision, universe_scan, signals/fusion, prediction_tracker and briefing/overnight, and the v1 routes (/api/predict/{ticker}, /api/predictions, /api/top-picks, /api/signals, /api/scan, /api/snapshot/{ticker}, /api/risk/{ticker} and /api/dashboard). On each, predicted_return_pct and the band built around it (interval_lo/interval_hi, plus interval_half_width on ml_predict and ml_top_picks, or lo/hi/half_width in conformal_interval) are null, and the row or block carries withheld: "uncalibrated_point_estimate"; prediction_intervals withholds lo, hi and half_width the same way. The value was blended_score × 100: a monotone rescaling of the ranking score, not a calibrated return forecast. Direction, conviction, decile, rank and the ordering of rows are unchanged, so rank on those. point_estimate describes the field and point_estimate_supported is false. point_estimate.field names the key the rows carry, predicted_return_pct on ml_prediction, ml_predict and multi_horizon_batch. Until 2026-09-25 it always said expected_return_pct. The same rule withholds the Kelly size that kelly_uncertainty would derive from that value (see Kelly sizing). /api/risk/{ticker} serves kelly_fraction: null with kelly_withheld instead of a size of 0. /api/predictions/accuracy and /api/v2/models/calibration withhold the mean point estimate and the band's mean width; hit rate, IC and coverage are still served. /api/results withholds its predicted column and says why in track_record_note.

Example 8: Ensemble weights and signal overlap#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/ml/weights" curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/ml/weights/history?days=90" curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/signals/correlation" curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v2/features/importance?top_n=10"

ml_weights returns one stored weights row per regime under regimes, keyed by regime label, with as_of_ts; ml_weights_history returns the same rows over time under rows, newest first. Each row carries regime, as_of_ts, lookback_days, n_outcomes_used, and a w_<voter> weight (and an ic_<voter> information coefficient where the retuner measured one) per voter. These routes return the payload without the ok/timestamp envelope. Illustrative structure:

{  "regimes": {    "normal": {      "regime": "normal",      "as_of_ts": "2026-09-23T00:00:00+00:00",      "lookback_days": 60,      "n_outcomes_used": 5200,      "w_ml_ensemble": 0.14,      "ic_ml_ensemble": 0.021    }  },  "as_of_ts": "2026-09-23T00:00:00+00:00"}

signal_correlation returns correlation[], one object per voter with its correlation to every other voter:

{  "ok": true,  "timestamp": "2026-09-24T14:09:00Z",  "correlation": [    { "voter": "options_flow", "options_flow": 1.0, "insider_flow": 0.08, "sentiment_news": 0.21 }  ],  "n_rows_sampled": 2000,  "source": "computed_from_latest_snapshot_voter_scores"}

When the latest snapshot cannot be used, the matrix comes from a fitted historical panel instead, with n_observations, fitted_at and source: "historical_voter_scores_panel".

feature_importance returns {features[], model, source}. Each item has feature, importance and kind (ff5_factor_loading or voter_posterior_weight when served from the factor-loading and voter-posterior snapshots). Served from those snapshots, importance is a factor beta or a voter's posterior weight, not a feature importance, and note says so. report_freshness grades each snapshot by its own timestamp (limit 14 days for the factor loadings, 72 hours for the voter weights; fields as in Example 5), and stale is true when either is stale. factor_importance answers the same way. model narrows the list only when per-model importances are available (source: "warehouse:feature-importance"); otherwise it is echoed.

Example 9: Firm characteristics and factor exposures#

# Full characteristic vector as of a past monthcurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/factors/characteristics/AAPL?as_of=2024-12-31" # One characteristic over time (book-to-market)curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/factors/characteristics/AAPL/history?char=bm&start=2020-01-01" # Rolling factor betas, last 24 months of historycurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/factors/exposures/AAPL?limit=24"

Illustrative structures, not live samples:

{  "ok": true,  "timestamp": "2026-09-24T14:10:00Z",  "ticker": "AAPL",  "permno": 14593,  "characteristic": "bm",  "n": 2,  "series": [    { "date": "2025-11-30", "value": 0.045 },    { "date": "2025-10-31", "value": 0.05 }  ],  "start": "2020-01-01",  "source": "warehouse:factor-panel-archive",  "identity_verified": true}

{  "ok": true,  "timestamp": "2026-09-24T14:10:02Z",  "ticker": "AAPL",  "permno": 14593,  "model": "FF5+UMD rolling OLS",  "as_of": "2025-11-30",  "exposures": {    "beta_mkt": 1.21,    "beta_smb": -0.35,    "beta_hml": -0.52,    "beta_rmw": 0.41,    "beta_cma": -0.28,    "beta_umd": 0.05    // plus alpha, volatility and R² columns  },  "n": 24,  "history": [    // one row per month, newest first  ],  "source": "warehouse:factor-betas-archive",  "identity_verified": true}

All three routes resolve the symbol to one security first. A symbol that cannot be pinned to exactly one current security returns error: "ticker_not_linked" with identity_verified: false and no numbers, rather than another company's panel. These are lagged monthly archives: read as_of (or the newest series date) before treating a value as current. A name too young for the estimation window returns exposures: null with a warning.

Point-in-time use. ?as_of= picks the month. The panel also stores realized forward returns, its training labels: fwd_ret_1m is the following month's return and excess_ret_1m is that same forward return less the risk-free rate. Neither was known at as_of, and used as a feature either one puts look-ahead bias into a backtest. So the vector withholds every fwd_* column and excess_ret_1m, and outcome_labels_withheld names the ones it left out. /history?char= refuses them with 422 unknown_characteristic; the message says the column is a realized forward return. ret_crsp, which stays in the vector, is the return of the month the row is dated, realized by as_of.

Example 10: Price snapshot#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/snapshot/AAPL"

Illustrative structure, not a live sample:

{  "ok": true,  "timestamp": "2026-09-24T14:11:00Z",  "ticker": "AAPL",  "quote": {    "price": 227.48,    "prev_close": 225.9,    "change": 1.58,    "change_pct": 0.7,    "volume": 41250000,    "bid": 227.46,    "ask": 227.5,    "as_of_ts": "2026-09-24T14:10:58Z"  },  "fundamentals": {    "market_cap": 3400000000000.0,    "pe_ratio": 34.6,    "forward_pe": null,    "pb_ratio": null,    "ev_to_ebitda": null,    "dividend_yield": null,    "beta": 1.21,    "sector": "Technology",    "industry": "Consumer Electronics"  },  "prediction": {    "ticker": "AAPL",    "as_of_ts": "2026-09-24T13:30:00+00:00",    "blended_score": 0.18,    "predicted_return_pct": 0.42,    "conviction": 0.61,    "decile": 8,    "interval_lo": -1.9,    "interval_hi": 2.7,    "voters": { "ml_ensemble": 0.22, "fundamental": 0.09 }    // plus prediction_id, knowledge_ts, tier, regime, rank, interval_half_width,    // coverage, staleness and model fields, and the other seven voters  }}

quote and fundamentals can each be null, and any field inside them can be null when the source does not carry it. In quote:

• volume is the current session's volume only. It is null before 04:00 ET, on weekends and exchange holidays, and whenever the source's daily bar is empty or from an earlier session, rather than the previous session's volume.
• as_of_ts is the source's last-trade time.
• When price and prev_close are both known, change is price minus prev_close and change_pct is that change as a percent of prev_close. When the source sends a change but no previous close, prev_close is derived as price minus change.

prediction is the ticker's stored ensemble prediction row (blended score, return estimate, conviction, decile, interval bounds and per-voter scores) when one exists, and null otherwise; its data_staleness_days is computed from the row's as_of_ts when you call. For a fund or ADR, prediction is null and prediction_excluded says why; when the book guard cannot verify the book, prediction is null and prediction_unavailable says so, and the quote and fundamentals are still served (see Funds and ADRs). Call ml_prediction when you also need its calibration and research-use fields. The snapshot is billed as Quant Signals (Starter, 3 credits), so a Free key gets 402 plan_required; see the quickstart for how that differs from a plain quote.

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:

# the US-listed equity, not Bitcoincurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/ml_prediction/BTC?asset_class=equity"

Responses for those nine carry a disambiguation note:

{  "ticker_collision": {    "note": "This is the US-listed equity 'BTC'. For the crypto asset, pass asset_class=crypto.",    "crypto_available": false,    "asset_class": "equity"  }}

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#