market-breadth-analyzer

name	market-breadth-analyzer
version	1.0.2
description	Measure US equity market breadth using advance/decline lines, percentage of stocks above moving averages, and new highs/lows via the Finskills API.
author	finskills
metadata	{"openclaw":{"requires":{"env":["FINSKILLS_API_KEY"]},"primaryEnv":"FINSKILLS_API_KEY"},"homepage":"https://github.com/finskills/market-breadth-analyzer"}

Market Breadth Analyzer

Assess internal market health and regime using breadth indicators from the Finskills API: advance/decline data, percentage of stocks above key moving averages, new highs vs. new lows, and short volume. Identify divergences between index price action and underlying breadth — the most reliable early warning system for market tops and bottoms.

---

Setup

API Key required — Register at https://finskills.net to get your free key.
Header: X-API-Key: <your_api_key>

Get your API key: Register at https://finskills.net — free tier available, Pro plan unlocks real-time quotes, history, and financials.

---

When to Activate This Skill

Activate when the user:

• Asks "is this rally broad-based or narrow?"
• Wants to assess whether the market is healthy or deteriorating
• Asks about advance/decline ratio, new highs/lows, or breadth divergence
• Wants to understand if it's a good environment to be fully invested
• Asks "are we in a bull or bear market internally?"

---

Data Retrieval — Finskills API Calls

1. Market Breadth Indicators

GET https://finskills.net/v1/free/market/breadth

Extract:

• advancers: number of stocks advancing
• decliners: number of stocks declining
• unchanged: number of stocks flat
• new52wHigh: stocks hitting 52-week highs
• new52wLow: stocks hitting 52-week lows
• pctAbove200MA: % of S&P 500 stocks trading above 200-day MA
• pctAbove50MA: % of S&P 500 stocks trading above 50-day MA
• advanceVolume: volume in advancing stocks
• declineVolume: volume in declining stocks

2. Market Summary (Index Price Context)

GET https://finskills.net/v1/market/summary

Extract: S&P 500 and Nasdaq current level, daily change, YTD performance

3. Short Volume (Market Stress Signal)

GET https://finskills.net/v1/free/market/short-volume-top

Extract: list of most heavily shorted stocks today (ratio of short vol to total vol)

---

Analysis Workflow

Step 1 — Advance/Decline Analysis

Advance/Decline Ratio (ADR):

ADR = advancers / decliners

ADR	Signal
> 3.0	Strong breadth — broad rally
1.5–3.0	Good breadth — healthy market
0.75–1.5	Mixed breadth — selective market
0.25–0.75	Weak breadth — narrow or declining market
< 0.25	Very weak breadth — broad selloff

Volume-Weighted A/D:

Volume A/D = advanceVolume / declineVolume

If Volume ADR > ADR: Distribution (smart money selling into rally) — bearish signal
If Volume ADR < ADR: Accumulation (buying on pullbacks) — bullish signal

Net New Highs/Lows:

Net New Highs = new52wHigh - new52wLow

• Positive and growing: Strong bull market confirmation
• Negative while index is rising: Breadth divergence ⚠️ (early warning signal)
• Accelerating lows: Risk-off, potential broad decline

Step 2 — Moving Average Participation

Classify market health by % of stocks above key moving averages:

% Stocks Above 200-Day MA:

Level	Market Health
> 70%	Bull market — broad participation
50–70%	Moderate — mixed conditions
30–50%	Weakening — selective market
< 30%	Bear market conditions

% Stocks Above 50-Day MA:

• Leading indicator (shorter-term): signals shifts 2–4 weeks before 200MA
• When 50MA% drops below 40% while 200MA% still > 60%: caution flag ⚠️

Step 3 — Breadth Divergence Detection

Bullish Divergence (oversold bounce setup):

• Index near 52-week lows
• But % stocks above 200MA is rising
• ADR improving → Signal: Internal strength building before price recovers

Bearish Divergence (distribution signal):

• Index near 52-week highs
• But % stocks above 200MA is falling
• New highs count shrinking (fewer stocks making highs)
• Net new lows expanding → Signal: Market becoming a narrow rally — top risk elevated

Participation Narrowing: Calculate the ratio:

Narrowness Index = (leaders outperforming SPY with > 5% weight) / total S&P 500 constituents

If < 10 stocks are driving most of the index return, flag as "narrow rally" with high reversal risk.

Step 4 — Short Volume Stress Signals

Top heavily-shorted stocks signal areas of market stress:

• If heavily shorted stocks are in key sectors: sector under significant bearish pressure
• High short ratio on recent IPOs or hyper-growth names: speculative froth reducing
• Short squeeze potential: stocks with high short ratio + positive news catalyst = snapback risk

Step 5 — Overall Market Health Score

Score each dimension and compute composite:

Dimension	Score (1–5)
ADR (daily)	5=very strong, 1=very weak
NetNewHighs	5=expanding, 1=contracting
% > 200MA	5= > 70%, 1= < 30%
% > 50MA	5= > 65%, 1= < 35%
Vol. A/D Confirm	5=confirmed, 3=neutral, 1=diverging

Market Health Score = avg of 5 dimensions (scale 1–5)

• 4–5: Healthy bull market — stay invested
• 3–4: Moderate — selective stock picking
• 2–3: Weakening — raise cash, reduce risk
• 1–2: Unhealthy — defensive positioning

---

Output Format

╔══════════════════════════════════════════════════════╗
║    MARKET BREADTH REPORT  —  {DATE}                 ║
╚══════════════════════════════════════════════════════╝

📊 MARKET INDEXES
  S&P 500:  {level}  {change}%  YTD: {ytd}%
  Nasdaq:   {level}  {change}%  YTD: {ytd}%
  Russell:  {level}  {change}%  YTD: {ytd}%

🩺 MARKET HEALTH SCORE: {X}/5  →  {HEALTHY / MODERATE / WEAKENING / UNHEALTHY}

📈 BREADTH DASHBOARD
  Advancers / Decliners:  {adv} / {dec}  (ADR: {ratio} — {Strong/Weak/Mixed})
  Volume Split:           {adv_vol}B advancing / {dec_vol}B declining
  Volume A/D Ratio:       {ratio} [{Accumulation/Distribution}]

  New 52-Week Highs:  {n}
  New 52-Week Lows:   {n}
  Net New Highs:      {+/-n}  [{Expanding/Contracting}]

  % Stocks > 200-Day MA: {%}  [{Bull/Moderate/Bear} zone]
  % Stocks > 50-Day MA:  {%}

🔍 DIVERGENCE CHECK
  Price vs. Breadth: {No divergence / BULLISH divergence / BEARISH divergence ⚠️}
  Detail: {Brief explanation of any divergence}
  Narrowing Rally Check: {Broad / Narrowing ⚠️}

📊 SHORT INTEREST SIGNALS
  Top Heavily Shorted Stocks Today:
    {TICKER}: {short_ratio}% short volume
    {TICKER}: {short_ratio}% short volume
  Signal: {Normal / Elevated stress in {sector}}

🎯 MARKET HEALTH ASSESSMENT
  Overall Verdict: {Healthy Bull / Mixed / Weakening / Risk-Off}

  Implication for Investors:
    ✅ {What to do if healthy}  OR
    ⚠️ {What to watch / reduce if weakening}

  Key indicator to monitor: {The metric most likely to confirm direction}

---

Limitations

• Breadth indicators work best over 5–20 day windows; single-day readings can be noisy.
• % above MA data depends on the data provider's stock universe (may cover S&P 500 constituents only).
• Short volume data from the prior trading day (T+1 reporting lag for official FINRA data).