04/02/026 Cup & Handle

1.1 Indicator Concept

The Cup & Handle indicator is based on the theory of market psychology patterns discovered by William O'Neil. This pattern believes that:

• Cup Phase: Represents the process where price gradually declines, forms a bottom, then recovers back to the initial level. This is the market "consolidation" phase after a previous uptrend, where weak sellers exit and strong buyers accumulate.
• Handle Phase: After the cup forms, price has a small pullback creating the handle. This is the final "test" before the breakout.
• Breakout: When price breaks above the cup's rim, this signals a strong uptrend is about to occur, with a price target equal to the cup's depth.

This indicator automatically detects both bullish patterns (Cup & Handle) and bearish patterns (Inverted Cup & Handle) based on price pivot points (swing highs/lows).

1.2 Indicator Features

• Display Cup & Handle Pattern:
  • Cup Curve: Drawn with curved polyline connecting 3 points: left rim → cup bottom → right rim. Green for bullish pattern, red for bearish pattern.
  • Handle Curve: Drawn from right rim → handle low → projected breakout point. Same color as cup.
  • Filled Area: Light color fill inside cup and handle for easy identification.
  • Pattern Label: Displays "Cup+Handle" or "Inv Cup+Handle" text at cup center.
  • Target Line: Horizontal line showing price target after breakout, calculated as: Rim Price ± (Cup Depth × Target Multiplier)
• Alerts:
  • "Cup & Handle (Brewed)": Triggers when valid bullish pattern is detected.
  • "Inverted Cup & Handle (Brewed)": Triggers when valid bearish pattern is detected.

1.3 How to Use the Indicator

• Identify Entry Opportunities: When the indicator draws a Cup & Handle pattern and price breaks out from the rim (if "Require breakout confirmation" is enabled), this is a signal to enter BUY (bullish pattern) or SELL (bearish pattern).
• Set Take Profit Target: Use the Target Line as the profit-taking level. Default is 0.5× cup depth, adjustable via "Target multiplier".
• Set Stop Loss: Place SL below the "Invalidation" level (default 61.8% of handle depth from rim). If price touches this level, the pattern is invalidated.
• Filter Quality Signals: Adjust parameters like "Rim similarity tolerance", "Handle retrace min/max" to filter more accurate patterns and reduce noise.
• Combine with Larger Timeframes: Cup & Handle pattern works best on H4, Daily, Weekly timeframes. Avoid using on very small timeframes (M1, M5) due to noise.

1.4 How the Indicator Works

Inputs & Roles

• pivotSpan (Integer, default: 10): Number of bars needed to confirm a swing high/low (pivot). For example, pivotSpan=10 means 10 bars on the left and 10 bars on the right must all be lower (for high) or higher (for low) to confirm a pivot. Increase pivotSpan → fewer but stronger pivots, fewer patterns but higher quality. Decrease pivotSpan → more pivots, more signals but more noise.
• rimTolPct (Integer %, default: 18%): Allowed deviation between left rim and right rim of the cup. For example, if left rim is at $100, right rim at $110, deviation = 10%. If rimTolPct=18%, it's accepted; if rimTolPct=5%, it's rejected. Decrease rimTolPct → cup must be more balanced, fewer patterns but more accurate. Increase rimTolPct → accept more unbalanced cups, more patterns.
• hMin (Float, default: 0.12): Minimum depth of handle relative to cup depth. For example, if cup is $100 deep, handle must be at least $12 deep (0.12×100). Too small → handle too shallow, insufficient "test", weak signal.
• hMax (Float, default: 0.55): Maximum depth of handle. For example, if cup is $100 deep, handle cannot be deeper than $55. Too large → handle too deep, messy pattern, no longer a standard Cup & Handle.
• killAtFib (Float, default: 61.8%): Pattern "invalidation" level. If price drops below 61.8% of handle depth (from rim), pattern is broken. This is the safe Stop Loss level. Decrease → tighter SL, less risk but easier to stop out early. Increase → looser SL, accept larger swings.
• needConfirm (Boolean, default: false): Whether to require price breakout past rim. false → early detection as soon as pattern forms. true → only triggers when price has broken past rim, higher quality signal but later.
• targetMult (Float, default: 0.5): Multiplier to calculate price target. For example, cup depth $100, rim at $200, target = 200 + (100×0.5) = $250. Increase → farther target, larger profit but harder to reach. Decrease → closer target, easier to reach but smaller profit.
• showName, bgBull, lnBull, bgBear, lnBear, wOk, stOk, showTarget, targetWidth, targetStyle: Display options (show/hide label, colors, line width, line style). Don't affect detection logic, only visual appearance.

Main Logic Blocks

🎯 Flow 1: Cup & Handle Pattern Detection

• Step 1 - Collect Pivots (Swing Highs/Lows):
  • The indicator uses ta.pivothigh() and ta.pivotlow() functions to find swing highs and lows based on pivotSpan.
  • Each time a pivot is found, it's saved to a "pivot list" (array) with 3 pieces of information: price (p), bar position (i), direction (d) (+1 = high, -1 = low).
  • This list only keeps the most recent 12 pivots (if more than 12, the oldest pivot is deleted).
  • Example: If pivotSpan=10, price makes a high at bar 100 with price $50, and 10 bars before + 10 bars after are all below $50, then this pivot is saved: {p: 50, i: 100, d: +1}.
• Step 2 - Identify Valid 4-Pivot Sequence:
  • The indicator takes the 4 most recent pivots from the list: s0, s1, s2, s3.
  • Bullish pattern (Cup & Handle): Sequence must be: High → Low → High → Low (s0.d=+1, s1.d=-1, s2.d=+1, s3.d=-1).
  • Bearish pattern (Inverted Cup & Handle): Sequence must be: Low → High → Low → High (s0.d=-1, s1.d=+1, s2.d=-1, s3.d=+1).
  • Bullish pattern example: s0 = high $100 (left rim), s1 = low $80 (cup bottom), s2 = high $98 (right rim), s3 = low $92 (handle low).
• Step 3 - Validate Cup Conditions:
  • Rim similarity: Compare prices of s0 (left rim) and s2 (right rim). If deviation ≤ rimTolPct%, it's valid.
  • Example: s0=$100, s2=$110, deviation = |100-110|/100 = 10%. If rimTolPct=18% → valid. If rimTolPct=5% → rejected.
  • Calculate cup depth: depth = |rimPrice - Bp|, where rimPrice = min(s0, s2) for bullish pattern, or max(s0, s2) for bearish pattern.
  • Bullish pattern example: s0=$100, s2=$98, s1=$80 → rimPrice=$98 (take lower), depth=|98-80|=$18.
• Step 4 - Validate Handle Conditions:
  • Calculate handle depth (hRet): hRet = |rimPrice - Hp| / depth, where Hp is the price of s3 (handle low).
  • Example: rimPrice=$98, Hp=$92, depth=$18 → hRet = |98-92|/18 = 6/18 = 0.33 (33%).
  • Check hRet is within [hMin, hMax]: If hMin=0.12, hMax=0.55, then 0.33 is within range → valid.
  • Check handle position: For bullish pattern, Hp must be < rimPrice (handle must be below cup rim). For bearish pattern, Hp must be> rimPrice.
• Step 5 - Check Breakout (if needConfirm enabled):
  • If needConfirm=true, indicator only triggers when closing price (close) breaks past rimPrice.
  • Bullish pattern: close > rimPrice.
  • Bearish pattern: close < rimPrice.
  • If needConfirm=false, skip this step, trigger as soon as pattern forms.
• Step 6 - Remove Duplicates:
  • Check if new pattern duplicates a previous pattern (based on rim position and rim price).
  • If duplicate (deviation < 0.15%), skip to avoid drawing multiple times.

🎨 Flow 2: Draw Pattern on Chart

• Draw Cup Curve:
  • Create 3 points: point 1 (Li, rimPrice), point 2 (midBar, Bp), point 3 (Ri, rimPrice).
  • Use polyline.new() function with curved=true parameter to draw curved line connecting these 3 points.
  • Line color and fill color chosen based on bullish/bearish pattern (bgBull/lnBull or bgBear/lnBear).
• Draw Handle Curve:
  • Create 3 points: point 1 (Ri, rimPrice), point 2 (Hi, Hp), point 3 (projBar, rimPrice).
  • projBar = Hi + (Hi - Ri), meaning extend handle forward to create complete handle shape.
  • Draw similar to cup, using curved polyline.
• Draw Target Line:
  • If showTarget=true, draw horizontal line from Ri to Hi+25 bars, at price level tgtPrice.
  • tgtPrice = Rp + (depth × targetMult) for bullish pattern, or Rp - (depth × targetMult) for bearish pattern.
  • Example: Rp=$98, depth=$18, targetMult=0.5 → tgtPrice = 98 + (18×0.5) = $107.
• Draw Pattern Label:
  • If showName=true, draw label "Cup+Handle" or "Inv Cup+Handle" at cup center (midBar, rimPrice).

🔔 Flow 3: Trigger Alerts

• When a valid pattern is detected, variable newSignal = true and newSide = +1 (bullish) or -1 (bearish).
• Function alertcondition() checks this condition and triggers corresponding alert.
• Alert "Cup & Handle (Brewed)": Triggers when newSignal=true and newSide=+1.
• Alert "Inverted Cup & Handle (Brewed)": Triggers when newSignal=true and newSide=-1.

Outputs & Usage Roles

• Cup & Handle Curves: Help traders visually identify the pattern on chart, determine accumulation zone and potential breakout point.
• Target Line: Shows price target for profit-taking, based on cup depth theory.
• Invalidation Level (invPrice): Price level where if touched, pattern is broken. Used to set Stop Loss. Example: invPrice = Rp - (depth × 0.618) for bullish pattern.
• Alerts: Timely notifications when pattern appears, helping traders not miss opportunities.