Products
Execution & Research
Execution & Research covers the work before a trade: order-schedule scenarios (TWAP and VWAP), a returns-correlation mesh for finding co-movers and hedge candidates, and three one-call research skills that fuse many data sources into a single read on a ticker. Nothing here submits orders.
Available calculations and limits
VWAP allocates whole shares using the observed minute-by-minute volume of one
completed US equity session. Pass reference_, or omit it for the
last completed session, and minutes_per_slice (1–60; default 30). The response
names the session, observation time, minute coverage, and source snapshot hash.
Every session minute must have an observed bar; missing evidence is not filled
with an assumed curve. Holidays and early closes use the exchange calendar.
The profile describes that historical session. It is not a forecast or a fill
guarantee.
TWAP produces an arithmetic schedule from your quantity and duration. It does not prove that the order can execute at a given price or participation rate, and it applies no liquidity or market-calendar check.
VWAP returns a 503 whose status is unavailable_ without an
empirical symbol volume curve, and consumes no credits. reason names the check the
session failed, such as incomplete_. That body has no error
field and no retry flag, and an immediate retry is unlikely to help: pass another
reference_date, or try later, once that session's missing bars may have been
captured. These unavailable outputs do not fulfill an execution-data request.
Calibrated cost estimates and smart routing are not part of the public API. Their
routes stay unavailable until timestamped market quotes, account fees, routing
evidence, and calibrated fills are bound, and answer
503 capability_ (body status is unavailable_,
retryable is false) without reading data or consuming credits.
The research skills (ta_master, apex_equity, trading_plan) call several data
sources in parallel. When one of them fails, the skill still answers with what
succeeded and lists the failure in vendor_errors; check it before relying on a
field. A count or total from a feed that was not fetched (not configured, or not in
your plan) or whose call failed is null, never 0: in ta_master and apex_equity
the components counts, and in apex_equity the intel fields such as
insider_30d, congress_30d, ttm_lobbying_usd, ttm_gov_contract_usd and
wsb_7d_mentions. A 0 is a feed that answered with nothing. Each skill embeds a
PNG chart as base64 in chart.data_b64.
Access
4 credits per call, Pro and up. Quarantined data_pending routes have a zero-credit policy.
Endpoints
Execution scenarios
| Method | Path | MCP tool | Description |
|---|---|---|---|
| GET | /api/ | twap_plan | Arithmetic TWAP schedule: qty (1–10,000,000, default 100) sliced evenly over minutes (1–390, default 60). |
| GET | /api/ | vwap_plan | Historical volume-weighted allocation from one complete observed session: qty (1–10,000,000, default 100), reference_date (YYYY-MM-DD, default the last completed session), minutes_per_slice (1–60, default 30). |
Research skills
| Method | Path | MCP tool | Description |
|---|---|---|---|
| GET | /api/ | technical_analysis | One-call technical read: candlestick chart with RSI/MACD/Bollinger, GEX, max pain, options flow and volume, insider and congressional trades, and off-exchange volume, fused into a signal list and an aggregate bull/bear stance. interval (minute, hour, day, week or month; default day), bars (40–400, default 120). |
| GET | /api/ | equity_brief | Single-call equity brief for "what do you think about this stock": a fundamentals digest, an alternative-data digest (insider, congressional, lobbying, government contracts, WSB, patents, dark-pool share), notable-pattern flags, a daily chart and an hourly chart. A digest, not the full data: call the dedicated fundamentals and intel routes for complete lists. |
| GET | /api/ | trading_plan | Long or short plan: entry, stop, 1R/2R/3R targets, position size for a given risk, a thesis citing the supporting signals, and a chart. bias (auto, long or short; default auto, which picks the side from the technical stance), risk_pct (account risk per trade in percent, 0.1–5.0, default 1.0). |
Relationships
| Method | Path | MCP tool | Description |
|---|---|---|---|
| GET | /api/ | research_ | "What moves with X": a mesh of tickers whose 36-month realised returns correlate with the seed at a magnitude of 0.6 or more. seed (required, the ticker to build around), depth (hops from the seed, 1–3, default 1). |
Examples
Historical VWAP scenario:
curl --fail-with-body --max-time 30 \ -H "Authorization: Bearer $WEALTHNOW_API_KEY" \ "https://firm.wealthnow.io/api/v3/execution/vwap_plan/AAPL?qty=100&minutes_per_slice=30"Check status, reference_date, data_as_of, and observed_minutes before
using the schedule. Positive child quantities sum exactly to total_qty.
Incomplete or conflicting tape returns 503 and consumes no credits.
TWAP execution plan:
curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \ "https://firm.wealthnow.io/api/v3/execution/twap_plan/AAPL?qty=50000&minutes=120"What moves with NVDA (correlation mesh):
Each node keeps up to 8 co-movers per hop. Leveraged and inverse trackers of the seed are
filtered out as the same bet, and counted in filtered_. An edge's weight
is the signed correlation, so a negative weight is an inverse co-mover.
curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \ "https://firm.wealthnow.io/api/v3/research/correlation_mesh?seed=NVDA&depth=1" # Illustrative response structure; values are placeholders, not live data:# {# "ok": true,# "timestamp": "2026-09-24T14:05:00Z",# "seed": "NVDA",# "depth": 1,# "kind": "returns_correlation_mesh",# "nodes": [{"id": "AMD"}, {"id": "AVGO"}, {"id": "NVDA"}],# "edges": [# {"src": "NVDA", "dst": "AVGO", "weight": 0.71, "kind": "returns_corr"},# {"src": "NVDA", "dst": "AMD", "weight": 0.66, "kind": "returns_corr"}# ],# "filtered_seed_derivatives": 2,# "note": "36-month realised-return correlations (|rho|>=0.6); leveraged/inverse trackers of the seed are filtered out ..."# }A seed without 36 months of overlapping returns (a recent listing, or a thinly traded name)
answers 404 with status: "correlation_ and a note saying it is not in the
correlation universe. Right after a service restart, while the correlation data loads, the route
answers 503 with status: "unavailable_ and Retry-After: 5; retry after a
few seconds. Neither response consumes credits.
Trading plan (Python):
The plan sizes the position against a $100,000 account proxy (plan.sizing.account_):
scale shares and notional_usd to your own account. The stop is the recent 20-day swing low
(high, for a short) when it sits beyond the entry, and otherwise 1.5 times an ATR proxy built from
the 14-day range. Targets are 1, 2 and 3 times the stop distance.
import os, requests r = requests.get( "https://firm.wealthnow.io/api/v3/skills/trading_plan/AAPL", params={"bias": "auto", "risk_pct": 1.0}, headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"}, timeout=30,)r.raise_for_status()plan = r.json()if plan.get("error"): raise SystemExit(f"No plan: {plan['error']} {plan.get('vendor_errors')}")p = plan["plan"]print(plan["direction"], "entry", p["entry"], "stop", p["stop"], "targets", p["targets"])print("thesis:", plan["thesis"]["citations"])print("callouts:", plan["thesis"]["risk_callouts"]) # Illustrative response structure; values are placeholders, not live data:# {# "ok": true,# "skill": "trading_plan",# "ticker": "AAPL",# "direction": "long",# "stance_score": 2,# "plan": {# "entry": 210.0, "stop": 203.5, "stop_distance": 6.5, "stop_distance_pct": 3.1,# "targets": {"t1_1R": 216.5, "t2_2R": 223.0, "t3_3R": 229.5},# "sizing": {"account_proxy_usd": 100000.0, "risk_pct": 1.0, "risk_usd": 1000.0,# "shares": 153, "notional_usd": 32130.0}# },# "thesis": {# "citations": ["Trend: last close 210.00 > 20-SMA 205.12", "Unusual flow: 68% calls"],# "risk_callouts": []# },# "chart": {"format": "png", "media_type": "image/png", "data_b64": "<base64 PNG>"},# "vendor_errors": []# }risk_callouts flags a thin signal majority, failed data sources, and a stop wider than 10% of
the entry. When price history is too short to set levels, the response carries error
(no_price_bars or insufficient_price_data) instead of a plan. That response is a 200 and
is billed like a plan, as is a ta_master response with error: "no_price_bars".
Equity brief:
curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \ "https://firm.wealthnow.io/api/v3/skills/apex_equity/AAPL" # Illustrative response structure (abridged); values are placeholders, not live data:# {# "ok": true,# "skill": "apex_equity",# "ticker": "AAPL",# "fundamentals": {# "name": "...", "sector": "...", "market_cap": ..., "last_price": ...,# "day_change_pct": ..., "price_as_of": "...", "price_is_stale": false,# "latest_revenue": ..., "latest_net_income": ..., "latest_eps": ...,# "total_assets": ..., "total_liabilities": ..., "total_equity": ...,# "filing_date": "...", "fundamentals_staleness_days": ..., "data_quality_flags": []# },# "intel": {# "insider_30d": {"buys": 1, "sells": 6, "trades": 15},# "congress_30d": {"buys": 2, "sells": 1, "trades": 3},# "ttm_lobbying_usd": ..., "ttm_gov_contract_usd": ...,# "wsb_7d_mentions": ..., "wsb_7d_avg_sentiment": ...,# "patent_filings_recent": ..., "avg_dark_pool_pct_30d": ...# },# "flags": [{"tag": "insider_cluster_sell", "severity": "high", "summary": "6 insider sells vs 1 buys"}],# "chart": {"name": "daily_120", "format": "png", "media_type": "image/png", "data_b64": "<base64 PNG>"},# "charts": [{"name": "hourly_80", "format": "png", "media_type": "image/png", "data_b64": "<base64 PNG>"}],# "components": {"insider_count": 15, "congress_count": 3, "...": "..."},# "vendor_errors": []# }Check price_is_stale, fundamentals_ and data_quality_flags before quoting a
figure. The insider and congressional counts cover the most recent trades each feed returned
(up to 15), not a calendar window. Congressional trades appear only when your plan includes the
Congressional product. Flags include insider_cluster_buy, insider_cluster_sell,
congress_buying, elevated_dark_pool, major_gov_contractor, retail_attention_spike and
patent_velocity.
Technical read:
curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \ "https://firm.wealthnow.io/api/v3/skills/ta_master/AAPL?interval=day&bars=120" # Response structure (abridged):# {# "ok": true,# "skill": "ta_master",# "ticker": "AAPL",# "interval": "day",# "bars_count": 120,# "synthesis": {# "aggregate": {"stance": "bullish", "bull": 3, "bear": 1},# "last_close": ..., "period_high": ..., "period_low": ..., "period_change_pct": ...,# "max_pain": {"expiration": "...", "max_pain": ..., "distance_pct": ...}# },# "signals": [{"name": "unusual_flow", "direction": "bullish", "strength": ..., "why": "..."}],# "chart": {"format": "png", "media_type": "image/png", "data_b64": "<base64 PNG>"},# "components": {"flow_count": ..., "insider_count": ..., "congress_count": ..., "...": "..."},# "vendor_errors": []# }aggregate.stance is bullish, bearish, mixed or insufficient_data.