# Fractal Chaos Bands

`D07-F07-A08` · Technical Indicators → Bands, Envelopes, and Squeezes · archetype `series-transform` · difficulty 2/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/technical-indicators/bands-envelopes-and-squeezes/fractal-chaos-bands/
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 { fractalChaosBands } from "fintech-algorithms/technical-indicators/bands-envelopes-and-squeezes/fractal-chaos-bands";
```

## Signature

```ts
fractalChaosBands(input)
```

Fractal Chaos Bands: carries forward the most recent confirmed five-bar fractal high and fractal low, each held flat until a new fractal of that side confirms.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `input` | `TopicInput` | yes | `bars` is the required OHLCV array -- each bar carries `timestamp`, `open`, `high`, `low`, `close`, `volume` and an optional `basis`, strictly ordered by timestamp. This topic reads no keys of its own from `parameters`; the five-bar fractal window is fixed in code. `period` (default 20, integer >= 2) and `multiplier` (default 2, a finite number >= 0) are read and validated by the band family for every topic in it. Neither is used by this branch, but an invalid value is still rejected. |

## Returns

`TopicResult`

`series` holds only `upper` and `lower` -- there is no `center` for this topic -- and `latest` carries the last of each. The warm-up is data dependent: a fractal is confirmed two bars after its pivot, so nothing can appear before index 4, and each side stays null until its first fractal confirms. In the canonical fixture `upper` first appears at index 5 and `lower` at index 8, making `ready_at` 5.

## Warm-up

The first `at least 4 bars, then data dependent per side` positions are `null`. Confirmation needs two bars either side of the pivot, so index 4 is the earliest possible reading, and the actual first index depends on when a qualifying high or low occurs. `upper` and `lower` can therefore become available on different bars.

## Errors

- When `parameters.period` is not an integer >= 2 — throws Error
- When a bar is missing open, high, low, close, or volume, or one of them is not a finite number — throws Error
- When bars are not strictly ordered by timestamp, or a bar's high is below its open, low, or close — 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
fractalChaosBands(input)
```

### Returns

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

```json
{
  "topic_id": "D07-F07-A08",
  "title": "Fractal Chaos Bands",
  "state": "calculated",
  "ready": true,
  "ready_at": 5,
  "series": {
    "upper": [null, null, null, null, null, 105.01857496],
    "lower": [null, null, null, null, null, null]
  },
  "latest": {
    "upper": 109.83623682,
    "lower": 101.07584902
  },
  "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/bands-envelopes-and-squeezes/fractal-chaos-bands/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/technical-indicators/bands-envelopes-and-squeezes/fractal-chaos-bands/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/technical-indicators/llms.txt