# Heikin-Ashi Transform

`D07-F08-A05` · Technical Indicators → Price Transforms · archetype `series-transform` · difficulty 2/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/technical-indicators/price-transforms/heikin-ashi-transform/
Agent skill: `npx skills add IslamBaraka90/Fintech-Algorithms-Library` — https://docs.thefintechbuilder.com/guides/agent-skill/

## Install and import

```bash
npm install fintech-algorithms
```

```ts
import { heikinAshiTransform } from "fintech-algorithms/technical-indicators/price-transforms/heikin-ashi-transform";
```

## Signature

```ts
heikinAshiTransform(input)
```

Rebuilds each bar as a Heikin-Ashi candle, averaging OHLC into the smoothed close and carrying the smoothed open forward from the previous candle.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `input` | `TopicInput` | yes | `bars` needs `timestamp`, `open`, `high`, `low` and `close`. This topic reads no keys from `parameters`, though `parameters` must still be an object when supplied. |

## Returns

`TopicResult`

`series` holds `open`, `high`, `low` and `close`, the four smoothed candle legs, and `latest` carries the last element of each. The smoothed close is `(open + high + low + close) / 4`; the smoothed open is the midpoint of the raw open and close on the first bar and thereafter the midpoint of the previous smoothed open and close; the smoothed high and low extend the raw ones to include both. Every bar produces values, so there is no positional warm-up.

## Warm-up

The first `none` positions are `the first smoothed open is seeded from the first bar's own open and close`. `ready_at` is 0, but the smoothed open is recursive, so the whole series depends on which bar the input starts at. Two runs over different slices of the same history do not agree exactly until the seed has decayed.

## Errors

- When a bar's `open`, `high`, `low` or `close` is not a finite number — throws Error
- When a `high` is below the bar's `open`, `low` or `close` — throws Error
- When timestamps are not strictly increasing — throws Error

## Complexity

Time `O(n)`, space `O(n)`.

## Worked example

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

`input`:

```json
{
  "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

```ts
heikinAshiTransform(input)
```

### Returns

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

```json
{
  "topic_id": "D07-F08-A05",
  "title": "Heikin-Ashi Transform",
  "state": "calculated",
  "ready": true,
  "ready_at": 0,
  "series": {
    "open": [
      100,
      100.018125,
      100.84876797625,
      101.798356894375,
      102.40147850843749,
      102.53449461546874
    ],
    "high": [101.45, 103.38381693, 104.6701838, 105.01857496, 104.62741155, 104.01164055],
    "low": [98.695, 100.018125, 100.84876797625, 101.0799399, 100.79741547, 100.54198995],
    "close": [
      100.03625,
      101.6794109525,
      102.7479458125,
      103.0046001225,
      102.6675107225,
      102.233242385
    ]
  },
  "latest": {
    "open": 102.4337036124137,
    "high": 102.4337036124137,
    "low": 98.68874251,
    "close": 100.21300550000001
  },
  "parameters": {},
  "diagnostics": {
    "causal": true,
    "input_count": 96
  }
}
```

## Verification and provenance

Tier: **verified** (via E).

The worked example below is the figure published in this algorithm's article, replayed and asserted by the test suite on every build. The arithmetic cannot drift without the build failing.

Both tiers guarantee the signature. Full explanation: https://docs.thefintechbuilder.com/guides/verification/

Generated from the docs.json payload shipped inside fintech-algorithms@0.13.0.
The signature and parameter list are checked against the compiled implementation at build time,
so a description that contradicts the code fails the build rather than reaching this file.

## Links

- Article (how it works, step by step): https://thefintechbuilder.com/technical-indicators/price-transforms/heikin-ashi-transform/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/technical-indicators/price-transforms/heikin-ashi-transform/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/technical-indicators/llms.txt