fintech-algorithms
/
Using a coding agent? Give it the skill: npx skills add IslamBaraka90/Fintech-Algorithms-Library What it does →

Circuit-Breaker Trigger

Install and import#

bash
npm install fintech-algorithms
ts
import { circuitBreakerTrigger } from "fintech-algorithms/matching-engines-and-venue-logic/order-controls/circuit-breaker-trigger";

Signature#

circuitBreakerTrigger(reference_close_atoms, current_index_atoms, level_thresholds_bps, previously_triggered_level)

Evaluates market-wide circuit breaker levels against the index move. Levels are sequential — once a level has fired it cannot fire again the same session, which is why the previously-triggered level is an input.

Parameters#

NameTypeNotes
reference_close_atomsnumberPrior close the move is measured from, in atoms.
min: 0 · integer: true
current_index_atomsnumberCurrent index level in atoms.
min: 0 · integer: true
level_thresholds_bpsnumber[]Thresholds in basis points, ascending.
previously_triggered_levelnumberHighest level already triggered this session; 0 if none.

Returns#

{ triggered, level, decline_bps, halt_required, … }

Whether a breaker fires, at which level, and the measured decline.

Errors#

  • When thresholds are not ascending — throws

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

Worked example#

executed 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#

reference_close_atoms
4000000
current_index_atoms
3480000
level_thresholds_bps
[700, 1300, 2000]
previously_triggered_level
1

Call#

circuitBreakerTrigger(reference_close_atoms, current_index_atoms, level_thresholds_bps, previously_triggered_level)

Returns#

object with 12 fields: reference_close_atoms, current_index_atoms, decline_bps, level_thresholds_bps, previously_triggered_level, reached_level, newly_triggered_level, newly_triggered, …

{
  "reference_close_atoms": 4000000,
  "current_index_atoms": 3480000,
  "decline_bps": 1300,
  "level_thresholds_bps": [700, 1300, 2000],
  "previously_triggered_level": 1,
  "reached_level": 2,
  "newly_triggered_level": 2,
  "newly_triggered": true,
  "action": "level-2-halt",
  "next_threshold_bps": 2000,
  "distance_to_next_threshold_bps": 700,
  "state": "triggered"
}

Other exports#

This module also exports tickSizeValidation, priceBandValidation, selfTradePrevention, cancelOnDisconnect, fatFingerLimit, calculate. 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#

Circuit-Breaker Trigger — system map

Calculation flow#

Circuit-Breaker Trigger calculation flow 
flowchart LR
    S1["Validate reference observation thresholds and prior st"]
    S2["Compute nonnegative decline"]
    S3["Find the highest reached threshold"]
    S4["Compare reached level with prior triggered level"]
    S5["Return action and next threshold distance"]
    S1 --> S2
    S2 --> S3
    S3 --> S4
    S4 --> S5
    S5 --> D{"exact equality and alreadytriggered suppression"}
    D --> O["newly_triggered_level + diagnostics"]
    O --> A["Audit: Thresholds are strictly increasing"]

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#

The rest of the Order Controls family#