Candle Anatomy

Install and import#

npm install fintech-algorithms

import { analyzeCandle } from "fintech-algorithms/price-action-and-candlesticks/candle-foundations/candle-anatomy";

Signature#

analyzeCandle(candle, directionEpsilon)

Decomposes one candle into body, upper and lower shadow, and direction. Every candlestick pattern is built on these measurements, so an inconsistent decomposition propagates into every pattern above it.

Parameters#

Returns#

{ open, high, low, close, body, upper_shadow, lower_shadow, direction, … }

Every measurement a pattern rule needs, in price units.

Errors#

• When high is below low, or open or close falls outside the range — throws

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

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

{
  "timestamp": "2026-01-05T10:00:00Z",
  "instrument_id": "SYNTH:ABC",
  "interval": "5m",
  "open": 100,
  "high": 108,
  "low": 97,
  "close": 105,
  "is_closed": true,
  "price_basis": "raw-trades",
  "session": "synthetic-utc"
}

0

Call#

analyzeCandle(candle, directionEpsilon)

Returns#

object with 23 fields: open, high, low, close, timestamp, instrument_id, interval, is_closed, …

{
  "open": 100,
  "high": 108,
  "low": 97,
  "close": 105,
  "timestamp": "2026-01-05T10:00:00Z",
  "instrument_id": "SYNTH:ABC",
  "interval": "5m",
  "is_closed": true,
  "volume": null,
  "price_basis": "raw-trades",
  "session": "synthetic-utc",
  "body_high": 105,
  "body_low": 100,
  "body": 5
}

Showing 14 of 23 fields.

Other exports#

This module also exports analyzeCandles. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams#

Calculation flow#

stateDiagram-v2
    [*] --> Collecting
    Collecting --> Provisional: first eligible price
    Provisional --> Provisional: new trade updates high, low, or close
    Provisional --> Closed: interval ends
    Closed --> Revised: provider correction
    Revised --> Closed: corrected OHLC republished
    Closed --> [*]

flowchart TD
    A["Receive OHLC and metadata"] --> B{"All OHLC values finite?"}
    B -->|"No"| X["Reject with validation error"]
    B -->|"Yes"| C{"High and low contain open and close?"}
    C -->|"No"| X
    C -->|"Yes"| D["Compute body high and body low"]
    D --> E["Compute body, shadows, and range"]
    E --> F["Assign direction using epsilon"]
    F --> G{"Range greater than zero?"}
    G -->|"Yes"| H["Compute component ratios and positions"]
    G -->|"No"| I["Set ratios and positions to null"]
    H --> J["Return anatomy and metadata"]
    I --> J

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#

• Chart Types: Candlestick, Line, Bar — CME Group
• Candlestick chart definition — Nasdaq
• Kline/Candlestick Streams — Binance
• RFC 3339: Date and Time on the Internet: Timestamps — G. Klyne and C. Newman, Internet Engineering Task Force
• NYMEX and COMEX Definitions: Settlement Price — CME Group
• Evidence classification

The rest of the Candle Foundations family#

• Scale-Aware Body ClassificationClassifies a candle body as long, short or doji **relative to recent bodies** rather than against a fixed threshold.
• Shadow-to-Body RatioDecomposes one OHLC candle and reports raw and tick-stabilized shadow-to-body ratios without hiding the zero-body case.
• Gap ClassificationClassifies full-range, body, or opening gaps in either direction using an explicit tick-scaled minimum distance.
• Trend-Context FilterClassifies prior closes as an uptrend, downtrend, or sideways context from normalized net movement and path efficiency.