Tool
Candlestick Patterns
market.candlestick_patterns
Inputs
No typed inputs.
Outputs
A per-bar event feed of detected candlestick patterns, each carrying the pattern's name (engulfing, hammer, doji, dark-cloud, morning star, …) and its bullish or bearish bias. Feed it into interpretor.candlestick_pattern to turn a named formation into a tradable signal.
Scans the last few candles and tells you when a classic reversal shape prints — engulfings, hammers, dojis, dark-cloud covers, morning/evening stars and more. Each detected pattern is reported with its name and direction so you can fade or follow the turn it suggests.
How it works
It reads each bar's open, high, low and close and measures body size, wick length and gaps relative to a rolling average body, then matches those proportions against a library of named candlestick formations. A pattern only qualifies if the candle geometry passes its ratio tests and the prior trend (judged over trend_lookback bars by the trend_method) points the right way for a reversal.
Modes
Judges the prior trend by the net price change (momentum) over trend_lookback bars — if price is up over the window the context is an uptrend, so only bearish reversal patterns qualify, and vice versa.
When to use: The faster, more responsive context check; good when you want recent swing direction rather than a smoothed average to gate the patterns.
Judges the prior trend by comparing price to a simple moving average over trend_lookback bars — price above the rising average means uptrend context, price below a falling average means downtrend context.
When to use: The smoother, steadier context check; prefer it when you want fewer whipsaws in the trend gate so patterns are only accepted within a cleanly established move.
Configuration
Maximum body-to-range ratio for a candle to count as a doji (a near-zero body with the open and close almost equal). Smaller values demand a flatter, more textbook doji; 0.1 means the body may be at most 10% of the full range.
The body-to-average-body ratio below which a candle is treated as having a 'short' body, used by star and harami logic. Lower values require a smaller body to qualify as short.
The body-to-average-body ratio above which a candle is treated as having a 'long' body, used to confirm the strong candle in engulfing, marubozu and star patterns. Higher values demand a more dominant body.
Minimum ratio of the long lower shadow to the body for a hammer (or to the upper shadow for a shooting star). Larger values require a more pronounced rejection wick before the pattern qualifies.
Maximum allowed upper shadow for a hammer, expressed relative to the body, so a true hammer has little or no wick on top. Smaller values enforce a cleaner hammer with the close near the high.
How much larger the engulfing candle's body must be than the body it swallows, as a ratio. 1.0 means it must merely cover the prior body; values above 1.0 require it to be visibly bigger.
For a dark-cloud cover (and its bullish mirror, the piercing line), the minimum fraction the second candle must close back into the first candle's body. 0.5 is the classic 'past the midpoint' requirement.
For morning- and evening-star patterns, how far the third candle must close into the first candle's body to confirm the reversal. Higher values demand a more decisive recovery or rejection.
Tolerance, as a fraction of price, for treating two levels as equal — used to detect matching opens, closes or wicks in tweezers and harami patterns. Larger values accept slightly mismatched levels as 'equal'.
Minimum price gap between candles required by gap-dependent patterns such as stars and abandoned-baby formations. Larger values insist on a clearer gap before those patterns qualify.
How many bars back the tool looks to decide the prior trend that a reversal pattern must reverse. Longer windows judge the bigger swing; shorter windows react to the most recent leg.
How the prior trend is measured before a reversal pattern is accepted: 'momentum' uses the net price change over the lookback, 'sma' compares price to a simple moving average. The trend must oppose the pattern (e.g. an uptrend for a bearish engulfing) for it to fire.
The moving-average type used to compute the rolling average body that 'short' and 'long' body tests are measured against (for example simple or exponential). It sets how quickly the average body adapts to recent candles.
Connects to
Examples
- Reversal trigger: in an uptrend context (trend_method 'sma'), fire a short when a bearish engulfing prints with engulfing_min_ratio at 1.1.
- Confirmation filter: gate long entries to only the bars where a bullish hammer or piercing line is detected near support.
Common mistakes
- Loosening doji_body_ratio and the body ratios so far that almost every candle matches some pattern — the detector then fires constant noise instead of rare, meaningful turns.
- Forgetting the trend gate: a bearish engulfing inside a downtrend is just continuation, not a reversal, so a mismatched trend_method / trend_lookback suppresses the patterns you expected.