Skill: eodhd-api

Purpose

Use EODHD market data APIs to fetch, normalize, and summarize financial data including:

• Prices (historical, intraday, real-time)
• Company fundamentals and financial statements
• Options data with Greeks (from EODHD Marketplace)
• Technical indicators
• News and sentiment
• Macro-economic indicators
• Corporate events (dividends, splits, earnings, IPOs)
• US Treasury interest rates (bill rates, long-term rates, yield curves, real yield curves)
• ESG / environmental scores (from EODHD Marketplace — Investverte)
• Risk analytics and multi-factor reports (from EODHD Marketplace — PRAAMS)
• Bank financials and bond analysis (from EODHD Marketplace — PRAAMS)
• Tick-level market data (from EODHD Marketplace)
• Trading hours and market status (from EODHD Marketplace — TradingHours)

Supports equities, ETFs, indices, forex, crypto, and bonds across 70+ exchanges worldwide.

Trigger

Use this skill whenever the user's task involves financial data, markets, investing, or building financial tools. This includes — but is not limited to — the categories below.

Direct data requests

• End-of-day or historical stock/ETF/index/forex/crypto prices
• Intraday price bars (1m, 5m, 1h intervals)
• Real-time or delayed quotes, extended US quotes with bid/ask
• Company fundamentals, financials, valuation metrics, or financial ratios
• Options chains, Greeks, or options analytics (from EODHD Marketplace)
• Technical indicators (SMA, EMA, RSI, MACD, Bollinger Bands, Stochastic, ADX, ATR, etc.)
• Company or market news, sentiment scores, trending topics
• Stock screening / filtering by fundamental or technical criteria
• Exchange listings, ticker search, or market metadata
• Macro-economic indicators (GDP, inflation, unemployment, interest rates, trade balance, etc.)
• Corporate calendar events (earnings, dividends, splits, IPOs)
• Insider trading activity (executive purchases, sales, SEC filings)
• ESG scores and environmental data — company, sector, country level (from EODHD Marketplace — Investverte)
• Risk scoring, volatility analytics, beta, risk/return profiles (from EODHD Marketplace — PRAAMS)
• Bank balance sheets, income statements, bond analysis (from EODHD Marketplace — PRAAMS)
• US Treasury rates (bill rates, long-term rates, yield curves, real yield curves)
• Historical market capitalisation
• Index composition and components
• Bulk data exports for an entire exchange
• Symbol change history and delisted tickers
• Trading hours, market status, and market holidays (from EODHD Marketplace — TradingHours)
• Company logos and branding assets

Endpoint support tiers — not all endpoints are equally reliable. Check references/general/support-matrix.md (generated from registry/capabilities.json) for the authoritative list:

• validated — call via the Python client (scripts/eodhd_client.py); covered by e2e tests.
• fallback — in the Python client but not e2e-verified; works, but verify the response.
• documented — marketplace add-ons (options, ESG/Investverte, PRAAMS, TradingHours, tick data); call via curl per the endpoint doc. Not in the Python client.

Building financial tools and applications

Activate this skill when the user is programming or designing any of:

• Stock screeners / scanners — filtering stocks by P/E, market cap, sector, growth, dividends, etc.
• Portfolio trackers — tracking holdings, calculating P&L, showing allocation
• Investment dashboards / panels — visualising market data, watchlists, sector heatmaps
• Trading systems / bots — algorithmic or rule-based strategies that need price feeds
• Backtesting engines — testing strategies against historical price and volume data
• Price alert / notification systems — monitoring price levels, volume spikes, or indicator crossovers
• Dividend trackers / income planners — modelling dividend income from a portfolio
• Earnings calendars / event trackers — upcoming earnings, IPOs, splits, economic releases
• Financial data pipelines / ETL — ingesting market data into databases, data warehouses, or analytics platforms
• Market data APIs or microservices — wrapping EODHD data for downstream consumers
• Charting / technical analysis tools — rendering candlestick charts, overlaying indicators
• Options analysis tools — payoff diagrams, implied volatility surfaces, Greeks dashboards
• Risk management tools — VaR calculators, portfolio risk decomposition, drawdown analysis
• Sector / industry analysis tools — comparing metrics across sectors or industries
• Financial reporting generators — producing PDF / HTML reports with market data
• Watchlist applications — letting users curate and monitor symbol lists
• Market data widgets or embeds — price tickers, mini-charts, quote cards for websites
• Robo-advisor prototypes — automated portfolio construction using fundamental and technical data
• Tax-loss harvesting helpers — identifying lots to sell, calculating wash-sale windows
• Crypto portfolio tools — tracking crypto alongside equities, forex, and bonds

Financial analysis, research, and advice

Activate this skill when the user is performing or asking for:

• Fundamental analysis — valuation (DCF, comparables), financial-statement review, ratio analysis
• Technical analysis — chart patterns, indicator interpretation, support/resistance, trend analysis
• Quantitative / statistical analysis — correlation, regression, factor models, Monte Carlo simulation using market data
• Risk assessment — portfolio volatility, beta, Sharpe ratio, maximum drawdown, Value at Risk
• Peer / competitive comparison — comparing financial metrics across a group of companies
• Sector or industry research — analysing sector performance, rotation, relative strength
• Macro-economic research — linking GDP, inflation, or interest-rate data to market performance
• Event studies — measuring price impact around earnings, M&A announcements, policy changes
• Insider-activity analysis — tracking executive buying/selling as a signal
• ESG / sustainability research — screening by environmental or governance scores
• Dividend analysis — yield, payout ratio, growth rate, sustainability
• Earnings quality analysis — trends, surprises, revision momentum
• IPO research — upcoming offerings, sector trends, pricing
• Bond and fixed-income analysis — yield curves, duration, credit spread trends
• Currency / forex analysis — exchange-rate trends, carry-trade research
• Investment advice or recommendations — when the user asks "what should I invest in?", "is X a good buy?", or similar questions that benefit from real market data
• Portfolio allocation or rebalancing — constructing or adjusting a portfolio using current and historical data
• Retirement or financial planning — modelling scenarios that reference market returns, inflation, interest rates
• Academic or educational projects — coursework, papers, or tutorials that need real market data

Required inputs

• API key — the EODHD_API_TOKEN environment variable. If it is not set, ask the user to provide their API key interactively. Once received, export it in the current shell session (export EODHD_API_TOKEN="<key>"). The user can obtain a free or paid key at https://eodhd.com/. If the user is concerned the key may have been compromised, they can provide a new key at any time and the session variable will be updated.
• Instrument identifier in EODHD format: {TICKER}.{EXCHANGE} (e.g., AAPL.US, BMW.XETRA)
• Date range (--from-date, --to-date) for time-series requests
• Endpoint-specific parameters (e.g., --function for technical indicators)

Workflow

1. Clarify the request
   • Check that EODHD_API_TOKEN is set; if not, ask the user for their key and export it
   • Identify objective: price analysis, screening, fundamentals, event study, etc.
   • Confirm symbol(s), date range, and specific metrics needed
   • Determine output format (tables, charts, summary)
2. Select endpoint(s)
   • Reference references/endpoints/README.md or individual files in references/endpoints/ for endpoint specs
   • Choose minimal set of endpoints to satisfy the request
   • Consider endpoint-specific parameters
3. Execute API calls
   • Use scripts/eodhd_client.py for supported endpoints
   • For unsupported endpoints, construct curl commands per endpoint docs
   • Handle pagination for large result sets
4. Validate response
   • Confirm symbol exists and has data for requested range
   • Check for null/missing fields
   • Verify date coverage is adequate
5. Process and present
   • Transform data as needed (calculate returns, ratios, etc.)
   • Use templates/analysis_report.md for structured output
   • Include tables for comparisons, bullet points for conclusions
6. Document reproducibility
   • Include exact commands used
   • Note any data limitations or caveats
   • Provide token-redacted curl examples

Supported endpoints (Python client)

¹ Calendar parameter mapping: The Python client accepts --symbol, but the underlying API parameter is symbols= (plural). If you build curl commands directly, use symbols=AAPL.US,MSFT.US — using symbol= (singular) will be silently ignored, returning empty results with HTTP 200. For calendar/earnings, providing symbols= causes the API to ignore from/to dates.

² Dividends calendar parameter mapping: The API uses bracket-style parameters: filter[symbol], filter[date_from], filter[date_to], page[limit], page[offset]. The Python client translates --symbol/--from-date/--to-date/--limit/--offset automatically. For raw curl, use the bracket format directly (see references/endpoints/upcoming-dividends.md).

³ Real Estate parameter mapping: For the Real Estate endpoints, --symbol carries the ISO 3166-1 alpha-2 country {code} (case-insensitive, e.g. US). The API uses bracket-style filters (filter[type], filter[metric], filter[area], filter[property_type], filter[vintage], filter[freq], filter[from], filter[to]) plus sort, page[limit], page[offset]; the Python client translates --re-*/--sort/--limit/--offset automatically. --re-from/--re-to take period values (YYYY-Qn for SPP). See references/endpoints/real-estate-selected-property-prices.md.

The table above covers Python client support only. An additional 30+ endpoints (Marketplace: options, ESG/Investverte, PRAAMS, TradingHours, tick data, logos, search, WebSockets, etc.) are documented in references/endpoints/ and require curl or manual HTTP calls. See references/endpoints/README.md for the full index.

API call costs: Most endpoints cost 1 call. technical and intraday cost 5 calls. fundamentals costs 10 calls. News-related endpoints (news, sentiment, news-word-weights) cost 5 calls + 5 per ticker. Bulk endpoints cost 100 calls (+ N symbols if --symbols used). Marketplace endpoints (options, ESG, PRAAMS, index-components, tick data) typically cost 10 calls per request. See references/general/rate-limits.md for full details.

Output requirements

• State exact parameters: symbols, date ranges, endpoints used
• Separate facts from interpretation: clearly distinguish API data from analysis
• Note limitations: mention missing fields, null values, date gaps
• Use appropriate formats:
  • Tables for multi-symbol comparisons
  • Bullet points for conclusions and insights
  • JSON/code blocks for raw data samples
• Include reproducible commands: token-redacted curl or client commands

Guardrails

• Never fabricate data: if retrieval fails, report the error and command attempted
• Validate before acting: confirm symbol exists before making multiple calls
• Respect rate limits: avoid unnecessary duplicate requests
• Handle errors gracefully: provide actionable error messages
• Warn on large requests: ask for confirmation before broad multi-exchange pulls
• Protect the API key: never echo or print the token in plain text to the user. Always redact it in example commands (EODHD_API_TOKEN=***). If the user suspects their key is compromised, prompt them to supply a new one and re-export it
• Disclaim on advice: when providing investment recommendations or analysis that could be interpreted as advice, include "This is not financial advice. Data is for informational purposes only."
• Warn on stale data: for real-time/intraday endpoints outside US market hours or on weekends/holidays, note that data may be delayed or from a prior session
• Check Marketplace access: before calling Marketplace endpoints (options, ESG, PRAAMS, TradingHours, tick data), warn that these require specific subscription tiers and consume 10+ API calls per request
• Note currency context: prices are in local exchange currency, not always USD — mention this when presenting data from non-US exchanges

Common patterns

See references/workflows.md for detailed recipes.

Core analysis workflows

1. Single-ticker deep dive: EOD + fundamentals + news + insider activity
2. Peer comparison: Screener + fundamentals for multiple symbols
3. Event study: Intraday bars around earnings/announcements
4. Macro context: Stock performance vs. economic indicators
5. Technical analysis: Price data + indicators (SMA, RSI, MACD)
6. Options analysis: Options chains + Greeks (from EODHD Marketplace)

Building financial tools

7. Stock screener / scanner: Use screener endpoint with filters, then enrich top results with fundamentals and eod for display
8. Portfolio dashboard: Combine real-time (or us-quote-delayed) for live prices, fundamentals for holdings data, eod for historical P&L charts
9. Dividend income tracker: Use calendar/dividends + fundamentals (dividend yield, payout ratio) + eod for ex-date price context
10. Earnings calendar app: Use calendar/earnings + calendar/trends + intraday for pre/post-earnings price movement
11. Backtesting engine data feed: Bulk-fetch via eod or eod-bulk-last-day, use technical for indicator overlays, splits and dividends for adjustment
12. Watchlist with alerts: Use real-time or us-quote-delayed for price monitoring, technical for indicator-based triggers
13. Market heatmap / sector view: Use screener by sector, eod-bulk-last-day for daily moves, index-components for index breakdown

Research and advice workflows

14. Investment thesis research: fundamentals (valuation, growth) + news (catalysts) + insider-transactions (conviction) + sentiment (market mood)
15. Risk assessment: eod (returns series) + technical (ATR, Bollinger) + PRAAMS risk-scoring endpoints (from EODHD Marketplace) + macro overlays
16. ESG screening: Investverte ESG endpoints (from EODHD Marketplace) + fundamentals for financial context
17. Fixed-income analysis: UST rate endpoints (bill, long-term, yield, real-yield) + macro-indicator for inflation/GDP context
18. Currency analysis: Forex pairs via eod (e.g., EURUSD.FOREX) + macro-indicator for interest-rate differentials
19. IPO pipeline review: calendar/ipos for upcoming offerings + eod + fundamentals for comparable public companies

Example commands

# Historical prices
python eodhd_client.py --endpoint eod --symbol AAPL.US --from-date 2025-01-01 --to-date 2025-01-31

# Company fundamentals
python eodhd_client.py --endpoint fundamentals --symbol MSFT.US

# 50-day SMA
python eodhd_client.py --endpoint technical --symbol NVDA.US --function sma --period 50

# Company news with sentiment
python eodhd_client.py --endpoint news --symbol TSLA.US --limit 10

# Daily sentiment scores
python eodhd_client.py --endpoint sentiment --symbol AAPL.US --from-date 2025-01-01 --to-date 2025-01-31

# Trending topics in news (word weights)
python eodhd_client.py --endpoint news-word-weights --symbol AAPL.US --from-date 2025-01-01 --to-date 2025-01-15 --limit 20

# US inflation data
python eodhd_client.py --endpoint macro-indicator --symbol USA --indicator inflation_consumer_prices_annual

# Stock screener
python eodhd_client.py --endpoint screener --limit 20

# Insider transactions
python eodhd_client.py --endpoint insider-transactions --symbol AAPL.US --from-date 2025-01-01 --limit 50

# Upcoming IPOs
python eodhd_client.py --endpoint calendar/ipos --from-date 2025-01-01 --to-date 2025-03-31

# Stock splits calendar
python eodhd_client.py --endpoint calendar/splits --from-date 2025-01-01 --to-date 2025-01-31

# Bulk fundamentals for an exchange (first 100)
python eodhd_client.py --endpoint bulk-fundamentals --symbol NASDAQ --limit 100

# Bulk fundamentals for specific symbols
python eodhd_client.py --endpoint bulk-fundamentals --symbol NASDAQ --symbols AAPL.US,MSFT.US

# User account details and API usage
python eodhd_client.py --endpoint user

# US extended quote (Live v2)
python eodhd_client.py --endpoint us-quote-delayed --symbol AAPL.US,TSLA.US

# US Treasury Bill Rates for 2012
python eodhd_client.py --endpoint ust/bill-rates --filter-year 2012 --limit 100

# US Treasury Long-Term Rates for 2020
python eodhd_client.py --endpoint ust/long-term-rates --filter-year 2020

# US Treasury Yield Curve for 2023
python eodhd_client.py --endpoint ust/yield-rates --filter-year 2023

# US Treasury Real Yield Curve for 2024
python eodhd_client.py --endpoint ust/real-yield-rates --filter-year 2024

References

General Documentation

• Getting Started: references/general/README.md - Start here for setup and basics
• Authentication: references/general/authentication.md - API tokens, protocols (HTTPS/HTTP), CORS, security
• Symbol Format: references/general/symbol-format.md - How to format tickers correctly
• Exchanges: references/general/exchanges.md - Complete list of 70+ exchanges, coverage gaps
• Update Times: references/general/update-times.md - When data is refreshed
• Rate Limits: references/general/rate-limits.md - Quotas (~17 req/sec), optimization, error codes
• Fundamentals API: references/general/fundamentals-api.md - Complete guide to company fundamentals, ETFs, funds, and indices
• Pricing & Plans: references/general/pricing-and-plans.md - Subscription tiers, WebSocket limits, marketplace
• Subscription Plans: references/subscriptions/README.md - Detailed per-plan feature breakdowns
• SDKs & Integrations: references/general/sdks-and-integrations.md - Official Python/.NET/R SDKs, MCP Server, tools
• Versioning: references/general/versioning.md - API stability guarantees, backwards-compatibility
• Glossary: references/general/glossary.md - Financial, technical, and EODHD-specific terms

Endpoint Documentation

• Endpoint catalog: references/endpoints/README.md - Overview of all endpoints
• Individual endpoint docs: references/endpoints/*.md - Detailed specs per endpoint
• Analysis workflows: references/workflows.md - Common usage patterns
• Output template: templates/analysis_report.md - Structured report format