Back to Details

market-top-detector

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Market Top Detector Skill

Market Top Detector Skill

Purpose

用途

Detect the probability of a market top formation using a quantitative 6-component scoring system (0-100). Integrates three proven market top detection methodologies:
  1. O'Neil - Distribution Day accumulation (institutional selling)
  2. Minervini - Leading stock deterioration pattern
  3. Monty - Defensive sector rotation signal
Unlike the Bubble Detector (macro/multi-month evaluation), this skill focuses on tactical 2-8 week timing signals that precede 10-20% market corrections.
通过由6个组件构成的量化评分系统（0-100分）检测市场顶部形成的概率。整合了三种经过验证的市场顶部检测方法：
  1. O'Neil - 派发日累积（机构抛售信号）
  2. Minervini - 领涨股恶化模式
  3. Monty - 防御板块轮动信号
与泡沫检测工具（宏观/跨数月评估）不同，本Skill聚焦于战术性2-8周时机信号，这类信号通常出现在市场回调10-20%之前。

When to Use This Skill

何时使用本Skill

English:
  • User asks "Is the market topping?" or "Are we near a top?"
  • User notices distribution days accumulating
  • User observes defensive sectors outperforming growth
  • User sees leading stocks breaking down while indices hold
  • User asks about reducing equity exposure timing
  • User wants to assess correction probability for the next 2-8 weeks
Japanese:
  • 「天井が近い？」「今は利確すべき？」
  • ディストリビューションデーの蓄積を懸念
  • ディフェンシブセクターがグロースをアウトパフォーム
  • 先導株が崩れ始めているが指数はまだ持ちこたえている
  • エクスポージャー縮小のタイミング判断
  • 今後2〜8週間の調整確率を評価したい
中文场景：
  • 用户询问“市场是否正在见顶？”或“我们是否接近顶部？”
  • 用户注意到派发日在累积
  • 用户观察到防御板块跑赢成长板块
  • 用户发现领涨股破位但指数仍保持稳定
  • 用户询问减少股票敞口的时机
  • 用户想要评估未来2-8周的回调概率

Difference from Bubble Detector

与泡沫检测工具的区别

AspectMarket Top DetectorBubble Detector
Timeframe2-8 weeksMonths to years
Target10-20% correctionBubble collapse (30%+)
MethodologyO'Neil/Minervini/MontyMinsky/Kindleberger
DataPrice/Volume + BreadthValuation + Sentiment + Social
Score Range0-100 composite0-15 points
维度Market Top DetectorBubble Detector
时间范围2-8周数月至数年
目标10-20%的回调泡沫破裂（跌幅30%+）
方法论O'Neil/Minervini/MontyMinsky/Kindleberger
数据来源价格/成交量+市场广度估值+情绪+社交数据
评分范围0-100综合分0-15分

Execution Workflow

执行流程

Phase 1: Data Collection via WebSearch

第一阶段：通过WebSearch收集数据

Before running the Python script, collect the following data using WebSearch. Data Freshness Requirement: All data must be from the most recent 3 business days. Stale data degrades analysis quality.
1. S&P 500 Breadth (200DMA above %)
   AUTO-FETCHED from TraderMonty CSV (no WebSearch needed)
   The script fetches this automatically from GitHub Pages CSV data.
   Override: --breadth-200dma [VALUE] to use a manual value instead.
   Disable: --no-auto-breadth to skip auto-fetch entirely.

2. [REQUIRED] S&P 500 Breadth (50DMA above %)
   Valid range: 20-100
   Primary search: "S&P 500 percent stocks above 50 day moving average"
   Fallback: "market breadth 50dma site:barchart.com"
   Record the data date

3. [REQUIRED] CBOE Equity Put/Call Ratio
   Valid range: 0.30-1.50
   Primary search: "CBOE equity put call ratio today"
   Fallback: "CBOE total put call ratio current"
   Fallback: "put call ratio site:cboe.com"
   Record the data date

4. [OPTIONAL] VIX Term Structure
   Values: steep_contango / contango / flat / backwardation
   Primary search: "VIX VIX3M ratio term structure today"
   Fallback: "VIX futures term structure contango backwardation"
   Note: Auto-detected from FMP API if VIX3M quote available.
   CLI --vix-term overrides auto-detection.

5. [OPTIONAL] Margin Debt YoY %
   Primary search: "FINRA margin debt latest year over year percent"
   Fallback: "NYSE margin debt monthly"
   Note: Typically 1-2 months lagged. Record the reporting month.
在运行Python脚本前，使用WebSearch收集以下数据。 数据新鲜度要求：所有数据必须来自最近3个工作日。过时数据会降低分析质量。
1. 标普500广度（高于200日均线的股票占比）
   从TraderMonty CSV自动获取（无需WebSearch）
   脚本会自动从GitHub Pages的CSV数据中获取该值。
   手动覆盖：使用--breadth-200dma [数值]来指定手动值。
   禁用自动获取：使用--no-auto-breadth完全跳过自动获取。

2. [必填] 标普500广度（高于50日均线的股票占比）
   有效范围：20-100
   主要搜索词："S&P 500 percent stocks above 50 day moving average"
   备选搜索词："market breadth 50dma site:barchart.com"
   记录数据日期

3. [必填] CBOE股票看跌/看涨期权比率
   有效范围：0.30-1.50
   主要搜索词："CBOE equity put call ratio today"
   备选搜索词："CBOE total put call ratio current"
   备选搜索词："put call ratio site:cboe.com"
   记录数据日期

4. [可选] VIX期限结构
   取值：steep_contango / contango / flat / backwardation
   主要搜索词："VIX VIX3M ratio term structure today"
   备选搜索词："VIX futures term structure contango backwardation"
   说明：如果VIX3M报价可用，会通过FMP API自动检测。
   使用CLI参数--vix-term可覆盖自动检测结果。

5. [可选] 保证金债务同比增长率
   主要搜索词："FINRA margin debt latest year over year percent"
   备选搜索词："NYSE margin debt monthly"
   说明：通常有1-2个月的滞后。记录报告月份。

Phase 2: Execute Python Script

第二阶段：执行Python脚本

Run the script with collected data as CLI arguments:
bash
python3 skills/market-top-detector/scripts/market_top_detector.py \
  --api-key $FMP_API_KEY \
  --breadth-50dma [VALUE] --breadth-50dma-date [YYYY-MM-DD] \
  --put-call [VALUE] --put-call-date [YYYY-MM-DD] \
  --vix-term [steep_contango|contango|flat|backwardation] \
  --margin-debt-yoy [VALUE] --margin-debt-date [YYYY-MM-DD] \
  --output-dir reports/ \
  --context "Consumer Confidence=[VALUE]" "Gold Price=[VALUE]"
运行脚本并传入收集到的数据作为CLI参数：
bash
python3 skills/market-top-detector/scripts/market_top_detector.py \
  --api-key $FMP_API_KEY \
  --breadth-50dma [VALUE] --breadth-50dma-date [YYYY-MM-DD] \
  --put-call [VALUE] --put-call-date [YYYY-MM-DD] \
  --vix-term [steep_contango|contango|flat|backwardation] \
  --margin-debt-yoy [VALUE] --margin-debt-date [YYYY-MM-DD] \
  --output-dir reports/ \
  --context "Consumer Confidence=[VALUE]" "Gold Price=[VALUE]"

200DMA breadth is auto-fetched from TraderMonty CSV.

200日均线广度从TraderMonty CSV自动获取。

Override with --breadth-200dma [VALUE] if needed.

如需覆盖，使用--breadth-200dma [数值]。

Disable with --no-auto-breadth to skip auto-fetch.

使用--no-auto-breadth可完全禁用自动获取。


The script will:
1. Fetch S&P 500, QQQ, VIX quotes and history from FMP API
2. Fetch Leading ETF (ARKK, WCLD, IGV, XBI, SOXX, SMH, KWEB, TAN) data
3. Fetch Sector ETF (XLU, XLP, XLV, VNQ, XLK, XLC, XLY) data
4. Calculate all 6 components
5. Generate composite score and reports

脚本将执行以下操作：
1. 从FMP API获取标普500、QQQ、VIX的报价和历史数据
2. 获取领涨ETF（ARKK, WCLD, IGV, XBI, SOXX, SMH, KWEB, TAN）的数据
3. 获取板块ETF（XLU, XLP, XLV, VNQ, XLK, XLC, XLY）的数据
4. 计算所有6个组件的得分
5. 生成综合评分和报告

Phase 3: Present Results

第三阶段：展示结果

Present the generated Markdown report to the user, highlighting:
  • Composite score and risk zone
  • Data freshness warnings (if any data older than 3 days)
  • Strongest warning signal (highest component score)
  • Historical comparison (closest past top pattern)
  • What-if scenarios (sensitivity to key changes)
  • Recommended actions based on risk zone
  • Follow-Through Day status (if applicable)
  • Delta vs previous run (if prior report exists)
向用户展示生成的Markdown报告，重点突出：
  • 综合评分和风险区间
  • 数据新鲜度警告（如有数据超过3天）
  • 最强烈的警告信号（得分最高的组件）
  • 历史对比（最接近的过往顶部模式）
  • 假设场景（关键变量变化的敏感性分析）
  • 基于风险区间的建议操作
  • 跟进日（FTD）状态（如适用）
  • 与上次运行的差异（如存在过往报告）

6-Component Scoring System

六组件评分系统

#ComponentWeightData SourceKey Signal
1Distribution Day Count25%FMP APIInstitutional selling in last 25 trading days
2Leading Stock Health20%FMP APIGrowth ETF basket deterioration
3Defensive Sector Rotation15%FMP APIDefensive vs Growth relative performance
4Market Breadth Divergence15%Auto (CSV) + WebSearch200DMA (auto) / 50DMA (WebSearch) breadth vs index level
5Index Technical Condition15%FMP APIMA structure, failed rallies, lower highs
6Sentiment & Speculation10%FMP + WebSearchVIX, Put/Call, term structure
序号组件权重数据来源核心信号
1派发日计数25%FMP API过去25个交易日内的机构抛售信号
2领涨股健康度20%FMP API成长ETF组合的恶化情况
3防御板块轮动15%FMP API防御板块与成长板块的相对表现
4市场广度背离15%自动获取（CSV）+ WebSearch200日均线广度（自动）/50日均线广度（WebSearch）与指数点位的背离
5指数技术状态15%FMP API均线结构、失败反弹、高点下移
6情绪与投机性10%FMP + WebSearchVIX、看跌/看涨期权比率、期限结构

Risk Zone Mapping

风险区间映射

ScoreZoneRisk BudgetAction
0-20Green (Normal)100%Normal operations
21-40Yellow (Early Warning)80-90%Tighten stops, reduce new entries
41-60Orange (Elevated Risk)60-75%Profit-taking on weak positions
61-80Red (High Probability Top)40-55%Aggressive profit-taking
81-100Critical (Top Formation)20-35%Maximum defense, hedging
评分区间风险预算操作建议
0-20绿色（正常）100%正常操作
21-40黄色（早期预警）80-90%收紧止损，减少新仓位
41-60橙色（风险升高）60-75%对弱势仓位获利了结
61-80红色（顶部概率高）40-55%积极获利了结
81-100危急（顶部形成中）20-35%最大化防御，进行对冲

API Requirements

API要求

Required: FMP API key (free tier sufficient: ~33 calls per execution) Optional: WebSearch data for breadth and sentiment (improves accuracy)
必填：FMP API密钥（免费 tier足够：每次执行约33次调用） 可选：用于市场广度和情绪数据的WebSearch（可提升准确性）

Output Files

输出文件

  • JSON: 
    market_top_YYYY-MM-DD_HHMMSS.json
  • Markdown: 
    market_top_YYYY-MM-DD_HHMMSS.md
  • JSON: 
    market_top_YYYY-MM-DD_HHMMSS.json
  • Markdown: 
    market_top_YYYY-MM-DD_HHMMSS.md

Reference Documents

参考文档

references/market_top_methodology.md

references/market_top_methodology.md

  • Full methodology with O'Neil, Minervini, and Monty frameworks
  • Component scoring details and thresholds
  • Historical validation notes
  • 包含O'Neil、Minervini和Monty框架的完整方法论
  • 组件评分细节和阈值
  • 历史验证说明

references/distribution_day_guide.md

references/distribution_day_guide.md

  • Detailed O'Neil Distribution Day rules
  • Stalling day identification
  • Follow-Through Day (FTD) mechanics
  • 详细的O'Neil派发日规则
  • 滞涨日识别方法
  • 跟进日（FTD）机制

references/historical_tops.md

references/historical_tops.md

  • Analysis of 2000, 2007, 2018, 2022 market tops
  • Component score patterns during historical tops
  • Lessons learned and calibration data
  • 2000、2007、2018、2022年市场顶部的分析
  • 历史顶部期间的组件得分模式
  • 经验总结和校准数据

When to Load References

何时加载参考文档

  • First use: Load 
    market_top_methodology.md
    for full framework understanding
  • Distribution day questions: Load 
    distribution_day_guide.md
  • Historical context: Load 
    historical_tops.md
  • Regular execution: References not needed - script handles scoring
  • 首次使用：加载
    market_top_methodology.md
    以全面了解框架
  • 派发日相关问题：加载
    distribution_day_guide.md
  • 历史背景查询：加载
    historical_tops.md
  • 常规执行：无需参考文档 - 脚本会自动处理评分