Fintech Algorithms

fintech-algorithms

717 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.

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 717 topics, and the archetype is on every index line:

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:

Reads node_modules/fintech-algorithms/docs.json when the package is installed