COTVault Premium · Instruction Guide

COT Divergence

COTVault+ Div · Pine v6 · weekly / daily charts · FX majors, crosses & US futures

Finds momentum divergences and tells you how often they've actually resolved — measured across 12 markets and 26 years of CFTC data, against a base rate. It doesn't tell you to buy or sell. It validates its own claim so you can weigh it against your own system.

1 · Quick start

Load it on a weekly chart. COT data is weekly by nature — every statistic in this guide was measured on weekly bars. Daily works but the numbers no longer apply.
Use a market with CFTC data. FX majors, FX crosses, and US futures (6E, 6B, GC, CL, ZC…). If the panel says "No COT market mapped", the symbol has no CFTC contract behind it.
Leave the gates at their defaults. Bear gate ON, bull gate OFF. That is the tested configuration — see §4 for why the asymmetry exists.
Watch the "Resolved on this chart" row. It counts how many divergences on your market actually resolved. That's your own verification of the published numbers.

2 · Why divergence is measured on the stochastic

The intuitive way to build a COT divergence tool is to look for divergence between price and positioning — and that is how most COT tools would ship it. We built it that way, tested it across 12 markets and 26 years, and it does not work:

Divergence detected on…	2 wk lift	3 wk	4 wk	Markets positive
Positioning (the intuitive build)	−2.4	−2.5	−3.2	3–5 / 12
Stochastic (what this ships)	+7.2	+4.8	+4.6	10 / 12

Both rows are the ungated signal, so the two builds are compared like for like. The 2-week column is the window everything else in this guide uses; the 3- and 4-week columns are shown only to make the point that the positioning build is negative at every horizon, not just the one we picked.

Negative lift at every window means that claim is worse than random. So this indicator does it the other way round: divergence is detected on the 9-3-3 stochastic, and COT positioning is the gate rather than the divergence series.

Why we show you the failure. Every number in this guide can be reproduced from public CFTC data. Publishing the approach that failed next to the one that worked is deliberate — a vendor who only ever shows you winning numbers has not told you how many they tried.

3 · Reading the pane

Blue heat line — the StochasticThe divergence detector (9/3/3). Colour shifts teal → blue → red as it rises. Divergences are drawn on this line.

Gold line — Large Speculator positioningThe COT index, 0–100. This is the gate, not the divergence series. On cross pairs it's the COTVault two-leg synthetic.

Gold shading — positioning at an extremeCrowded long (≥80) or crowded short (≤20). Gold marks a state, never a direction — crowded long is not a sell signal, and that claim was tested and rejected. Inside crowded-long, the bear gate is open.

Red line + "BEAR" tagTwo stochastic peaks joined: the second is lower while price made a higher high. A red triangle also prints above the price bar.

Teal line + "BULL" tagTwo stochastic troughs joined: the second is higher while price made a lower low. Teal triangle below the price bar.

4 · The two signals & their numbers

Resolution is defined as: price makes a 4-week extreme in the signal's direction within 2 weekly reports. The base rate is how often that happens from any randomly chosen bar — that's the control, and the difference between them is the only number that means anything.

Signal	Resolved	Base rate	Lift	Markets	Sample
BEAR — stoch bearish divergence with specs crowded long	54%	45%	+8.8	9 / 12	87
BULL — stoch bullish divergence, ungated	58%	50%	+8.0	11 / 12	198

These are the figures the shipped engine earns. The pivot is compared on the high and low of the bar, which is what the Pine does. An earlier study compared closes and produced a different, slightly lower set; those numbers are retired and appear nowhere in this product.

The asymmetry is measured, not assumed

Adding the COT gate helps one side and destroys the other:

	Ungated	With COT gate	Verdict
Bear divergence	+7.2	+8.8	gate ON by default
Bull divergence	+8.0	+0.5 (3/9 mkts)	gate OFF by default

The bull row's 9 is not a typo against the 12-market universe elsewhere: the backtest drops any market with fewer than five gated signals, and gating the bull side leaves only nine markets with enough to measure. That thinning is itself part of why the gate hurts.

Both gate toggles are exposed in Settings so you can reproduce the failure yourself. Turning the bull gate on will make the indicator worse — it's there for verification, not tuning.

Does it survive out-of-sample?

Split at 2010: fitted before, checked on 2010–2026 untouched.

Signal	Full sample	Before 2010	2010–2026
BULL, ungated	+8.0 (n=198)	−2.4 (n=34)	+8.2 (n=140)
BEAR, gated	+8.8 (n=87)	not testable — only 5 gated signals, in a single market
BEAR, ungated (reference)	+7.2 (n=250)	+12.0	+4.8

The bear gate cannot be walk-forward tested, and we are not going to pretend otherwise. The gate is rare: before 2010 it produces five signals in one market, which is not a sample. Its +8.8 rests on the full 26-year run and on breadth — 9 of 12 markets positive — not on an out-of-sample split. The ungated bear signal, which does have the sample for it, holds in both halves. Treat the bear side as the thinner of the two claims in this indicator.

5 · The data panel, row by row

Row	What it tells you
Stochastic	Current %K with a meter, plus overbought / oversold / mid. The meter colour and the word are driven by the same rule, so they can never disagree. This is the series divergences are measured on.
Positioning	The COT index 0–100 and its crowding state, in gold. When it reads CROWDED LONG · gate armed, bear divergences are permitted. Gold means at an extreme, not bearish.
BEAR divs / BULL divs	How many of each have fired across the loaded history on this market. Each label and its count sit in one coloured chip, so the number always belongs to the word beside it.
Resolved on this chart	The important one. Of the divergences on your chart, how many resolved within 2 reports. Compare it to the 54–58% published figures. Expect variance — a single market is a small sample.
Verdict row	Plain English, with the measured rate attached. Stays lit for six bars after a signal.
Config line	Stochastic length, pivot settings, and whether each gate is in its tested position.

Worked example. On 6A1! weekly the panel reads 67% of 33 signals — above the pooled 54–58%. That's a favourable market, not proof the indicator is better than published. Check several markets before drawing conclusions.

6 · Settings reference

Setting	Default	What it does
Pivot left / right	3 / 3	How many reports either side define a peak. Tested 2/2 through 5/5 — all positive; 3/3 strongest on the bear side. Right also sets the confirmation lag.
Stochastic %K length	9	The 9-3-3 stochastic default. Changing it invalidates the published statistics.
Max reports between peaks	52	Two peaks further apart than this won't be paired.
Keep last N divergences	12	Older lines are deleted so long look-backs don't turn into spaghetti.
Gate BEAR on crowded longs	ON	The tested configuration. Off drops the lift from +8.8 to +7.2.
Gate BULL on crowded shorts	OFF	The tested configuration. On drops it from +8.0 to +0.5, positive in only 3 of the 9 markets that produce enough gated signals to measure.
Positioning line	on	The gold gate series. Turning it off hides the line, not the gate.
Price percentile line	off	Context only — where price sits in its own range. Takes no part in the signal.
Connect the diverging peaks	on	Draws the two lines that make the divergence visible.
Arrows on the price chart	on	Mirrors each signal onto the price pane.
Crowded LONG / SHORT levels	80 / 20	Percentile thresholds for the gate and the shading.
COT Index lookback	156	Weekly reports used to rank positioning. 156 ≈ 3 years, the classic setting.
Include options data	off	Futures-only is the COTVault standard and matches the dashboard. Turning this on makes the two disagree.
Data box position / size	Top right / Normal	Eight anchor points. Compact keeps the header, the Stochastic row, the verdict and the link, and drops the detail rows in between.
Show the full guide on the chart	off	Renders the on-chart manual as a panel. TradingView always drops the ⓘ tooltip downward, so it runs off screen when the data box sits low — this is the way around it.
Guide position / text size	Middle left / Small	Nine anchor points, independent of the data box so the two never collide.

7 · Alerts

Three alert conditions ship with the indicator. Add them the normal way — right-click the chart, Add alert, then pick the condition from the dropdown.

Alert	Fires when
BEARISH divergence (gated)	A bear divergence confirms with specs crowded long. The message carries the measured rate so the alert itself states its own accuracy.
BULLISH divergence	A bull divergence confirms. Ungated, which is the tested configuration.
New COT report ingested	A fresh weekly CFTC release lands — useful as a Friday review prompt rather than a trade signal.

Set alerts to Once per bar close. A divergence confirms on the pivot-right lag, so an intrabar alert would fire on a peak that can still un-form.

8 · How to actually use it

This indicator is context, not a trade trigger. It answers one question — "is momentum diverging, and how often does that resolve?" — and hands the entry decision back to you.

Let it flag the condition. A BEAR tag means momentum is fading while price makes new highs, with the crowd already positioned long.
Go to your own chart structure. Where is price relative to your levels? A divergence into resistance is a very different proposition from one in open space.
Use your own entry rules. The published figure says price made a 4-week extreme within 2 reports 54% of the time on the gated bear signal, 58% on the bull. It says nothing about where to enter, how much to risk, or where to exit.
Weight it by the gate. A bear divergence with positioning at 85 carries the tested +8.8 lift. The same divergence with positioning at 50 doesn't fire at all by default — and that's deliberate.

9 · Reading the colours

One colour language runs across the whole COTVault suite, so a colour never means two things:

Colour	Meaning
GOLD	A state, never a direction. Positioning is at an extreme, and inside crowded-long the bear gate is armed. Gold does not mean bearish — that claim was tested at 46.7% against a 45.2% base rate and rejected.
RED	A bearish signal has actually fired — a BEAR divergence line, tag and arrow.
TEAL	A bullish signal has actually fired.
SLATE	Neutral. Nothing measured is happening.

In the panel a meter's colour always matches the word printed beside it — if they ever disagree, that is a bug worth reporting. The stochastic line in the pane is the one exception: it keeps a continuous teal→blue→red heat ramp, because there it is a thermometer showing level, not a verdict. That is the ordinary convention for reading an oscillator and it makes no COT claim — unlike the gate bands, which are gold, because crowding arms a gate rather than pointing a direction.

10 · Limitations — read this

These are resolution rates, not returns. "54% resolved" means the price event happened. It says nothing about magnitude, drawdown, spread, or whether a trade built on it would be profitable. A 54% hit rate with poor payoff still loses money.

Pivots confirm late. A peak isn't known until pivot right reports after it forms — three weeks at the default. This lag is inherent to pivot detection and cannot be removed by any indicator.
Weekly only. Every figure was measured on weekly bars. On daily charts the signals still draw, but the statistics don't transfer.
Futures prices, not spot. Resolution was measured on futures weekly OHLC. On a spot FX chart the reading is transferred, not measured.
On a cross the gate is much harder to arm. A cross has no CFTC contract, so positioning is a two-leg synthetic and the rescaling halves the scale — the same 80/20 gate fires far less often than on a major, and no cross was in the tested twelve. Use a major or a futures contract for the gated bear signal.
Sample sizes are modest. The gated bear signal rests on 87 events across 12 markets and 26 years. Real, but not enormous — expect single markets to vary widely.
Breadth is not universal. Bear works in 9 of 12 markets, bull in 11 of 12. Some markets simply don't cooperate.
The bear side is the thinner one. Its gate is rare — 87 signals in 26 years, and only five of them before 2010, so it cannot be walk-forward tested. The bull side has both the sample and the split. Tops and bottoms form differently and the indicator reflects that rather than pretending to symmetry, but do not read the bear gate as the stronger claim just because its lift is larger.

11 · Methodology

Data — CFTC Legacy, futures-only, pulled from the CFTC's own public API. 12 markets: 7 FX majors, US Dollar Index, gold, silver, WTI crude, corn. The CFTC series reaches back to 1986, but the measured sample is bounded by the weekly price join: 2000–2026 for ten markets, 2003 for NZD — 16,284 market-weeks, about 26 years.
Price — weekly continuous futures, aligned to each report date.
Divergence — pivot highs/lows on %K, compared with the BAR HIGH at each pivot high and the BAR LOW at each pivot low. Signals are stamped at the confirmation bar, never the pivot bar, so nothing uses information that didn't exist yet.
Base rate — the same resolution event measured across all bars in the same market. Every published figure is conditional-minus-base.
Walk-forward — split at 2010 with no adjustment. The bull signal holds (+8.2 after, on 140 signals). The gated bear signal has only five pre-2010 signals in one market, so no honest split exists and none is claimed; see §4.
Sensitivity — pivot settings swept 2/2 through 5/5; all positive, so the result isn't a single-setting artifact.
Publication lag — CFTC reports Tuesday positions on Friday. Signals were also tested with a full extra week of delay; the edge held.

Same report, same mode, same contract codes as the COTVault dashboard — so the indicator and the site never disagree.