ta-crypto

Technical analysis indicators and crypto-market utilities for Node.js. The current stable release line is v0.4.

Install

npm install ta-crypto

Start here

import { rsi, atr, toOHLCV } from "ta-crypto";

const candles = [
  { open: 100, high: 102, low: 99, close: 101, volume: 10, time: 1 },
  { open: 101, high: 103, low: 100, close: 102, volume: 12, time: 2 }
];

const { high, low, close } = toOHLCV(candles);
const rsi14 = rsi(close, 14);
const atr14 = atr(high, low, close, 14);

Indicator results are aligned with the input. Values that need more history are returned as null.

Choose an API

| Task | Use | Reference | | --- | --- | --- | | Normalize candle objects or aliases | toOHLCV, pluck* | Inputs and candles | | Calculate classic indicators in batch | sma, rsi, macd, atr, adx, and others | Indicators | | Calculate funding, session VWAP, volatility regimes, or candle-derived orderflow | ta-crypto/crypto | Crypto utilities | | Process prices or candles one at a time | createSMA, createEMA, createRSI, createMACD, createATR, createBBANDS, createVWAPSession, createRealizedVolatility, createVolatilityRegime, createVolumeDelta, createOrderflowImbalance | Stateful API | | Review benchmarks, scaling guards, and regression policy | deterministic harness and baseline | Performance & benchmarks | | Review tolerances and external references | compatibility scripts and policy | Compatibility | | Verify releases and project limitations | CI, tags, changelog, and trust policy | Trust and verification |

Module imports

import { sma, createMACD } from "ta-crypto/indicators";
import { vwapSession, createVolumeDelta } from "ta-crypto/crypto";
import { toOHLCV } from "ta-crypto/candles";
import { createRSI, createBBANDS } from "ta-crypto/stateful";

The root ta-crypto entry point exports all public functions, stateful constructors, and types.

Streaming example

import { createMACD, createATR, createBBANDS, createVolumeDelta } from "ta-crypto";

const macd = createMACD(12, 26, 9);
const atr = createATR(14);
const bbands = createBBANDS(20, 2);
const volDelta = createVolumeDelta(14);

for (const candle of liveCandles) {
  const m = macd.next(candle.close);       // { macd, signal, histogram }
  const a = atr.next(candle);              // number | null
  const bb = bbands.next(candle.close);    // { basis, upper, lower }
  const vd = volDelta.next(candle);        // number | null
  // Values remain null until individual indicator warmup is complete.
}

See Stateful API for warmup, parity, and reset behavior.

What is included

• Batch overlap, momentum, volatility, performance, volume, and trend indicators.
• Candle normalization for long keys and o/h/l/c/v/t aliases.
• Stateful streaming constructors (createSMA, createEMA, createRSI, createMACD, createATR, createBBANDS, createVWAPSession, createRealizedVolatility, createVolatilityRegime, createVolumeDelta, createOrderflowImbalance).
• Crypto-specific funding, volatility-regime, session-VWAP, and orderflow-proxy utilities.
• Golden regression tests and external compatibility checks against TA-Lib and technicalindicators.

What is not included

• A backtest or portfolio accounting engine.
• Built-in strategies, screeners, or exchange/network adapters.
• Complete multi-timeframe alignment or candle resampling.
• L2/L3 order-book imbalance. Current orderflow functions are candle-derived proxies.

These items remain roadmap work and must not be treated as current package capabilities.

Known behavior in v0.4

• percentReturn(values, { cumulative: true }) compounds cumulative return from the initial price (issue #27). Arithmetic sum of periodic returns is available via sumPeriodicReturns(values) or { mode: "sum" }. The deprecated boolean signature is supported with compound semantics during the v0.4 migration window.
• logReturn, realizedVolatility, and volatilityRegime enforce strictly positive prices ($P_t > 0$) with index-aware errors (issue #28).
• natr enforces strictly positive closing prices ($close > 0$) with index-aware errors (issue #29).
• Period-bearing batch indicators and stateful constructors uniformly validate positive integer periods (issue #30).

Examples

Runnable examples are in examples/:

npm run example:all

They cover RSI signals, batch/stateful session VWAP parity, funding metrics, and an external RSI comparison.

Development

npm ci
npm test

Additional compatibility and benchmark commands are documented in CONTRIBUTING.md.

GitHub Actions and Release Please are the single release authority. Conventional commits on main create or update a Release PR; merging that PR creates the matching tag and GitHub Release, runs the release checks, and publishes to npm. Local commands are limited to validation and dry runs. See Trust and verification for the complete flow and recovery boundaries.

Project references

• Contributing
• Security policy
• Dependency security policy
• Release policy
• Performance policy
• Roadmap
• Changelog
• Trust and verification
• License