/stock-screener

name: stock-screener
description: >-
  Screen stocks by fundamental and technical criteria using EODHD screener —
  filter by market cap, P/E, dividend yield, sector, signals, and more.
  Use when the user wants to find stocks matching specific criteria.
version: 0.4.0

Skill: stock-screener

Purpose

Find stocks matching user-defined criteria using EODHD's screener endpoint, then enrich top results with detailed fundamentals and price data for comparison.

Trigger

Activate when the user asks for:

• Stock screening or filtering ("find stocks with P/E under 15")
• "Best dividend stocks" or "cheap growth stocks"
• Sector-specific stock lists
• Signal-based screening (new highs, oversold, etc.)
• Comparative analysis of filtered stocks
• "What should I invest in?" (screen first, then analyze)

Workflow

1. **Translate criteria to filters** — map user language to EODHD screener JSON filters 2. **Run screener** — `screener` endpoint with filters, sort, signals, limit 3. **Review results** — present initial list with key metrics 4. **Enrich top picks** — `fundamentals` for detailed data on top 5-10 results 5. **Add price context** — `eod` for recent price trends 6. **Compile screener report**

Filter Format (critical)

`filters` is a **JSON array of `[field, operation, value]` triples** — NOT dot-notation (`market_capitalization.gte`) and NOT a JSON object. If the shape is wrong, the EODHD API silently ignores the filter and returns unfiltered, irrelevant results.

Operations: `=`, `!=`, `>`, `>=`, `<`, `<=`, `match`. A JSON object is rejected with HTTP 422.

[["market_capitalization",">=",10000000000],["sector","=","Technology"]]

**Sort:** `--sort field.direction` (e.g. `market_capitalization.desc`, `pe.asc`). A bare field name is rejected with HTTP 422 ("sort.0.direction is required").

**Currency caveat (important):** absolute-money fields — `market_capitalization`, `revenue`, `ebitda` — are in each listing's **local currency**, not USD. A raw threshold leaks huge non-USD companies (e.g. a Vietnam-listed firm at "3.88T" ₫ ≈ $150M passes `>= 10B`). Each result row has a `currency_symbol` field indicating its currency. So:

• Filtering/sorting by an absolute-money field → **scope to one market** with `["exchange","=","us"]` (or the

intended exchange) so the threshold is currency-consistent.

• Multi-market screens → don't compare raw caps across rows; group/label by `currency_symbol`.
• Ratio/percent fields (`pe`, `pb`, `ps`, `peg`, `roe`, `roa`, `beta`, `dividend_yield`) are

currency-independent and safe to compare across markets.

**Instrument-type noise (the screener has NO `type` filter — `["type",...]` → HTTP 422):** the combined `["exchange","=","us"]` includes OTC foreign cross-listings (codes ending `F`/`Y`, broken 55–110% `dividend_yield`) and preferred shares (codes with a `-`, e.g. `JPM-PD`). For a clean common-stock screen: scope to a real venue (`["exchange","=","nyse"]`/`"nasdaq"`), add `["dividend_yield","<=",0.25]` on dividend screens, and post-filter result rows whose `code` contains `-`.

Available Filters

The screener supports these filter fields:

• `market_capitalization` — market cap in the listing's **local currency** (see currency caveat; scope by `exchange` for a consistent threshold)
• `earnings_share` — EPS
• `dividend_yield` — dividend yield as a **fraction** (0.03 = 3%, not 3)
• `sector` — sector name (exact match)
• `industry` — industry name (exact match)
• `exchange` — exchange code (e.g., `us`)
• `pe` — P/E ratio
• `wallstreet_target_price` — analyst target price
• Plus many more fundamental fields (see endpoint reference)

Each result row also returns `currency_symbol` (currency of the absolute-money fields) and `exchange` — surface these when presenting caps.

Available Signals

• `50d_new_hi` / `50d_new_lo` — 50-day new high/low
• `200d_new_hi` / `200d_new_lo` — 200-day new high/low
• `bookvalue_neg` — negative book value
• `wallstreet_lo` / `wallstreet_hi` — at analyst low/high

Output Structure

Stock Screener Results — [Criteria Description]

**Filter Applied**

{filters_used}

**Results ([N] matches)** | # | Ticker | Name | Sector | Mkt Cap (ccy) | P/E | Div Yield | Price | |---|--------|------|--------|---------------|-----|-----------|-------|

Show the `currency_symbol` alongside Mkt Cap; never render a non-USD cap as USD. If the screen spans multiple currencies, say so in the Summary caveats.

**Top Picks — Detailed Analysis** For each top 5 result:

• Valuation metrics (P/E, P/S, P/B, EV/EBITDA)
• Growth metrics (Revenue growth, EPS growth)
• Profitability (margins, ROE)
• 30-day price trend
• Analyst target vs current price

**Sector Distribution** | Sector | Count | Avg P/E | Avg Yield | |--------|-------|---------|-----------|

**Summary**

• Key themes in results
• Caveats and limitations

> This is not financial advice. Data is for informational purposes only.

Example Filters

# High-dividend large caps (dividend_yield is a fraction: 0.03 = 3%; nyse avoids OTC junk; <=0.25 caps broken yields)
python eodhd_client.py --endpoint screener --filters '[["dividend_yield",">=",0.03],["dividend_yield","<=",0.25],["market_capitalization",">=",10000000000],["exchange","=","nyse"]]' --sort dividend_yield.desc --limit 20
# then drop rows whose code contains '-' (preferred shares)

# Undervalued growth stocks
python eodhd_client.py --endpoint screener --filters '[["market_capitalization",">=",1000000000],["earnings_share",">=",1],["exchange","=","us"]]' --signals 200d_new_lo --limit 20

# Tech sector screening
python eodhd_client.py --endpoint screener --filters '[["sector","=","Technology"],["market_capitalization",">=",5000000000],["exchange","=","us"]]' --sort market_capitalization.desc --limit 30

Endpoints Used

| Endpoint | Purpose | Cost | |----------|---------|------| | `screener` | Filter and rank stocks | 1 call | | `fundamentals` | Detailed data for top picks | 10 call