# Causal Pivot Detection

`D08-F01-A01` · Geometric Chart Patterns → Pivots and Levels · archetype `row-classify` · difficulty 2/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/geometric-chart-patterns/pivots-and-levels/causal-pivot-detection/
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 { detectCausalPivots } from "fintech-algorithms/geometric-chart-patterns/pivots-and-levels/causal-pivot-detection";
```

## Signature

```ts
detectCausalPivots(bars, leftSpan, rightSpan, minSeparation)
```

Finds swing highs and lows using only bars that had already arrived. Most pivot code confirms a pivot with bars that come *after* it and then plots it at the earlier index — which is lookahead bias, and it is invisible on a chart.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `bars` | `Bar[]` | yes | OHLC bars in chronological order. |
| `leftSpan` | `number` | yes | Bars before the candidate that must be lower (or higher). · min: 1, integer: true |
| `rightSpan` | `number` | yes | Bars after the candidate required to confirm it. **This is the confirmation lag**: a pivot at index `i` is not knowable until `i + rightSpan`. · min: 1, integer: true |
| `minSeparation` | `number` | yes | Minimum bars between accepted pivots, which stops a noisy region producing a cluster of them. · min: 0, integer: true |

## Returns

`{ kind, event_index, confirmation_index, price }[]`

Both indices are returned deliberately: `event_index` is where the pivot occurred and `confirmation_index` is when you could have known. Any backtest must use the second.

## Errors

- When leftSpan or rightSpan is less than 1 — throws

## Complexity

Time `O(n × span)`, space `O(pivots)`.

## Worked example

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

### Input

`bars`:

```json
[
  {
    "timestamp": "2026-01-01T00:00:00Z",
    "high": 10,
    "low": 8,
    "close": 9
  },
  {
    "timestamp": "2026-01-01T01:00:00Z",
    "high": 12,
    "low": 10,
    "close": 11
  },
  {
    "timestamp": "2026-01-01T02:00:00Z",
    "high": 15,
    "low": 13,
    "close": 14
  }
]
```

Showing 3 of 5 elements.

`leftSpan`:

```json
2
```

`rightSpan`:

```json
2
```

`minSeparation`:

```json
0
```

### Call

```ts
detectCausalPivots(bars, leftSpan, rightSpan, minSeparation)
```

### Returns

object with 1 field: 0

```json
{
  "0": {
    "kind": "high",
    "event_index": 2,
    "confirmation_index": 4,
    "price": 15,
    "separation": 2,
    "latency": 2
  }
}
```

## Verification and provenance

Tier: **verified** (via input-expected).

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.1.
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/geometric-chart-patterns/pivots-and-levels/causal-pivot-detection/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/geometric-chart-patterns/pivots-and-levels/causal-pivot-detection/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/geometric-chart-patterns/llms.txt