Products
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
2 credits per call. Starter plan and up.
Exceptions, each marked in the tables below:
- The two deep estimate archives,
/api/andv3/ intel/ street_ estimates_ history/ {ticker} /api/, bill as the Funds product at 4 credits per call (Starter and up).v3/ intel/ street_ estimates_ guidance/ {ticker} /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_bill as Alt-Data (history/* alt_data): 3 credits per call, Pro and up./api/bills as Transcripts & Events (v3/ intel/ calendar/ conference_ calls events_transcripts): 3 credits per call, Pro and up.
Endpoints
Rates and yields
| Method | Path | MCP tool | Description |
|---|---|---|---|
GET | /api/v3/macro/treasury_ | macro_treasury_curve | Live 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_ | intel_yield_curve | Treasury 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_ | intel_risk_free_rate | Short-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
| Method | Path | MCP tool | Description |
|---|---|---|---|
GET | /api/v3/intel/commodities | intel_commodities | Real-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
| Method | Path | MCP tool | Description |
|---|---|---|---|
GET | /api/macro | macro_dashboard | One-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/regime | market_regime | Current market regime: regime label, regime_multiplier, confidence, hmm_state, vix, sp500_trend, as_of_ts. 60 s cache. |
GET | /api/v3/intel/macro_ | intel_macro_snapshot | Cross-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_ | signals_cross_asset | The 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_ | origin_macro_pulse | Cross-asset state from the issuing authorities in one call: volatility_ (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_ 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
| Method | Path | MCP tool | Description |
|---|---|---|---|
GET | /api/v3/intel/cftc_cot | intel_cftc_cot | CFTC 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_. 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)
| Method | Path | Plan / credits | MCP tool | Description |
|---|---|---|---|---|
GET | /api/ | Pro+ / 4 | volatility_vix_indices | Daily 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_ | Pro+ / 4 | volatility_vx_curve | The 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_ and stale label a late feed. Params: date, history. |
GET | /api/v3/positioning/cot | Pro+ / 4 | positioning_cot | The 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.
| Method | Path | Plan / credits | MCP tool | Description |
|---|---|---|---|---|
GET | /api/ | Pro+ / 3 | macro_ | Weekly 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/ | Pro+ / 3 | macro_ | The 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/ | Pro+ / 3 | macro_ | US 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/ | Pro+ / 3 | macro_ | OECD 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/ | Pro+ / 3 | macro_ | Daily 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_ | Pro+ / 3 | macro_ | The 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/ | Pro+ / 3 | macro_history_series | One 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_ (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_. Default window by frequency; up to 5,000 newest points. An unknown id is a 422 listing the ids. Params: start, end. |
GET | /api/ | Pro+ / 3 | macro_ | S&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
| Method | Path | MCP tool | Description |
|---|---|---|---|
GET | /api/ | intel_ | Macro 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_, 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_ below. |
GET | /api/ | news_ | FX-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_. 10-min cache. |
Earnings and Street estimates
| Method | Path | MCP tool | Description |
|---|---|---|---|
GET | /api/ | earnings_next | Next 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_. 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_ (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_, because the top-level next_earnings_date is this route's own consensus and can differ when the issuer confirmed another date. most_ 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_ is options_flow_calendar, most_ and summary follow it, and the superseded date and its source are in most_. On 2026-09-25 NVDA's read 2025-05-28 before this and 2026-08-26 after. 1 h cache. |
GET | /api/ | none (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/ | intel_street_estimates | Street 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/ | intel_earnings_history | Last 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_ and max_. 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/ | intel_ | 3 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/ | intel_calendar_ratings | Analyst 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/ | intel_ | 4 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_ plus the archive clocks described under How far the estimate archives run. |
GET | /api/ | intel_ | 4 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:
dateandtime_of_day, andstatus:confirmed,projectedorunknown.confirmed_by:companywhen the issuer confirmed the date,vendor_consensuswhen the calendars and web search agree, ornullfor a projection. An issuer-confirmed date wins over a consensus date, and a consensus date over a projection.source, andalternatives: other dates the inputs held, each with itsstatusandsource.inputssays which sources the answer was resolved from:options_flowisconsultedorunavailable;consensusisconsulted,not_needed(the issuer confirmed the date) orunavailable(the consensus was not ready in time; retry for the settled date). Both arenot_consultedfor 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_pctis that session's open-to-close move andday_range_pctits high-to-low range.day_move_datenames the session.day_move_basisisreaction_sessionwhen the release time is known,release_time_unknownwhen it is not (the first session on or afterreport_date, so the reaction may be the next one), orreaction_when that session has not closed yet, and then the move issession_ pending null.reaction_move_pctruns from the last close before the release to the reaction session's close, the move to compare with an implied move. It isnullunless the release time is known.warning: "report_means the report-date source failed; the EPS rows are still served.dates_ unavailable"
How far the estimate archives run
street_ and street_ 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_ 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.
| Method | Path | Plan / credits | MCP tool | Description |
|---|---|---|---|---|
GET | /api/ | Pro+ / 3 | estimates_ | Quarterly 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/ | Pro+ / 3 | estimates_ | Monthly 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/ | Pro+ / 3 | estimates_ | Monthly 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.
| Method | Path | MCP tool | Description |
|---|---|---|---|
GET | /api/ | news_forex_summary | One 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_ | news_forex_latest | Recent 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_. 3-min cache. |
GET | /api/ | news_forex_by_category | Macro 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_. |
GET | /api/v3/news_ | news_forex_events | Clustered 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_. |
GET | /api/v3/news_ | news_forex_trending | Noise-filtered top FX stories. Query: pair (optional; omit for market-wide). Returns {pair, items[], n}. |
GET | /api/ | news_forex_top_mentions | Most-mentioned FX pairs with sentiment tilt. Query: date_range (today|last7days|last30days, default last7days). Returns {date_. |
GET | /api/ | news_ | Daily 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_. 10-min cache. |
GET | /api/ | news_ | Overall FX market sentiment rollup with no pair filter. Query: date_range (default last7days). Returns {date_range, market}. 10-min cache. |
GET | /api/ | news_ | Daily evening FX market summary. Query: date_range (optional, e.g. today, last7days). Returns {date_. |
GET | /api/v3/news_ | news_forex_prices | Live 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_, 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_, not billed, instead of a 200 with empty data. error_code names the failure (for example upstream_, 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_: 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/economicswithoutdate_fromreturns503witherror_(not billed). With an explicitcode: "forward_ window_ empty" date_fromit serves archived past events withdegraded: true, or503withupstream_when the window is newer than the archive.dead_ no_ archive calendar/ratingsreads its archive (newest action 2026-06-26) only when the live ratings feed fails.- A
503caused by the retired feed (forward_window_emptyorupstream_) carriesdead_ no_ archive Retry-After: 86400and 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 shortRetry-After. - For recent macro prints with actual, forecast and previous values use
GET /. For current analyst upgrades, downgrades and initiations useapi/ v3/ news_ forex/ economic_ calendar calendar/ratingsorGET /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:
200withitems: []andresult: "empty_. That is a genuine empty result.but_ healthy" - The feed is down and the archive has usable rows:
200withdegraded: true. Quote each item with its own date. - The feed is down and the archive cannot answer:
503witherror: "upstream_, anunavailable" error_code(forward_window_empty,upstream_,dead_ no_ archive archive_read_timeoutorarchive_read_failed),is_and aempty_ result_ set: false Retry-Afterheader. The body has noitemsfield 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 explicitdate_fromto 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:
dateandtimeare New York time, named intime_.zone: "America/New_ York" analyst_firm,rating_prior,rating_current,pt_prior,pt_currentandpt_pct_changecome from the feed, andcurrencyisUSDwhen a target is given in dollars.analyst_name,company,urlandimportancearenull: the live feed does not carry them.action_companyis the feed's action type asUpgrades,Downgrades,Initiates,ReiteratesorResumes.action_ptis derived from the two targets:RaisesorLowerswhen the target moved,Maintainswhen it did not,Announceswhen there was no prior target, andnullwhen the action carries no target.actionmatchesaction_ptoraction_company.Maintainsalso matches a reiterated rating (action_), because the feed has no separate "maintains" type.company: "Reiterates" scansays how much of the feed was read:rows_read,pages,completeandfiltered_after_read. The feed filtersInitiatesitself; any otheractionis matched after reading the newest actions, at most two pages of 50. When that read stopped before the feed ran out and fewer thanlimititems matched,resultisnot_found_in_rows_read(nothing matched) orpartial_scan(some did), anddetailasks you to narrowtickersordate_fromanddate_to. Neither means no such action exists.- A live answer with no items has
result: "empty_. Withbut_ healthy" tickers,stalenessisstale: falsewithfeed_read_at, andage_daysis 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): always200; staleness is reported, not enforced.live:503witherror_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.code: "data_ stale" strict:503if 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 / (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: partialarrives 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: resultalways follows once web search has verified (about 2–3 s). If the web disagrees with the paid sources it setsvendor_coverage_alert.event: errorwitherror_replacescode: "stream_ failure" resultif 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
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
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
curl -H "Authorization: Bearer $WEALTHNOW_API_KEY" \ "https://firm.wealthnow.io/api/v3/intel/macro_snapshot" | jq '.credit'{ "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
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
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
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_, 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.
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
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