# Gap Volatility

`D07-F06-A08` · Technical Indicators → Range and Volatility Indicators · archetype `series-transform` · difficulty 2/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/technical-indicators/range-and-volatility-indicators/gap-volatility/
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 { gapVolatility } from "fintech-algorithms/technical-indicators/range-and-volatility-indicators/gap-volatility";
```

## Signature

```ts
gapVolatility(input)
```

Gap Volatility: measures each bar's opening gap -- this open less the prior close -- and the rolling standard deviation of those gaps.

## 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. From `parameters` this topic reads only `period` (default 14, integer >= 2), the standard-deviation window. |

## Returns

`TopicResult`

`series` holds `gap`, the raw open-minus-prior-close difference, and `value`, the population standard deviation of `gap` over `period` bars. `latest` carries the last of each. The two warm-ups differ: `gap` is null only on the first bar, which makes `ready_at` 1, while `value` first appears at index `period` (14 at the default).

## Warm-up

The first `1 bar for `gap`, `period` bars for `value` (14 at the default period)` positions are `null`. `gap` is undefined on the first bar because there is no prior close, so the deviation window needs one extra bar and lands at index `period` rather than `period - 1`.

## 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 * period)`, 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
gapVolatility(input)
```

### Returns

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

```json
{
  "topic_id": "D07-F06-A08",
  "title": "Gap Volatility",
  "state": "calculated",
  "ready": true,
  "ready_at": 1,
  "series": {
    "gap": [
      null,
      1.4911145199999964,
      0.6672783399999958,
      -0.26733595999999693,
      -0.8183669500000121,
      -0.720687060000003
    ],
    "value": [null, null, null, null, null, null]
  },
  "latest": {
    "gap": -1.106646689999991,
    "value": 1.1343149298154644
  },
  "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/range-and-volatility-indicators/gap-volatility/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/technical-indicators/range-and-volatility-indicators/gap-volatility/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/technical-indicators/llms.txt