Harami Cross

Install and import#

npm install fintech-algorithms

import { haramiCross } from "fintech-algorithms/price-action-and-candlesticks/two-candle-patterns/harami-cross";

Signature#

haramiCross(input)

Scans consecutive pairs of bars for a doji whose body sits inside the previous bar's body, and reports the pattern's direction from the colour of that earlier bar.

Parameters#

Returns#

TopicResult

series.matched is the boolean verdict for the pair ending at that index, and series.label is "bullish" when the first bar closed down, "bearish" when it closed up, and "none" when the pattern failed or the first bar closed exactly at its open. latest carries the last value of each. The warm-up is the one leading bar that has no predecessor.

Warm-up#

The first 1 bar positions are null. The pattern needs a two-bar window, so both series hold null at index 0 and ready_at is 1. From index 1 onward matched is false or true, and false is a real verdict rather than a warm-up placeholder, so ready_at does not depend on any pattern ever firing. A one-bar input returns null throughout, with ready_at null and state "waiting".

Errors#

• When a bar has a non-finite price or volume, a negative volume, a high below its own open/low/close, a low above them, or a timestamp that does not advance — throws Error
• When doji_body_ratio is not a finite number or falls outside 0..1, or tick_tolerance is not a finite number or is negative — throws Error
• When input is not an object, input.parameters is not an object, or bars is not an array holding at least one bar — throws Error

Complexity: time O(n), space O(n).

Worked example#

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input#

{
  "bars": [
    {
      "timestamp": "2024-01-02",
      "basis": "synthetic-unadjusted",
      "open": 100,
      "high": 101.45,
      "low": 98.695,
      "close": 100,
      "volume": 750000,
      "benchmark": 200
    },
    {
      "timestamp": "2024-01-03",
      "basis": "synthetic-unadjusted",
      "open": 101.49111452,
      "high": 103.38381693,
      "low": 100.05480022,
      "close": 101.78791214,
      "volume": 795117,
      "benchmark": 200.56326135
    },
    {
      "timestamp": "2024-01-04",
      "basis": "synthetic-unadjusted",
      "open": 102.45519048,
      "high": 104.6701838,
      "low": 100.91147007,
      "close": 102.9549389,
      "volume": 840234,
      "benchmark": 201.11020913
    }
  ],
  "parameters": {}
}

Call#

haramiCross(input)

Returns#

object with 9 fields: topic_id, title, state, ready, ready_at, series, latest, parameters, …

{
  "topic_id": "D06-F03-A09",
  "title": "Harami Cross",
  "state": "calculated",
  "ready": true,
  "ready_at": 1,
  "series": {
    "label": [null, "none", "none", "none", "none", "none"],
    "matched": [null, false, false, false, false, false]
  },
  "latest": {
    "label": "none",
    "matched": false
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}

Diagrams#

Calculation flow#

flowchart LR
    A["two consecutive closed OHLC candles, tick size, declared g"] --> B["Validate order, basis, and finite values"]
    B --> C["Apply the selected Harami Cross convention"]
    C --> D["Emit value, readiness, and diagnostics"]
    D --> E["Interpret descriptively; test outcomes separately"]
    B -->|invalid or insufficient| X["Withhold output with a reason"]

stateDiagram-v2
    [*] --> Waiting
    Waiting --> Ready: enough valid causal observations
    Waiting --> Rejected: malformed or unsupported input
    Ready --> Calculated: selected formula applied
    Calculated --> Interpreted: diagnostic and limitation retained
    Interpreted --> Ready: next observation arrives
    Rejected --> Waiting: corrected input and deterministic reset

How it works#

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References#

• TA-Lib pattern-recognition catalog — see linked primary or authoritative record
• CME Group candlestick chart lesson — see linked primary or authoritative record
• Japanese Candlestick Charting Techniques — see linked primary or authoritative record
• Evidence decision
• Level 1 evidence map

The rest of the Two-Candle Patterns family#

• Bullish EngulfingEvaluates two candles against explicit bullish-engulfing geometry, scale, and downtrend context conventions.
• Bearish EngulfingEvaluates two candles against explicit bearish-engulfing geometry, scale, and uptrend context conventions.
• Bullish HaramiEvaluates two candles against explicit bullish-harami containment, scale, and downtrend context conventions.
• Bearish HaramiEvaluates two candles against explicit bearish-harami containment, scale, and uptrend context conventions.
• Piercing LineEvaluates two candles against explicit piercing-line gap, midpoint, scale, and downtrend conventions.
• Dark Cloud CoverEvaluates two candles against explicit dark-cloud gap, midpoint, scale, and uptrend conventions.
• Tweezer TopEvaluates two candles against explicit tweezer-top tolerance, rejection, scale, and uptrend conventions.
• Tweezer BottomEvaluates two candles against explicit tweezer-bottom tolerance, rejection, scale, and downtrend conventions.
• Kicking PatternScans consecutive pairs of bars for two near-marubozu candles of opposite colour separated by a clean gap, with no overlap betw…
• Matching LowScans consecutive pairs of bars for two down candles whose closes land within a tick of each other, marking a repeated closing …
• Rising/Falling WindowScans consecutive pairs of bars for a price gap, where the second bar's range clears the first bar's entirely in either direction.