quant-demo

macOS only — Windows and Linux are not supported yet.

⚠️ Demo Data Only: This project runs exclusively on static / dummy demo historical data. It does not connect to live market data feeds, live brokerages, or execute live trades.

A C++ backtesting engine for trading strategies, with a Node.js native addon so you can call it directly from JavaScript.

You give it price history as a CSV, pick a strategy, and it tells you what trades it would have made, the final P&L, and how bad the worst drawdown was.

Prerequisites

This package compiles C++ on install. You need these installed before running anything.

1. Xcode Command Line Tools (gives you the C++ compiler and make)

xcode-select --install

If it says already installed, you're good.

2. Node.js 18+

Download from nodejs.org or via Homebrew:

brew install node

3. Python 3 (required by node-gyp internally)

Comes pre-installed on macOS. Verify:

python3 --version

If missing:

brew install python

Verify everything is in order:

node --version     # should be v18+
npm --version      # should be 9+
python3 --version  # any 3.x
clang++ --version  # should print Apple clang version...

Running the CLI

make
./quant_demo

Swap the strategy, pass your own CSV data, or tune the windows without touching code:

./quant_demo --strategy ma-crossover --short 5 --long 20
./quant_demo --csv /path/to/prices.csv
./quant_demo --csv data/template.csv
./quant_demo --list    # see what strategies are registered
./quant_demo --help

Running from JavaScript

npm install   # builds the native addon
node demo.js  # run the example

const { run, listStrategies } = require('./index');

const result = run({
  strategy:     'ma-crossover',
  shortWindow:  3,
  longWindow:   5,
  slippageRate: 0.0005,
  initialCash:  10000,
  csvPath:      './data/template.csv', // optional: path to custom CSV
});

console.log(result.profitLoss);     // 14.39
console.log(result.returnPct);      // 0.144
console.log(result.maxDrawdownPct); // 0.083
console.log(result.trades);         // [{ timestamp, type, quantity, price }]
console.log(result.equityCurve);    // [{ timestamp, value }]

All options are optional — defaults are used if you omit them (bundled demo dataset is used by default).

Using Your Own Data (CSV Template)

A ready-to-use CSV template is provided at data/template.csv.

CSV Format Requirements

timestamp,price
1700000000,100.00
1700086400,101.50
1700172800,99.75

• Header: Must start with timestamp,price.
• timestamp: Unix timestamp (seconds).
• price: Number / float (closing or trade price).
• One bar per row, sorted in ascending chronological order.

How to use your own CSV file

1. Copy the template:

   cp data/template.csv data/my-stock.csv

2. Populate it with your own historical price data.

3. Pass the path to your file:

   CLI:

   ./quant_demo --csv data/my-stock.csv

   JavaScript:

   const result = run({
     csvPath: '/absolute/or/relative/path/to/my-stock.csv'
   });

Adding a Strategy

Create strategy/MyStrategy.hpp:

class MyStrategy : public Strategy {
public:
  Signal generateSignal(const PricePoint &point) override {
    // return Signal::BUY, Signal::SELL, or Signal::NONE
  }
  std::string getName() const override { return "My Strategy"; }
};

Register it in strategy/StrategyFactory.hpp:

#include "MyStrategy.hpp"

// inside the constructor:
add("my-strategy", [](Params p) -> std::unique_ptr<Strategy> {
  return std::unique_ptr<Strategy>(new MyStrategy());
});

Then just use it:

./quant_demo --strategy my-strategy

Nothing else needs to change.