Risk Analytics

How the proposals are made#

/api/v3/institutional/hedging reads the latest trading day's options signals for each of the three index ETFs and applies three rules. Every number in a proposal is a raw value from that day, not a model estimate:

When no rule fires, proposals is an empty list and note says no hedge trigger active; the per-index metrics are still in market_context. An empty list is an answer, not an error. The proposals do not know your positions: they describe the index hedge market, not a hedge sized for a portfolio.

Results are cached for 5 minutes. Each proposal and each market_context entry carries as_of, the trading date of the signals it used; check it rather than the response timestamp.

Access#

Endpoints#

Example#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/institutional/hedging" # Illustrative response structure; values are placeholders, not live data:# {#   "ok": true,#   "timestamp": "2026-09-24T14:10:00Z",#   "kind": "index_hedge_proposals",#   "hedge_set": ["SPY", "QQQ", "IWM"],#   "proposals": [#     {#       "instrument": "QQQ",#       "hedge_type": "collar",#       "action": "collar: sell calls to finance protective puts",#       "rationale": "25-delta risk reversal positive (+0.0120) ... collar financing is attractive",#       "dealer_gamma_net": ...,#       "dealer_gamma_z": ...,#       "iv_rank_pct": ...,#       "risk_reversal_25d": 0.012,#       "term_structure_signal": ...,#       "as_of": "2026-09-23"#     }#   ],#   "market_context": {#     "SPY": {#       "dealer_gamma_net": ..., "dealer_gamma_z": ..., "iv_rank_pct": ...,#       "risk_reversal_25d": ..., "term_structure_iv0": ..., "term_structure_iv30": ...,#       "term_structure_signal": ..., "term_structure_state": "contango",#       "as_of": "2026-09-23",#       "dealer_greeks": {"date": "2026-09-23", "call_gamma": ..., "put_gamma": ...,#                         "gamma_net": ..., "call_vanna": ..., "put_vanna": ...,#                         "call_charm": ..., "put_charm": ...}#     },#     "QQQ": {"...": "..."},#     "IWM": {"...": "..."}#   }# }

If no signals are available for any of the three indices, there is no answer: the route returns 503 with status: "unavailable_options_signals" and warning: "no_options_signals_data", and the call consumes no credits. It means the signals are missing, not that no hedge is needed.

Kelly sizing#

/api/v3/validation/{ticker}/kelly_uncertainty sizes one ticker from its latest stored ensemble prediction (the book). When it serves a size, it computes in decimal returns, from the prediction's return estimate and 90% interval, both stored in percent:

mu_decimal     = predicted_return_pct / 100sigma_decimal  = (interval_half_width / 1.645) / 100kelly_uncapped = mu_decimal / sigma_decimal^2 x convictionkelly_fraction = kelly_uncapped, capped at -0.25 and +0.25

Before 2026-09-25 the route divided a percent by a percent squared, so every fraction it served was 100 times too small.

The size is withheld today. kelly_fraction is null when either condition below holds, and withheld_reasons lists each one that does:

No stored return is a calibrated forecast yet, so every ticker with a complete prediction answers with magnitude_unsupported. A withheld answer also sets inputs to null, because its return estimate is the unsupported number, keeps cap, and repeats the first reason in warning. It is a refusal, not a size of zero: do not substitute a size of your own.

Every answer for a ticker in the book says how old the book is: as_of_ts (the prediction's own timestamp), book_age_sessions (US equity sessions after that date, up to and including today), is_stale and stale_after_sessions.

Response for AAPL on 2026-09-25. kelly_fraction, inputs, withheld_reasons, magnitudes_withheld.reason, book_age_sessions and is_stale are the captured values; the other fields are shown as the route builds them, and ... marks values that were not captured:

{  "ok": true,  "timestamp": "...",  "ticker": "AAPL",  "kelly_fraction": null,  "warning": "book_stale",  "as_of_ts": "...",  "book_age_sessions": 9,  "is_stale": true,  "stale_after_sessions": 2,  "inputs": null,  "cap": 0.25,  "withheld_reasons": ["book_stale", "magnitude_unsupported"],  "magnitudes_withheld": {    "fields": ["kelly_fraction", "inputs"],    "reason": "the expected return is blended_score*100, not a calibrated forecast, so no size can be derived from it",    "use_instead": ["rank", "percentile", "decile"],    "...": "..."  },  "method": "fractional_kelly_uncertainty_discounted"}

When a size is served, the response adds kelly_uncapped and cap_binding (true when the cap cut the size), and inputs holds mu_pct and sigma_pct in percent (mu and sigma_estimate are the same two values under their earlier names), mu_decimal, sigma_decimal, conviction, interval_half_width_pct and units.

Other null answers name their cause in warning:

• ticker_not_in_predictions (the ticker has no stored prediction) or no_predictions (no prediction table was available). These carry no book age.
• A fund or ADR names its cause in an excluded block instead of warning (error_code: "excluded_from_equity_ranking"), with no book age: its row carries an equity-model score for characteristics a fund or ADR does not have, so no size is derived from it (see Funds and ADRs).
• no_predicted_return, no_interval_half_width or no_conviction: the stored prediction lacks that input. Nothing is substituted for it; the route used to put a fixed volatility of 0.02 in place of a missing interval, and a conviction of 0.5 in place of a missing one.

Every answer, withheld or not, is a 200 and is billed. Answers are cached for 60 seconds.

A Kelly fraction is a research input, not an instruction to trade.

Historical VaR for a portfolio you send#

POST /api/v3/risk/historical_var_scenario computes empirical historical Value at Risk and expected shortfall. You supply the positions, their market values and their daily return history; the API runs non-overlapping historical scenarios over that history and returns the loss at your chosen confidence and horizon. It reads no account: the numbers describe the portfolio in your request.

The route is served on REST. It is not an MCP tool, and the public OpenAPI spec does not list it yet. GET /api/capabilities carries its full request schema under tengu_v3_risk_historical_var_scenario.

The request#

The body has four top-level fields:

The calculation needs at least ten tail observations at the chosen confidence and horizon. With fewer, the route refuses rather than estimating.

Reading the result#

The response states the VaR and expected shortfall in USD, the scenario window and its age, and where each input came from. It does not verify that the positions are held anywhere, it does not calibrate future coverage, and it is not an instruction to trade.

Handle unavailable output#

Inspect ok, status, and any availability or warning fields before using a numeric risk field. A successful HTTP exchange can carry an unavailable result. Do not use the response timestamp as the time of the underlying market data. See API reference for error handling and pricing and credits for settlement behavior.

Related#