MeridianAlgo

Professional-grade quantitative finance framework for JavaScript & TypeScript

Institutional-quality algorithmic trading, backtesting, risk management, and portfolio optimization — in a single unified package.

Installation · Quick Start · Examples · API · Docs · Changelog

🚧 Active Development Notice: This repository is currently being updated toward v4.0.0. The 3.x line is stable and production-ready — pin to a specific 3.x version (e.g. meridianalgo@^3.9) if you need API stability while v4 is in flight. v4 will introduce expanded ML, streaming-first indicators, and broader runtime support (Deno, Bun, browser).

Why MeridianAlgo?

Traditional JavaScript trading libraries cover indicators. MeridianAlgo covers the entire quant stack in one cohesive, typed, tree-shakable package:

| Capability | What's included | |---|---| | 100+ Indicators | Classic TA (SMA, EMA, RSI, MACD, Bollinger, ATR, Stochastic) + advanced (Ichimoku, Supertrend, Connors RSI, Fisher, Coppock, Aroon, Donchian, Keltner, Mass Index, Choppiness, Elder Ray, Pivot Points) | | Candlestick Patterns | 15 detectors: doji, hammer, shooting star, engulfing, morning/evening star, three soldiers/crows, marubozu, spinning top, piercing, dark cloud cover, tweezers + detectAllPatterns aggregator | | Streaming Indicators | StreamingSMA/EMA/RSI/MACD/Bollinger with nextValue/replace/reset for real-time tick processing | | Backtesting | Event-driven time-based engine with slippage, commission, partial fills, custom cost models | | Risk Analytics | VaR (historical, parametric, Cornish-Fisher), CVaR, GARCH(1,1), range volatility, stress testing, drawdown, Sharpe, Sortino, Calmar, Information Ratio, Tracking Error, Active Share, up/down capture | | Portfolio Optimization | Mean-Variance (Markowitz), Black-Litterman, Hierarchical Risk Parity (HRP), Risk-Parity, Kelly criterion (discrete/continuous/multi-asset/fractional), constrained solvers | | Performance Attribution | Brinson-Hood-Beebower (allocation/selection/interaction), CAPM, Fama-French 3/5-factor OLS regression, custom multi-factor models | | Stochastic Models | GBM, Heston (stochastic vol), CIR, Merton jump-diffusion, Ornstein-Uhlenbeck, Monte Carlo | | Options Pricing | Black-Scholes, implied vol (Brent solver), full Greeks (Δ/Γ/Θ/Vega/Ρ), option chains | | Fixed Income | TVM (NPV/IRR/PMT/PV/FV), bond pricing, duration, convexity, yield curves (bootstrap, Nelson-Siegel) | | Credit | CDS pricing, hazard-rate bootstrap, Z-spread, default probability | | Execution Algorithms | VWAP, TWAP, POV, Almgren-Chriss Implementation Shortfall closed-form | | Microstructure | Order book mid/microprice/imbalance, quoted/effective/realized/Roll spreads, square-root + Almgren-Chriss market impact | | Wealth Protection | CPPI (fixed floor) and TIPP (ratcheting floor) dynamic strategies | | Strategies | Mean-reversion, momentum, trend-following, pairs-trading, composer for multi-strategy ensembles | | Data Adapters | Yahoo, Binance, Alpaca, Polygon — pluggable | | Execution Brokers | Paper broker, extensible broker adapter interface | | Machine Learning | Pure-JS LSTM/GRU forward pass, walk-forward CV (expanding/rolling), feature engineering, Gaussian HMM (Baum-Welch + Viterbi) for regime detection, Kalman filter, ARIMA, linear regression, fractional differencing | | Parameter Search | Grid search + random search with parallelizable objective functions | | Plugin System | Drop in custom indicators, strategies, data sources, brokers |

Fully typed. First-class TypeScript. No any in the public surface. Zero heavy deps. Built on native math — only commander, yahoo-finance2, tslib at runtime. Node 18+. ESM + CJS builds. Tree-shakable.

Installation

npm install meridianalgo
# or
pnpm add meridianalgo
# or
yarn add meridianalgo

Requirements: Node.js >=18.0.0, TypeScript >=5.0 (for TS users).

Quick Start

30-second backtest

import { TimeBasedEngine, YahooAdapter, Indicators } from 'meridianalgo';

const data = await new YahooAdapter().ohlcv('AAPL', {
  start: '2023-01-01',
  end: '2024-01-01',
  interval: '1d',
});

const engine = new TimeBasedEngine({
  initialCash: 100_000,
  data,
  strategy: {
    id: 'sma-crossover',
    next: (bar, ctx) => {
      const closes = ctx.history.map((b) => b.c);
      const fast = Indicators.sma(closes, 10).at(-1) ?? 0;
      const slow = Indicators.sma(closes, 30).at(-1) ?? 0;
      return { t: bar.t, value: fast > slow ? 1 : 0 };
    },
  },
});

const result = await engine.run();
console.log(`Return: ${(result.metrics.totalReturn * 100).toFixed(2)}%`);
console.log(`Sharpe: ${result.metrics.sharpeRatio.toFixed(2)}`);
console.log(`Max DD: ${(result.metrics.maxDrawdown * 100).toFixed(2)}%`);

Examples

Full runnable examples live in examples/. Run them with:

npm run example:basic      # Basic backtest
npm run example:advanced   # Advanced features
npm run example:utils      # Math/stats utilities
npm run example:quant      # Quantitative strategies
npm run example:risk       # Risk management

1. Technical Indicators

import { Indicators } from 'meridianalgo';

const closes = [44, 44.3, 44.1, 44.5, 44.7, 45.1, 45.3, 45.5, 45.9, 46.2, 46.5];

Indicators.sma(closes, 5);     // Simple Moving Average
Indicators.ema(closes, 5);     // Exponential Moving Average
Indicators.rsi(closes, 14);    // Relative Strength Index
Indicators.macd(closes);       // { macd, signal, histogram }
Indicators.bollinger(closes);  // { upper, middle, lower }
Indicators.atr(highs, lows, closes, 14);
Indicators.stochastic(highs, lows, closes, 14);

2. Advanced Quant Tools

import { AdvancedMath, KalmanFilter } from 'meridianalgo';

// Hurst Exponent — detect mean reversion (<0.5) vs trending (>0.5)
const hurst = AdvancedMath.hurstExponent(returns);

// Fractional differencing — stationarity without losing memory
const diffed = AdvancedMath.fractionalDiff(prices, 0.4);

// Ornstein-Uhlenbeck — mean-reversion speed + equilibrium
const { theta, mu, sigma } = AdvancedMath.fitOU(spread);

// Kalman filter — dynamic signal smoothing
const kf = new KalmanFilter({ Q: 1e-5, R: 0.01 });
const smoothed = prices.map((p) => kf.filter(p));

3. Risk Metrics

import { RiskPerformanceMetrics, StressTesting } from 'meridianalgo';

const returns = [0.01, -0.02, 0.015, -0.005, 0.03, -0.01];

RiskPerformanceMetrics.sharpe(returns, 0.02);       // risk-free rate 2%
RiskPerformanceMetrics.sortino(returns, 0.02);
RiskPerformanceMetrics.calmar(returns);
RiskPerformanceMetrics.valueAtRisk(returns, 0.95);  // 95% VaR
RiskPerformanceMetrics.cvar(returns, 0.95);         // Expected Shortfall

StressTesting.historicalScenario(portfolio, '2008-crisis');
StressTesting.monteCarlo(portfolio, { simulations: 10_000, horizon: 252 });

4. Portfolio Optimization

import { MeanVarianceOptimizer, BlackLittermanModel, RiskParityOptimizer } from 'meridianalgo';

// Markowitz mean-variance with target return
const mv = new MeanVarianceOptimizer();
const weights = mv.optimize({
  expectedReturns: [0.08, 0.12, 0.06],
  covariance: covMatrix,
  targetReturn: 0.10,
  constraints: { minWeight: 0, maxWeight: 0.5 },
});

// Black-Litterman — blend market equilibrium with investor views
const bl = new BlackLittermanModel({
  marketCaps: [1e12, 5e11, 3e11],
  riskAversion: 2.5,
});
const posteriorReturns = bl.computePosterior({
  views: [{ assets: [0, 1], weights: [1, -1], expectedReturn: 0.03, confidence: 0.8 }],
});

// Risk parity — equal risk contribution
const rp = new RiskParityOptimizer();
const rpWeights = rp.optimize(covMatrix);

5. Built-in Strategies

import { MeanReversionStrategy, MomentumStrategy, PairsTradingStrategy, StrategyComposer } from 'meridianalgo';

const mr = new MeanReversionStrategy({ lookback: 20, entryZ: 2, exitZ: 0.5 });
const mom = new MomentumStrategy({ lookback: 60, topN: 10 });
const pairs = new PairsTradingStrategy({ lookback: 60, entryZ: 2, exitZ: 0 });

// Combine strategies with weighted voting
const composite = new StrategyComposer([
  { strategy: mr, weight: 0.4 },
  { strategy: mom, weight: 0.6 },
]);

6. Parameter Optimization

import { GridSearchOptimizer } from 'meridianalgo';

const optimizer = new GridSearchOptimizer({
  parameters: {
    fast: [5, 10, 15, 20],
    slow: [30, 50, 100, 200],
  },
  objective: async ({ fast, slow }) => {
    const result = await runBacktest({ fast, slow });
    return result.metrics.sharpeRatio;
  },
});

const best = await optimizer.run();
console.log(`Best params: ${JSON.stringify(best.params)} (Sharpe ${best.score})`);

7. Custom Data Adapter (Plugin)

import { DataAdapter, OHLCVBar } from 'meridianalgo';

export class MyExchangeAdapter implements DataAdapter {
  async ohlcv(symbol: string, opts: { start: string; end: string; interval: string }): Promise<OHLCVBar[]> {
    const response = await fetch(`https://api.myexchange.com/bars?symbol=${symbol}`);
    const json = await response.json();
    return json.bars.map((b: any) => ({
      t: new Date(b.timestamp).getTime(),
      o: b.open, h: b.high, l: b.low, c: b.close, v: b.volume,
    }));
  }
}

8. Custom Indicator Plugin

import { registerIndicator } from 'meridianalgo';

registerIndicator('zscore', (values: number[], lookback = 20) => {
  return values.map((_, i) => {
    if (i < lookback - 1) return NaN;
    const window = values.slice(i - lookback + 1, i + 1);
    const mean = window.reduce((a, b) => a + b, 0) / lookback;
    const std = Math.sqrt(window.reduce((s, v) => s + (v - mean) ** 2, 0) / lookback);
    return (values[i] - mean) / std;
  });
});

9. Hierarchical Risk Parity (HRP)

Lopez de Prado's clustering-based allocation. No matrix inversion — robust on near-singular covariance.

import { hrpAllocate } from 'meridianalgo';

// returns: rows = time, cols = assets
const { weights, order } = hrpAllocate({ returns });
console.log('HRP weights:', weights);  // sums to 1

10. Kelly Criterion

import { kellyBet, kellyContinuous, kellyMultiAsset, fractionalKelly } from 'meridianalgo';

// Discrete bet: 60% win, 2:1 payoff
const f = kellyBet({ winProb: 0.6, winPayoff: 2, lossPayoff: 1 });

// Continuous (Merton): expected return / variance
const fc = kellyContinuous({ mu: 0.10, sigma: 0.20, riskFree: 0.02 });

// Multi-asset: Σ⁻¹(μ − r·1)
const w = kellyMultiAsset({ expectedReturns, covariance, riskFree: 0.02 });

// Fractional (half-Kelly is industry standard for live trading)
const safe = fractionalKelly(f, 0.5);

11. Brinson Performance Attribution

import { brinsonAttribution } from 'meridianalgo';

const result = brinsonAttribution({
  segments: [
    { name: 'Tech',     portfolioWeight: 0.40, benchmarkWeight: 0.30, portfolioReturn: 0.15, benchmarkReturn: 0.12 },
    { name: 'Energy',   portfolioWeight: 0.20, benchmarkWeight: 0.25, portfolioReturn: 0.08, benchmarkReturn: 0.10 },
    { name: 'Finance',  portfolioWeight: 0.40, benchmarkWeight: 0.45, portfolioReturn: 0.06, benchmarkReturn: 0.07 },
  ],
});
console.log(result.totals);
// { allocation, selection, interaction, totalActive }

12. Factor Models (CAPM / Fama-French)

import { capmRegression, famaFrench3, famaFrench5 } from 'meridianalgo';

const capm = capmRegression({ portfolioReturns, marketReturns, riskFree: rfSeries });
console.log(`α=${capm.alpha.toFixed(4)} β=${capm.betas[0].toFixed(2)} R²=${capm.rSquared.toFixed(2)}`);

const ff3 = famaFrench3({
  portfolioReturns, marketReturns, smb, hml, riskFree: rfSeries,
});
// { alpha, betas: [Mkt-RF, SMB, HML], rSquared, residualStdError, n }

13. Execution Algorithms — VWAP/TWAP/POV/Almgren-Chriss

import {
  vwapSchedule, twapSchedule, povSchedule, implementationShortfallSchedule,
} from 'meridianalgo';

const totalQty = 100_000;

const vwap = vwapSchedule({
  totalQty,
  volumeProfile: [0.05, 0.15, 0.20, 0.10, 0.08, 0.07, 0.08, 0.10, 0.12, 0.05],
});

const twap = twapSchedule({ totalQty, buckets: 10 });

const pov = povSchedule({
  totalQty,
  participation: 0.10,
  marketVolume: forecastVolume,
});

// Almgren-Chriss optimal IS: x_k = X·sinh(κ(T−t_k))/sinh(κT), κ=√(λσ²/η)
const isq = implementationShortfallSchedule({
  totalQty, buckets: 10,
  sigma: 0.20, riskAversion: 1e-6,
  gamma: 1e-7, eta: 1e-6,
});

isq.forEach(s => console.log(`bucket ${s.index}: ${Math.round(s.qty)}`));

14. Order-Book Microstructure

import { OrderBook, rollSpread, squareRootImpact } from 'meridianalgo';

const ob = new OrderBook({
  bids: [{ price: 99.95, size: 1000 }, { price: 99.90, size: 500 }],
  asks: [{ price: 100.05, size: 800 }, { price: 100.10, size: 600 }],
});
console.log('Mid:', ob.midPrice());
console.log('Microprice:', ob.microprice());     // size-weighted mid
console.log('Imbalance:', ob.imbalance());       // (bidSize − askSize) / total

// Roll (1984) effective spread from trade prices
const spread = rollSpread(tradePrices);

// Almgren-Chriss square-root impact: c·σ·√(Q/ADV)
const cost = squareRootImpact({ qty: 50_000, adv: 1_000_000, sigma: 0.20, c: 0.5 });

15. Streaming Indicators (Real-Time Ticks)

import { StreamingMACD, StreamingBollinger } from 'meridianalgo';

const macd = new StreamingMACD(12, 26, 9);
const bb = new StreamingBollinger(20, 2);

ws.on('tick', ({ price }) => {
  const m = macd.nextValue(price);
  const b = bb.nextValue(price);
  if (m && price > b.upper) signalShort();
});

// Mid-bar revisions: replace() snapshots prior state, no compounding
macd.replace(correctedPrice);

16. Pure-JS ML — LSTM/GRU + HMM Regime Detection

Zero-dep ML primitives. No tfjs, no native bindings — runs in Node, Deno, Bun, browser.

import {
  LSTMCell, GRUCell, randomLSTMWeights,
  walkForward,
  trainHMM, viterbi,
  lagFeatures, rollingMean, logReturns, zScore,
} from 'meridianalgo';

// Forward pass with weights trained in Python/JAX
const cell = new LSTMCell(loadedWeights);
const { h, c } = cell.forward(sequence);

// Walk-forward time-series CV
const cv = walkForward(X, y, {
  mode: 'expanding', initialTrainSize: 100, testSize: 20, step: 20,
  fit: (Xtr, ytr) => trainModel(Xtr, ytr),
  predict: (m, Xte) => m.predict(Xte),
});
console.log('Mean MSE:', cv.meanMse);

// HMM regime detection (bull/bear classification)
const { params, logLik } = trainHMM(returns, 2, { maxIter: 100 });
const states = viterbi(returns, params);  // 0 or 1 per timestep

17. Wealth Protection — CPPI / TIPP

import { cppiStrategy, tippStrategy } from 'meridianalgo';

// CPPI: fixed floor protection
const path = cppiStrategy({
  riskyReturns,                    // per-period risky asset returns
  safeRate: 0.02 / 252,            // daily risk-free
  multiplier: 3,                   // leverage on cushion
  floorRatio: 0.80,                // protect 80% of starting wealth
  startingValue: 1_000_000,
});

// TIPP: ratcheting floor (raises with portfolio highs)
const tippPath = tippStrategy({
  riskyReturns, safeRate: 0.02 / 252,
  multiplier: 3, floorRatio: 0.80,
  startingValue: 1_000_000,
});

18. CLI

npx meridianalgo backtest --symbol AAPL --start 2023-01-01 --end 2024-01-01 --strategy sma-crossover
npx meridianalgo optimize --strategy momentum --grid config.json
npx meridianalgo analyze --returns returns.csv

API Reference

Full surface area documented in docs/API.md. Highlights:

Core Modules

import {
  // Indicators
  Indicators, AdvancedMath, KalmanFilter,

  // Data
  YahooAdapter, BinanceAdapter, AlpacaAdapter, PolygonAdapter, DataManager,

  // Backtest
  TimeBasedEngine, CommissionModel, SlippageModel,

  // Strategies
  MeanReversionStrategy, MomentumStrategy, TrendFollowingStrategy,
  PairsTradingStrategy, StrategyComposer, PositionSizer,

  // Risk
  RiskPerformanceMetrics, StressTesting, PerformanceAttribution,

  // Portfolio
  MeanVarianceOptimizer, BlackLittermanModel, RiskParityOptimizer,

  // Optimization
  GridSearchOptimizer, RandomSearchOptimizer,

  // Execution
  PaperBroker,

  // Utils
  MathUtils, StatUtils, TimeUtils,
} from 'meridianalgo';

Documentation index

• Getting Started
• Quick Start
• API Reference
• Indicators Catalog
• Strategies Guide
• Risk Management
• Setup & Development
• Security
• What's Next

Project Structure

src/
├── core/         Types, config, logger, plugin registry, errors
├── indicators/   100+ classic + advanced TA (momentum, volatility, volume, ML, microstructure, regime, seasonality)
├── data/         Yahoo, Binance, Alpaca, Polygon adapters + DataManager
├── backtest/     Event-driven TimeBasedEngine + cost models
├── strategies/   Mean-reversion, momentum, trend, pairs, composer, position sizer
├── risk/         Metrics, VaR/CVaR, stress testing, performance attribution
├── portfolio/    Mean-variance, Black-Litterman, risk-parity optimizers
├── execution/    Paper broker + broker adapter interface
├── models/       ARIMA, linear regression, state-space models
├── optimize/     Grid + random parameter search
├── utils/        Math, stats, time utilities
└── cli/          Command-line interface

Performance

• Zero-copy indicator computations where possible (typed arrays).
• NaN-padded outputs for lossless alignment with input series.
• Streaming-friendly TimeBasedEngine — process millions of bars without loading all in memory.
• Benchmark: Indicators.sma(series, 20) on 1M bars ≈ 15ms on M1 MBP.

Testing

npm test              # Run all tests (66 passing)
npm run test:coverage # Coverage report
npm run test:watch    # TDD mode

Coverage targets maintained across core/, indicators/, backtest/, risk/, strategies/, data/.

Contributing

Contributions welcome. See CONTRIBUTING.md and CODE_OF_CONDUCT.md.

1. Fork and clone
2. pnpm install
3. Create a feature branch
4. npm test && npm run lint
5. Open a PR with a clear description

License

MIT © 2026 Meridian Algorithmic Research Team. See LICENSE.

Disclaimer

For educational and research purposes only. Past performance is not indicative of future results. Trading financial markets involves substantial risk of loss. The authors and contributors are not responsible for any financial losses incurred through use of this software. Full text in DISCLAIMER.md.

Built by quants, for quants.

GitHub · npm · Issues