Stock Market Data (Unified Dispatch Layer)
Provide stock-analysis agents with unified data retrieval and evidence provenance. Most currently integrated sources require no API key, but every call must follow an explicit provider policy. Future official sources for China, Japan, and Korea must use the same dispatch layer.
Required operating discipline
- Use the unified entry point for every new call:
python scripts/market_data.py <command>. Legacy scripts are compatibility entry points only.
- Resolve the security identity before analyzing a stock:
python scripts/market_data.py resolve "<company name>". Never guess a ticker; consume entity → listing → security, and do not treat a ticker as a permanent identity.
- Script failures return JSON error declarations. Treat the data item as unavailable, disclose the degraded result, and never fabricate a substitute. Reddit and StockTwits may be rate-limited (429/403); this is an expected degradation path.
- Cache writes go to the system temporary directory and may be redirected with
SKILL_CACHE_DIR. Scripts are repeatable and idempotent.
- Never fall back silently: use only the order explicitly listed in
scripts/provider_config.json, and inspect _meta.provider_attempts and _meta.fallback_used.
- Every field must be traceable: read the reference period, publication time, retrieval time, adjustment basis, and field paths in
_meta.sources. Data without published_at must not be used for strict historical analysis.
- Never backfill historical analysis with current network data: use
market_data.py as-of to read immutable snapshots that were public before the cutoff. If the query fails, declare the data unavailable.
- Always describe current prices as “research-grade current/delayed quotes,” never as exchange-authorized real-time quotes or execution inputs. Check
quote_availability. Disclose the nominal 20-minute delay for Japan/Korea yfinance quotes. Label Tencent/Sina mainland-China quotes as near-real-time web quotes with no SLA, and distinguish quote time from retrieval time.
- Judge quote freshness by the latest completed exchange session, not elapsed natural hours. Read references/session-freshness.md. Nights, weekends, holidays, and pre-market time do not by themselves make the latest completed close stale.
See references/data-contract.md for the full contract.
Unified entry point
python scripts/market_data.py resolve "Apple"
python scripts/market_data.py price AAPL MSFT
python scripts/market_data.py fundamentals AAPL
python scripts/market_data.py events AAPL
python scripts/market_data.py news AAPL
python scripts/market_data.py earnings-calendar AAPL
python scripts/market_data.py short-interest AAPL
python scripts/market_data.py positioning AAPL
python scripts/market_data.py technicals AAPL --period medium
python scripts/market_data.py macro --market us
python scripts/market_data.py providers prices --market CN-SH
python scripts/market_data.py as-of prices AAPL --as-of 2026-08-21T20:00:00Z
Script catalog
Run every script with the interpreter (python scripts/<name>.py). Dependencies use inline PEP 723 declarations, which support automatic installation through uv run. Every script outputs JSON.
| Script |
Purpose |
Example |
scripts/market_data.py |
Unified dispatch for identity, prices, fundamentals, events, news, earnings dates, positioning, macro, technicals, and historical queries |
python scripts/market_data.py price NBIS |
scripts/search_ticker.py |
Compatibility entry point: company name → ticker (US/HK) |
python scripts/search_ticker.py "nebius" |
scripts/fetch_price.py |
Compatibility entry point: research-grade regular-session price, volume ratio, and explicitly labeled yfinance pre/post-market quotes when available |
python scripts/fetch_price.py NBIS |
scripts/fetch_fundamentals.py |
Valuation and financial summary (PE/PS/margins/growth) |
python scripts/fetch_fundamentals.py NBIS |
scripts/fetch_events.py |
Event scan: earnings, rating changes, and insider trades |
python scripts/fetch_events.py NBIS |
scripts/fetch_news.py |
Company and macro news from Yahoo, Google News RSS, and Seeking Alpha |
python scripts/fetch_news.py NBIS |
scripts/fetch_earnings_calendar.py |
Next earnings date, required for wait-state decisions |
python scripts/fetch_earnings_calendar.py NBIS |
scripts/check_earnings_released.py |
Whether earnings have been released |
python scripts/check_earnings_released.py NBIS |
scripts/fetch_earnings_report.py |
Locate original earnings filings (SEC 10-Q/10-K) |
python scripts/fetch_earnings_report.py NBIS |
scripts/fetch_earnings_transcript.py |
Earnings-call transcript (8-K; 6-K foreign issuers are not yet supported) |
python scripts/fetch_earnings_transcript.py NBIS |
scripts/fetch_short_interest.py |
US reported short-interest fields; HK same-day short-selling turnover and shortable eligibility. Not real-time borrow data or a complete net-short position |
python scripts/fetch_short_interest.py NBIS |
scripts/fetch_options_flow.py |
US options-volume Put/Call, FINRA off-exchange short-sale volume, and selected Form 4 data. Not signed options flow or dealer GEX |
python scripts/fetch_options_flow.py NBIS |
scripts/fetch_13f.py |
A specified manager's quarterly 13F long positions from SEC EDGAR, not market-wide institutional ownership by ticker |
python scripts/fetch_13f.py --cik 0001423298 |
scripts/fetch_reddit.py |
Discussion activity on finance subreddits via RSS, with automatic rate-limit backoff |
python scripts/fetch_reddit.py NBIS --limit 5 |
scripts/fetch_stocktwits.py |
StockTwits message stream for retail sentiment |
python scripts/fetch_stocktwits.py NBIS |
scripts/fetch_polymarket.py |
Prediction-market implied probabilities for macro/events |
python scripts/fetch_polymarket.py "fed rate" |
scripts/fetch_macro.py |
Macro snapshot: VIX, equity-index futures, oil, and US Treasuries |
python scripts/fetch_macro.py |
scripts/analyze_technicals.py |
Technical-research inputs: trend, regime, multi-timeframe structure, OBV, 20-day rolling VWAP, Bollinger Bands, KDJ, MFI, volume-price effort/result, and bar metadata |
python scripts/analyze_technicals.py NBIS --period medium |
scripts/generate_chart.py |
Weekly, daily, or intraday research chart plus a same-stem component-data sidecar: candlesticks, volume, EMA8/21/55, support/resistance, and swing structure; research mode excludes trade annotations |
python scripts/generate_chart.py --symbol NBIS --mode research --interval 1wk --days 104 |
scripts/analyze_zones.py |
Trading-layer entry zones and backtest (win rate/odds/Kelly); must not be used by research-layer stock-technical-structure |
python scripts/analyze_zones.py --symbol NBIS --direction long |
Utility modules (not called directly): provider_runtime.py (explicit dispatch), data_contract.py (provenance contract), security_master.py (three-layer identity), snapshot_store.py (immutable snapshots), cache_utils.py (short-term cache), resample_utils.py (candlestick resampling), and technical_indicators.py (deterministic calculations that consume only normalized OHLCV and never access a data source directly).
Recommended combinations by analytical dimension
- Fundamentals:
market_data.py fundamentals + market_data.py events (insiders)
- News:
market_data.py news + market_data.py events + market_data.py earnings-calendar
- Earnings period:
check_earnings_released + fetch_earnings_report + fetch_earnings_transcript
- Sentiment/crowding inputs:
market_data.py short-interest + market_data.py positioning; Reddit, StockTwits, and 13F remain compatibility entry points. stock-sentiment-positioning owns basis distinctions, official-source supplementation, and conclusions.
- Technicals:
market_data.py price + market_data.py technicals + weekly and daily generate_chart.py --mode research views; trading-layer analyze_zones remains a compatibility entry point.
- Macro backdrop:
market_data.py macro + fetch_polymarket
Sources and acknowledgments
The scripts originated from the novark market-data toolkit. fetch_reddit, fetch_stocktwits, and fetch_polymarket were adapted from TauricResearch/TradingAgents (Apache-2.0).
1---2name: stock-market-data3description: Unified, provenance-aware market data dispatcher for stock research. Resolves entity/listing/security identity and fetches research-grade current or delayed prices, fundamentals, filings, events, positioning, sentiment, macro and technical inputs through explicit provider chains, immutable snapshots and strict point-in-time queries. Use whenever an analysis needs any market number, ticker resolution, source audit, historical as-of data, valuation, volume, positioning, crowding or catalyst dates. Never use model memory for numbers.4---56# Stock Market Data (Unified Dispatch Layer)78Provide stock-analysis agents with unified data retrieval and evidence provenance. Most currently integrated sources require no API key, but every call must follow an explicit provider policy. Future official sources for China, Japan, and Korea must use the same dispatch layer.910## Required operating discipline11121. **Use the unified entry point for every new call**: `python scripts/market_data.py <command>`. Legacy scripts are compatibility entry points only.132. **Resolve the security identity before analyzing a stock**: `python scripts/market_data.py resolve "<company name>"`. Never guess a ticker; consume `entity → listing → security`, and do not treat a ticker as a permanent identity.143. **Script failures return JSON error declarations**. Treat the data item as unavailable, disclose the degraded result, and never fabricate a substitute. Reddit and StockTwits may be rate-limited (429/403); this is an expected degradation path.154. Cache writes go to the system temporary directory and may be redirected with `SKILL_CACHE_DIR`. Scripts are repeatable and idempotent.165. **Never fall back silently**: use only the order explicitly listed in `scripts/provider_config.json`, and inspect `_meta.provider_attempts` and `_meta.fallback_used`.176. **Every field must be traceable**: read the reference period, publication time, retrieval time, adjustment basis, and field paths in `_meta.sources`. Data without `published_at` must not be used for strict historical analysis.187. **Never backfill historical analysis with current network data**: use `market_data.py as-of` to read immutable snapshots that were public before the cutoff. If the query fails, declare the data unavailable.198. Always describe current prices as “research-grade current/delayed quotes,” never as exchange-authorized real-time quotes or execution inputs. Check `quote_availability`. Disclose the nominal 20-minute delay for Japan/Korea yfinance quotes. Label Tencent/Sina mainland-China quotes as near-real-time web quotes with no SLA, and distinguish quote time from retrieval time.209. Judge quote freshness by the latest completed exchange session, not elapsed natural hours. Read [references/session-freshness.md](references/session-freshness.md). Nights, weekends, holidays, and pre-market time do not by themselves make the latest completed close stale.2122See [references/data-contract.md](references/data-contract.md) for the full contract.2324## Unified entry point2526```bash27python scripts/market_data.py resolve "Apple"28python scripts/market_data.py price AAPL MSFT29python scripts/market_data.py fundamentals AAPL30python scripts/market_data.py events AAPL31python scripts/market_data.py news AAPL32python scripts/market_data.py earnings-calendar AAPL33python scripts/market_data.py short-interest AAPL34python scripts/market_data.py positioning AAPL35python scripts/market_data.py technicals AAPL --period medium36python scripts/market_data.py macro --market us37python scripts/market_data.py providers prices --market CN-SH38python scripts/market_data.py as-of prices AAPL --as-of 2026-08-21T20:00:00Z39```4041## Script catalog4243Run every script with the interpreter (`python scripts/<name>.py`). Dependencies use inline PEP 723 declarations, which support automatic installation through `uv run`. Every script outputs JSON.4445| Script | Purpose | Example |46| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |47| `scripts/market_data.py` | Unified dispatch for identity, prices, fundamentals, events, news, earnings dates, positioning, macro, technicals, and historical queries | `python scripts/market_data.py price NBIS` |48| `scripts/search_ticker.py` | Compatibility entry point: company name → ticker (US/HK) | `python scripts/search_ticker.py "nebius"` |49| `scripts/fetch_price.py` | Compatibility entry point: research-grade regular-session price, volume ratio, and explicitly labeled yfinance pre/post-market quotes when available | `python scripts/fetch_price.py NBIS` |50| `scripts/fetch_fundamentals.py` | Valuation and financial summary (PE/PS/margins/growth) | `python scripts/fetch_fundamentals.py NBIS` |51| `scripts/fetch_events.py` | Event scan: earnings, rating changes, and insider trades | `python scripts/fetch_events.py NBIS` |52| `scripts/fetch_news.py` | Company and macro news from Yahoo, Google News RSS, and Seeking Alpha | `python scripts/fetch_news.py NBIS` |53| `scripts/fetch_earnings_calendar.py` | Next earnings date, required for wait-state decisions | `python scripts/fetch_earnings_calendar.py NBIS` |54| `scripts/check_earnings_released.py` | Whether earnings have been released | `python scripts/check_earnings_released.py NBIS` |55| `scripts/fetch_earnings_report.py` | Locate original earnings filings (SEC 10-Q/10-K) | `python scripts/fetch_earnings_report.py NBIS` |56| `scripts/fetch_earnings_transcript.py` | Earnings-call transcript (8-K; 6-K foreign issuers are not yet supported) | `python scripts/fetch_earnings_transcript.py NBIS` |57| `scripts/fetch_short_interest.py` | US reported short-interest fields; HK same-day short-selling turnover and shortable eligibility. Not real-time borrow data or a complete net-short position | `python scripts/fetch_short_interest.py NBIS` |58| `scripts/fetch_options_flow.py` | US options-volume Put/Call, FINRA off-exchange short-sale volume, and selected Form 4 data. Not signed options flow or dealer GEX | `python scripts/fetch_options_flow.py NBIS` |59| `scripts/fetch_13f.py` | A specified manager's quarterly 13F long positions from SEC EDGAR, not market-wide institutional ownership by ticker | `python scripts/fetch_13f.py --cik 0001423298` |60| `scripts/fetch_reddit.py` | Discussion activity on finance subreddits via RSS, with automatic rate-limit backoff | `python scripts/fetch_reddit.py NBIS --limit 5` |61| `scripts/fetch_stocktwits.py` | StockTwits message stream for retail sentiment | `python scripts/fetch_stocktwits.py NBIS` |62| `scripts/fetch_polymarket.py` | Prediction-market implied probabilities for macro/events | `python scripts/fetch_polymarket.py "fed rate"` |63| `scripts/fetch_macro.py` | Macro snapshot: VIX, equity-index futures, oil, and US Treasuries | `python scripts/fetch_macro.py` |64| `scripts/analyze_technicals.py` | Technical-research inputs: trend, regime, multi-timeframe structure, OBV, 20-day rolling VWAP, Bollinger Bands, KDJ, MFI, volume-price effort/result, and bar metadata | `python scripts/analyze_technicals.py NBIS --period medium` |65| `scripts/generate_chart.py` | Weekly, daily, or intraday research chart plus a same-stem component-data sidecar: candlesticks, volume, EMA8/21/55, support/resistance, and swing structure; research mode excludes trade annotations | `python scripts/generate_chart.py --symbol NBIS --mode research --interval 1wk --days 104` |66| `scripts/analyze_zones.py` | Trading-layer entry zones and backtest (win rate/odds/Kelly); must not be used by research-layer `stock-technical-structure` | `python scripts/analyze_zones.py --symbol NBIS --direction long` |6768Utility modules (not called directly): `provider_runtime.py` (explicit dispatch), `data_contract.py` (provenance contract), `security_master.py` (three-layer identity), `snapshot_store.py` (immutable snapshots), `cache_utils.py` (short-term cache), `resample_utils.py` (candlestick resampling), and `technical_indicators.py` (deterministic calculations that consume only normalized OHLCV and never access a data source directly).6970## Recommended combinations by analytical dimension7172- **Fundamentals**: `market_data.py fundamentals` + `market_data.py events` (insiders)73- **News**: `market_data.py news` + `market_data.py events` + `market_data.py earnings-calendar`74- **Earnings period**: `check_earnings_released` + `fetch_earnings_report` + `fetch_earnings_transcript`75- **Sentiment/crowding inputs**: `market_data.py short-interest` + `market_data.py positioning`; Reddit, StockTwits, and 13F remain compatibility entry points. `stock-sentiment-positioning` owns basis distinctions, official-source supplementation, and conclusions.76- **Technicals**: `market_data.py price` + `market_data.py technicals` + weekly and daily `generate_chart.py --mode research` views; trading-layer `analyze_zones` remains a compatibility entry point.77- **Macro backdrop**: `market_data.py macro` + `fetch_polymarket`7879## Sources and acknowledgments8081The scripts originated from the novark market-data toolkit. `fetch_reddit`, `fetch_stocktwits`, and `fetch_polymarket` were adapted from TauricResearch/TradingAgents (Apache-2.0).
arcocodes