Market Data

What's inside#

• Latest price. price_snapshot returns the last trade in any session, the latest regular session and any extended-hours move with their dates, the current daily bar, the quote while the exchange is in a session, and valuation context computed against the live price, with as_of, price_age_seconds and is_stale.
• OHLCV bars. fundamentals/prices returns bars at second, minute, hour, day, week or month granularity for any window.
• Research-grade history. prices/history returns daily closes as traded, total and price returns, volume and cumulative adjustment factors from a survivorship-bias-free archive (default window the last 365 days; pass start for history back to 2000 and earlier), stitched with live daily bars from 2025 to today, plus the delisting record. prices/corporate_actions returns dividends, splits and distributions from first listing, each as it was known on an as_of date, with the date the data runs through.
• Charts. A candlestick chart as a base64 PNG with RSI, MACD and Bollinger overlays and a summary block of levels.
• ETFs. Holdings of an ETF, the ETFs that hold a stock, and a one-call ETF rollup.

Crypto quotes, the crypto universe, derivatives positioning and crypto news are on Crypto. Two routes on this page also serve crypto when you pass asset_class=crypto: /api/v3/fundamentals/price_snapshot and /api/v3/fundamentals/prices. The other routes here do not take asset_class, so /api/v3/prices/history/BTC looks up the US-listed security with the ticker BTC, not the crypto asset.

For live bars and ticks over SSE, see Streaming. For intraday minute bars from Wealthnow's own capture, see Tape & Intraday History.

Access#

The research-grade history routes read a licensed archive and bill with the other licensed research datasets. Failed requests are not billed. See Pricing & credits.

Endpoints#

Crypto quotes (/api/crypto/{ticker}) moved to Crypto.

Read the latest price and its freshness#

price_snapshot returns one snapshot object. Read the freshness and session fields before you treat price as current: off hours, on weekends and on holidays the price is an older trade, and the snapshot says so instead of hiding it.

Volumes are whole shares. day_volume and regular_session.volume are integers, extended hours included, and so is volume on equity bars from prices (fractional-share trades are rounded to the nearest share). While a session is forming, both snapshot volumes are the live day bar's running tally. Once the session is final, regular_session.volume is the consolidated daily total, the same figure prices serves for that day; the running tally can differ from it by a few hundred shares.

With asset_class=crypto, the snapshot is the crypto asset's last trade and its event time. Valuation fields are omitted, not set to null, because a crypto asset has no P/E. A crypto price older than 15 minutes, future-dated or undated is not served: the call is refused (see below), and the snapshot reports the limit as max_age_seconds.

Dividend status#

dividend.status says which yields you can use. reason gives the detail when the status is not ok.

Before 2026-09-29 (MCP manifest 2.154), dividend_yield was the last fiscal year's dividends paid over that year's shares, as filed. That lagged a raise by up to a year and ignored later splits: NVDA read 0.017% against 0.23% trailing, and BKNG read 23.8% against about 1% after its 25-for-1 split.

When no price can be retrieved#

When every price source fails, price_snapshot and prices answer 503, not billed, with error: "upstream_unavailable", error_code: "price_feed_unavailable" (also on the X-Error-Code header), is_empty_result_set: false and a vendor_error naming the failure. prices carries no items field, so the refusal cannot be read as a symbol with no bars. price_snapshot keeps its snapshot, with price: null.

A crypto snapshot whose last trade is older than 15 minutes answers the same 503 with error_code: "data_stale". Its snapshot carries is_stale: true, price_age_seconds and stale_price_suppressed, and the price is withheld. A future-dated or undated trade is price_feed_unavailable, with vendor_error.kind future_live_trade or invalid_live_trade.

Treat both as "price unknown", never as a symbol with no price. Neither says anything about the whole route: another ticker can answer normally at the same moment. An empty series with no vendor error, such as a delisted symbol or a window with no bars, is a 200 with items: [].

timestamp on the response envelope is when the API answered. It is not a market time.

Bars still forming#

fundamentals/prices serves the bar that is still forming instead of stopping at yesterday: for equities, for C: forex and X: crypto tickers, and, since 2026-09-25, with asset_class=crypto. A bar whose period has not ended carries partial: true: its close is the latest price, not a final close. For a US equity, a day bar stays partial until the tape closes at 20:00 ET. A C: or X: day bar, and every asset_class=crypto bar, runs on the UTC day: today's day bar is partial until that UTC day ends, and the open week's bar until its week ends. Before 2026-09-25, asset_class=crypto served today's bar and the open week's bar as if final, without these fields. Finished bars are returned unchanged, without a partial key. The response adds:

A window with no bars yet, for example today's minute bars before the open, is a 200 with items: [], not an outage. Skip partial: true bars when you need settled closes, and read session_complete before treating a window as final.

Adjusted bars#

fundamentals/prices states the price basis of its bars in three fields:

For example, KLAC traded at 2,108.06 on 2026-06-08, before its 10-for-1 split on 2026-06-12; the day bar for that date reads 210.806.

Research-grade daily history#

prices/history is built for backtests and long-horizon charts. The archive keeps securities that later delisted, so a universe drawn from it does not silently drop the losers.

• Window. With no start, the window is the last 365 days, and the response says so with start_defaulted: true and a window_note. Pass start=2000-01-01 (or earlier) for the full daily archive.
• Rows carry date, prc (the close as traded), openprc, bidlo, askhi, vol (shares traded that day, as traded), ret, retx, shrout (null on live rows), the cumulative adjustment factors cfacpr (prices) and cfacshr (shares), and source: archive_daily for archive rows, live_daily_bars for live rows.
• One price basis on every row. prc is the price as traded, on archive and live rows alike. prc / cfacpr is the price on today's share basis, and vol * cfacshr the volume on today's share basis. Before a forward split cfacpr is above 1 (BKNG's 2025 rows carry 25 for its 25-for-1 split); before a reverse split it is below 1 (a 1-for-30 reverse split gives 1/30). A negative prc follows the archive's convention for a day with no trade: it is the bid/ask midpoint, so use abs(prc).
• Returns. retx is the price return, close to close, dividends excluded, on every row. ret is the total return. On archive rows it is the archive's own figure. On live rows it is retx plus the cash dividend on its ex-date over the prior close, that is (P_t + D) / P_(t-1) - 1 with the USD dividend D (two dividends on one ex-date are summed). Live ret is null when the dividend record could not be read, on a day whose dividend is not in USD, when retx is null, and on a dividend day when the split events could not be read; retx is still the price return. Compound ret for a total-return series, never retx.
• returns_basis (whenever the window runs past 2024-12-31) states what ret and retx mean in each segment (archive, live), live_dividends_status (applied, not_configured, timeout, read_failed, bad_payload, truncated or no_time_left), the dividends applied (live_dividends: ex_date, cash_amount, currency, split_adjusted_cash_amount) and live_rows_without_ret. When the dividend record could not be read on this call (any status but applied and not_configured), warning says so and the answer is not cached: retry for the total returns.
• price_basis (whenever the window runs past 2024-12-31) states the price basis: prc (as_traded, or unverified_split_events_unread when the split events could not be read), adjusted_price (prc / cfacpr), adjusted_volume (vol * cfacshr), live_rows_restored and restored (the live rows that had been stored on a later split's basis and were put back to as traded: first_date, last_date and the split factor), evidence (how each live row's basis was established, counted by kind), continuity_checked (true) and, when present, flagged_steps.
• Continuity check. Every seam where a live row follows another row within 5 calendar days is checked. A price step of 1.25x or more that no recorded split explains is refused (see below) when the two sessions are adjacent and the later row carries its return, or when the step is the size of a recorded split. A step across a missing session, or onto a row with no return, is served and listed in price_basis.flagged_steps (from_date, to_date, from_segment, unexplained_factor, why: unexplained, missing_row or no_return, refused: false).
• Segments. segment is stitched when the answer includes archive rows and live_tail when it came entirely from live daily bars. A small limit for recent dates is served from the live tail alone. The archive covers 2000 to 2024; rows from 2025 on come from live bars. When a response carries live_splits or an adjustment_note, read it before adjusting across that boundary. A split the source lists twice is applied once. A window with no rows carries warning no_rows:archive or no_rows:live, naming the segment that was read.
• When the live bars cannot be read. The 2025-to-date bars are read within the request's time budget. If they cannot be read and the archive covers part of the window, the archive rows are served with live_segment: "unavailable" and a warning that rows after 2024-12-31 are omitted; retry for them. If nothing else covers the window, the route answers 503 with error: "upstream_unavailable" and error_code: "dataset_unavailable" (reason: "source_unreadable"), not billed, instead of a 504 or an empty list. When the post-2024 split events cannot be read and the series does not step, the answer is a 200 with price_basis.prc: "unverified_split_events_unread" and a warning that cfacpr and cfacshr may not reflect them; when it does step, it is the 503 split_events_unread below.
• Before 2000, adjustment factors are null. The archive's rows before 2000 were loaded without cfacpr and cfacshr, so both are null there until the archive is restated. When any returned row lacks them, an adjustment block says so (factors_available: false, rows_without_factors, the dates they span) and note no longer suggests adjusting with them. ret and retx are unaffected: compute returns from them, and do not treat a null factor as 1.
• ETFs and ADRs. Between 2000 and 2024 the archive holds common stocks only, and for many ETFs and ADRs the archive key cannot be proved at all, so such a symbol can return no rows before 2025. note says why (for example SPY and TSM in 2010).
• Delisting. delisting holds the archive's delisting record when the security left the tape.
• Identity. The ticker is resolved to one security first. When no archive key can be proved for the symbol, the response returns error: "ticker_not_in_registry" with no rows rather than another company's history. identity and identity_verified state how the match was made; on a live-tail answer that skipped the lookup, identity.reason is security_id_lookup_skipped.

Refusals on the price basis. These answer 503 with error: "upstream_unavailable", the code in error_code and on X-Error-Code, retryable, Retry-After, is_empty_result_set: false and billed: false. None is billed, and none carries rows.

prices/corporate_actions reads a distributions archive that records every version of each event. For every event (security, ex-date, sequence number) it serves the newest version whose known_from is at or before as_of; an event whose newest such version removes it is left out. The response carries as_of, current_through (the newest ex-date the archive holds, read from the data) with current_through_basis, and a versions block counting events held, known, removed, not yet known and revised after as_of. clock.clock_basis is vendor_availability_rule: a version counts as known from the earlier of known_from (the vendor's release schedule) and first_held_at (when Wealthnow first stored it), so an event the archive already holds is served even when the vendor's schedule dates it later. Treat history before 2026-09-23 as the vendor's record rather than point-in-time observation. The archive is refreshed by hand until its weekly job runs (coverage.refresh). If it cannot be read, the route answers 503 with error_code: "warehouse_read_failed", not billed; it never falls back to the retired archive. Rows are sorted by ex-date (exdt) and carry the per-share cash amount (divamt), the price factor (facpr), the share factor (facshr), the declare, record and pay dates, distype and the related type fields, and the version (version_seq, known_from, first_held_at, change_kind, changed_fields). distcd is null: the archive's type fields replace it. distype FRS marks a split or stock dividend; a facpr of 1.0 is a 2-for-1 split, 0.5 is a 3-for-2 split.

Examples#

Latest price with freshness (1 credit)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/price_snapshot?ticker=AAPL"

Live response captured 2026-10-02 at 16:15 UTC, in regular hours (units and dividend left out):

{  "ok": true,  "timestamp": "2026-10-02T16:15:27.432530+00:00",  "ticker": "AAPL",  "snapshot": {    "ticker": "AAPL",    "price": 332.805,    "as_of": "2026-10-02T16:15:27Z",    "source": "market-data:v2-snapshot",    "price_age_seconds": 0.17134451866149902,    "is_stale": false,    "day_change": 2.485,    "day_change_percent": 0.752301,    "prev_close": 330.32,    "bid": 332.79,    "ask": 332.82,    "bid_size": 280,    "ask_size": 120,    "quote_as_of": "2026-10-02T16:15:27Z",    "time": "2026-10-02T16:15:27Z",    "time_milliseconds": 1790957727261,    "day_open": 333.26,    "day_high": 334.54,    "day_low": 330.61,    "day_close": 332.97,    "day_volume": 14069369,    "day_vwap": 332.6572,    "session": "regular",    "pe_ttm": 38.16571100917431,    "forward_pe": 31.104898947982324,    "price_to_book": 45.36476650036804,    "dividend_yield": 0.0031850483015579694,    "market_cap": 4877626688550.0,    "eps_ttm": 8.72,    "book_value_per_share": 7.3362,    "dividend_yield_indicated": 0.0032451435525307614,    "forward_pe_basis": "pe_ttm_over_trailing_yoy_growth",    "eps_ttm_basis": {      "status": "ok",      "basis": "as_reported",      "splits_checked": true,      "splits_source": "market_data"    },    "forward_pe_growth": {      "source": "eps_growth_yoy",      "fiscal_year": 2025,      "percent": 22.7,      "splits_checked": true    },    "valuation_as_of": "2026-10-02T14:56:14+00:00",    "valuation_status": "ok",    "market_session": "regular",    "price_session": "regular",    "prev_close_date": "2026-10-01",    "day_bar_date": "2026-10-02",    "regular_session": {      "date": "2026-10-02",      "status": "in_progress",      "open": 333.26,      "high": 334.54,      "low": 330.61,      "close": null,      "last": 332.805,      "volume": 14069369,      "prev_close": 330.32,      "prev_close_date": "2026-10-01",      "change": 2.485,      "change_percent": 0.752301    },    "extended_hours": null,    "session_detail_status": "ok"  }}

The exchange was open, so market_session and price_session are both regular, a bid and ask are present with their own quote_as_of, and extended_hours is null. regular_session.close is null because the session had not finished. After 20:00 ET the same call answers with market_session: "closed", bid and ask null, and price the last after-hours trade, with the move since the close in extended_hours.

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/fundamentals/price_snapshot",    params={"ticker": "AAPL"},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()snap = r.json()["snapshot"]if snap.get("price") is None:    print("No price available.")elif snap.get("price_age_seconds") is None:    print(f"{snap['ticker']} {snap['price']} (trade time unknown; may be an older close, do not quote as live)")elif snap.get("is_stale"):    print(f"{snap['ticker']} last traded at {snap['price']} on {snap['as_of']} (stale; do not quote as live)")else:    change = snap.get("day_change_percent")    label = f"{change:+.2f}%" if isinstance(change, (int, float)) else "change unavailable"    print(f"{snap['ticker']} {snap['price']} ({label}), last trade {snap['as_of']}, session {snap['session']}")

Daily bars with a date range (1 credit)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/fundamentals/prices?ticker=NVDA&interval=day&start_date=2026-06-01&end_date=2026-07-02&limit=30" # Response structure (abbreviated):# {#   "ok": true,#   "timestamp": "2026-09-23T02:00:26Z",#   "ticker": "NVDA",#   "asset_class": "equity",#   "interval": "day",#   "interval_multiplier": 1,#   "start_date": "2026-06-01",#   "end_date": "2026-07-02",#   "adjusted": true,#   "adjustment_basis": "splits",#   "adjustment_note": "Split-adjusted to the share basis in force when fetched; not adjusted for dividends. ...",#   "items": [#     {#       "ticker": "NVDA",#       "open": 215.73,#       "high": 224.87,#       "low": 215.7,#       "close": 224.36,#       "volume": 212850685.062286,#       "vwap": 221.4785,#       "trades": 3465498,#       "time": "2026-06-01T04:00:00Z",#       "time_milliseconds": 1780286400000#     },#     ...#   ]# }

Bars are oldest first, with time in UTC. Equity bars are split-adjusted to the share basis in force when fetched and not dividend-adjusted, so a bar before a split is not the price that traded (see Adjusted bars). limit keeps the most recent N bars in the window. Several crypto symbols are also US-listed equity tickers (BTC, LINK), so pass asset_class=crypto for the crypto asset.

import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/fundamentals/prices",    params={        "ticker": "NVDA",        "interval": "day",        "start_date": "2026-06-01",        "end_date": "2026-07-02",        "limit": 30,    },    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()data = r.json()bars = data["items"]print(f"{len(bars)} bars for {data['ticker']} ({data['interval']})")for bar in bars[-5:]:    print(f"{bar['time'][:10]}: {bar['open']:.2f} -> {bar['close']:.2f}")

Split-adjusted history for a backtest (4 credits, Starter and up)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/prices/history/AAPL?start=2020-01-01&end=2024-12-31"

Dividend and split history (4 credits, Starter and up)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/prices/corporate_actions/AAPL?start=2014-01-01"

Chart with overlays (1 credit)#

curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/chart/AAPL?interval=day&bars=120&indicators=rsi,macd"

The response carries the image in chart.data_b64 (media_type: "image/png") and a data block with first_bar_time, last_bar_time, data_freshness, current_price, period_high, period_low, period_change_pct, sma_20, sma_50, sma_200, atr_14, recent_support and recent_resistance. A moving average needs enough bars: in a 120-bar daily chart, sma_200 is null. The bars end on the previous UTC day, so current_price (also served as last_close) is the last completed bar's close and data_freshness is that bar's time. For the current price, call price_snapshot.

import base64, os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/intel/chart/AAPL",    params={"interval": "day", "bars": 120, "indicators": "rsi,macd"},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()body = r.json()with open("AAPL.png", "wb") as f:    f.write(base64.b64decode(body["chart"]["data_b64"]))print(f"Last close {body['data']['last_close']}, data through {body['data']['data_freshness']}")

ETF composition (1 credit)#

# Holdings of an ETFcurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/etf_holdings?etf=SPY&limit=25" # Every ETF that holds a stockcurl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/etf_holdings?ticker=NVDA"

etf_summary is the one-call version. Live response to GET /api/v3/intel/etf_summary/SPY, captured 2026-09-23 and abbreviated:

{  "ok": true,  "ticker": "SPY",  "is_etf": true,  "holdings": [    { "etf_symbol": "SPY", "holding_symbol": "NVDA", "holding_name": "NVIDIA CORP", "weight_pct": 8.158692, "value_usd": 64204621094.9616, "as_of": "2026-09-22T00:00:00+00:00" },    { "etf_symbol": "SPY", "holding_symbol": "AAPL", "holding_name": "APPLE INC", "weight_pct": 7.440639, "value_usd": 58553921106.3972, "as_of": "2026-09-22T00:00:00+00:00" }  ],  "holdings_count": 25,  "commodity_exposure": null,  "available_signals": {    "tengu_v3_intel_etf_holdings": "top constituents by weight (etf=SPY)",    "tengu_v3_news_summary": "news summary for SPY",    "tengu_v3_intel_options_volume": "unusual options flow for SPY"  }}

available_signals is a fixed list, the same for every ETF, with one extra tengu_v3_intel_commodities entry for a commodity-tracking ETF. It is not a check that data exists for the ticker. Its keys are legacy tool names and are not current MCP tool names; the full list also carries tengu_v3_intel_offexchange, tengu_v3_options_chain and tengu_v3_intel_dark_pool. The current tools for the same data are intel_etf_holdings, news_summary, intel_off_exchange, intel_options_chain, intel_options_volume, intel_darkpool_ticker and intel_commodities. Do not call a tool by an available_signals key.

Related#