Data Providers Reference

All data providers available in Beyond Markets.ai — their tools, parameters, and actual API responses. Status is controlled via tools.json.

Summary

Provider	Module Key	Status	Auth	Cost	Cache TTL	Historical Depth	Tools
SEC 13F Filings	`13f`	✅ enabled	none	Free	24h	Latest complete quarter	1
Alpha Vantage	`alphavantage`	✅ enabled	`ALPHAVANTAGE_API_KEY`	Free	1h	30 days default; full history available	4
Economic Calendar	`economic_calendar`	✅ enabled	none	Free	6h	Current week + look-ahead	2
ETF Flows (ETF.com)	`etf_flows`	✅ enabled	none	Free	4h	Daily/weekly/monthly/YTD	2
FinViz Elite	`finviz`	✅ enabled	`FINVIZ_API_TOKEN`	$39.50/mo (Elite)	—	Per-request	7
FINRA Short Interest	`finra_short`	✅ enabled	none	Free	6–12h	T+1 daily; biweekly official	3
Financial Modeling Prep	`fmp`	✅ enabled	`FMP_API_KEY`	$49/mo (Premium)	Quotes 5 min; financials 24h	Full history from IPO	28
FRED (St. Louis Fed)	`fred`	✅ enabled	`FRED_API_KEY`	Free	30 min–1h	40–80+ years depending on series	14
GDELT	`gdelt`	✅ enabled	none	Free	4h	3-month rolling (default 7 days)	4
iBorrowDesk (short borrow)	`iborrowdesk`	✅ enabled	none	Free	1h	Daily borrow snapshots	2
IMF / ECB / BIS	`imf`	✅ enabled	none	Free	IMF 24h · ECB 1h · BIS 24h	10–20 years; IMF projections to 2031	24
Macro Liquidity Score	`macro_liquidity`	✅ enabled	`FRED_API_KEY` (indirect)	Free	via FRED	~2 years lookback (750 days)	4
NewsAPI.ai (Event Registry)	`newsapi_ai`	✅ enabled	`NEWSAPI_AI_KEY`	$64.75/mo (5K plan)	4h	5–7 year searchable archive	7
NewsData.io	`newsdata`	✅ enabled	`NEWSDATA_API_KEY`	Free	4h	Recent articles only	4
NewsAPI.org	`newsapi`	❌ disabled	`NEWSAPI_ORG_KEY`	Free (Developer)	4h	30 days (free) / 1 year (paid)	10
OpenFIGI	`openfigi`	✅ enabled	`OPENFIGI_API_KEY` (optional)	Free	24h	Current identifiers only	2
Polygon.io	`polygon`	✅ enabled	`POLYGON_API_KEY`	$29/mo (Advanced)	Prev close 1 min; OHLCV 1h; divs 1h	Full OHLCV history + 5-min intraday; extended hours 04:00–20:00 ET	6
Alpaca (market data)	`alpaca_mktdata`	✅ enabled	`ALPACA_API_KEY_PAPER`	Free (data API)	Snapshots real-time; movers 5 min	Intraday + recent only	4
SEC EDGAR	`sec`	✅ enabled	none	Free	24h	5–20+ years of filings	4
Unusual Whales (daily CSVs)	`uw`	✅ enabled	none (CSV snapshots)	$0 extra	Files refreshed daily by scheduler	EOD snapshots	4
EODHD	`eodhd`	✅ enabled	`EODHD_API_KEY`	Paid (Monthly)	Quote 1 min; fundamentals/HV 1h	Full EOD history	4
SEC Failure-to-Deliver	`sec_ftd`	✅ enabled	none	Free	12h	Bimonthly REGSHO files	2
Benzinga	`benzinga`	✅ enabled	`BEZINGA_API_KEY`	Paid	News 5 min; calendar/ratings 30 min	7–90 days look-back	5

SEC 13F Filings

Module: tools/data_ingestion_13f.py · Key: 13f · Status: ✅ enabled
Source: SEC EDGAR (data.sec.gov, efts.sec.gov)
Auth: None
Rate limit: ~8 req/s

Parses 13F-HR quarterly filings from institutional investment managers. Compares current to prior quarter to surface new positions.

`manager_new_positions`

Get institutional fund managers' latest 13F-HR SEC filings. Compares current quarter holdings to prior quarter to identify new positions.

Parameter	Type	Required	Default	Description
`period`	string	no	latest quarter	Quarter-end date `YYYY-MM-DD`
`top_filers`	integer	no	100	Number of 13F filers to analyse (max 500)
`max_results`	integer	no	50	Maximum rows to return

Sample response (top_filers=5, max_results=3):

{
  "managers": [
    {
      "Manager": "SUMMITRY LLC",
      "CIK": "1280043",
      "Period": "2026-03-31",
      "Filed": "2026-05-22",
      "New": 285,
      "Added": 0,
      "Reduced": 0,
      "Closed": 0,
      "Holdings": 285
    },
    {
      "Manager": "Independent Wealth Advisors LLC",
      "CIK": "2136099",
      "Period": "2025-12-31",
      "Filed": "2026-05-22",
      "New": 63,
      "Added": 0,
      "Reduced": 0,
      "Closed": 0,
      "Holdings": 63
    }
  ],
  "popular_assets": [
    { "Name": "APPLE INC",      "CUSIP": "037833100", "Managers": 2 },
    { "Name": "INVESCO QQQ TR", "CUSIP": "46090E103", "Managers": 2 },
    { "Name": "MICROSOFT CORP", "CUSIP": "594918104", "Managers": 2 }
  ]
}

Alpha Vantage

Module: tools/data_ingestion_alphavantage.py · Key: alphavantage · Status: ✅ enabled
Base URL: https://www.alphavantage.co/query
Auth: ALPHAVANTAGE_API_KEY
Rate limit: 1 req/15s (free tier ~4 req/min)

Provides forex, commodity, crypto, and US economic indicator data.

`get_forex_daily`

Daily OHLC exchange rates for a currency pair.

Parameter	Type	Required	Default	Description
`from_symbol`	string	yes	—	Base currency (`EUR`, `GBP`, `JPY`)
`to_symbol`	string	yes	—	Quote currency (`USD`)
`days`	integer	no	30	Days of history

Sample response (EUR/USD, days=3):

{
  "pair": "EUR/USD",
  "latest": 1.1602,
  "period_high": 1.1644,
  "period_low": 1.1575,
  "change_pct": -0.22,
  "prices": [
    { "date": "2026-05-22", "open": 1.1618, "high": 1.1622, "low": 1.1587, "close": 1.1602 },
    { "date": "2026-05-21", "open": 1.1625, "high": 1.1635, "low": 1.1575, "close": 1.1618 },
    { "date": "2026-05-20", "open": 1.1601, "high": 1.1644, "low": 1.1582, "close": 1.1627 }
  ]
}

`get_commodity_prices`

Monthly or quarterly commodity price history.

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	`Gold`, `Silver`, `WTI`, `Brent`, `Natural_Gas`, `Copper`, `Wheat`, `Corn`, `Cotton`, `Sugar`, `Coffee`
`interval`	string	no	`monthly`	`monthly` or `quarterly`

`get_crypto_daily`

Daily OHLCV data for major cryptocurrencies.

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	`BTC`, `ETH`, `SOL`, etc.
`market`	string	no	`USD`	Quote currency
`days`	integer	no	30	Days of history

`get_economic_data`

US economic indicator time series.

Parameter	Type	Required	Default	Description
`indicator`	string	yes	—	`REAL_GDP`, `CPI`, `INFLATION`, `UNEMPLOYMENT`, `FEDERAL_FUNDS_RATE`, `TREASURY_YIELD`
`interval`	string	no	—	`monthly`, `quarterly`, `annual`

Economic Calendar

Module: tools/data_ingestion_economic_calendar.py · Key: economic_calendar · Status: ✅ enabled
Auth: None · Cache TTL: 6h

Scheduled macroeconomic events (CPI, FOMC, NFP, GDP, PPI, etc.) for the current week and a configurable look-ahead window.

`get_economic_calendar`

This week's scheduled macro events.

Parameter	Type	Required	Default	Description
`currency`	string	no	—	Filter by currency, e.g. `USD`
`impact`	string	no	—	`high`, `medium`, `low`

`get_upcoming_events`

Next scheduled high-impact macro events within a look-ahead window.

Parameter	Type	Required	Default	Description
`hours_ahead`	integer	no	—	Look-ahead window in hours
`currency`	string	no	—	Filter by currency
`high_impact_only`	boolean	no	—	Only high-impact events

FinViz Elite

Module: tools/data_ingestion_finviz.py · Key: finviz · Status: ✅ enabled
Base URL: https://elite.finviz.com
Auth: FINVIZ_API_TOKEN
Rate limit: Token bucket (1/s, burst 5)

Stock screener, price history, sector performance, options, SEC filings, news, and portfolio data.

`screener`

Run the FinViz stock screener with filters, signals, and sorting.

Parameter	Type	Required	Default	Description
`filters`	string	no	—	Comma-separated FinViz filter codes (e.g. `cap_largeover,sec_technology`)
`view`	string	no	`111`	`111` Overview · `121` Valuation · `131` Ownership · `141` Performance · `161` Financial · `171` Technical
`order`	string	no	—	Sort column (`marketcap`, `pe`, `change`, `volume`)
`signal`	string	no	—	`ta_topgainers`, `ta_toplosers`, `ta_newhigh`, `ta_newlow`, `ta_mostvolatile`, `ta_mostactive`, `ta_unusualvolume`, `ta_overbought`, `ta_oversold`, `ta_downgrades`, `ta_upgrades`, `ta_earnings`, `ta_recentinsiderbuying`, `ta_recentinsiderselling`
`max_rows`	integer	no	200	Maximum results

Sample response (signal=ta_topgainers, max_rows=3):

[
  { "No.": "1", "Ticker": "AKTX", "Company": "Akari Therapeutics Plc ADR",
    "Sector": "Healthcare", "Industry": "Biotechnology", "Country": "USA",
    "Market Cap": "20.83", "Price": "18.27", "Change": "255.45%", "Volume": "34043144" },
  { "No.": "2", "Ticker": "PCLA", "Company": "PicoCELA Inc ADR",
    "Sector": "Communication Services", "Industry": "Telecom Services", "Country": "Japan",
    "Market Cap": "229.18", "Price": "6.62", "Change": "194.22%", "Volume": "37042732" },
  { "No.": "3", "Ticker": "RYOJ", "Company": "rYojbaba Co Ltd",
    "Sector": "Industrials", "Industry": "Consulting Services", "Country": "Japan",
    "Market Cap": "57.75", "Price": "5.00", "Change": "148.76%", "Volume": "41283106" }
]

`quote_history`

Historical OHLCV price data.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	Stock symbol (e.g. `AAPL`)
`timeframe`	string	no	`d`	`d` daily · `w` weekly · `m` monthly
`date_from`	string	no	—	`YYYY-MM-DD`
`date_to`	string	no	—	`YYYY-MM-DD`

`group_performance`

Sector, industry, or country performance aggregates.

Parameter	Type	Required	Default	Description
`group`	string	no	`sector`	`sector`, `industry`, `country`, `capitalization`
`view`	string	no	`110`	`110` overview · `120` valuation · `130` performance
`order`	string	no	—	Sort column

`options_screen`

Options chain data with strike, bid/ask, volume, open interest, IV.

Parameter	Type	Required	Default
`filters`	string	no	—
`max_rows`	integer	no	200

`latest_filings`

Latest SEC filings for a ticker.

Parameter	Type	Required	Default
`ticker`	string	yes	—
`filters`	string	no	—
`max_rows`	integer	no	200

`news`

Financial news headlines.

Parameter	Type	Required	Default
`filters`	string	no	—
`max_rows`	integer	no	200

`portfolio`

Export portfolio holdings with current prices and gains.

Parameter	Type	Required	Default
`pid`	string	no	—
`order`	string	no	—

Financial Modeling Prep (FMP)

Module: tools/data_ingestion_fmp.py · Key: fmp · Status: ✅ enabled
Base URL: https://financialmodelingprep.com/mcp (via fastmcp)
Auth: FMP_API_KEY

Comprehensive equity data: quotes, financials, analyst data, insider trades, congressional trades, news, macro indicators, and screening.

`get_stock_quote`

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	Stock ticker
`short`	boolean	no	false	Return minimal quote only

Sample response (AAPL, short=true):

{ "symbol": "AAPL", "price": 308.82, "change": 3.83, "volume": 43605063 }

`get_batch_quotes`

Parameter	Type	Required	Description
`symbols`	array[string]	yes	List of tickers

`get_price_history`

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	—
`endpoint`	string	no	`historical-price-eod-light`	`historical-price-eod-light`, `historical-price-eod-full`, `historical-price-eod-dividend-adjusted`, `historical-price-eod-non-split-adjusted`
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	`YYYY-MM-DD`

`get_intraday_prices`

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	—
`interval`	string	no	`intraday-1-hour`	`intraday-1-min`, `intraday-5-min`, `intraday-15-min`, `intraday-30-min`, `intraday-1-hour`, `intraday-4-hour`
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	`YYYY-MM-DD`

`get_company_profile`

Parameter	Type	Required
`symbol`	string	yes

`get_financial_statements`

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	—
`period`	string	no	`annual`	`annual` or `quarter`
`limit`	integer	no	4	Number of periods

`get_key_metrics`

Parameter	Type	Required	Default
`symbol`	string	yes	—
`ttm`	boolean	no	true

`get_financial_ratios`

Parameter	Type	Required	Default
`symbol`	string	yes	—
`ttm`	boolean	no	true

`get_analyst_data`

Parameter	Type	Required
`symbol`	string	yes

`get_sec_filings`

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	—
`form_type`	string	no	—	`10-K`, `10-Q`, `8-K`
`limit`	integer	no	10	—

`get_insider_trades`

Parameter	Type	Required	Default
`symbol`	string	yes	—
`limit`	integer	no	20

`get_congressional_trades`

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	—
`chamber`	string	no	`both`	`senate`, `house`, `both`
`limit`	integer	no	20	—

`get_news`

Parameter	Type	Required	Default	Description
`symbols`	array[string]	no	—	Omit for general market news
`limit`	integer	no	20	—
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	`YYYY-MM-DD`

`get_market_movers`

Parameter	Type	Required	Default	Description
`mover_type`	string	no	`biggest-gainers`	`biggest-gainers`, `biggest-losers`, `most-active`

`get_sector_performance`

Parameter	Type	Required	Description
`date`	string	no	`YYYY-MM-DD`; omit for latest

`get_economic_indicator`

Parameter	Type	Required	Description
`name`	string	yes	`GDP`, `CPI`, `unemploymentRate`, `federalFunds`, `retailSales`, `consumerSentiment`, `industrialProductionTotalIndex`
`from_date`	string	no	`YYYY-MM-DD`
`to_date`	string	no	`YYYY-MM-DD`

`get_treasury_rates`

Parameter	Type	Required
`from_date`	string	no
`to_date`	string	no

`get_dcf_valuation`

Parameter	Type	Required	Default
`symbol`	string	yes	—
`levered`	boolean	no	false

`get_esg`

Parameter	Type	Required
`symbol`	string	yes

`get_technical_indicator`

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	—
`indicator`	string	no	`simple-moving-average`	`simple-moving-average`, `exponential-moving-average`, `double-exponential-moving-average`, `triple-exponential-moving-average`, `weighted-moving-average`, `relative-strength-index`, `average-directional-index`, `williams`, `standard-deviation`
`period_length`	integer	no	20	Look-back periods
`timeframe`	string	no	`1day`	`1min`, `5min`, `15min`, `30min`, `1hour`, `4hour`, `1day`
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	`YYYY-MM-DD`

`screen_stocks`

Parameter	Type	Required	Default	Description
`sector`	string	no	—	—
`industry`	string	no	—	—
`country`	string	no	—	—
`exchange`	string	no	—	`NYSE`, `NASDAQ`
`market_cap_more_than`	number	no	—	USD
`market_cap_lower_than`	number	no	—	USD
`price_more_than`	number	no	—	—
`price_lower_than`	number	no	—	—
`volume_more_than`	number	no	—	—
`limit`	integer	no	50	—

`get_company_research_bundle`

Fetches all equity research data in one call: profile, quote, peers, financials, metrics, ratios, analyst, DCF, ESG, insider stats, news.

Parameter	Type	Required	Default
`symbol`	string	yes	—
`periods`	integer	no	3

`get_quote_l1` / `get_batch_quotes_l1`

Level-1 (NBBO bid/ask) quote for a single ticker / list of tickers.

Parameter	Type	Required	Description
`symbol` / `symbols`	string / array[string]	yes	Ticker or list of tickers

`get_aftermarket_quote` / `get_batch_aftermarket_quotes`

After-hours (post-close) quote for a single ticker / list of tickers.

Parameter	Type	Required	Description
`symbol` / `symbols`	string / array[string]	yes	Ticker or list of tickers

`get_earnings_calendar`

Upcoming earnings dates across the market.

Parameter	Type	Required	Default	Description
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	`YYYY-MM-DD`
`limit`	integer	no	—	Max rows

`get_earnings_by_company`

Earnings history (estimate vs actual, surprise) for one ticker.

Parameter	Type	Required	Default
`symbol`	string	yes	—
`limit`	integer	no	—

FRED (St. Louis Federal Reserve)

Module: tools/data_ingestion_fred.py · Key: fred · Status: ✅ enabled
Base URL: https://api.stlouisfed.org/fred
Auth: FRED_API_KEY

Access to 800,000+ US and international economic time series.

`search_series`

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Keywords (e.g. `consumer price index`)
`limit`	integer	no	20	—
`order_by`	string	no	`popularity`	`popularity`, `search_rank`, `last_updated`

`get_series_info`

Parameter	Type	Required	Description
`series_id`	string	yes	FRED series ID (e.g. `UNRATE`, `GDP`, `DGS10`)

`get_series`

Fetch observations for any FRED series. Common IDs: GDP, GDPC1, CPIAUCSL, UNRATE, FEDFUNDS, DGS10, T10Y2Y, BAMLH0A0HYM2, SP500, VIXCLS.

Parameter	Type	Required	Default	Description
`series_id`	string	yes	—	FRED series ID
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	`YYYY-MM-DD`
`limit`	integer	no	100	—
`sort_order`	string	no	`desc`	`desc` or `asc`
`units`	string	no	—	Transformation: `lin`, `chg`, `ch1`, `pch`, `pc1`, `pca`, `log`
`frequency`	string	no	—	Aggregation: `d`, `w`, `m`, `q`, `a`

`get_inflation`

CPI year-over-year % change.

Parameter	Type	Required	Default	Description
`measure`	string	no	`cpi`	`cpi`, `cpi_core`, `pce`, `pce_core`, `ppi`
`from_date`	string	no	—	—
`limit`	integer	no	60	—
`yoy`	boolean	no	true	Year-over-year % change

Sample response (limit=3):

[
  { "date": "2026-04-01", "value": 3.77925 },
  { "date": "2026-03-01", "value": 3.28596 },
  { "date": "2026-02-01", "value": 2.434 }
]

`get_gdp`

Parameter	Type	Required	Default	Description
`real`	boolean	no	true	Real GDP (chained 2017 USD) if true, nominal if false
`from_date`	string	no	—	—
`limit`	integer	no	40	Quarters

`get_labor_market`

Parameter	Type	Required	Default
`from_date`	string	no	—
`limit`	integer	no	60

`get_interest_rates`

Parameter	Type	Required	Default
`from_date`	string	no	—
`limit`	integer	no	252

`get_credit_conditions`

Parameter	Type	Required	Default
`from_date`	string	no	—
`limit`	integer	no	252

`get_housing`

Parameter	Type	Required	Default
`from_date`	string	no	—
`limit`	integer	no	60

`get_consumer_indicators`

Parameter	Type	Required	Default
`from_date`	string	no	—
`limit`	integer	no	60

`get_money_supply`

Parameter	Type	Required	Default
`from_date`	string	no	—
`limit`	integer	no	60

`get_market_indicators`

Parameter	Type	Required	Default
`from_date`	string	no	—
`limit`	integer	no	252

`get_macro_snapshot`

Comprehensive macro snapshot covering GDP, CPI, core PCE, labor market, interest rates, credit conditions, housing, consumer indicators, money supply, and market indicators in one call.

Parameter	Type	Required	Description
`from_date`	string	no	Limits all series to this start date

`get_category_series`

Parameter	Type	Required	Default	Description
`category_id`	integer	yes	—	Common: `32991` Money & Banking · `32992` National Accounts · `32455` Prices · `10` Labor Market · `32213` Interest Rates · `97` Business Cycles
`limit`	integer	no	30	—

GDELT

Module: tools/data_ingestion_gdelt.py · Key: gdelt · Status: ✅ enabled
Base URL: https://api.gdeltproject.org/api/v2/doc/doc
Auth: None (free)
Rate limit: 1 req/8s

Global news database covering 65 languages and 150+ countries with sentiment scoring.

`search_gdelt_news`

Full-text search across global news articles.

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Supports `"exact phrase"`, `(a OR b)`, `-exclude`
`language`	string	no	`english`	Source language
`country`	string	no	—	Source country (e.g. `China`, `Germany`)
`domain`	string	no	—	e.g. `reuters.com`
`tone`	string	no	—	`>5` positive · `<-5` negative
`timespan`	string	no	`7d`	`24h`, `7d`, `2w`, `1m`
`max_records`	integer	no	20	Max articles (1–75)
`sort`	string	no	`DateDesc`	`DateDesc`, `DateAsc`, `ToneDesc`, `ToneAsc`, `HybridRel`

Sample response (query="Federal Reserve interest rates", timespan="7d", max_records=2):

[
  {
    "title": "Warsh Fed 'regime change' may require patience, consensus",
    "url": "https://www.eastbaytimes.com/2026/05/23/warshs-fed-regime-change-may-require-patience-consensus-3/",
    "date": "20260523T204500Z",
    "domain": "eastbaytimes.com",
    "language": "English",
    "source_country": "United States"
  },
  {
    "title": "26.5% MPR Stays as CBN Walks Inflation-Stability Line",
    "url": "https://promptnewsonline.com/26-5-mpr-stays-as-cbn-walks-inflation-stability-line-by-demola-bakare/",
    "date": "20260523T191500Z",
    "domain": "promptnewsonline.com",
    "language": "English",
    "source_country": "Nigeria"
  }
]

`get_gdelt_sentiment`

Sentiment (tone) timeline for a topic. Positive > 0, negative < 0.

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Topic to track
`language`	string	no	`english`	—
`timespan`	string	no	`7d`	—

`get_gdelt_coverage_volume`

Article volume timeline — how many articles mention a topic over time.

Parameter	Type	Required	Default
`query`	string	yes	—
`language`	string	no	`english`
`timespan`	string	no	`7d`

`get_gdelt_geo_news`

News originating from a specific country.

Parameter	Type	Required	Default	Description
`query`	string	yes	—	—
`country`	string	yes	—	e.g. `China`, `Russia`, `India`
`language`	string	no	`english`	—
`timespan`	string	no	`7d`	—
`max_records`	integer	no	20	1–75

IMF / ECB / BIS

Module: tools/data_ingestion_imf.py · Key: imf · Status: ✅ enabled
Sources: IMF DataMapper (imf.org), ECB Statistical Data Warehouse, BIS Statistics
Auth: None

24 tools spanning IMF World Economic Outlook projections, ECB monetary data, and BIS financial stability indicators.

IMF Tools

`get_imf_indicators`

List all available WEO indicators with codes, labels, units. No parameters.

`get_imf_countries`

List all countries and regions available in IMF DataMapper. No parameters.

`get_imf_indicator`

Fetch annual WEO data for any indicator across countries. Includes IMF projections through 2031.

Parameter	Type	Required	Default	Description
`indicator`	string	yes	—	WEO code: `NGDPD` (GDP USD), `NGDP_RPCH` (GDP growth%), `PCPIPCH` (inflation), `LUR` (unemployment), `GGXWDG_NGDP` (debt/GDP), `BCA_NGDPD` (current account/GDP)
`countries`	array[string]	no	G20	ISO-3 codes (e.g. `USA`, `DEU`, `CHN`)

`get_imf_gdp`

Parameter	Type	Required	Default	Description
`countries`	array[string]	no	G20	ISO-3 codes
`real_growth`	boolean	no	true	`true` = real GDP growth %; `false` = nominal GDP USD

Sample response (countries=["USA","DEU","CHN"], real_growth=true, truncated):

{
  "USA": [
    { "year": 2020, "value": -2.1 },
    { "year": 2021, "value": 6.2 },
    { "year": 2022, "value": 2.5 },
    { "year": 2023, "value": 2.9 },
    { "year": 2024, "value": 2.8 },
    { "year": 2025, "value": 2.1 },
    { "year": 2026, "value": 2.3 }
  ],
  "DEU": [ "..." ],
  "CHN": [ "..." ]
}

`get_imf_inflation`

Annual CPI inflation by country. Parameters: countries (ISO-3 array).

`get_imf_unemployment`

Annual unemployment rate by country. Parameters: countries (ISO-3 array).

`get_imf_fiscal`

Government fiscal balance and gross debt (% of GDP). Parameters: countries (ISO-3 array).

`get_imf_current_account`

Current account balance (% of GDP). Parameters: countries (ISO-3 array).

`get_imf_country_snapshot`

All key WEO indicators for a single country. Parameters: country (ISO-3, required).

`get_imf_global_outlook`

Multi-country macro outlook: GDP growth, inflation, unemployment, fiscal balance, current account. Parameters: countries (ISO-3 array).

ECB Tools

`get_ecb_fx_rates`

EUR exchange rates.

Parameter	Type	Required	Default	Description
`currencies`	string	no	`USD+GBP+JPY+CHF+CNY`	`+`-separated ECB codes
`frequency`	string	no	—	`D` (daily) or `M` (monthly)
`start_period`	string	no	—	`YYYY` or `YYYY-MM`
`end_period`	string	no	—	—

`get_ecb_inflation`

HICP inflation. U2 = Euro area; individual codes: DE, FR, IT, ES.

`get_ecb_yield_curve`

Euro area AAA government bond yield curve (Svensson model). Maturities: SR_3M, SR_1Y, SR_2Y, SR_5Y, SR_10Y, SR_30Y.

`get_ecb_estr`

Euro short-term rate (€STR) — ECB's benchmark overnight rate.

`get_ecb_bank_lending`

Euro area bank lending volumes to non-financial corporations (monthly).

`get_ecb_snapshot`

All ECB data in one call: FX rates, HICP inflation, yield curve, €STR, bank lending.

BIS Tools

`get_bis_policy_rates`

Central bank policy rates (monthly). Parameters: countries (ISO-2 array), start_period, end_period.

`get_bis_eer`

Real effective exchange rates — trade-weighted, inflation-adjusted. Parameters: countries (ISO-2 array).

`get_bis_credit_gap`

Credit-to-GDP gaps — key financial stability indicator. Parameters: countries (ISO-2 array).

`get_bis_debt_service`

Debt service ratios — share of income used for debt payments. Parameters: countries (ISO-2 array).

`get_bis_total_credit`

Total credit to private non-financial sector as % of GDP. Parameters: countries (ISO-2 array).

`get_bis_property_prices`

Residential property prices (real, indexed, quarterly). Parameters: countries (ISO-2 array).

`get_bis_snapshot`

All BIS data in one call: policy rates, EER, credit gaps, debt service, total credit, property prices.

Combined

`get_global_macro_snapshot`

IMF + ECB + BIS in one call.

Parameter	Type	Required	Description
`countries_imf`	array[string]	no	ISO-3 codes for IMF queries
`countries_bis`	array[string]	no	ISO-2 codes for BIS queries
`start_period`	string	no	—
`end_period`	string	no	—

Macro Liquidity Score

Module: tools/macro_liquidity.py · Key: macro_liquidity · Status: ✅ enabled
Source: Computed from FRED series (indirect)
Auth: FRED_API_KEY (via FRED module)
Lookback: ~2 years (750 calendar days)

Composite liquidity scoring model with four weighted pillars: real_rate_impulse (35%), cb_balance_sheet (25%), credit_impulse (25%), funding_stress (15%).

`get_liquidity_regime`

Classify current liquidity regime without full score detail. Lighter-weight.

Parameter	Type	Required	Default
`region`	string	no	`US`

Sample response:

{
  "regime": "mild_expansion",
  "composite_score": 0.503,
  "description": "Liquidity is expanding modestly. Easing financial conditions support risk assets. Look for rotation into higher-beta.",
  "component_scores": {
    "real_rate_impulse": -0.299,
    "cb_balance_sheet": 1.224,
    "credit_impulse": 0.699,
    "funding_stress": 0.845
  }
}

Regimes: severe_tightening · tightening · neutral · mild_expansion · strong_expansion

`get_macro_liquidity_score`

Full composite score with z-scores and raw values per component.

Parameter	Type	Required	Default	Description
`region`	string	no	`US`	Currently US only
`lookback_days`	integer	no	750	Lookback window in calendar days

`explain_liquidity_for_asset`

Liquidity regime implications for a specific asset class.

Parameter	Type	Required	Description
`asset_class`	string	yes	`equities`, `bonds`, `commodities`, `crypto`
`region`	string	no	`US`

`generate_macro_liquidity_report`

Comprehensive report with full component breakdown, asset class implications, and methodology notes.

Parameter	Type	Required
`region`	string	no

NewsAPI.ai (Event Registry)

Module: tools/data_ingestion_newsapi_ai.py · Key: newsapi_ai · Status: ✅ enabled
Base URL: https://eventregistry.org/api/v1
Auth: NEWSAPI_AI_KEY
Rate limit: Token bucket (1/2s, burst 5)

150,000+ global news sources with sentiment scores on every article.

Sentiment scores

Every article returned by NewsAPI.ai includes a sentiment field in the range −1.0 to +1.0:

Range	Meaning
`> 0.3`	Positive — optimistic or favourable tone
`−0.3 to 0.3`	Neutral — factual or balanced reporting
`< −0.3`	Negative — pessimistic, critical, or alarming tone

The score reflects the language of the article, not the underlying financial event. A stock crash can score near zero if the journalist writes in a dry, factual style; a positive development can score negatively if the article is sceptical. Use it to detect sentiment shifts in coverage of a company or topic over time, not as a standalone buy/sell signal.

Example:

{ "title": "Hyperscaler Debt Flood Brings Derivatives Bonanza", "sentiment": 0.2 }
{ "title": "Reddit stock drops 6% after Meta launches standalone app", "sentiment": 0.08 }

Both are near-neutral: the first leans slightly positive ("bonanza" framing), the second is matter-of-fact despite reporting a decline.

`search_news`

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Supports OR operator
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	`YYYY-MM-DD`
`language`	string	no	`eng`	3-letter: `eng`, `deu`, `fra`, `spa`, `zho`, `jpn`
`sort_by`	string	no	`date`	`date`, `rel`, `socialScore`
`page_size`	integer	no	20	Max 100
`min_sentiment`	number	no	—	−1.0 to 1.0
`max_sentiment`	number	no	—	−1.0 to 1.0

`get_market_news`

Stock market and financial news from major outlets.

Parameter	Type	Required	Default
`from_date`	string	no	—
`to_date`	string	no	—
`page_size`	integer	no	20

Sample response (page_size=2):

[
  {
    "title": "Hyperscaler Debt Flood Brings Derivatives Bonanza",
    "url": "https://www.bloomberg.com/news/articles/2026-05-23/...",
    "date": "2026-05-23T19:00:00Z",
    "source": "Bloomberg Business",
    "source_uri": "bloomberg.com",
    "language": "eng",
    "sentiment": 0.2,
    "description": "Demand for hyperscaler CDS is driving up prices..."
  },
  {
    "title": "Reddit stock drops 6% after Meta launches standalone app",
    "url": "https://www.wsj.com/...",
    "date": "2026-05-23T18:00:00Z",
    "source": "The Wall Street Journal",
    "source_uri": "wsj.com",
    "sentiment": 0.08
  }
]

`get_company_news`

Parameter	Type	Required	Default	Description
`company`	string	yes	—	Company name or ticker
`from_date`	string	no	—	—
`to_date`	string	no	—	—
`page_size`	integer	no	20	—

`get_macro_news`

GDP, inflation, employment, central banks, interest rates, trade. Parameters: from_date, to_date, page_size.

`get_geopolitical_news`

Sanctions, tariffs, trade wars, conflicts, embargoes. Parameters: from_date, to_date, page_size.

`get_central_bank_news`

Fed, ECB, BoE, BoJ, PBOC, rate decisions. Parameters: from_date, to_date, page_size.

`get_finance_news_snapshot`

All categories fired concurrently: market, macro, central bank, geopolitical. Parameters: from_date, to_date.

NewsData.io

Module: tools/data_ingestion_newsdata.py · Key: newsdata · Status: ✅ enabled
Base URL: https://newsdata.io/api/1/
Auth: NEWSDATA_API_KEY
Rate limit: 1 req/5s

89 languages, 200+ countries, AI-powered sentiment (Professional/Corporate plan required for sentiment values).

`search_newsdata`

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Supports `AND`, `OR`, `NOT`, exact phrases
`language`	string	no	`en`	ISO language code
`country`	string	no	—	Lowercase ISO 3166
`category`	string	no	`business`	`business`, `economics`, `entertainment`, `environment`, `food`, `health`, `politics`, `science`, `sports`, `technology`, `top`, `world`
`domain`	string	no	—	e.g. `reuters.com`
`sentiment`	string	no	—	`positive`, `neutral`, `negative` (paid plan)
`timeframe`	string	no	—	Minutes (1–2880) or hours (1–48)
`max_records`	integer	no	20	1–50

Sample response (query="S&P 500", max_records=2):

[
  {
    "title": "Financial Comparison: Ballard Power Systems vs. Avista",
    "url": "https://www.watchlistnews.com/...",
    "date": "2026-05-23 10:01:33",
    "source": "watchlistnews",
    "country": ["united states of america"],
    "language": "english",
    "sentiment": "ONLY AVAILABLE IN PROFESSIONAL AND CORPORATE PLANS",
    "description": "..."
  }
]

`get_newsdata_market`

Financial and market news with richer financial metadata.

Parameter	Type	Required	Default
`query`	string	yes	—
`language`	string	no	`en`
`country`	string	no	—
`max_records`	integer	no	20

`get_newsdata_crypto`

Cryptocurrency and blockchain news.

Parameter	Type	Required	Default
`query`	string	yes	—
`language`	string	no	`en`
`max_records`	integer	no	20

`get_newsdata_sources`

List available news sources.

Parameter	Type	Required	Description
`country`	string	no	Country code
`language`	string	no	Language code
`category`	string	no	e.g. `business`

NewsAPI.org ❌ disabled

Module: tools/data_ingestion_newsapi.py · Key: newsapi · Status: ❌ disabled
Base URL: https://newsapi.org/v2
Auth: NEWSAPI_ORG_KEY
Rate limit: Token bucket (1/2s, burst 5); free tier ~100 req/24h

Disabled in tools.json. Enable by setting "newsapi": { "enabled": true }.
The API still works when called directly — sample response below was captured live.

`search_news`

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Supports `"exact"`, `+required`, `-excluded`, `AND`/`OR`/`NOT`
`from_date`	string	no	—	`YYYY-MM-DD`
`to_date`	string	no	—	—
`domains`	string	no	—	e.g. `reuters.com,bloomberg.com`
`exclude_domains`	string	no	—	—
`language`	string	no	`en`	ISO-639-1
`sort_by`	string	no	`publishedAt`	`publishedAt`, `relevancy`, `popularity`
`page_size`	integer	no	20	Max 100
`page`	integer	no	1	—

Sample response (get_market_news, page_size=2):

[
  {
    "title": "Qualcomm's stock pop shows investors are 'waking up' to boom in AI devices",
    "source": "CNBC",
    "author": "Katie Tarasov",
    "date": "2026-05-22T20:52:39Z",
    "description": "Qualcomm is on a big run, powered by investor bullishness that the company will be at the center of a boom in AI devices.",
    "url": "https://www.cnbc.com/2026/05/22/qualcomms-stock-pop-shows-investors-waking-up-to-boom-in-ai-devices.html"
  },
  {
    "title": "Reddit stock drops 6% after Meta launches standalone app for online forums",
    "source": "CNBC",
    "author": "Jonathan Vanian",
    "date": "2026-05-22T18:34:57Z",
    "description": "Reddit shares fell after Meta released a standalone app for Facebook Groups called Forum.",
    "url": "https://www.cnbc.com/2026/05/22/reddit-stock-drops-after-meta-launches-forum-app.html"
  }
]

`get_top_headlines`

Parameter	Type	Required	Description
`country`	string	no	ISO 3166-1 (e.g. `us`, `gb`). Cannot combine with `sources`.
`category`	string	no	`business`, `entertainment`, `general`, `health`, `science`, `sports`, `technology`
`query`	string	no	Optional keyword filter
`sources`	string	no	Comma-separated source IDs. Cannot combine with `country`/`category`.
`page_size`	integer	no	—

`get_business_headlines`

Top business headlines for a country. Parameters: country (default us), query, page_size.

`get_market_news`

Market news from Reuters, Bloomberg, FT, CNBC, WSJ. Parameters: from_date, to_date, page_size.

`get_company_news`

News about a specific company. Parameters: company (required), from_date, to_date, page_size.

`get_macro_news`

GDP, inflation, employment, central banks, trade. Parameters: from_date, to_date, page_size.

`get_geopolitical_news`

Sanctions, tariffs, trade wars, conflicts. Parameters: from_date, to_date, page_size.

`get_central_bank_news`

Fed, ECB, BoE, BoJ, PBOC. Parameters: from_date, to_date, page_size.

`get_news_sources`

List available sources. Parameters: category, language, country.

`get_finance_news_snapshot`

All finance news categories fired concurrently. Parameters: from_date, to_date.

OpenFIGI

Module: tools/data_ingestion_openfigi.py · Key: openfigi · Status: ✅ enabled
Base URL: https://api.openfigi.com/v3/
Auth: OPENFIGI_API_KEY (optional; free key at openfigi.com improves rate limits)
Rate limit: 1 req/3s

Maps tickers, ISINs, CUSIPs, and SEDOLs to Bloomberg FIGI global identifiers.

`map_identifiers`

Parameter	Type	Required	Description
`identifiers`	array[object]	yes	List of identifiers to map (max 10 without key, 100 with). Each: `id_type` (`TICKER`, `ID_ISIN`, `ID_CUSIP`, `ID_SEDOL`) + `id_value`
`exchange`	string	no	Exchange filter (e.g. `XNAS` NASDAQ, `XNYS` NYSE)

Sample response (AAPL TICKER, first 2 of 6 results):

[
  {
    "figi": "BBG000B9XRY4",
    "name": "APPLE INC",
    "ticker": "AAPL",
    "exchange": "US",
    "market": "Equity",
    "security_type": "Common Stock",
    "composite_figi": "BBG000B9XRY4"
  },
  {
    "figi": "BBG000B9XSK7",
    "name": "APPLE INC",
    "ticker": "AAPL",
    "exchange": "UA",
    "market": "Equity",
    "security_type": "Common Stock",
    "composite_figi": "BBG000B9XRY4"
  }
]

`search_figi`

Search for financial instruments by company name or keyword.

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Company name or keyword
`exchange`	string	no	—	e.g. `XNAS`, `XNYS`
`max_records`	integer	no	10	1–100

SEC EDGAR

Module: tools/data_ingestion_sec.py · Key: sec · Status: ✅ enabled
Sources: data.sec.gov, efts.sec.gov, www.sec.gov
Auth: None
Rate limit: ~6–7 req/s

Direct access to SEC filings and XBRL financial data. Authoritative source.

`get_sec_company_facts`

All XBRL financial facts for a company: Revenue, Net Income, Assets, EPS across recent fiscal years.

Parameter	Type	Required
`ticker`	string	yes

`get_sec_submissions`

Filing history with dates, form types, and direct document links.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	—
`form_type`	string	no	—	`10-K`, `10-Q`, `8-K`
`max_records`	integer	no	20	—

Sample response (AAPL, form_type=10-K, max_records=2):

{
  "company": "Apple Inc.",
  "cik": "0000320193",
  "sic": "3571",
  "sic_description": "Electronic Computers",
  "state": "CA",
  "filings": [
    {
      "form": "10-K",
      "date": "2025-10-31",
      "accession": "0000320193-25-000079",
      "description": "10-K",
      "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927.htm"
    },
    {
      "form": "10-K",
      "date": "2024-11-01",
      "accession": "0000320193-24-000123",
      "description": "10-K",
      "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019324000123/aapl-20240928.htm"
    }
  ]
}

`get_sec_concept`

Single financial metric across all periods. Good for tracking Revenue, NetIncomeLoss, Assets over time with exact filing sources.

Parameter	Type	Required	Description
`ticker`	string	yes	—
`concept`	string	yes	XBRL concept: `Revenues`, `NetIncomeLoss`, `Assets`, `EarningsPerShareDiluted`

`search_sec_filings`

Full-text search across all SEC filings. Useful for topics like climate risk, supply chain disruption, artificial intelligence.

Parameter	Type	Required	Default	Description
`query`	string	yes	—	Search keywords
`form_type`	string	no	—	`10-K`, `8-K`, etc.
`max_records`	integer	no	20	1–100

Unusual Whales (daily CSV snapshots)

Module: tools/data_ingestion_external_data.py · Key: uw · Status: ✅ enabled
Source: Unusual Whales end-of-day CSV snapshots (refreshed daily by the scheduler)
Auth: None (reads local CSV snapshots)

Options-flow and dark-pool signals sourced from daily CSV exports rather than the live API. Useful for detecting smart-money positioning: large call sweeps signal bullish bets, large put buys signal hedging or bearish conviction.

Note: the former live-API module (data_ingestion_unusualwhales.py, key unusualwhales, with uw_* tools) has been removed. This uw module (ext_* tools) is the current source.

`ext_get_options_flow`

Largest unusual options trades for a ticker from today's EOD report, sorted by total premium.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	Stock ticker, e.g. `PANW`
`limit`	integer	no	50	Max trades
`is_call`	boolean	no	—	Calls only
`is_put`	boolean	no	—	Puts only
`is_otm`	boolean	no	—	Out-of-the-money only

`ext_get_oi_changes`

Largest open-interest changes in a stock's options chain today. Rising OI confirms new positioning behind a move.

Parameter	Type	Required	Default	Description
`ticker`	string	no	—	Stock ticker; omit for top movers market-wide
`side`	string	no	—	`bullish` or `bearish`
`top_n`	integer	no	20	Number of results

`ext_get_options_screener`

Options-market metrics from today's snapshot. Omit the ticker for market-wide top movers.

Parameter	Type	Required	Default	Description
`ticker`	string	no	—	Optional ticker filter
`top_n`	integer	no	20	Number of results

`ext_get_dark_pool`

Dark pool (off-exchange) trade data from today's EOD report. Large prints can signal institutional accumulation or distribution.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	Stock ticker, e.g. `SPY`
`top_n`	integer	no	20	Number of results

iBorrowDesk (Short Borrow)

Module: tools/data_ingestion_iborrowdesk.py · Key: iborrowdesk · Status: ✅ enabled
Auth: None · Cache TTL: ~1h

Daily short-borrow data: cost-to-borrow rate and availability — a high or rising borrow fee signals short-squeeze pressure / hard-to-borrow status.

`get_short_borrow_data`

Daily short borrow history for a single stock (cost-to-borrow %, fee trend, availability).

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	US stock ticker
`days`	integer	no	—	Days of history

`get_batch_short_borrow`

Latest short-borrow snapshot for multiple stocks in one call.

Parameter	Type	Required	Default	Description
`symbols`	array[string]	yes	—	US stock tickers
`days`	integer	no	—	Days of history

ETF Flows (ETF.com)

Module: tools/data_ingestion_etf_flows.py · Key: etf_flows · Status: ✅ enabled
Source: ETF.com public pages (scraped)
Auth: None
Rate limit: 1 req/2s
Cache TTL: 4 hours

Provides daily/weekly/monthly/YTD ETF fund flow data (net inflows and outflows) and top-flow rankings. Data updates once daily after market close.

`etf_get_flows`

Get fund flow data for a specific ETF.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	ETF ticker, e.g. `SPY`, `QQQ`, `XLK`, `GLD`
`period`	string	no	`monthly`	`daily`, `weekly`, `monthly`, `ytd`, `1year`

Sample response (SPY, monthly):

{
  "ticker": "SPY",
  "period": "monthly",
  "net_flow_usd": 4230000000.0,
  "aum_usd": 615000000000.0,
  "flow_as_pct_aum": 0.6878,
  "source": "https://www.etf.com/SPY",
  "note": "Scraped from ETF.com; inflow/outflow breakdown not separately available."
}

`etf_get_top_flows`

Get the top ETFs by net inflow or outflow.

Parameter	Type	Required	Default	Description
`period`	string	no	`monthly`	`daily`, `weekly`, `monthly`, `ytd`
`direction`	string	no	`inflow`	`inflow` or `outflow`
`limit`	integer	no	20	Max ETFs to return (max 50)

FINRA Short Interest

Module: tools/data_ingestion_finra_short.py · Key: finra_short · Status: ✅ enabled
Source: FINRA REGSHO public files (cdn.finra.org)
Auth: None
Rate limit: Conservative (public CDN)
Cache TTL: Daily short volume 6h; biweekly short interest 12h

Two official FINRA public datasets. Daily short volume is published T+1. Biweekly short interest is published ~4 business days after each settlement date (twice per month).

Daily file URL: https://cdn.finra.org/equity/regsho/daily/CNMSshvol{YYYYMMDD}.txt
Columns: Date|Symbol|ShortVolume|ShortExemptVolume|TotalVolume|Market
Biweekly file URL: https://cdn.finra.org/equity/regsho/biweekly/FNRAshvol{YYYYMMDD}.txt
Columns: Date|Symbol|ShortInterest|SettlementDate|...

The module auto-discovers the most recent available file by checking back up to 7 trading days.

`finra_short_volume`

Daily short sale volume ratio for one or more symbols. Short volume ratio = ShortVolume / TotalVolume. A ratio above 0.55 is a bearish signal.

Parameter	Type	Required	Description
`symbols`	array[string]	yes	US stock tickers, e.g. `['GME', 'NVDA', 'TSLA']`

Sample response (['NVDA', 'GME'] on 2026-06-03):

[
  {
    "symbol": "NVDA",
    "file_date": "2026-06-03",
    "date": "20260603",
    "short_volume": 29418089,
    "short_exempt_volume": 152585,
    "total_volume": 70418648,
    "short_volume_ratio": 0.4178,
    "signal": "Bullish"
  },
  {
    "symbol": "GME",
    "file_date": "2026-06-03",
    "date": "20260603",
    "short_volume": 4837030,
    "short_exempt_volume": 11029,
    "total_volume": 7424290,
    "short_volume_ratio": 0.6515,
    "signal": "Bearish"
  }
]

Signal thresholds: > 0.55 → Bearish · 0.45–0.55 → Neutral · < 0.45 → Bullish

`finra_short_interest`

Official biweekly short interest (shares sold short) for one or more symbols.

Parameter	Type	Required	Description
`symbols`	array[string]	yes	US stock tickers

`finra_ats_volume`

Daily ATS (Alternative Trading System / dark pool / off-exchange) volume for one or more US stocks from the FINRA CNMS daily file. Accumulation can signal quiet institutional buying.

Parameter	Type	Required	Description
`symbols`	array[string]	yes	US stock tickers

Polygon.io

Module: tools/data_ingestion_polygon.py · Key: polygon · Status: ✅ enabled
Base URL: https://api.polygon.io
Auth: POLYGON_API_KEY
Plan: Advanced ($29/mo)
Rate limit: ~12 req/s

Important: polygon_aggregates and polygon_aggregates_extended must use millisecond timestamps (not YYYY-MM-DD strings) for minute and hour timespans. Date strings only work for day/week/month. Extended hours (04:00–20:00 ET pre/post-market) are available on the Advanced plan.

Advanced plan endpoint availability:

Endpoint	Available
`/v2/aggs/ticker/{ticker}/prev` (prev close)	✅
`/v2/aggs/ticker/{ticker}/range/...` (aggregates, incl. 5-min intraday)	✅
`/v3/reference/dividends`	✅
`/v3/reference/tickers/{ticker}` (details)	✅
`/v2/snapshot/...` (real-time snapshot)	❌ not on Advanced
`/v3/snapshot/options/...` (options snapshot)	❌ not on Advanced

`polygon_prev_close`

Previous trading day's OHLCV for one or more tickers. Fetches concurrently.

Parameter	Type	Required	Description
`tickers`	array[string]	yes	US stock tickers, e.g. `['AAPL', 'NVDA', 'SPY']`

Sample response:

[
  {
    "ticker": "NVDA",
    "date": "2026-06-03",
    "open": 221.72,
    "high": 222.82,
    "low": 214.51,
    "close": 214.75,
    "volume": 160907001.0,
    "vwap": 216.3986,
    "transactions": 2740287,
    "change_pct": -3.1436
  }
]

`polygon_aggregates`

Historical OHLCV bars. Daily default, also weekly and monthly.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	US stock ticker
`timespan`	string	no	`day`	`day`, `week`, `month`
`from_date`	string	no	90 days ago	`YYYY-MM-DD`
`to_date`	string	no	today	`YYYY-MM-DD`
`limit`	integer	no	90	Max bars (sorted newest first)

`polygon_aggregates_extended`

OHLCV bars including pre-market and after-hours sessions (04:00–20:00 ET). Use millisecond timestamps for minute/hour timespans.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	US stock ticker
`timespan`	string	no	—	`minute`, `hour`, `day`
`from_date`	string	no	—	ms timestamp (intraday) or `YYYY-MM-DD`
`to_date`	string	no	—	ms timestamp (intraday) or `YYYY-MM-DD`

`polygon_dark_pool`

ATS / dark pool volume signal for a US stock.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	US stock ticker
`days`	integer	no	—	Look-back window

`polygon_dividends`

Upcoming and historical dividends.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	US stock ticker
`limit`	integer	no	20	Max records

Sample response (AAPL):

[
  {
    "ex_dividend_date": "2026-05-11",
    "record_date": "2026-05-11",
    "pay_date": "2026-05-14",
    "cash_amount": 0.27,
    "frequency": 4,
    "dividend_type": "CD"
  }
]

`polygon_ticker_details`

Reference data: name, market cap, shares outstanding, SIC, exchange, description.

Parameter	Type	Required
`ticker`	string	yes

Sample response (NVDA):

{
  "ticker": "NVDA",
  "name": "Nvidia Corp",
  "market_cap": 5396923220000.0,
  "shares_outstanding": 24200000000,
  "weighted_shares_outstanding": 24221000000,
  "primary_exchange": "XNAS",
  "sic_description": "SEMICONDUCTORS & RELATED DEVICES",
  "locale": "us",
  "currency": "usd",
  "homepage_url": "https://www.nvidia.com",
  "description": "Nvidia is a leading developer of graphics processing units..."
}

EODHD

Module: tools/data_ingestion_eodhd.py · Key: eodhd · Status: ✅ enabled
Base URL: https://eodhd.com/api
Auth: EODHD_API_KEY
Plan: Monthly (paid) — update subscriptions.json with actual cost
Rate limit: ~5 req/sec
Cache TTL: Quote 1 min; fundamentals 1h; HV 1h

Note: Options chain / IV data requires the EODHD Options add-on (not on current plan). The eodhd_hist_volatility tool provides realised historical volatility rank as a proxy.

`eodhd_quote`

Live/delayed quote with technical context and short interest for one or more tickers.

Parameter	Type	Required	Description
`tickers`	array[string]	yes	US stock tickers, e.g. `['AAPL', 'NVDA']`

Sample response (NVDA):

{
  "ticker": "NVDA",
  "price": 214.75,
  "change": -8.07,
  "change_pct": -3.6218,
  "volume": 154661585,
  "52w_high": 236.2643,
  "52w_low": 140.6675,
  "50d_ma": 202.0494,
  "200d_ma": 188.2426,
  "beta": 2.244,
  "short_ratio": 1.92,
  "short_pct_float": 0.0128,
  "shares_short": 296966425,
  "wall_st_target": 298.069,
  "pe_ratio": 32.8867
}

`eodhd_fundamentals`

Comprehensive fundamentals: valuation, financials, analyst ratings (Buy/Hold/Sell counts + target), earnings history with surprise, ESG scores, insider transactions.

Parameter	Type	Required
`ticker`	string	yes

`eodhd_hist_volatility`

Compute historical (realised) volatility rank and percentile from EOD price data.

Parameter	Type	Required	Default	Description
`ticker`	string	yes	—	US stock ticker
`window`	integer	no	21	Rolling window in trading days (~1 month)
`lookback_days`	integer	no	252	History for rank calculation (~1 year)

Sample response (NVDA):

{
  "ticker": "NVDA",
  "current_hv": 0.4355,
  "hv_rank": 84.4,
  "hv_percentile": 88.9,
  "hv_52w_high": 0.4697,
  "hv_52w_low": 0.2498,
  "window": 21,
  "lookback_days": 252,
  "interpretation": "High — elevated realised volatility; options pricing likely expensive",
  "note": "Historical volatility (realised). IV rank requires options data (EODHD Options add-on)."
}

`eodhd_screener`

Screen stocks with financial filters.

Parameter	Type	Required	Default	Description
`filters`	array	no	—	List of `[field, operator, value]` triples
`sort_field`	string	no	`market_capitalization`	Sort field
`sort_order`	string	no	`desc`	`asc` or `desc`
`limit`	integer	no	20	Max results (max 100)

SEC Failure-to-Deliver (FTD)

Module: tools/data_ingestion_sec_ftd.py · Key: sec_ftd · Status: ✅ enabled
Source: SEC EDGAR REGSHO public zip files
Auth: None
Cache TTL: 12 hours
File URLs: - https://www.sec.gov/files/data/fails-deliver-data/cnsfails{YYYYMM}a.zip (first half) - https://www.sec.gov/files/data/fails-deliver-data/cnsfails{YYYYMM}b.zip (second half)

File format: SETTLEMENT DATE|CUSIP|QUANTITY (FAILS)|DESCRIPTION|PRICE

Published bimonthly under Regulation SHO. FTD spikes are a known short squeeze precursor — persistent settlement failures indicate shorts cannot locate shares to deliver.

`sec_ftd_get`

Most recent FTD data for one or more symbols.

Parameter	Type	Required	Description
`symbols`	array[string]	yes	US stock tickers

Sample response (['GME', 'NVDA'] — 2026-05 file):

[
  {
    "symbol": "GME",
    "settlement_date": "20260514",
    "quantity_fails": 443681,
    "price": 22.08,
    "cusip": "36467W109",
    "ftd_signal": "Moderate",
    "file_period": "202605a"
  },
  {
    "symbol": "NVDA",
    "settlement_date": "20260514",
    "quantity_fails": 2651,
    "price": 225.83,
    "ftd_signal": "Low",
    "file_period": "202605a"
  }
]

FTD signal thresholds: > 1,000,000 → Elevated · > 100,000 → Moderate · otherwise → Low

`sec_ftd_trend`

FTD history across recent bimonthly files, with trend classification.

Parameter	Type	Required	Default	Description
`symbol`	string	yes	—	US stock ticker
`n_periods`	integer	no	6	Bimonthly periods to look back (~3 months)

Returns: trend = rising / falling / stable / no_data

Benzinga

Module: tools/data_ingestion_benzinga.py · Key: benzinga · Status: ✅ enabled
Base URL: https://api.benzinga.com/api
Auth: BEZINGA_API_KEY (note: env var is spelled BEZINGA_API_KEY)
Plan: Paid — update subscriptions.json with actual cost
Rate limit: ~5 req/sec
Cache TTL: News 5 min; calendar/ratings 30 min

Five tools covering finance-specific news, analyst rating changes, earnings calendar with EPS data, dividends, and company guidance.

`benzinga_news`

Financial news filterable by ticker(s) or keyword.

Parameter	Type	Required	Default	Description
`tickers`	array[string]	no	—	Filter by tickers, e.g. `['AAPL', 'NVDA']`. Omit for market-wide.
`query`	string	no	—	Keyword search
`days`	integer	no	7	Look-back window in days
`limit`	integer	no	20	Max articles

Sample response (tickers=['AAPL'], limit=2):

[
  {
    "date": "2026-05-28",
    "title": "Apple's AI Push: What Wall Street Thinks Now",
    "author": "Chandrima Sanyal",
    "tickers": ["AAPL"],
    "url": "https://www.benzinga.com/...",
    "summary": "Analysts increasingly bullish on Apple Intelligence monetisation..."
  }
]

`benzinga_ratings`

Analyst rating changes: upgrades, downgrades, reiterations, initiations.

Parameter	Type	Required	Default	Description
`ticker`	string	no	—	Filter by ticker. Omit for all.
`days`	integer	no	30	Look-back window
`limit`	integer	no	20	Max results

Sample response (days=7, limit=3):

[
  {
    "date": "2026-06-03",
    "ticker": "IBM",
    "company": "International Business Machines",
    "analyst": "Citigroup",
    "action": "Maintains",
    "rating_current": "Buy",
    "rating_prior": "Buy",
    "price_target": "375.00",
    "price_target_prior": "320.00"
  }
]

action values: Upgrades, Downgrades, Maintains, Initiates Coverage On, Reiterates

`benzinga_earnings_calendar`

Earnings dates with EPS estimates, actuals, and surprise %.

Parameter	Type	Required	Default	Description
`ticker`	string	no	—	Filter by ticker. Omit for all.
`days_ahead`	integer	no	14	Days forward
`days_back`	integer	no	7	Days back (for recent results)
`limit`	integer	no	50	Max results

Sample response (days_ahead=60, limit=3):

[
  { "date": "2026-07-29", "ticker": "MSFT", "company": "Microsoft", "eps_est": "4.230", "eps_actual": "", "time": "AMC" },
  { "date": "2026-07-30", "ticker": "AAPL", "company": "Apple",     "eps_est": "1.890", "eps_actual": "", "time": "AMC" }
]

`benzinga_dividends`

Ex-dividend dates, amounts, yields, and prior dividend.

Parameter	Type	Required	Default	Description
`ticker`	string	no	—	Filter by ticker
`days_ahead`	integer	no	30	Days forward
`days_back`	integer	no	7	Days back
`limit`	integer	no	50	Max results

`benzinga_guidance`

Company forward EPS and revenue guidance ranges vs prior guidance.

Parameter	Type	Required	Default	Description
`ticker`	string	no	—	Filter by ticker
`days`	integer	no	30	Look-back window
`limit`	integer	no	20	Max results

Sample response (days=14, limit=2):

[
  {
    "date": "2026-05-27",
    "ticker": "CRM",
    "company": "Salesforce",
    "eps_guidance_max": "14.120",
    "eps_guidance_prior_max": "13.190"
  }
]

Data Providers Reference

Summary

SEC 13F Filings

manager_new_positions

Alpha Vantage

get_forex_daily

get_commodity_prices

get_crypto_daily

get_economic_data

Economic Calendar

get_economic_calendar

get_upcoming_events

FinViz Elite

screener

quote_history

group_performance

options_screen

latest_filings

news

portfolio

Financial Modeling Prep (FMP)

get_stock_quote

get_batch_quotes

get_price_history

get_intraday_prices

get_company_profile

get_financial_statements

get_key_metrics

get_financial_ratios

get_analyst_data

get_sec_filings

get_insider_trades

get_congressional_trades

get_news

get_market_movers

get_sector_performance

get_economic_indicator

get_treasury_rates

get_dcf_valuation

get_esg

get_technical_indicator

screen_stocks

get_company_research_bundle

get_quote_l1 / get_batch_quotes_l1

get_aftermarket_quote / get_batch_aftermarket_quotes

get_earnings_calendar

get_earnings_by_company

FRED (St. Louis Federal Reserve)

search_series

get_series_info

get_series

get_inflation

get_gdp

get_labor_market

get_interest_rates

get_credit_conditions

get_housing

get_consumer_indicators

get_money_supply

get_market_indicators

get_macro_snapshot

get_category_series

GDELT

search_gdelt_news

get_gdelt_sentiment

get_gdelt_coverage_volume

get_gdelt_geo_news

IMF / ECB / BIS

IMF Tools

get_imf_indicators

get_imf_countries

get_imf_indicator

get_imf_gdp

get_imf_inflation

get_imf_unemployment

get_imf_fiscal

get_imf_current_account

get_imf_country_snapshot

get_imf_global_outlook

ECB Tools

`manager_new_positions`

`get_forex_daily`

`get_commodity_prices`

`get_crypto_daily`

`get_economic_data`

`get_economic_calendar`

`get_upcoming_events`

`screener`

`quote_history`

`group_performance`

`options_screen`

`latest_filings`

`news`

`portfolio`

`get_stock_quote`

`get_batch_quotes`

`get_price_history`

`get_intraday_prices`

`get_company_profile`

`get_financial_statements`

`get_key_metrics`

`get_financial_ratios`

`get_analyst_data`

`get_sec_filings`

`get_insider_trades`

`get_congressional_trades`

`get_news`

`get_market_movers`

`get_sector_performance`

`get_economic_indicator`

`get_treasury_rates`

`get_dcf_valuation`

`get_esg`

`get_technical_indicator`

`screen_stocks`

`get_company_research_bundle`

`get_quote_l1` / `get_batch_quotes_l1`

`get_aftermarket_quote` / `get_batch_aftermarket_quotes`

`get_earnings_calendar`

`get_earnings_by_company`

`search_series`

`get_series_info`

`get_series`

`get_inflation`

`get_gdp`

`get_labor_market`

`get_interest_rates`

`get_credit_conditions`

`get_housing`

`get_consumer_indicators`

`get_money_supply`

`get_market_indicators`

`get_macro_snapshot`

`get_category_series`

`search_gdelt_news`

`get_gdelt_sentiment`

`get_gdelt_coverage_volume`

`get_gdelt_geo_news`

`get_imf_indicators`

`get_imf_countries`

`get_imf_indicator`

`get_imf_gdp`

`get_imf_inflation`

`get_imf_unemployment`

`get_imf_fiscal`

`get_imf_current_account`

`get_imf_country_snapshot`

`get_imf_global_outlook`

`get_ecb_fx_rates`

`get_ecb_inflation`

`get_ecb_yield_curve`

`get_ecb_estr`

`get_ecb_bank_lending`

`get_ecb_snapshot`

`get_bis_policy_rates`

`get_bis_eer`

`get_bis_credit_gap`

`get_bis_debt_service`

`get_bis_total_credit`

`get_bis_property_prices`