Market Data & Fundamentals
metricsPURPOSE: Look up live and historical financial market data — prices, charts, technical indicators, macroeconomic data, and company fundamentals. Always call this for current numbers; training data is stale.
COVERS (by intent):
market: [market-quote] live price / quote / snapshot, including optional extended-hours bid/ask quote for US stocks/ETFs · [market-history] OHLCV candles & price history (incl. generic crypto K-line and explicit Binance Futures raw candles) · [market-technical] technical indicators (RSI / MACD / moving averages) · [market-movers] US gainers / losers / most-active board · [market-derivatives] Binance USDT perpetual universe with 24h quote volume, current raw funding-rate board, and daily open-interest history
macro: [macro-indicator] economic series (CPI, GDP, unemployment, fed funds) · [macro-rates] treasury yields & yield curve · [macro-calendar] economic-event calendar, data release dates & important upcoming releases
fundamentals: [fundamentals-financials] income statement / balance sheet / cash flow · [fundamentals-earnings] fiscal-period financial statements, actual-versus-estimate earnings comparisons, and fiscal-period call transcripts · [fundamentals-earnings-calendar] next-earnings date for a ticker AND market-wide earnings calendar (with or without a ticker) · [fundamentals-analyst] sell-side analyst price targets, estimates, and rating upgrades/downgrades · [fundamentals-research-report] structured broker / sell-side research reports, report cards, report thesis/catalysts/caveats, matched mention context, section counts, and a most-mentioned board whose mention_impact counts how distinct reports describe each affected ticker · [fundamentals-valuation] DCF / ratios / key metrics / enterprise value · [fundamentals-growth] revenue & earnings growth · [fundamentals-profile] company profile, sector, shares outstanding / float · [fundamentals-peers] comparable companies / competitors · [fundamentals-filings] SEC filings (10-K, 8-K) · [fundamentals-esg] ESG ratings
BOUNDARIES:
Sell-side analyst ratings, price targets, estimates, and rating upgrades/downgrades → fundamentals-analyst. Structured broker research reports / 研报 / 券商研报 with report cards, thesis, catalysts, caveats, matched mention context, or "most mentioned stocks in research reports" → fundamentals-research-report. Plain "研报" consumption/summary/analysis defaults to metrics. Raw research-source article/document discovery uses news.sources=["research"]. Ratings / targets / "上调评级" / "how Wall Street rates it" / "华尔街怎么看…评级" are fundamentals datapoints.
"Comparable / peer companies" → fundamentals-peers.
Raw numbers / data → metrics; open-ended interpretation / commentary / "怎么看" / "解读" about events, media coverage, or social discussion → news.
Market movers cover US equities and drop sub-$1 penny stocks by default (include_penny_stocks=true to keep them).
USAGE: Argument contract: keywords is the ENTITY FIELD; query is the INTENT FIELD. Whenever the user names assets, companies, indices, commodities, or macro series, put each entity in a separate keywords item and put the requested metric or operation in query. Example: "JBLU next earnings date" → keywords=["JBLU"], query="next earnings date"; a batch uses keywords=["JBLU","CUBI"]. Standalone query serves entity-free screens such as economic calendar, biggest gainers, treasury yield curve, Binance perpetual universe, or current funding rates. categories (market | macro | fundamentals) is optional — omit to auto-detect. interval selects intraday candles; period is the indicator window. For economic events, sort_by="time" follows the schedule and "hot" brings higher-impact releases first, keeping time order within each priority level; omit it for the default order. Other result types keep their existing ordering. English query gives the best recall; up to 5 keywords run in parallel, and omissions are reported in meta.warnings. Contract-specific Binance Futures requests reuse keywords and accept aliases, canonical assets, or exact universe symbols. MCP resolves the common alias first, then checks the authoritative perpetual_universe: exact symbol wins; otherwise a unique baseAsset match selects the universe row's real symbol. MCP never constructs a symbol by appending USDT. An exact universe symbol is needed only when one base asset matches multiple contracts. This applies to OI, explicit Futures candles, and named funding/universe filtering. OI is daily, defaults to 3 points, and supports at most the latest 30 points per symbol. Use time_range="30d" to request the full available OI window; an explicit limit caps the rows inside that window. Explicit Binance Futures candle requests must say Binance Futures or perpetual in query; generic crypto history retains the spot/fallback route. Calendar, Binance perpetual-universe, and current-funding leaves return at most 50 rows per page; meta.pagination supplies an opaque next_cursor, and sending it back unchanged in cursor with the same arguments continues that leaf. A requested page limit above 50 uses 50 and is reported in meta.warnings. Perpetual-universe pages are ordered by 24h quoteVolume descending; current-funding pages are ordered by absolute lastFundingRate descending. Structured research-report asset mode searches every resolved ticker, including multiple listings from one alias; report cards are deduplicated by event_id with subject matches preferred, then ordered by report date descending with subject matches first on the same date; all ticker groups share one card stream, and each page contains at most 10 cards. Continue fundamentals.research_reports with its opaque next_cursor and unchanged arguments, including verbosity. Every card always includes report_subject_target_price and matched_asset_target_price (null when unavailable); legacy target-price aliases are absent. No-ticker research aggregation counts each report/ticker pair once and exposes mention_impact counts for beneficiary, adverse, neutral, and mixed descriptions; dominant is tie when buckets share the highest count and mixed only when the mixed bucket uniquely leads. detail returns capped evidence sections plus original section counts. Both structured research-report modes honor time_range/date_from/date_to by filtering inclusive report_date bounds. Use time_range=24h / 7d / 30d for recent-report views. Because report_date is date-granularity, 24h resolves to an inclusive calendar-date range rather than a sub-day publication timestamp. If no time parameter is supplied, all available reports are used. No-ticker aggregation uses limit as leaderboard item count within the effective window.
RETURNS: results bucketed market.{snapshot,history,technical,movers,perpetual_universe,funding_rate,open_interest}, macro.{indicators,calendar}, fundamentals.{concise,earnings_calendar,research_reports,research_report_most_mentioned} — only fired buckets present. Binance Futures numeric values remain raw decimal strings; MCP does not annualize funding, calculate OI changes, filter weekend bars, or emit scanner/trading judgments. Fundamentals concise output groups corresponding financial_statement and earnings_surprise blocks under fiscal_quarters[].fiscal_period; earnings_surprise is the standard actual-results-versus-consensus comparison. Transcript rows carry their actual date, fiscal_year, fiscal_quarter, and stable freshness. Pagination state is keyed by result leaf in meta.pagination. Per-input failures / no-match notices in meta.warnings[] (reason=not_applicable / kw_not_canonical / no_match).
EXAMPLES (user → args; cross-lingual — translate intent to English):
"BTC 现价" → keywords=["BTC"]
"Binance USDT 永续合约池" → query="Binance USDT perpetual universe", categories=["market"], asset_type="crypto"
"当前永续资金费率" → query="current perpetual funding rates", categories=["market"], asset_type="crypto"
"BTC 的 Binance Futures 日 K" → keywords=["BTC"], query="Binance Futures candles", categories=["market"], asset_type="crypto"
"比特币和 Ethereum 的 OI 日线" → keywords=["比特币","Ethereum"], query="open interest history", categories=["market"], limit=3
"BTC 最近30天的 OI" → keywords=["BTC"], query="open interest history", categories=["market"], asset_type="crypto", time_range="30d"
"苹果近30天走势带 RSI" → keywords=["AAPL"], query="RSI", time_range="30d"
"비트코인 1년 차트" → keywords=["BTC"], asset_type="crypto", time_range="1y"
"Giá Bitcoin hôm nay" → keywords=["BTC"]
"美国 CPI 和 GDP 增速" → keywords=["CPI","GDP"], categories=["macro"]
"国债收益率曲线" → query="treasury yield curve", categories=["macro"]
"经济日历" → query="economic calendar", categories=["macro"]
"先看重要经济事件" → query="economic calendar", categories=["macro"], sort_by="hot"
"分析师给英伟达的目标价" → keywords=["NVDA"], query="analyst price target"
"华尔街最近有没有上调特斯拉评级" → keywords=["TSLA"], query="analyst rating"
"NVDA 的券商研报怎么看" → keywords=["NVDA"], query="broker research reports", categories=["fundamentals"]
"最近7天研报提到最多的美股" → query="most mentioned stocks in research reports", categories=["fundamentals"], time_range="7d"
"最近24小时的 NVDA 研报" → keywords=["NVDA"], query="latest broker research reports", categories=["fundamentals"], time_range="24h"
"美股财报日历" → query="earnings calendar"
"苹果下次财报时间" → keywords=["AAPL"], query="next earnings date"
"和英伟达对标的几家公司" → keywords=["NVDA"], query="peers"
"苹果的自由现金流" → keywords=["AAPL"], query="cash flow"
"AAPL 全面分析" → keywords=["AAPL"], query="comprehensive analysis"
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Display records per topic (default 10): snapshot keeps one object per actual asset; technical keeps every asset and indicator series with at most N latest observations each; fundamentals keeps every company and caps each nested record list after calculations. Other per-asset or per-series buckets retain independent limits — e.g. results.market.history holds up to limit OHLCV rows per requested symbol. Binance Futures open-interest history returns at most 30 daily points per symbol; when limit is omitted\, an explicit time_range up to 30d determines its point count\, otherwise OI defaults to 3 points. Structured research-report asset mode searches all resolved tickers, deduplicates reports by event_id with subject matches preferred, and shares one card page across all returned ticker groups. Its maximum page size is 10; more cards continue through meta.pagination.next_cursor. Research-report aggregate mode uses limit as leaderboard item count. Historical price series supports up to 365; other leaf buckets cap at 50. Calendar, Binance perpetual-universe, and current-funding leaves report a limit above 50 in meta.warnings and provide continuation through meta.pagination.next_cursor. | |
| query | No | INTENT FIELD — State the requested metric, operation, analytical angle, or entity-free screen in natural language. Pair with keywords whenever the request names assets or other entities. Examples paired with keywords: 'next earnings date'\, 'RSI'\, 'valuation'\, 'balance sheet'\, 'comprehensive analysis'. Standalone query supports entity-free requests such as 'treasury yield curve'\, 'economic calendar'\, 'biggest gainers'\, and 'most mentioned stocks in research reports'. English usually gives the best recall. Put explicit time constraints in time_range/date_from/date_to. Up to 500 runes; truncation is reported in meta.warnings. | |
| cursor | No | Opaque continuation token returned in meta.pagination by a pagination-capable metrics leaf. Send it back unchanged with the same query\, filters\, sorting\, limit\, and verbosity to fetch the next page. Economic calendar\, earnings calendar\, fundamentals.research_reports\, Binance perpetual-universe\, and current-funding boards support this field; research-report pages contain at most 10 cards. | |
| period | No | Technical-indicator window length (e.g. 14 for RSI\, 50 or 200 for moving averages). | |
| country | No | Request-wide ISO 3166-1 alpha-2 country constraint\, e.g. US\, CA\, GB. Uses issuer domicile from stored company profiles for symbol-bound market/fundamentals rows and event country for economic calendars. Crypto and rows whose country cannot be verified are omitted. | |
| date_to | No | Explicit end date (YYYY-MM-DD). Defaults to today when only date_from is set. Structured research-report results apply it inclusively to report_date. | |
| sort_by | No | Sort order: time orders results by time; hot prioritizes results by importance or popularity\, depending on the data type. Supported modes vary by data type. Leave unset to use the default ordering. | |
| interval | No | Intraday candlestick granularity: 1min | 5min | 15min | 30min | 1hour | 4hour. Set it for intraday candles at that resolution; omit for daily. | |
| keywords | No | ENTITY FIELD — Put every named asset, security, token, ETF, index, commodity, company ticker, macro series code, or Binance Futures contract here as a separate array item. Known complete token addresses are also aliases (e.g. the UNI contract address resolves to UNI). Use aliases or canonical IDs such as Bitcoin\, BTC\, AAPL\, NVDA\, CPI\, GDP\, FEDFUNDS. Contract-specific Binance Futures requests (OI\, Futures candles\, or named funding/universe filtering) use the same field: MCP first resolves aliases to a canonical asset and then selects an authoritative perpetual_universe row by exact symbol or unique baseAsset. It never constructs a contract by appending USDT; pass an exact universe symbol only when one base asset is genuinely ambiguous. Required whenever the request names a specific entity. Example: 'JBLU next earnings date' → keywords=['JBLU']; query carries 'next earnings date'. At most 5 keywords are processed; omissions are reported in meta.warnings. Each keyword supports up to 128 runes; truncation is reported in meta.warnings. Research-report asset mode searches every resolved ticker (including multiple listings resolved from one alias) and applies one shared card limit. | |
| date_from | No | Explicit start date (YYYY-MM-DD). Takes priority over time_range when both are set. Calendar absolute ranges use earliest-first time ordering, including ties within a priority level. Structured research-report results apply it inclusively to report_date. | |
| verbosity | No | Free-text fields (including nested prose) use original prefixes: concise 200 Unicode runes | standard 600 (default for empty or unknown) | detail 2000. Numeric facts, dates, IDs, URLs, tags and technical data are not shortened. Detail still applies this cap; record counts use topic-specific limit. | |
| asset_type | No | crypto | tradfi. Use when a name could be either a crypto token or a traditional asset. Leave empty to get both. | |
| categories | No | Restrict to one or more domains: market (prices / charts / technicals)\, macro (economic data)\, fundamentals (company financials). Omit to auto-detect. | |
| time_range | No | Explicit caller-requested lookback\, written as <number><unit> where unit is h|d|w|m|y — e.g. 24h\, 7d\, 30d\, 1y. Supply this field when a time constraint is required; the server does not infer a window from query text. Internally derives date_from = now - this; explicit date_from wins. Binance Futures OI supports at most the latest 30 daily points; time_range longer than 30d is reported as partial with an effective 30d window. Calendar lookbacks use newest-first time ordering, including ties within a priority level. Structured research-report cards and leaderboards filter inclusively on date-granularity report_date. | |
| include_penny_stocks | No | US-equity movers setting (gainers / losers / most active). Default false drops penny stocks (price < $1); set true to include them. Applies to US-equity movers queries. |