cot-contrarian-detector

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

COT Contrarian Detector

COT逆向交易检测器

Overview

概述

Implements step 1 of Jason Shapiro's COT (Commitment of Traders) contrarian process: detect when large speculators are crowded into one side of a futures market. Crowded positioning is a precondition for a contrarian trade, not a trade signal — a market only becomes tradable once crowding is confirmed by a news failure and price-action reversal (steps 2-3), which this skill guides the user through manually.

Core thesis (Shapiro): Large speculators (hedge funds, CTAs, momentum traders) tend to be maximally positioned at trend exhaustion, not trend inception. When they are already crowded onto one side, the next big move is statistically more likely to run them over than to reward them further. Fade the speculators, not the commercials (commercials hedge for structural reasons and are not a crowd-psychology signal).

实现Jason Shapiro的COT（Commitment of Traders，交易者持仓报告）逆向交易流程的第1步：检测大型投机者是否集中在期货市场的某一侧。拥挤头寸是逆向交易的前提条件，而非交易信号——只有当拥挤头寸得到消息失效和价格走势反转（第2-3步）的确认后，市场才具备交易价值，本技能会引导用户手动完成这些步骤。

核心论点（Shapiro）： 大型投机者（对冲基金、CTA、动量交易者）往往在趋势末期而非初期达到最大持仓规模。当他们集中在某一侧时，从统计数据来看，下一轮大行情更有可能让他们亏损而非进一步获利。应逆向操作投机者的头寸，而非商业交易者（商业交易者因结构性原因进行对冲，不属于群体心理信号）。

When to Use This Skill

适用场景

English:

"What markets are the speculators crowded into right now?"
"Run a COT report analysis" / "Show me COT positioning extremes"
"Is anyone 'trapped' in gold / the dollar / bonds right now?"
User wants to find contrarian futures setups
User asks for a Jason Shapiro-style COT screen

Japanese:

「COTレポートで買われすぎ・売られすぎのポジションを調べて」
「投機筋が偏っている市場は？」
「ジェイソン・シャピロ式の逆張り分析をして」

Do NOT use when:

The user wants a trade signal right now — crowding alone is not actionable; see Guardrails below
The user is asking about individual equities — COT reports cover CFTC futures markets only (indices, rates, FX, metals, energy, agri, crypto), not single stocks

中文表述参考：

“当前投机者集中在哪些市场？”
“进行COT报告分析” / “展示COT头寸极端情况”
“黄金/美元/债券当前是否有交易者被套牢？”
用户想要寻找逆向期货交易机会
用户要求进行Jason Shapiro风格的COT筛选

日文表述：

「COTレポートで買われすぎ・売られすぎのポジションを調べて」
「投機筋が偏っている市場は？」
「ジェイソン・シャピロ式の逆張り分析をして」

不适用场景：

用户当前想要交易信号——仅拥挤头寸不足以作为交易依据；请参阅下方的注意事项
用户询问个股情况——COT报告仅覆盖CFTC期货市场（指数、利率、外汇、金属、能源、农产品、加密货币），不包含个股

Prerequisites

前置条件

FMP API Key: Required. Set
```
FMP_API_KEY
```
environment variable or pass
```
--api-key
```
. COT endpoints require an FMP Premium+ plan — a free-tier key will not have access.
Python 3.9+ with
```
requests
```
installed.
API Budget: One call per market (23 for
```
--core
```
, up to ~65 for the full universe), plus one call for the market list when neither
```
--symbols
```
nor
```
--core
```
is given.

FMP API密钥： 必需。设置
```
FMP_API_KEY
```
环境变量或通过
```
--api-key
```
参数传入。COT接口需要FMP Premium+套餐——免费版密钥无法访问。
Python 3.9+ 环境，并已安装
```
requests
```
库。
API调用次数限制： 每个市场调用一次API（使用
```
--core
```
参数时为23个市场，全市场模式下最多约65个），若未指定
```
--symbols
```
或
```
--core
```
参数，还需额外调用一次获取市场列表。

Workflow

工作流程

Phase 1: Run the crowding screen

阶段1：运行拥挤头寸筛选

bash

undefined

bash

undefined

Curated core futures universe (23 liquid/representative markets)

精选核心期货市场（23个流动性强、具有代表性的市场）

python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --core --output-dir reports/

Explicit symbols

指定特定标的

python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --symbols "ES,GC,CL" --output-dir reports/

Full universe (all ~65 markets FMP's COT list covers)

全市场模式（覆盖FMP COT列表中的所有约65个市场）

python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --output-dir reports/


The script fetches each market's weekly legacy COT report (large-speculator
long/short positions), computes a 156-week (3-year) and 26-week COT Index per
market, and classifies extremes:

- `CROWDED_LONG` — COT Index >= 90 (near the 3-year net-long high)
- `CROWDED_SHORT` — COT Index <= 10 (near the 3-year net-short high)
- `NEUTRAL` — everything in between

Markets with insufficient history to compute the index are never silently
dropped — they appear in a `skipped` list with the reason (e.g. "insufficient
history: 40/156 weeks").

python3 skills/cot-contrarian-detector/scripts/screen_cot_crowding.py --output-dir reports/


该脚本获取每个市场的每周传统COT报告（大型投机者的多头/空头头寸），计算每个市场的156周（3年）和26周COT指数，并对极端情况进行分类：

- `CROWDED_LONG` — COT指数 >= 90（接近3年净多头高点）
- `CROWDED_SHORT` — COT指数 <= 10（接近3年净空头高点）
- `NEUTRAL` — 介于两者之间的情况

历史数据不足以计算指数的市场不会被静默丢弃——它们会出现在`skipped`列表中，并标注原因（例如："insufficient history: 40/156 weeks"）。

Phase 2: Present the crowding report

阶段2：展示拥挤头寸报告

Present the generated Markdown report, highlighting:

Which markets are
```
CROWDED_LONG
```
/
```
CROWDED_SHORT
```
and by how much
The 26-week index for context (is the crowding fresh or aging?)
Week-over-week net-position swings (fast-moving crowds are more fragile)
The methodology note and disclaimer — crowding is not a trade signal

展示生成的Markdown报告，重点突出：

哪些市场处于
```
CROWDED_LONG
```
/
```
CROWDED_SHORT
```
状态，以及程度如何
26周指数作为背景参考（拥挤头寸是新出现的还是已持续一段时间？）
每周净头寸变化（快速变化的头寸群体更脆弱）
方法说明和免责声明——拥挤头寸并非交易信号

Phase 3: Guide steps 2-5 manually (Shapiro process)

阶段3：手动引导完成第2-5步（Shapiro流程）

For any

CROWDED_LONG

CROWDED_SHORT

market the user wants to pursue, load

references/shapiro-methodology.md

and walk through the remaining steps — these are not automated:

~~Crowding detection~~ (done — this skill)
News failure — use WebSearch to check whether recent news favorable to the crowd's direction failed to move price the way the crowd would expect (e.g. crowded-long market doesn't rally on bullish news). This is the core edge and the most important manual confirmation.
Price-action confirmation — check the weekly chart for a reversal pattern or a failure at a new high/low.
Entry — against the crowd, with a stop at the recent swing extreme and small, fixed-risk sizing (see
```
position-sizer
```
skill).
Exit — when positioning normalizes toward neutral (COT Index back toward 50) or the stop is hit.

Never recommend an entry from crowding alone — steps 2 and 3 must both confirm first.

对于用户想要深入研究的

CROWDED_LONG

CROWDED_SHORT

市场，加载

references/shapiro-methodology.md

并引导完成剩余步骤——这些步骤未实现自动化：

~~拥挤头寸检测~~（已完成——本技能实现）
消息失效——使用WebSearch检查近期对群体持仓方向有利的消息是否未如群体预期推动价格走势（例如：处于拥挤多头状态的市场在利好消息下并未上涨）。这是核心优势，也是最重要的手动确认步骤。
价格走势确认——查看周线图是否出现反转形态，或在新高/新低位置出现走势失效。
入场——逆向操作群体头寸，止损设置在近期波动极值处，并采用小额固定风险仓位（参阅
```
position-sizer
```
技能）。
离场——当头寸回归中性（COT指数回到50附近）或触发止损时离场。

绝不要仅根据拥挤头寸推荐入场——必须先完成第2步和第3步的确认。

Output

输出结果

JSON:
```
reports/cot_crowding_<as-of-date>.json
```
— machine-readable, with a
```
run_context
```
block (schema_version, params, universe, data_date) plus
```
markets
```
(ranked results) and
```
skipped
```
(never silently dropped).
Markdown:
```
reports/cot_crowding_<as-of-date>.md
```
— human-readable report with Crowded Long / Crowded Short / Full Ranking / Week-over-Week Swings / Skipped Markets / Methodology sections.

JSON文件：
```
reports/cot_crowding_<as-of-date>.json
```
— 机器可读格式，包含
```
run_context
```
块（schema_version、参数、市场范围、数据日期），以及
```
markets
```
（排名结果）和
```
skipped
```
（未被静默丢弃的市场）。
Markdown报告：
```
reports/cot_crowding_<as-of-date>.md
```
— 人类可读格式的报告，包含拥挤多头/拥挤空头/完整排名/每周头寸变化/跳过的市场/方法说明等章节。

Cadence

运行频率

CFTC publishes the COT report Fridays ~3:30pm ET, with positions as of the prior Tuesday — data is always 3+ days old by the time it's published, and up to 9 days old by the following Friday. Run this skill:

Weekly, after Friday's publication or over the weekend, for a fresh read
Ad hoc, when the user asks about a specific market's positioning — the underlying data will be from the most recent Friday release either way

CFTC于美国东部时间周五约15:30发布COT报告，报告中的头寸数据截止到上周二——发布时数据已滞后3天以上，到下周五时最多滞后9天。运行本技能的时机：

每周一次：在周五报告发布后或周末运行，获取最新数据
按需运行：当用户询问特定市场的头寸情况时运行——无论何时运行，基础数据均来自最近一次周五发布的报告

Guardrails

注意事项

Crowdedness alone is NOT a trade signal. It is a precondition. Never suggest an entry without steps 2 (news failure) and 3 (price action) from
```
references/shapiro-methodology.md
```
also confirming.
Data is lagged. COT positions are 3-9 days old by the time they're read; do not treat them as a real-time signal.
Fade speculators, not commercials. This skill only looks at non-commercial ("large speculator") positioning — commercial hedging flows are structurally different and not a crowd-psychology signal.
Not investment advice. All output is for research/educational purposes.

仅拥挤头寸并非交易信号。 它只是前提条件。在未通过
```
references/shapiro-methodology.md
```
中的第2步（消息失效）和第3步（价格走势）确认之前，绝不要建议入场。
数据存在滞后性。 COT头寸数据在读取时已滞后3-9天；请勿将其视为实时信号。
逆向操作投机者，而非商业交易者。 本技能仅关注非商业交易者（“大型投机者”）的头寸——商业交易者的对冲流具有结构性差异，不属于群体心理信号。
不构成投资建议。 所有输出仅用于研究/教育目的。

Resources

参考资源

references/shapiro-methodology.md

references/shapiro-methodology.md

The full 5-step process (crowding → news failure → price action → entry → exit), why speculators (not commercials) are the fade target, the 3-day publication lag caveat, and a table of what this skill automates vs. what stays manual. Load this whenever guiding a user past step 1.

完整的5步流程（拥挤头寸→消息失效→价格走势→入场→离场），解释为何选择投机者而非商业交易者作为逆向操作目标，说明报告3天滞后性的注意事项，以及本技能自动化内容与手动内容的对比表。当引导用户完成第1步之后时，加载此文档。

references/cot-index-calculation.md

references/cot-index-calculation.md

The COT Index formula, lookback rationale (156w primary / 26w context), extreme threshold sensitivity, open-interest normalization rationale, the legacy-vs-disaggregated report distinction (this skill uses the legacy report's non-commercial = large-speculator fields), and a glossary of the FMP COT API field names consumed by

scripts/cot_index.py

包含COT指数计算公式、回溯周期的依据（156周主周期/26周背景周期）、极端阈值的敏感性分析、持仓量归一化的依据、传统报告与分类报告的区别（本技能使用传统报告中的非商业交易者=大型投机者字段），以及

scripts/cot_index.py

所使用的FMP COT API字段术语表。

When to Load References

何时加载参考文档

First use / explaining the methodology: Load
```
references/shapiro-methodology.md
```
Explaining a specific number in the report: Load
```
references/cot-index-calculation.md
```
Regular execution: References not needed — the script handles the crowding computation

首次使用/解释方法： 加载
```
references/shapiro-methodology.md
```
解释报告中的特定数值： 加载
```
references/cot-index-calculation.md
```
常规执行： 无需加载参考文档——脚本会自动处理拥挤头寸计算