Sign up

Products

Status

Macro, Rates & FX

Cross-asset macro data and the earnings calendar: live Treasury curves and T-bill yields, commodity spot prices, the macro regime, CFTC positioning, economic and analyst-ratings calendars, next earnings dates with Street estimates, and FX news, sentiment and prices. The core macro desk toolkit.

What's inside

Treasury yields & rates: Live US Treasury curve (1M–30Y) with per-tenor 1-day changes, recession-watch spreads (2s10s, 3m10y), breakeven inflation (5Y, 10Y), the trade-weighted USD index, and a T-bill quick reference for parked cash. The curve is T+1 (the latest record is the prior business day). Quote these numbers verbatim instead of training data.

Real-time commodities: Live spot prices for WTI oil, Brent, gold, silver, natural gas, and copper: the last official FRED close anchored to the live return of a tracking ETF (USO, BNO, GLD, SLV, UNG, CPER), so prices reflect today's market rather than FRED's publish lag.

Cross-asset state & regime: A one-call macro dashboard, the current regime read, a cross-asset composite with real underlying values and a CDX credit block, regime signals by asset class, and a pulse from the issuing authorities (volatility term structure, leading indicators, official-sector positioning, Treasury auctions, shipping chokepoints).

CFTC Commitments-of-Traders: Weekly futures positioning by trader cohort (money managers, producers and hedgers, other reportables, small traders), with a 4-week money-manager delta per contract.

Volatility and positioning (Pro): Daily open, high, low and close of VIX (from 1990), VXO (from 1986), VXN and VXD; the VIX futures settlement curve with contango or backwardation stated; and every trader category of the full disaggregated Commitments of Traders report.

Macro history (Pro): The history beneath macro_pulse, which serves only the latest reading: weekly primary-dealer positions, the Fed's Treasury holdings, Treasury auction results, OECD leading indicators, daily transits through 24 shipping chokepoints, 68 US economic series as first released, and S&P 500 valuation since 1871.

Calendars: Macro releases (CPI, NFP, FOMC, GDP and more) with actual, consensus and prior values, analyst rating and price-target actions, and each company's earnings-call dates (Pro). The feed behind the economics calendar is retired: it returned no data after 2026-06-30 and will not be restored. That calendar answers only from an archive that ends around that date, and returns 503 when called without date_from; see When a calendar feed is unavailable. The ratings calendar reads a live ratings feed, and the earnings-call schedule reads the corporate-events archive. The FX economic calendar below and news/ratings on News & Sentiment come from a different feed and do not depend on the retired one.

Earnings & the Street: The next confirmed earnings date from a multi-source consensus (also as a stream), Street consensus EPS with the options-implied expected move, past quarters' surprises with the one-day move after each report, every individual analyst estimate revision back to 1980, and management guidance history. On Pro, the estimates archive adds EPS surprises on one share basis, monthly analyst rating counts and monthly insider sentiment.

FX news, sentiment & prices: Articles with sentiment for currency pairs (EUR-USD, GBP-USD, USD-JPY and so on), macro FX themes (Fed, ECB, BoJ, CPI and more), daily pair sentiment, clustered FX events, an FX economic calendar, and live FX mid prices.

Access

Note:

2 credits per call. Starter plan and up.

Exceptions, each marked in the tables below:

  • The two deep estimate archives, /api/v3/intel/street_estimates_history/{ticker} and /api/v3/intel/street_estimates_guidance/{ticker}, bill as the Funds product at 4 credits per call (Starter and up).
  • /api/v3/volatility/* and /api/v3/positioning/* bill as Volatility & Positioning (volatility_positioning): 4 credits per call, Pro and up.
  • /api/v3/macro_history/* and /api/v3/estimates_history/* bill as Alt-Data (alt_data): 3 credits per call, Pro and up.
  • /api/v3/intel/calendar/conference_calls bills as Transcripts & Events (events_transcripts): 3 credits per call, Pro and up.

Endpoints

Rates and yields

MethodPathMCP toolDescription
GET/api/v3/macro/treasury_curvemacro_treasury_curveLive US Treasury yield curve (1M–30Y) with per-tenor 1-day change in bps and the 2s10s and 3m10y spreads with inversion flags. as_of is the feed's record date (T+1).
GET/api/v3/intel/yield_curveintel_yield_curveTreasury yields (1M, 3M, 2Y, 5Y, 10Y, 30Y), the 10Y-2Y and 10Y-3M spreads with inverted flags, 5Y/10Y breakeven inflation and the trade-weighted USD index; includes 5-day history for each series. 5-min cache.
GET/api/v3/intel/risk_free_rateintel_risk_free_rateShort-end yields for capital-allocation answers: rates (1M, 3M, 2Y, 10Y with yield_pct, as_of, fred_days_stale, change_bp_1d), a parked_yield_example (annual coupon on $10,000 at each tenor) and tbill_etfs (SGOV, BIL, SHV with expense ratios and use case). The ETF rows show the underlying T-bill yield, not the ETF's own yield. 5-min cache.

Commodities

MethodPathMCP toolDescription
GET/api/v3/intel/commoditiesintel_commoditiesReal-time spot prices with FRED anchor, live ETF-bridge estimates and historical changes. Query: symbol (all, oil, wti_oil, brent_oil, gold, silver, natgas, copper; default all; oil returns WTI and Brent). Quote spot; check spot_basis before quoting a unit.

Cross-asset state and regime

MethodPathMCP toolDescription
GET/api/macromacro_dashboardOne-call macro dashboard, the first call for "how is the macro backdrop?". Returns vix, vvix, sp500_trend, fear_greed, dxy, tnx_10y, credit_spread, regime, as_of_ts, and a fred map of the latest macro series values when available.
GET/api/regimemarket_regimeCurrent market regime: regime label, regime_multiplier, confidence, hmm_state, vix, sp500_trend, as_of_ts. 60 s cache.
GET/api/v3/intel/macro_snapshotintel_macro_snapshotCross-asset macro composite with real underlying values: VIX, 10Y yield, narrow and trade-weighted USD indices, WTI, gold, S&P 500, Nasdaq-100, DJIA, Russell 2000, plus vol_regime, per-field freshness, a credit block (CDX IG/HY 5Y spreads, see below) and a nowcasts block. Query: freshness (off|live|strict, default off). 60 s cache.
GET/api/v3/signals/cross_assetsignals_cross_assetThe regime read taken across asset classes. Returns cross_asset[], one entry per bucket (rates, fx, vol, commodities, equity, regime, inflation) with its own fields and as_of. A futures value the source cannot have meant comes back null, with every field derived from it, and the bucket's invalid_fields says why; dx_front is always null (see Withheld values in cross_asset).
GET/api/v3/origin/macro_pulseorigin_macro_pulseCross-asset state from the issuing authorities in one call: volatility_term_structure (front, second and back VIX futures, contango_pct, inverted), leading_indicator (composite leading indicator by country, 100 = trend), official_sector (primary-dealer series and central-bank balance-sheet dates), treasury_auctions (recent auctions) and trade_chokepoints (vessel counts and capacity). Each block reports its own available flag. The leading indicator publishes with a ~2-month reference lag by construction; that is not staleness.

macro_pulse caveats. volatility_term_structure is indicative, not official settlement: it is built from Cboe's public web feed since 2026-08-01, holds 9 monthly contracts (Cboe also lists weeklies), and on a few days repeats the prior session's values or carries a non-session date.

Positioning

MethodPathMCP toolDescription
GET/api/v3/intel/cftc_cotintel_cftc_cotCFTC Commitments-of-Traders positioning by cohort. Without a filter: the top-10 money-manager net longs and shorts across all contracts on the latest report. Query: contract (optional, case-insensitive substring of the contract name, e.g. GOLD, WTI, NATGAS, SP500-EMINI, 10Y-NOTE, BITCOIN-MICRO) returns the matched contract's latest report plus 4 prior weeks with cohort net positions, % of open interest and a 4-week money-manager delta. A filter that matches nothing returns available: false with hint_contracts_available. Published weekly (polled Fridays 18:00 ET); 4 h cache.

COT report timing. Each report is stamped at 20:00 ET on the Thursday after its Tuesday report date, before the CFTC releases it on Friday at 15:30 ET, and releases delayed by the 2018 to 2019 and 2025 government shutdowns and the 2023 ION outage came later still. Positions are correct; do not use the stamp as the release time in a backtest until it is restated.

Volatility and positioning (Pro)

MethodPathPlan / creditsMCP toolDescription
GET/api/v3/volatility/vix_indicesPro+ / 4volatility_vix_indicesDaily open, high, low and close of VIX (S&P 500 30-day implied volatility, from 1990-01-02), VXO (S&P 100, the original method, from 1986), VXN (Nasdaq-100) and VXD (Dow Jones Industrial Average). Values are index points, which are annualised implied volatility in percent (20.0 = 20% a year over the next 30 days). An end-of-day archive delivered in monthly batches, not a live quote: freshness.data_through is its newest session and freshness.stale turns true past 49 days. start and end (YYYY-MM-DD) bound the window, by default the year up to the newest session; limit (1 to 2600, default 260) caps sessions per index, newest kept (truncated says so). Each series states its coverage, and series_ended when the index stopped being published. Some 1990 to 2003 VIX sessions have no intraday range (range_withheld says why). Params: index (vix, vxo, vxn, vxd or all; default vix), start, end, limit.
GET/api/v3/volatility/vx_curvePro+ / 4volatility_vx_curveThe monthly VIX futures' daily settlements for one session (contract_month, expiration, days_to_expiration, settlement in VIX index points; 1 point = USD 1,000 per contract) and its term structure: front, second and back month, second_over_front_pct (percent) and state, contango (second above front, the usual state) or backwardation (front above second, typical of stress). history (0 to 250, default 20) gives the last N sessions' front, second, back and state. By default the newest session, written the evening of each trading day; date picks an earlier one (404 with the nearest prior session if none). History from August 2026. On a contract's expiry day its final settlement is served apart (final_settlement) and the front is the next contract. Rows captured before 2026-09-25 name only the contract month and are withheld and counted (coverage.withheld_rows). freshness.sessions_behind and stale label a late feed. Params: date, history.
GET/api/v3/positioning/cotPro+ / 4positioning_cotThe CFTC's full disaggregated Commitments of Traders report (commodity futures only): per market, each trader category (producer/merchant, swap dealer, managed money, other reportable, total reportable, non-reportable) with long, short and spreading positions in contracts, net, weekly changes, percent of open interest, trader counts, and the 4 and 8 largest traders' concentration. report_date is the Tuesday the positions are as of; the CFTC releases it the following Friday (release_date_scheduled). Without market: the latest report's markets by open interest with each category's net (group filters, limit 1 to 400 caps). market takes a contract market code, the exact name or a common name (GOLD, WTI) and returns its newest weeks reports (1 to 52, default 8); an ambiguous name is a 409, a financial future a 404 market_not_in_report. History from July 2026 (coverage says). The legacy and financial-futures reports are not served; intel_cftc_cot above has four cohorts from 2006. Params: market, weeks, group, limit.

Macro history (Pro)

The full history beneath macro_pulse, which serves only the latest reading of the same datasets.

MethodPathPlan / creditsMCP toolDescription
GET/api/v3/macro_history/dealer_positioningPro+ / 3macro_history_dealer_positioningWeekly primary-dealer net positions (long minus short; negative = net short) in Treasury bills, coupons by maturity bucket, TIPS, floating-rate notes and agency debt, in millions of USD, each week as of its Wednesday (as_of_date). History from 2013. The New York Fed publishes a week about eight days later; freshness.as_of is the newest week held. Use it for dealer balance-sheet capacity, duration positioning or how dealers absorbed supply. An unknown series is a 422 listing the accepted ones. Params: series (comma list, such as bills,coupons_7y_to_11y; default all 15), start (default two years before end), end (at most 20 years per call).
GET/api/v3/macro_history/fed_holdingsPro+ / 3macro_history_fed_holdingsThe Federal Reserve's Treasury holdings (System Open Market Account), weekly as of each Wednesday: total par in USD and par by type (bills, notes and bonds, TIPS, FRNs) with security counts; or, with cusip, one security's weekly par, change on the week (USD; 0 when unchanged), coupon (percent) and share of the issue outstanding (percent). Published the next day. The weekly history is held from late July 2026; missing_weeks lists Wednesdays with nothing held. Agency MBS are not included. Use it to track quantitative tightening or the Fed's share of an issue. Params: start (default 26 weeks before end), end (at most 10 years per call), cusip.
GET/api/v3/macro_history/treasury_auctionsPro+ / 3macro_history_treasury_auctionsUS Treasury auction results, newest first: CUSIP, term, auction, issue and maturity dates, high yield (percent; bills: high discount and investment rate; FRNs: high discount margin), coupon, bid-to-cover, offering, tendered and accepted amounts (USD), and indirect, direct and primary-dealer takedown (percent of the competitive amount accepted). tail_bp is null: the record has no when-issued yield. Results post on the auction day; held_range says where the held history starts. Use it for auction demand, foreign (indirect) appetite or dealer take-up by tenor. Params: security_type (Bill, Note, Bond, TIPS, FRN, CMB), term (such as 10-Year), start (default 180 days before end), end (at most 10 years per call), limit (1 to 500, default 100).
GET/api/v3/macro_history/leading_indicatorsPro+ / 3macro_history_leading_indicatorsOECD composite leading indicators, monthly, by country or area (US, China, G7, G20 and 18 more): the amplitude-adjusted index (long-term average = 100; above 100 and rising means growth above trend ahead), with the latest month and its one-month change. month is the reference month; a month publishes about six weeks after it starts, and the newest release's revised history is served (earlier vintages are not held). Held from 2020. Use it for turning points in the cycle across economies. Params: country (name or code; default all; an unknown one is a 422 listing those accepted), start (default three years before end), end.
GET/api/v3/macro_history/chokepointsPro+ / 3macro_history_chokepointsDaily ship transits and estimated cargo (metric tons) through 24 maritime chokepoints (Suez Canal, Panama Canal, Strait of Hormuz, Malacca, Bab el-Mandeb, Bosporus and more), by vessel type: tanker, container, dry bulk, general cargo, ro-ro and total. From IMF PortWatch satellite ship tracking, published about a week after the day; history from 2019. One chokepoint can span up to 8 years per call, all of them up to 92 days. Use it for shipping disruptions, energy flows or trade-volume nowcasts. Params: chokepoint (default all; an unknown name is a 422 listing those held), start (default 365 days before end for one chokepoint, 30 for all), end.
GET/api/v3/macro_history/seriesPro+ / 3macro_history_series_catalogThe catalogue of the 68 US economic series macro_history_series serves: FRED series id, title, the source's unit, frequency and seasonal-adjustment labels, the date a rebased series' current unit took effect, value basis and the newest observation held with its freshness. Covers Treasury yields and curve spreads, policy and money-market rates, inflation and breakevens, money and the Fed balance sheet, credit spreads and financial conditions, FX and oil, output, labour, housing and GDP nowcasts. Call it to find a series id and its unit before asking for its history.
GET/api/v3/macro_history/series/{series_id}Pro+ / 3macro_history_seriesOne US economic series' observations by FRED series id (such as CPIAUCSL, DGS10, UNRATE, GDPNOW), with the source's own unit, frequency and seasonal-adjustment labels. Each value states its value_basis: first_release (as first published, with the instant it became public, so a backtest sees what was known then), earliest_archived_vintage (older than the source's vintage archive), latest_estimate (nowcasts) or as_of_pull. Every value is in today's unit: one first published in an earlier base year is withheld with published_in_an_earlier_base_year. Default window by frequency; up to 5,000 newest points. An unknown id is a 422 listing the ids. Params: start, end.
GET/api/v3/macro_history/sp500_valuationPro+ / 3macro_history_sp500_valuationS&P 500 valuation, monthly since 1871: CAPE (price over ten years of inflation-adjusted earnings), trailing P/E (ratios), dividend yield and earnings yield (percent), each with its definition. Values are dated the first of the month; the current month's row is provisional (provisional: true) until the month ends. Use it for valuation regimes, long-horizon return context, or comparing today's multiple with history. Params: metric (comma list of cape, pe, dividend_yield, earnings_yield; default all), start (default 20 years before end), end.

Economic calendar

MethodPathMCP toolDescription
GET/api/v3/intel/calendar/economicsintel_calendar_economicsMacro economic-release calendar (CPI, NFP, FOMC, GDP, retail sales and more). Each item: country, date, time, event, category, period, actual, actual_unit, consensus, prior, importance (5 = market-moving), notes. Query: country (ISO-3, e.g. USA, CAN, DEU), date_from, date_to (YYYY-MM-DD), importance (0–5), limit (1–100, default 50). Forward-looking. Its live feed has returned no data since 2026-06-30, so a call without date_from currently returns 503 with error_code: "forward_window_empty", and an explicit date_from reads the archive of past releases instead (degraded: true), which holds nothing recent; see When a calendar feed is unavailable. For recent prints use news_forex/economic_calendar below.
GET/api/v3/news_forex/economic_calendarnews_forex_economic_calendarFX-focused economic calendar with actual, forecast and previous values for macro releases. Query: currency (ISO, e.g. USD, EUR, JPY, GBP), importance (high|medium|low), date_range (today|last7days|last30days, default last7days). Returns {currency, importance, date_range, items[], n}. 10-min cache.

Earnings and Street estimates

MethodPathMCP toolDescription
GET/api/v3/earnings/next/{ticker}earnings_nextNext confirmed earnings date for a ticker from a multi-source consensus. next_earnings_date is null unless a date is confirmed; projections move to _meta.domain.next_earnings_date_projection_only. Also returns time_of_day (BMO/AMC/DMT), confirmed, fiscal_period, eps_estimate, revenue_estimate, days_until, summary, per_source[], citations[] and _meta.confidence (high/medium/low). A retired source is not queried: it keeps its per_source row with the reason, is listed in _meta.domain.sources_retired (currently newswire), and does not count in sources_attempted or sources_total. Also returns next_report_resolved, the one next-report date this route and street_estimates both serve (see One next-report date); read the date from next_report_resolved.date, because the top-level next_earnings_date is this route's own consensus and can differ when the issuer confirmed another date. most_recent_reported_date is the latest report that has happened. When the options-flow earnings calendar (the one that dates earnings_history) holds a newer reported quarter than the consensus found, that date wins: most_recent_reported_source is options_flow_calendar, most_recent_reported_days_ago and summary follow it, and the superseded date and its source are in most_recent_reported_alternatives. On 2026-09-25 NVDA's read 2025-05-28 before this and 2026-08-26 after. 1 h cache.
GET/api/v3/earnings/next/{ticker}/streamnone (REST only, SSE)The same consensus delivered as Server-Sent Events: a fast partial event, then a verified result. See Streaming the next earnings date.
GET/api/v3/intel/street_estimates/{ticker}intel_street_estimatesStreet consensus EPS and the options-implied expected move. next_report carries report_date, report_time, report_date_basis (company = issuer-confirmed, estimation = projected, not confirmed), street_mean_eps, expected_move_usd, expected_move_pct; recent_reports[] has up to 8 past quarters (estimate, actual, surprise, post_earnings_move_1d); plus beat_rate_pct. eps_basis is unknown for this feed's actual EPS (see eps_basis_note), so its surprise and beat_rate_pct may compare figures on different EPS bases; for a basis-labelled actual against its estimate use earnings_history. Also returns next_report_resolved (see One next-report date); next_report stays the feed's own row. A ticker that is not a plain symbol ([A-Z][A-Z0-9.-]{0,11} after upper-casing, so not X:BTCUSD or ^VIX) returns 400 invalid_ticker. 30-min cache.
GET/api/v3/intel/earnings_history/{ticker}intel_earnings_historyLast N quarters of earnings: report_date (the day results were announced), period_quarter, EPS estimate vs actual, surprise and surprise %, and the price move on the session that traded on the release (day_move_pct, day_range_pct, reaction_move_pct), plus avg_abs_day_move_pct, max_abs_day_move_pct, avg_abs_reaction_move_pct and max_abs_reaction_move_pct. EPS is company-adjusted (eps_basis: "adjusted", the basis the consensus is struck on). Query: lookback_quarters (1–12, default 4); the upstream may return fewer quarters than requested. 6 h cache. See Earnings reaction moves.
GET/api/v3/intel/calendar/conference_callsintel_calendar_conference_calls3 credits, Pro and up, billed as Transcripts & Events. When a company's next earnings calls are, read from the corporate-events archive, which dates scheduled calls ahead: one row per call with ticker, company, date (the call's day), period and period_year (the fiscal period the call's title names, such as Q3 2026), headline, announced and keydev_id, soonest first. tickers is required, at most 5 (422 tickers_required or too_many_tickers). Default window: today to 90 days ahead; a lone date_from or date_to opens 90 days from that date; both set any window up to 366 days, with history from 1990. data_through is the archive's newest entry day (loaded about weekly; is_stale past 21 days), so a call scheduled after it may be missing, and an empty answer carries empty_reason. The start time, dial-in numbers, access codes, webcast link and importance score are not carried: they are served null and listed in fields_not_carried, and the importance filter is refused (422 unsupported_filter). Query: tickers, date_from, date_to (YYYY-MM-DD), limit (1–100, default 50).
GET/api/v3/intel/calendar/ratingsintel_calendar_ratingsAnalyst rating actions and price-target changes from the live ratings feed, newest first: analyst_firm, action_company (Upgrades, Downgrades, Initiates, Reiterates or Resumes), action_pt (Raises, Lowers, Maintains or Announces, derived from the targets), rating_current/rating_prior, pt_current/pt_prior, pt_pct_change, date, time and time_zone. analyst_name, company and url are null. Query: tickers (comma-separated), date_from, date_to (YYYY-MM-DD), action (Raises, Lowers, Maintains, Announces, Initiates, Reiterates), limit (1–100, default 50). The response adds scan, which says how much of the feed was read. See The analyst ratings calendar.
GET/api/v3/intel/street_estimates_history/{ticker}intel_street_estimates_history4 credits, billed as Funds. Every individual broker estimate from the analyst-estimate detail archive (1980 to 2025): announce and revision dates, analyst id, fiscal period, estimated value and realised actual. Use it to see how the Street walked numbers before a print. Query: measure (default EPS; also SAL, EBI, CPS, DPS, GRM, NET, PRE, ROA, ROE and more), days (announcement-date look-back, 1–9500, default 365), limit (1–50000, default 2000): rows are the newest limit estimates in the window, oldest first. Returns {ticker, measure, window_days, n, rows[], source} plus the archive clocks described under How far the estimate archives run.
GET/api/v3/intel/street_estimates_guidance/{ticker}intel_street_estimates_guidance4 credits, billed as Funds. Management guidance history: every company-issued guidance range with measure, period, low and high values, announce date and the Street consensus at that date. Query: measure (optional, e.g. EPS, SAL, EBI; default all), start (earliest announce date, YYYY-MM-DD; default all history), limit (1–5000, default 500): rows are the newest limit in the window, oldest first. Keyed by the estimate-vendor ticker, which can differ from the exchange symbol for dual-listed or renamed issuers. Returns {ticker, n, rows[], source} plus the archive clocks.

One next-report date

earnings_next and street_estimates both carry next_report_resolved, one next-report date resolved from the same inputs, so the two routes never print different dates for the same ticker:

  • date and time_of_day, and status: confirmed, projected or unknown.
  • confirmed_by: company when the issuer confirmed the date, vendor_consensus when the calendars and web search agree, or null for a projection. An issuer-confirmed date wins over a consensus date, and a consensus date over a projection.
  • source, and alternatives: other dates the inputs held, each with its status and source.
  • inputs says which sources the answer was resolved from: options_flow is consulted or unavailable; consensus is consulted, not_needed (the issuer confirmed the date) or unavailable (the consensus was not ready in time; retry for the settled date). Both are not_consulted for a ticker that is not a symbol.

On street_estimates, next_report is still the options-flow feed's own row, with its report_date_basis; read the date from next_report_resolved.

Earnings reaction moves

On earnings_history, report_date is the day results were announced, from the options-flow earnings calendar, and null when that calendar has no date for the quarter. It used to be the calendar-quarter end, which is now calendar_quarter_end; fiscal_quarter_end, fiscal_year and fiscal_quarter identify the quarter, and report_time and report_date_source say when and where the date came from. The move is measured on the session that traded on the release: the next session for an after-close report, the report day otherwise.

  • day_move_pct is that session's open-to-close move and day_range_pct its high-to-low range. day_move_date names the session.
  • day_move_basis is reaction_session when the release time is known, release_time_unknown when it is not (the first session on or after report_date, so the reaction may be the next one), or reaction_session_pending when that session has not closed yet, and then the move is null.
  • reaction_move_pct runs from the last close before the release to the reaction session's close, the move to compare with an implied move. It is null unless the release time is known.
  • warning: "report_dates_unavailable" means the report-date source failed; the EPS rows are still served.

How far the estimate archives run

street_estimates_history and street_estimates_guidance add data_through (the archive's newest announcement date), is_stale, max_lag_days (65 for the estimate archive, 21 for guidance) and window_after_coverage. When window_after_coverage is true the window starts after the archive ends, so no rows means the archive holds none for the window, not that no analyst estimated. A failed archive read answers with error: "warehouse_read_failed" and empty rows, where it used to say warning: "no_rows".

Estimates history (Pro)

The estimates feed's archived quarters and months, beneath earnings_history and analyst_consensus (which answer from the live feed). An unlisted symbol is a 404 unknown_ticker.

MethodPathPlan / creditsMCP toolDescription
GET/api/v3/estimates_history/earnings_surprises/{ticker}Pro+ / 3estimates_history_earnings_surprisesQuarterly EPS estimate against actual as the estimates feed published them: period_end (calendar quarter end), fiscal labels, consensus EPS, actual EPS (company-adjusted), surprise per share and in percent, and when each row was taken. Held as reported from 2026-09-23 (about four quarters then, one more each quarter). Every row is on today's share basis: quarters taken before a split are restated by its exact ratio from the corporate-actions record, and a row whose estimate and actual sit a split apart is withheld with split_basis_mismatch. Stock dividends are not in that record. Params: limit (quarters, 1 to 80, default 20).
GET/api/v3/estimates_history/recommendations/{ticker}Pro+ / 3estimates_history_recommendationsMonthly analyst rating counts: strong buy, buy, hold, sell and strong sell, their sum, and the buy and sell shares (percent of the sum). month is the tally's month; the feed publishes it during the month. Use it to see how the rating mix moved; for price targets and rating actions use intel_analyst_consensus. Params: months (1 to 120, default 24).
GET/api/v3/estimates_history/insider_sentiment/{ticker}Pro+ / 3estimates_history_insider_sentimentMonthly insider sentiment: mspr, the monthly share purchase ratio from -100 (insiders only sold) to +100 (only bought), and net_share_change (shares bought minus sold). A month with no insider transactions has no row; months the feed files ahead of the current one are not served. For the filings themselves use origin_insider_flow. Params: months (1 to 120, default 24).

FX news, sentiment and prices

FX pairs are sent to the feed as EUR-USD. pair and pairs also accept EURUSD, EUR/USD, eur_usd and C:EURUSD, normalised to that form, and the response echoes the normalised pair. EURUSD used to reach the feed unchanged and fail: latest answered 503, and sentiment_stats and summary came back empty.

MethodPathMCP toolDescription
GET/api/v3/news_forex/summary/{pair}news_forex_summaryOne call for "what's going on with EUR-USD?": recent_news (today), 7-day sentiment_stats, trending headlines and news_count_24h. 3-min cache.
GET/api/v3/news_forex/latestnews_forex_latestRecent FX news with sentiment for one or more pairs: title, source, sentiment (Positive/Neutral/Negative), date and topic tags. Query: pairs (required, comma-separated, e.g. EUR-USD,GBP-USD), items (1–50, default 20), date_range (today|yesterday|last7days|last30days, default today). Returns {pairs[], date_range, items[], n}. 3-min cache.
GET/api/v3/news_forex/by_categorynews_forex_by_categoryMacro and cross-pair FX news. Query: section (general = market macro such as Fed, CPI, ECB, NFP, BoJ, BoE; alltickers = cross-pair coverage; default general), topic (general only: cpi, unemployment, fed, ecb, boj, boe, gdp, inflation, war, election, oil, gold, recession, tradedeals), items (1–50, default 20), date_range (default today). Returns {section, topic, date_range, items[], n}.
GET/api/v3/news_forex/eventsnews_forex_eventsClustered FX news events: high press-coverage stories such as central-bank decisions, rate moves and intervention rumours. Query: pair (optional), date_range (pass it explicitly: today for today only, last7days for the past week), items (1–50, default 20). Events are clustered after the fact, so today can come back empty early in the day; widen to last7days. Returns {pair, date_range, items[], n}.
GET/api/v3/news_forex/trendingnews_forex_trendingNoise-filtered top FX stories. Query: pair (optional; omit for market-wide). Returns {pair, items[], n}.
GET/api/v3/news_forex/top_mentionsnews_forex_top_mentionsMost-mentioned FX pairs with sentiment tilt. Query: date_range (today|last7days|last30days, default last7days). Returns {date_range, items[], n}.
GET/api/v3/news_forex/sentiment_statsnews_forex_sentiment_statsDaily sentiment for one pair: positive, negative and neutral counts and a -1.5 to +1.5 sentiment_score per day. Query: pair (required), date_range (last7days|last30days|last60days, default last30days). Returns {pair, date_range, stats}. 10-min cache.
GET/api/v3/news_forex/market_sentimentnews_forex_market_sentimentOverall FX market sentiment rollup with no pair filter. Query: date_range (default last7days). Returns {date_range, market}. 10-min cache.
GET/api/v3/news_forex/sundown_digestnews_forex_sundown_digestDaily evening FX market summary. Query: date_range (optional, e.g. today, last7days). Returns {date_range, items[], n}.
GET/api/v3/news_forex/pricesnews_forex_pricesLive FX mid prices, refreshed upstream every 15 minutes. Query: pairs (comma-separated) for specific quotes, or base (e.g. USD) for every pair against one currency; pairs wins if you pass both. Returns {pairs, base, items[], n}. 30 s cache.

A filter a news_forex route does not take is refused, not dropped: a non-blank pair, pairs, currency, currencies, ticker, tickers, symbol, symbols, sector, sectors, industry, topic or topics that the route does not declare answers 422 with error: "unsupported_filter", not billed, and detail names the parameter or route to use: pairs on latest and prices, pair on sentiment_stats, trending, events and summary/{pair}, currency on economic_calendar, topic on by_category. market_sentiment, top_mentions and sundown_digest take no pair filter.

When the FX news feed fails and returns nothing, every news_forex route answers 503 with error: "upstream_unavailable", not billed, instead of a 200 with empty data. error_code names the failure (for example upstream_quota_exhausted, or upstream_not_configured when no feed is configured), upstream_error summarises it, and Retry-After says when to retry; the body has no data field. A feed that answered with nothing is still a 200, and a partial failure keeps its rows beside a vendor_error block. summary/{pair} refuses this way when its parts come back empty while the feed is out of quota. When the feed states when its quota resets, upstream_error adds quota_resets_at (UTC) and quota_resets_at_basis, and the body adds retry_after_basis: "firm_recheck": Retry-After is when Wealthnow next checks the feed, not when the quota returns (see News & Sentiment). On by_category, a section other than general or alltickers returns 422 instead of an empty list.

When a calendar feed is unavailable

Current status (2026-09-30). The feed behind the economics calendar is retired. It returned no data after 2026-06-30, and the archive stops at about that date, so every call takes the fallback path described below. The ratings calendar answers from a live ratings feed instead; see The analyst ratings calendar. Since 2026-09-30 the conference-call calendar reads each company's earnings calls from the corporate-events archive (see its row above), so nothing in this section applies to it.

  • calendar/economics without date_from returns 503 with error_code: "forward_window_empty" (not billed). With an explicit date_from it serves archived past events with degraded: true, or 503 with upstream_dead_no_archive when the window is newer than the archive.
  • calendar/ratings reads its archive (newest action 2026-06-26) only when the live ratings feed fails.
  • A 503 caused by the retired feed (forward_window_empty or upstream_dead_no_archive) carries Retry-After: 86400 and says that retrying will not change the answer. Do not poll it. A failed archive read (archive_read_timeout, archive_read_failed) is transient and keeps a short Retry-After.
  • For recent macro prints with actual, forecast and previous values use GET /api/v3/news_forex/economic_calendar. For current analyst upgrades, downgrades and initiations use calendar/ratings or GET /api/v3/news/ratings (News & Sentiment), which read the same live ratings feed. Neither depends on the retired newswire.

The economics calendar reads its live feed first and falls back to a warehouse archive; the ratings calendar reads its live ratings feed first and falls back to its archive the same way. Every served response carries a coverage block (items_returned, newest_item_date, oldest_item_date, forward_dated_items, upstream_reachable) and a staleness block (stale, severity, age_days, disclosure).

  • The feed answered with nothing: 200 with items: [] and result: "empty_but_healthy". That is a genuine empty result.
  • The feed is down and the archive has usable rows: 200 with degraded: true. Quote each item with its own date.
  • The feed is down and the archive cannot answer: 503 with error: "upstream_unavailable", an error_code (forward_window_empty, upstream_dead_no_archive, archive_read_timeout or archive_read_failed), is_empty_result_set: false and a Retry-After header. The body has no items field on purpose, and the call is not billed.
  • The economics calendar is forward-looking. When the live feed is down and you did not pass date_from, the archive is read only from today on, so past events are never returned as an upcoming schedule. Pass an explicit date_from to read past releases from the archive. The ratings calendar has no forward window: a rating action stays true after the day it happened.

The analyst ratings calendar

Since 2026-09-25 calendar/ratings answers from the live analyst-ratings feed that news/ratings reads, with source: "vendor:news-ratings-feed" and a source_note. It used to serve an archive whose newest action was 2026-06-26. Items come newest first:

  • date and time are New York time, named in time_zone: "America/New_York". analyst_firm, rating_prior, rating_current, pt_prior, pt_current and pt_pct_change come from the feed, and currency is USD when a target is given in dollars.
  • analyst_name, company, url and importance are null: the live feed does not carry them.
  • action_company is the feed's action type as Upgrades, Downgrades, Initiates, Reiterates or Resumes.
  • action_pt is derived from the two targets: Raises or Lowers when the target moved, Maintains when it did not, Announces when there was no prior target, and null when the action carries no target.
  • action matches action_pt or action_company. Maintains also matches a reiterated rating (action_company: "Reiterates"), because the feed has no separate "maintains" type.
  • scan says how much of the feed was read: rows_read, pages, complete and filtered_after_read. The feed filters Initiates itself; any other action is matched after reading the newest actions, at most two pages of 50. When that read stopped before the feed ran out and fewer than limit items matched, result is not_found_in_rows_read (nothing matched) or partial_scan (some did), and detail asks you to narrow tickers or date_from and date_to. Neither means no such action exists.
  • A live answer with no items has result: "empty_but_healthy". With tickers, staleness is stale: false with feed_read_at, and age_days is the newest action's age: an old action on a quiet ticker is still a current read.

If the live feed fails, the archive answers as it did before 2026-09-25, and vendor_error names the live feed's failure. A 503 in that case advises a retry once the live feed is restored, rather than saying the feed is retired.

Freshness policy on macro_snapshot

macro_snapshot judges every field against its own update cadence and reports it: is_stale, stale_fields, and field_freshness (as_of, age_hours, stale per field). The freshness parameter decides what happens when something is stale:

  • off (default): always 200; staleness is reported, not enforced.
  • live: 503 with error_code: "data_stale" if a live-market field (VIX, gold, S&P 500, Nasdaq-100, DJIA, Russell 2000) is stale. Slower reference series such as the broad USD index are tolerated.
  • strict: 503 if any field is past its cadence.

The 503 body names the stale fields (stale_fields, field_freshness) so you can branch on data. Retry with freshness=off to accept stale values explicitly.

Streaming the next earnings date

GET /api/v3/earnings/next/{ticker}/stream (2 credits, Starter and up) returns text/event-stream with the same consensus contract as earnings_next. It is a REST route only; there is no MCP tool for it.

  • event: partial arrives when the paid sources already agree (about 500 ms), with the web-search source marked as still in flight. It is skipped when they do not agree.
  • event: result always follows once web search has verified (about 2–3 s). If the web disagrees with the paid sources it sets vendor_coverage_alert.
  • event: error with error_code: "stream_failure" replaces result if the stream fails.

A malformed ticker is rejected with 400 invalid_ticker before the stream opens. Use the stream when you can render incrementally (chat surfaces, live tickers); synchronous callers should keep using earnings_next, which skips the web lookup when the paid sources agree. See Streaming for the other SSE feeds.

Credit block in macro_snapshot

macro_snapshot carries a credit block, the credit market's risk gauge alongside the equity and rates indicators. It reports on-the-run 5Y composite spreads already converted to basis points, plus the session-over-session change. Widening IG/HY spreads signal risk-off; tightening signals risk-on. The block is T-2 (two sessions behind) because the underlying composites are disseminated with a lag: as_of always tells you the true date, and stale flags per field. For the full index history by series and tenor, use /api/v3/credit/indices.

Withheld values in cross_asset

signals_cross_asset checks each futures level before serving it. A level is withheld (served null) when the source wrote no value (reason: "missing_null"), when it holds the source's 0.0 marker for an input missing from its feed (missing_sentinel), or when it falls outside a wide plausibility range (out_of_range, with valid_range). Every field computed from a withheld level, such as a curve slope, a momentum reading or the regime bucket's regime_score, is withheld with it (derived_from_invalid, naming the level in source). invalid_fields in each bucket maps every withheld field to its value in the source and its reason.

The feed has no ICE Dollar Index. Its dx_front column holds EUR per USD, the inverse of the CME euro future, so dx_front is always null (not_this_instrument) and that value is served as usd_proxy_eur_per_usd in the fx bucket (null when the euro future's own level, eu_front, is withheld). dx_curve_slope is always null too (not_measured), and dxy_momentum_basis says that dxy_momentum is a direction read from that proxy, not a Dollar Index level or return.

Examples

Bash: Get live Treasury curve

Shell
curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/macro/treasury_curve" # Response (points keyed by tenor: 1m, 3m, 6m, 1y, 2y, 3y, 5y, 7y, 10y, 20y, 30y):# {#   "ok": true,#   "timestamp": "2026-09-24T14:32:00Z",#   "as_of": "2026-09-23",#   "age_hours": 38.5,#   "is_stale": false,#   "source": "vendor:market-data",#   "points": {#     "1m":  {"yield_pct": 4.12, "change_1d_bps": 1.0},#     "3m":  {"yield_pct": 4.05, "change_1d_bps": 0.0},#     "2y":  {"yield_pct": 3.61, "change_1d_bps": -2.0},#     "10y": {"yield_pct": 4.08, "change_1d_bps": -3.0},#     "30y": {"yield_pct": 4.66, "change_1d_bps": -2.0},#     ...#   },#   "spreads": {#     "spread_2s10s_bps": 47.0,#     "inverted_2s10s": false,#     "spread_3m10y_bps": 3.0,#     "inverted_3m10y": false,#     "source": "computed:treasury_curve_points"#   },#   "prev_date": "2026-09-22",#   "units": "percent (points), basis points (changes/spreads)"# }

A tenor the feed did not publish comes back with yield_pct: null. is_stale turns true when the record date is more than 120 hours old.

Python: Get real-time commodity spot prices

Python
import os, requests r = requests.get(    "https://firm.wealthnow.io/api/v3/intel/commodities",    params={"symbol": "all"},    headers={"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"},    timeout=30,)r.raise_for_status()data = r.json() # Response:# {#   "ok": true,#   "timestamp": "2026-07-05T14:32:00Z",#   "items": {#     "wti_oil": {#       "name": "WTI Crude Oil",#       "unit": "USD per barrel",#       "spot": 82.45,#       "spot_basis": "live_etf_bridged",#       "spot_time": "2026-07-05T14:30:00Z",#       "official_close": 81.92,#       "official_close_as_of": "2026-07-03",#       "change_pct_1d": 0.68,#       "change_pct_5d": 1.25,#       "etf_proxy_quote": {"etf": "USO", "price": 82.45, "day_change_pct": 0.68}#     },#     "gold": {#       "name": "Gold (LBMA PM Fix)",#       "unit": "USD per troy ounce",#       "spot": 2457.50,#       "spot_basis": "live_etf_bridged",#       "official_close": 2450.00,#       "change_pct_1d": 0.31,#       "etf_proxy_quote": {"etf": "GLD", "price": 195.60, "day_change_pct": 0.31}#     }#   },#   "count": 6,#   "source": "fred.stlouisfed.org + live ETF bridge",#   "as_of_date_utc": "2026-07-05",#   "any_stale": false# } for commodity, data in data["items"].items():    print(f"{commodity}: ${data['spot']:.2f} ({data.get('change_pct_1d', 0):+.2f}%)")

Bash: the credit block in macro_snapshot

Shell
curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/macro_snapshot" | jq '.credit'
JSON
{  "source": "warehouse:credit-index-composites",  "as_of": "2026-07-30",  "is_stale": false,  "stale_fields": [],  "fields": {    "cdx_na_ig_5y_bps": {      "value": 53.1,      "prev": 54.7,      "delta_bps": -1.6,      "as_of": "2026-07-30",      "stale": false    },    "cdx_na_hy_5y_bps": {      "value": 313.6,      "prev": 322.4,      "delta_bps": -8.8,      "as_of": "2026-07-30",      "stale": false    }  },  "note": "on-the-run 5Y composite spreads, T-2 by source, the credit market's risk gauge; full series at /api/v3/credit/indices"}

Bash: refuse a stale macro snapshot

Shell
curl -i -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/intel/macro_snapshot?freshness=live" # 200 when every live-market field is inside its cadence. Otherwise a 503# (not billed) that names what is stale:# HTTP/1.1 503# {#   ...#   "error_code": "data_stale",#   "freshness_policy": "live",#   "stale_fields": ["vix"],#   "field_freshness": {"vix": {"as_of": "2026-09-19T20:15:00Z", "age_hours": 114.0, "stale": true}},#   ...# }

Python: next earnings date, then what the Street expects

Python
import os, requests HEADERS = {"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"}BASE = "https://firm.wealthnow.io" nxt = requests.get(f"{BASE}/api/v3/earnings/next/NVDA", headers=HEADERS, timeout=30)nxt.raise_for_status()e = nxt.json()# {#   "ok": true,#   "ticker": "NVDA",#   "next_earnings_date": "2026-11-18",     # null unless confirmed#   "time_of_day": "AMC",#   "confirmed": true,#   "fiscal_period": "Q3 2027",#   "days_until": 55,#   "primary_source": "market_data",#   "sources_agreed": 3,#   "sources_total": 5,#   "summary": "...",#   "per_source": [{"source": "market_data", "date": "2026-11-18", "confirmed": true}, ...],#   "citations": [...],#   "data_freshness": "2026-09-24T14:12:00Z",#   "_meta": {"confidence": "high", "coverage": "confirmed", "is_projected": false, ...}# }print(e["summary"]) est = requests.get(f"{BASE}/api/v3/intel/street_estimates/NVDA", headers=HEADERS, timeout=30)est.raise_for_status()s = est.json()# {#   "ok": true,#   "ticker": "NVDA",#   "next_report": {#     "report_date": "2026-11-18",#     "report_time": "postmarket",#     "report_date_basis": "company",       # "estimation" = projected, not confirmed#     "date_confirmed_by_company": true,#     "street_mean_eps": 1.12,#     "expected_move_usd": 11.8,#     "expected_move_pct": 6.4,#     "fiscal_quarter_end": "2026-10-31"#   },#   "recent_reports": [{"report_date": "2026-08-26", "street_mean_eps": 1.01, "actual_eps": 1.05,#                       "eps_surprise": 0.04, "eps_surprise_pct": 3.96, "post_earnings_move_1d": ...,#                       "eps_basis": "unknown"}],#   "beat_rate_pct": 87.5,#   "events_available": 40,#   "as_of": "2026-09-24T14:12:03Z",#   "source": "vendor:options-flow",#   "eps_basis": "unknown",#   "eps_basis_note": "...",#   "next_report_resolved": {#     "date": "2026-11-18", "status": "confirmed", "confirmed_by": "company",#     "source": "options_flow", "time_of_day": "AMC", "alternatives": [],#     "inputs": {"options_flow": "consulted", "consensus": "not_needed"}, ...#   }# }nr = s["next_report"]resolved = s["next_report_resolved"]if resolved["status"] == "confirmed" and nr:    print(f"Reports {resolved['date']} ({resolved['confirmed_by']}); "          f"Street EPS {nr['street_mean_eps']}, implied move ±{nr['expected_move_pct']}%")

Bash: stream the next earnings date

Shell
curl -N -H "Authorization: Bearer $WEALTHNOW_API_KEY" \  "https://firm.wealthnow.io/api/v3/earnings/next/NVDA/stream" # event: partial# data: {"ticker": "NVDA", "next_earnings_date": "2026-11-18", "confirmed": true, "per_source": [...,#        {"source": "web_search", "reason": "streaming_partial_web_in_flight", ...}], "_meta": {...}, ...}## event: result# data: {"ticker": "NVDA", "next_earnings_date": "2026-11-18", "confirmed": true,#        "vendor_coverage_alert": null, "_meta": {"confidence": "high", ...}, ...}

Python: macro calendar for the week ahead, with a fallback

While the calendar feed is down (see When a calendar feed is unavailable) the first call returns 503 forward_window_empty, so this example falls back to the past week's US releases from the FX economic calendar. Those are recent prints, not an upcoming schedule.

Python
import os, requestsfrom datetime import date, timedelta HEADERS = {"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"}BASE = "https://firm.wealthnow.io" today = date.today()r = requests.get(    f"{BASE}/api/v3/intel/calendar/economics",    params={"country": "USA", "date_to": (today + timedelta(days=7)).isoformat(),            "importance": 3, "limit": 50},    headers=HEADERS, timeout=30,)if r.status_code == 503:    body = r.json()    # Not an empty calendar: the feed is down and the archive cannot answer (not billed).    print(body.get("error_code") or body.get("error"),          "retry after", r.headers.get("Retry-After"), "s")    fx = requests.get(        f"{BASE}/api/v3/news_forex/economic_calendar",        params={"currency": "USD", "importance": "high", "date_range": "last7days"},        headers=HEADERS, timeout=30,    )    fx.raise_for_status()    for row in fx.json()["items"]:  # actual, forecast and previous values per release        print(row)else:    r.raise_for_status()    data = r.json()    print(data["staleness"]["disclosure"])    for ev in data["items"]:        print(ev["date"], ev["time"], ev["event"], "consensus", ev["consensus"], "prior", ev["prior"])

Python: what is moving EUR-USD

Python
import os, requests HEADERS = {"Authorization": f"Bearer {os.environ['WEALTHNOW_API_KEY']}"}BASE = "https://firm.wealthnow.io" s = requests.get(f"{BASE}/api/v3/news_forex/summary/EUR-USD", headers=HEADERS, timeout=30)s.raise_for_status()summary = s.json()  # {"ok": true, "pair": "EUR-USD", "recent_news": [...], "sentiment_stats": {...},                    #  "trending": [...], "news_count_24h": 14, ...}print(summary["news_count_24h"], "stories in the last 24h") px = requests.get(f"{BASE}/api/v3/news_forex/prices", params={"pairs": "EUR-USD,USD-JPY"},                  headers=HEADERS, timeout=30)px.raise_for_status()print(px.json()["items"])  # live mids, refreshed upstream every 15 minutes