MACD Divergence

MACD Divergence is a reversal strategy that detects when momentum (MACD histogram) is fading even as price continues to make new extremes. The classical setup: price makes a higher high, but MACD makes a lower high — momentum is exhausting.

This is one of the more nuanced strategies in the engine. Implementation correctness matters — naive divergence detectors leak look-ahead bias by referencing future bars to confirm a swing high or low.

Bearish divergence (short entry): the strategy detects a confirmed price swing high that exceeds a previous swing high, while the corresponding MACD histogram swing high is *lower* than the previous MACD swing high. The entry triggers on the bar after the second swing is confirmed.

Bullish divergence (long entry): symmetric — price makes a lower low, MACD makes a higher low.

Critical: swing detection uses a look-back window (default 5 bars), and entries are only taken at confirmedAt (when the swing is no longer ambiguous). This avoids look-ahead bias.

Defaults: MACD 12/26/9, swing lookback 5, divergence window 30 bars, hold 6 bars.

Late-cycle exhaustion phases when a market has been trending strongly and momentum starts to wane before price tops or bottoms. Daily charts on indices and BTC have multiple textbook divergence reversals each year.

Markets with clear cyclical behaviour where swings tend to revert rather than extend indefinitely.

Strong, persistent trends where divergences appear repeatedly but price keeps extending. The famous "stairs up, elevator down" market pattern can produce many false bearish divergences before the actual top.

Sideways markets where every minor swing produces a "divergence" that isn't really one.

Low-volume / illiquid markets where the MACD histogram is too noisy to define real swings.