fintech-algorithms

fintech-algorithms

697 pure functions for market, financial and statistical calculations. Plain arrays and
objects in, plain values out. Zero runtime dependencies, Node >= 22, ESM.

Docs: https://docs.thefintechbuilder.com ·
Authoritative agent guide: https://docs.thefintechbuilder.com/guides/ai-agents/

Non-negotiables

Four rules. Breaking any one produces output that looks right and is wrong.

1. Never invent an import path, a function name, or a parameter. Every
   subpath mirrors its docs URL exactly, which makes a plausible guess wrong in
   a way that reads as correct. Look it up — scripts/lookup.mjs or the
   resolution order below. If the topic does not exist, say so and stop.
2. Never guess a returned field name. Return-key casing is not consistent
   across the library: bollingerBands returns percent_b, macd rows return
   fastEma. Read the captured example output for that topic. See
   references/pitfalls.md.
3. State the verification tier on any numeric claim. verified (601 topics)
   means the arithmetic is replayed and asserted on every build against expected
   values the catalog computed with a Python implementation written alongside
   the TypeScript — cross-language parity, not an independent third-party
   figure. Say it that way if asked. contract (74 topics) means the signature
   and shape are checked but nothing asserts the numbers.
4. Analysis, not advice. These functions compute quantities. An indicator
   crossing is an observation about a series — not a prediction, not a signal,
   and never a recommendation for a specific person's money. Report what was
   computed, on what input, at which tier. If asked what to buy or sell, say
   that is a question for a licensed adviser.

The library does not fetch data

There is no HTTP client, no vendor SDK, no API key, no node:fs. If a task
needs prices, the caller supplies them. This is deliberate: vendor APIs get
rewritten every few years and algorithms do not.

When a user wants "live analysis", the shape is always: their feed → their
adapter → validate → compute → report. Only the middle two steps are this
library. Load references/ingestion.md for the adapter pattern and the
canonical Trade / Bar shapes.

Which surface answers which question

Five things carry this library's name. Sending a question to the wrong one is the
most common way to end up guessing.

Surface	Answers	Do not use it for
node_modules/fintech-algorithms/docs.json	signature, contract, worked example, verification tier	— prefer this for everything
docs.thefintechbuilder.com	the same reference, over the network	prose about why an algorithm exists
thefintechbuilder.com	the article — what the algorithm is and when to reach for it	signatures or field names; it teaches, it does not specify
the npm package	the code you import	discovering what exists — the registry does that
this skill	how to look any of it up	as a substitute for looking it up

Two relationships matter and are enforced, not conventional:

• A docs URL and an import path are the same string. Swap
  https://docs.thefintechbuilder.com/ for fintech-algorithms/, drop the
  trailing slash. A test fails if that ever stops being true.
• The docs can be ahead of npm. The site rebuilds from main without a
  release. If a documented topic will not import, the installed version is older
  than the page — check https://docs.thefintechbuilder.com/version.json before
  concluding anything is broken.

A topic may ship a hand-written implementation from the repository's
optimised/ tree instead of the catalog's. It is asserted to return identical
values and throw identical errors, so it changes nothing you report — but the
code in the article and the code in the package can legitimately differ.

Resolution order

Stop at the first step that answers the question.

1. Installed package — if fintech-algorithms is a dependency, read
   node_modules/fintech-algorithms/docs.json. Every signature, contract and
   worked example, no network. Prefer this. scripts/lookup.mjs uses it
   automatically.
2. Domain index — https://docs.thefintechbuilder.com/{domain-slug}/llms.txt
   (3–11 KB each). The map of all seventeen is the ## Per-domain indexes block
   at the top of /llms.txt; one root fetch gives a permanent routing table.
3. Topic markdown — append index.md to any docs URL. The full contract in
   3–11 KB instead of 68–114 KB of HTML.
4. Full payload — https://docs.thefintechbuilder.com/reference/payload.json
   (~2.6 MB). For ingestion, not for answering one question.

Turn a docs URL into an import: swap https://docs.thefintechbuilder.com/ for
fintech-algorithms/ and drop the trailing slash.

Check the installed version matches the docs with
https://docs.thefintechbuilder.com/version.json (under 1 KB).

Workflow

1. Identify the quantity. What is actually being asked for? "Is this
overbought" → RSI. "Smooth this" → which moving average, and why that one.

2. Narrow by archetype before fetching anything. Five input shapes cover all
697 topics, and the archetype is on every index line:

Archetype	Takes	Returns	Count
series-transform	(number | null)[] + numeric params	same-length array	137
tape-aggregate	Trade[] + config	Bar[]	7
row-classify	rows	one verdict per row	24
snapshot-evaluate	one snapshot + decision time	one verdict	6
record-transform	domain-specific	domain-specific	501

record-transform is the residual bucket — read that topic's own contract.
Details and executed examples: references/archetypes.md.

3. Read the contract. Signature, params, returns, warm-up, errors.

node scripts/lookup.mjs show rsi

4. Shape the data. Map the user's payload into the documented input. Run the
boundary validator first when the input is bars, ticks or quotes.

5. Compute and report. Say what was computed, on what input, at which tier,
and how many leading values are warm-up rather than signal.

Quick start

npm install fintech-algorithms

Algorithms are subpath-only. The root export carries metadata and lookups
(topics, topic, byDomain, byFamily, byArchetype, load, runner) and
re-exports no algorithm. A sibling topic's function is never re-exported from
another subpath — import each from its own.

import { calculateSma } from "fintech-algorithms/technical-indicators/trend-smoothing/sma";

calculateSma([44.34, 44.09, 44.15, 43.61, 44.33, 44.83], 5);
// → [null, null, null, null, 44.104, 44.202]
//     ^^^^ four warm-up nulls: window - 1

The require condition resolves to the same ES module — there is no separate
CommonJS build, so require() needs a runtime supporting require(esm).

The lookup script

scripts/lookup.mjs sits next to this file. The working directory is the user's
project, not the skill, so always invoke it by absolute path.

These files write ${SKILL_DIR} for the directory containing this SKILL.md.
In Claude Code that is ${CLAUDE_SKILL_DIR}, which the harness substitutes for
you. In any other agent, substitute the real path before running the command.

node "${CLAUDE_SKILL_DIR}/scripts/lookup.mjs" search "moving average"

Commands:

Command	Does
search <query>	find topics by name, slug, family or entry
show <slug|id|path>	full contract, warm-up, errors, executed example
archetype <name>	every topic sharing an input shape, plus its caveat
domain <id|slug>	every topic in a domain, grouped by family
domains	the seventeen domains with their index URLs
version	the reference version vs the published one

Reads node_modules/fintech-algorithms/docs.json when the package is installed
anywhere above the working directory; otherwise fetches and caches the published
payload for a day. Set FINTECH_DOCS_JSON to point it at a specific file.
Accepts a slug (rsi), a catalog id (D07-F03-A01), a full path, or a docs URL.

If show cannot find the topic it says so rather than guessing — that failure is
the correct answer, not an obstacle to route around.

Load a reference when

• references/archetypes.md — mapping user data into an input shape, or
  deciding how much adapter code a task needs.
• references/ingestion.md — the user has a provider, a CSV, a websocket or
  a broker API and asks how to connect it.
• references/recipes.md — an end-to-end task: clean a feed, build bars,
  compute a multi-indicator report.
• references/pitfalls.md — before finalising any numeric answer. Short,
  and every entry is a real failure mode with a real cause.

Coverage

18 domains: Financial Mathematics, Statistics, and Data Foundations (120) ·
Market Data Engineering (31) · Corporate Actions and Security Master Data (20) ·
Index and Benchmark Engineering (40) · Market Breadth and Internals (28) · Price
Action and Candlesticks (52) · Technical Indicators (137) · Geometric Chart
Patterns (64) · Statistical Time Series (37) · Market Microstructure (29) ·
Matching Engines and Venue Logic (21) · Execution and Transaction Cost Analysis
(9) · Fundamental Analysis and Valuation (52) · Credit Risk and Default (7) ·
Digital Assets and On-Chain Finance (10) · Model Validation and Backtesting (10)
· Earnings and Per-Share Analytics (8) · Volatility and Covariance (22).

Technical Indicators, Price Action and Geometric Chart Patterns are complete for
the first time in 0.13.0 — every topic in the catalog is installable.

Reach for the foundations domain first. Financial Mathematics, Statistics,
and Data Foundations is the base layer the rest of the library is built on — one
implementation each of mean, median, percentile, standard deviation, correlation,
regression, z-score, log return, volatility, drawdown, Sharpe and value at risk,
rather than a private copy inside every indicator. When a task needs a plain
statistic, import it from there instead of hand-rolling one or borrowing an
indicator's internals. It is intentionally absent from the package README, which
indexes the market-facing algorithms; it is fully present here and in the docs.

Not a backtester, an execution system, a portfolio manager, or a source of
market data. It computes quantities, places no orders, and holds no state
between calls.