Skip to main content

Screener

POST /v1/screen

The unified screener intersects up to four independent legs — technical analysis, fundamentals, options positioning, and dividend criteria — scoped to a custom universe, in a single call.

Cost: 5 credits per call (flat).

Legs at a glance​

LegWhat it screensDetail
universeWhich stocks are eligible before any leg runsCountry, GICS sector, size tier, market cap, asset type, theme
taTechnical signals — crossovers, divergences, squeezes, Ichimoku20+ patterns × 15+ operands, multi-timeframe
fundamentalFinancial ratios, dollar amounts, growth rates50+ ratio keys + hundreds of statement fields
optionsOptions-market positioning behaviourUS-listed optionable stocks only (~557 names)
dividendDividend streak and growth gateCombine with TA or fundamentals

Every leg is optional. The screener intersects whichever you include.

Quick example​

US large-cap tech — golden cross and ROE > 20%:

curl -X POST \
  -H "Authorization: Bearer avn_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "universe": {
      "include": [{ "country": ["US"], "gics": "45", "size": ["large", "mid"] }]
    },
    "ta": [{
      "anchor": [{ "pattern": "crossover_up", "a": "ema50", "b": "ema200" }]
    }],
    "fundamental": [{ "concept": "roe", "pattern": "above", "threshold": 0.2 }],
    "limit": 10
  }' \
  "https://api.marketdx.app/v1/screen"

Request body​

Full shape — all fields optional except at least one leg
{
  "universe":    { "include": [...], "exclude": [...] },
  "ta":          [ ...steps ],
  "fundamental": [ ...conditions ],
  "options":     { "pattern": "...", "horizon": "long", "min_strength": 0.0 },
  "dividend":    { "min_streak_years": 5, "min_cagr": 0.05 },
  "timeframe":   1,
  "window_bars": 30,
  "sort":        "ta",
  "sort_dir":    "desc",
  "limit":       50
}

sort and sort_dir​

sort valueDescriptionDefault direction
"ta" (default)TA chain score — how strongly/recently the TA fireddesc
"options"Options signal strengthdesc
"mcap"Market cap (USD)desc (largest first)
"pe" "pb" "ev_ebitda"Valuation multiplesasc (cheapest first)
"roe" "revenue" "net_margin"Any fundamental concept keydesc (best first)
"rsi" "adx"TA oscillator valuedesc

Response​

Typical response
{
  "universe": 1842,
  "count": 4,
  "capped": false,
  "sort": "ta",
  "notes": [],
  "results": [
    {
      "head_listing_id": 31809,
      "ticker": "NVDA.US",
      "name": "NVIDIA Corporation",
      "country": "US",
      "gics": "453010",
      "score": 2.85,
      "matched_legs": ["ta", "fundamental"],
      "matched": {
        "ta": {
          "crossover_up": {
            "a": "ema50", "b": "ema200",
            "at": "2026-07-15",
            "detail": "EMA50 crossed above EMA200 (golden cross)"
          }
        },
        "fundamental": {
          "roe": { "value": 0.52, "pattern": "above", "threshold": 0.2 }
        }
      },
      "context": {
        "ta": { "rsi14": 61.4, "adx": 32.1, "ema50": 196.8, "ema200": 185.3, "close": 198.2 },
        "fundamental": { "roe": 0.52, "pe": 52.1, "revenue": 130500000000 }
      }
    }
  ]
}

Response fields​

FieldTypeDescription
universenumberStocks matching the universe scope before leg filtering.
countnumberStocks in results (≤ limit).
cappedbooltrue if results were truncated — increase limit or narrow scope.
notesstring[]Operand snapping notes, cohort scope info, warnings. Always check this.
results[].scorenumberTA chain score. Higher = more recent / stronger.
results[].matched_legsstring[]Which legs this stock passed.
results[].matchedobjectPer-leg evidence: signal details, values, dates.
results[].context.taobjectCurrent TA values (RSI, ADX, MAs, close).
results[].context.fundamentalobjectCurrent fundamental values for screened metrics.

Partial matches​

When fewer than 3 stocks match all legs, the response adds near-misses:

{
  "partial": true,
  "intersection_count": 1,
  "near_misses": [
    { "ticker": "AMD.US", "matched_legs": ["ta"], "missing_legs": ["fundamental"] }
  ]
}

Recipes​

Dip buyer: down >10%, revenue growing, not overvalued
{
  "universe": { "include": [{ "country": ["US"], "size": ["large","mid"] }] },
  "ta": [{ "anchor": [{ "pattern": "net_change_dn", "window_bars": 20 }] }],
  "fundamental": [
    { "concept": "revenue", "pattern": "consecutive_growth", "N": 2 },
    { "concept": "pe",      "pattern": "below", "threshold": 40 }
  ]
}
Asian chip makers: cheap PE + above 200-day MA
{
  "universe": { "include": [{ "country": ["TW","KR","JP"], "gics": "453010" }] },
  "ta": [{ "anchor": [{ "pattern": "above", "a": "close", "b": "sma200" }] }],
  "fundamental": [{ "concept": "pe", "pattern": "below", "threshold": 20 }]
}
Volatility squeeze coiling up — US small/mid
{
  "universe": { "include": [{ "country": ["US"], "size": ["small","mid"] }] },
  "ta": [{ "anchor": [{ "pattern": "ttm_squeeze" }] }]
}
Options crowd turning bullish + oversold RSI
{
  "universe": { "include": [{ "country": ["US"] }] },
  "ta": [{ "anchor": [{ "pattern": "oversold", "a": "rsi14" }] }],
  "options": { "pattern": "fear_to_confidence", "horizon": "long" }
}
Ichimoku TK cross + price above cloud
{
  "ta": [{
    "anchor": [{ "pattern": "crossover_up", "a": "ichi_tenkan", "b": "ichi_kijun" }],
    "quals": [{ "any": [{ "pattern": "above", "a": "close", "b": "ichi_senkou_a" }] }]
  }]
}
Reliable dividend growers with bullish momentum
{
  "ta": [{ "anchor": [{ "pattern": "above", "a": "close", "b": "ema200" }] }],
  "dividend": { "min_streak_years": 5, "min_cagr": 0.05 }
}
  • POST /v1/ta/find-signal — Resolve a plain-language TA phrase to a pattern token
  • POST /v1/financials/find — Resolve a financial concept to a concept key
  • POST /v1/options/find-pattern — Resolve an options-behaviour phrase to a pattern token
  • GET /v1/stocks/dividends — Pure dividend screen (ranked by yield)