fintech-algorithms

v0.13.0

Published

4 days ago

The Fintech Builder algorithm library — canonical, cross-language reference implementations of market-data, corporate-action, index, breadth, candlestick and technical-indicator algorithms, exposed as provider-agnostic subpath modules.

fintech-algorithms

Corporate actions, index construction, market breadth, market microstructure, matching engines, execution algorithms and technical indicators — as plain TypeScript functions with zero dependencies.

📖 Documentation → docs.thefintechbuilder.com — a reference page for every algorithm, with a worked example whose output was produced by running the code. Start with the quick start.

Split and dividend adjustment factors, capped free-float index weighting, McClellan breadth internals, dollar and imbalance bars, and the usual moving averages. Most npm packages in this space stop at indicators; the harder back-office arithmetic is the reason this one exists.

npm install fintech-algorithms

How the pieces fit together

Five things carry this library's name, and it is worth knowing which one answers which question before you go looking.

flowchart TD
  CAT[("private catalog<br/><i>the single source of truth</i><br/>article · implementation · tests · fixtures")]

  CAT -->|"scripts/sync.mjs"| REPO["<b>this repository</b><br/>src/ generated · optimised/ hand-written<br/>github.com/IslamBaraka90/Fintech-Algorithms-Library"]
  CAT -->|"article build"| SITE["<b>thefintechbuilder.com</b><br/>the lesson — why the algorithm<br/>exists and how to read it"]

  REPO -->|"push a v* tag<br/>CI publishes with provenance"| NPM["<b>npm: fintech-algorithms</b><br/>what you install<br/>zero dependencies"]
  REPO -->|"docs.json on main<br/>rebuilds the site"| DOCS["<b>docs.thefintechbuilder.com</b><br/>the reference — signature, contract,<br/>worked example, verification tier"]
  REPO -->|"ships inside the package"| SKILL["<b>the agent skill</b><br/>skills/fintech-algorithms/<br/>lookup instead of guessing"]

  NPM -.->|"node_modules/…/docs.json"| SKILL
  DOCS -.->|"same subpath, same URL"| NPM

  style CAT stroke-dasharray: 4 3

| | Answers | Updated by | |---|---|---| | npm | Give me the function. | A v* tag — CI publishes, never a laptop | | docs.thefintechbuilder.com | What are the arguments, what comes back, is the arithmetic verified? | Every push to main — no release needed | | thefintechbuilder.com | What is this algorithm and why would I use it? | The article, on its own schedule | | this repository | How is it built, and how do I contribute? | Pull requests — see CONTRIBUTING.md | | the agent skill | Which import path and which field name? | Ships inside the package |

Two of those links are worth spelling out, because they are the ones people assume and get wrong:

A documentation URL and an import path are the same string. Swap https://docs.thefintechbuilder.com/ for fintech-algorithms/ and you have the import. That is enforced by a test, not a convention.
Docs do not wait for a release. The site builds from docs.json on main, so a corrected sentence ships immediately while the version on npm stays put. Check the two agree with version.json.

Writing this code with an agent? Install the skill first

npx skills add IslamBaraka90/Fintech-Algorithms-Library

This is the single highest-value thing you can do before asking an agent to use this library. Several hundred algorithms is more API than any model has read, and the failure mode is not refusal — it is a plausible import path, a plausible parameter and a plausible field name on the result, none of which exist. The skill replaces every one of those guesses with a lookup.

It ships in the Agent Skills format, so Claude Code, Codex, Cursor and some seventy other agents load it on demand. It carries the routing rules for every topic, the five input shapes with executed examples, the data-ingestion patterns for wiring up a provider, the failure modes that do not throw — the category that otherwise produces a confident wrong number — and a lookup script that answers from the installed docs.json, offline:

node <skill-dir>/scripts/lookup.mjs show rsi
# → signature, parameters, warm-up (p leading nulls), errors, executed example

The skill is skills/fintech-algorithms/ here and also ships inside the npm tarball, version-matched to the docs.json beside it, so a project that already depends on the package already has it.

📘 The agent skill → docs.thefintechbuilder.com/guides/agent-skill/ · Background on how an agent should read this library: Using this library from an agent.

Adjust a price history for a 2-for-1 split

import { calculate } from "fintech-algorithms/corporate-actions-and-security-master-data/adjustment-factors/backward-split-adjustment";

calculate({
  prices: [120, 123, 60, 62],
  volumes: [1000, 1200, 2400, 2000],
  eventIndex: 2,
  postSplitSharesPerPreSplitShare: 2,
});
// adjustedPrices:  [60, 61.5, 60, 62]
// adjustedVolumes: [2000, 2400, 2400, 2000]

Pre-split prices are divided and volumes multiplied, so the series is continuous across the event and returns computed over it are correct.

Indicators work the same way — plain arrays in, plain arrays out:

import { calculateEma } from "fintech-algorithms/technical-indicators/trend-smoothing/ema";

calculateEma([10, 13, 16, 19], 3); // → [null, null, 13, 16]

null marks a warm-up observation where the indicator is not yet defined.

Bring your own data

The library ships no data provider. No Yahoo client, no exchange SDK, no node:fs, no network calls, zero runtime dependencies. Every algorithm takes plain arrays and plain objects, so the same code runs in Node, the browser, a Worker, Deno or Bun.

Adapting a provider is a short mapping function that you own:

// Your provider's payload → the library's Trade contract. You own this file.
const toTrades = (payload: ProviderResponse): Trade[] =>
  payload.results.map((r) => ({
    tradeId: r.id,
    timestamp: new Date(r.t).toISOString(),
    session: "S1",
    symbol: r.sym,
    price: r.p,
    volume: r.s,
    currency: "USD",
  }));

When a vendor changes their API you edit one adapter; the algorithms never move.

Requires Node ≥ 22.12 — the require condition resolves to the same ES module, and require(esm) is unflagged from 22.12 onward.

Verified against published worked examples

481 of 555 topics have their arithmetic replayed and asserted on every build (145 via { input, expected }, 143 via a separate input and expected-output pair, 11 via row fixtures, 30 via bar/checkpoint fixtures).

Worth being precise about what that proves. The expected values come from the catalog, computed by a Python implementation written alongside the TypeScript rather than derived from it — so this is a cross-language parity check, not an independent third-party figure. It catches transcription and generation errors, which is the failure mode that has actually occurred here. It would not catch both implementations sharing a misreading of the source material.

The remaining 74 load and expose a callable entry point, but ship no machine-readable expected values, so nothing asserts their numbers. That gap is stated per topic rather than averaged away.

Every algorithm accompanies a published article that walks through a worked example by hand. Where that article ships machine-readable numbers, the test suite replays them and asserts the output matches exactly — so a green run means the package, the article and the standalone repo agree on the arithmetic.

It is an honest split, not a marketing number. Each algorithm's reference page states which tier it is in, and every worked example shown there is a fixture the test suite asserts — so those numbers cannot drift.

Import paths mirror article URLs

The subpath of every module is exactly the path of its article:

| | | |---|---| | Article | https://thefintechbuilder.com/technical-indicators/trend-smoothing/ema/ | | Import | fintech-algorithms/technical-indicators/trend-smoothing/ema |

One mental model for the site, the standalone repos and the package. It also means the 63 topics that each export a function named calculate never collide — they live in separate namespaces.

The five shapes

Every topic is an instance of one of five archetypes:

| Archetype | Signature | Count | Example | |---|---|--:|---| | record-transform | (input) → output | 381 | backward-split-adjustment | | series-transform | (values, ...params) → (number\|null)[] | 137 | ema, rsi, macd | | row-classify | (rows, config?) → verdict[] | 24 | ohlc-consistency-validator | | tape-aggregate | (trades, config) → bar[] | 7 | time-bars, volume-bars | | snapshot-evaluate | (snapshot, policy) → result | 6 | price-source-consensus-check |

Classifiers return a verdict per row instead of throwing, so one bad tick cannot abort a batch.

The registry

The package root exports metadata only — never algorithm code — so importing it stays light. Use it to enumerate the library, build docs, or dispatch dynamically.

import { topics, topic, byDomain, byFamily, byArchetype, load, runner } from "fintech-algorithms";

topics.length;                    // every topic in the catalog
topic("D07-F01-A02")?.path;       // "technical-indicators/trend-smoothing/ema"
byFamily("D01-F01").map(t => t.slug);
                                  // ["time-bars", "tick-bars", "volume-bars", ...]

const run = await runner("D07-F01-A01");
run([1, 2, 3, 4, 5], 3);          // [null, null, 2, 3, 4]

Every module also exports a uniform run alias for its primary function, plus a meta object carrying its catalog id, domain, family, shape, article URL and repo URL.

Coverage

The table below counts the market-facing algorithms — the ones you came here looking for. The package also ships a foundations layer of 120 statistics and financial-mathematics topics (fintech-algorithms/foundations/…): one implementation each of a mean, a percentile, a z-score, a log return, a volatility, a drawdown. It is the base the rest of the library is built on rather than something to browse, so it is documented and exported but deliberately not listed here. topics.length counts everything.

555 topics · 16 domains · 70 families

| Domain | Topics | Families | Name | |---|--:|--:|---| | D01 | 31 | 5 | Market Data Engineering | | D02 | 20 | 4 | Corporate Actions and Security Master Data | | D03 | 40 | 6 | Index and Benchmark Engineering | | D04 | 28 | 5 | Market Breadth and Internals | | D06 | 52 | 5 | Price Action and Candlesticks | | D07 | 137 | 9 | Technical Indicators | | D08 | 64 | 7 | Geometric Chart Patterns | | D09 | 37 | 6 | Statistical Time Series | | D11 | 29 | 5 | Market Microstructure | | D12 | 21 | 4 | Matching Engines and Venue Logic | | D13 | 9 | 2 | Execution and Transaction Cost Analysis | | D18 | 52 | 6 | Fundamental Analysis and Valuation | | D21 | 7 | 1 | Credit Risk and Default | | D25 | 10 | 2 | Digital Assets and On-Chain Finance | | D40 | 10 | 1 | Model Validation and Backtesting | | D46 | 8 | 2 | Earnings and Per-Share Analytics |

Every algorithm

Each name links to its reference page — signature, worked example, verification tier, diagrams and source.

Full reference for every algorithm →

D09 — Statistical Time Series · 37 topics

Diagnostics — ACF · [PACF](https://docs.thefintechbuilder.com/statistical-time-s

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

fintech-algorithms

How the pieces fit together

Writing this code with an agent? Install the skill first

Adjust a price history for a 2-for-1 split

Bring your own data

Verified against published worked examples

Import paths mirror article URLs

The five shapes

The registry

Coverage

Every algorithm

D01 — Market Data Engineering · 31 topics

D02 — Corporate Actions and Security Master Data · 20 topics

D03 — Index and Benchmark Engineering · 40 topics

D04 — Market Breadth and Internals · 28 topics

D06 — Price Action and Candlesticks · 52 topics

D07 — Technical Indicators · 137 topics

D08 — Geometric Chart Patterns · 64 topics

D09 — Statistical Time Series · 37 topics