@backtest/command-line

Backtest JS: Command-line Interface (CLI)

Enhance your trading strategies with Backtest, the leading CLI tool crafted for trading developers. Leverage the power of TypeScript (or JavaScript) to backtest your strategies with unmatched precision, efficiency, and flexibility.

This or that (!?)

TL;DR If you are unaware of the original project, you probably don’t need to read further unless you’re curious.

If you’re wondering why there are two similar repositories (this one and the one you can find here), the answer is simple: Andrew’s is the original platform, and it’s well-made, but it hasn’t been updated for a while. While waiting for the author to resume work on it, I decided to create an updated and maintained version. The original license allows this (at least it seems clear to me), and we don’t intend to change the license in the future. The basic idea is to keep this product updated and add some features over time. So far, we’ve added what we needed, which includes:

• Agile loading of strategies (added the command 🌀 Scan Trading Strategies);
• Removed explicit commands for adding and deleting strategies in favor of the single scan command;
• Strategies are always reloaded as code, so you just need to modify the code on the fly and save the .ts file. Then, by restarting the strategy from the CLI, even from an already running process, the new version is used;
• Modified the HTML template to make a few things clearer for now (like params, colors, note, ..);
• Added the ability to include a note on purchase and sale (to understand why a purchase or sale was made, the reason is reported in the “all orders” section of the HTML file);
• Added structure properties inside strategy file .ts. This greatly helps in adding or proliferating strategies; just rescan and you’re done;
• Ability to use Node v18 or higher (for this, we removed tulind and added technicalindicators, although both are old and tulind is undoubtedly a great choice. If you need it, you can still add it back in the fork).
• Decoupling of Backtest Framework functionality from CLI commands exposed through this project.

What might come or be requested (f.e.):

• Ability to call it globally from the shell command line;
• Specify an external folders for strategies, especially useful if executed globally (see above point);
• A bit more structured documentation, including more specific and sophisticated examples.

Assumptions for the future:

• The product will remain accessible and usable for free;
• External collaborations or maintainers are always welcome.
• Possible funding options will be considered if needed to keep the product updated, but for now, it’s not necessary or useful to think about it;

Key Features 🌟

• Intuitive CLI Interface: User-friendly command-line interface for smooth operation.

• Comprehensive Candle Data: Access historical candle data from Binance or effortlessly import your own CSV files.

• Integrated Storage: Efficiently store your candle data, strategies, and results in the internal SQLite storage.

• Documentation: Maximize Backtest’s capabilities with thorough guides and resources.

Quick Start

Setup Environment

Follow these instructions to setup the environment:

  git clone [e-mail]:backtestjs/command-line.git backtest-cli
  cd backtest-cli
  npm install

Initial Setup

When you run the project for the first time, you need to set up the database. Follow these steps:

• Validate your Prisma schemas: npx prisma validate
• Generate the Prisma client: npx prisma generate
• Create the database: npx prisma db push

These commands ensure that your project is properly configured and ready to use.

Note: If you are not familiar with Prisma and the commands above, you can use npm run align-db to align the schema with the database.

npm run align-db

Run this project

Start strategic backtesting with a single command:

  npm run dev # main.ts
  npm run start # dist/main.js

Documentation

Explore the Backtest universe with our Full Documentation. Discover tutorials, video guides, and extensive examples.

Historical Candle Data

Easily download candle data from Binance or import it from a CSV file for strategy execution. Additionally, you can export your data to a CSV file via the CLI with just a few clicks. No coding or API key is required (thanks Binance!).

Custom Strategies

In addition to the demonstration strategies already present, you can create your own by adding a file under src/strategies.

Use one of the existing files or the examples in this guide as a reference. Each file should contain a runStrategy method, and if it uses external or dynamic parameters, it should also include a properly filled-out properties structure.

Whenever you create a new strategy, modify the properties structure of an existing one, or delete an existing strategy, you need to run the 🌀 Scan Trading Strategies CLI command.

There’s no need to stop or restart the backtest process if it’s running, or to exit the program. The program will reload the contents of your file with each launch, as long as it’s synchronized.

Using well-defined or dynamic parameters (instead of constants within your strategy) will allow you to run multiple tests simultaneously.

Candle Data

Each candle have the following information available:

export interface Candle {
  openTime: number
  open: number
  high: number
  low: number
  close: number
  volume: number
  closeTime: number
  assetVolume: number
  numberOfTrades: number
}

Buy and Sell

It is possible to execute a buy or sell by following this:

export interface BuySell {
  price?: number // Price of which you will trade the asset
  position?: string // Can be "short" or "long" (long is the default)
  amount?: number | string // Amount of asset to buy can be number or string (string must include a %), f.e. 300 or "10%"
  baseAmount?: number // Trade the base amount to use for percentage calculations (total worth for baseAmount equals to amount)
  stopLoss?: number // Price of which a stop loss will trigger (all will be sold on the stop loss)
  takeProfit?: number // Price of which a take profit will trigger (all will be sold on the take profit price)
  percentFee?: number
  percentSlippage?: number //
  note?: string // Add a simple note to identify this trade
}

Pay attention: follow these rules:

• You CAN short and long at the same time but they need to be two seperate calls
• If you try to buy or sell but you already bought or sold everything, the buy or sell will be skipped and not recorded
• You cannot use “amount” and “baseAmount” params together
• If in a short and a long you cannot use “amount” or “baseAmount” when selling without specifying a position.
• You cannot use stopLoss if you long and short at the same time
• You cannot use takeProfit if you long and short at the same time
• Amount param can be a number or a string, if a string it must contain a percent sign “%”

In particular, the buy signal:

bth.buy()

/* or */
await bth.buy({
  position: 'short',
  amount: '10%', // or baseAmount
  note: 'a simple note here',
  stopLoss: stopLoss,
  percentSlippage: percentSlippage,
  percentFee: percentFee
})

while the sell signal:

bth.sell()

/* or */

await bth.sell({
  amount: 250, // or baseAmount
  note: 'a simple note here'
})

Examples: buy & sell

Beginner: The simplest buy & sell

// Lets say you have $1000 and want to trade bitcoin
// Put in a long order and buy all which is $1000 worth of bitcoin
await buy()
// Lets say you bought bitcoin and are now worth $1000
// Put in a sell order and sell all which is $1000 worth of bitcoin
await sell()

Begginer: How to specify amount

// Lets say you have $1000 and want to trade bitcoin
// Put in a long order of $400 worth of bitcoin
await buy({ amount: 400 })
// Same thing can be achieved here
await buy({ amount: '40%' })
// Lets say you bought bitcoin and are now worth $1000 in bitcoin and put in a sell order of $400 worth of bitcoin
await sell({ amount: 400 })
// Same thing can be achieved here
await sell({ amount: '40%' })

Regular: How to specify stop loss and take profit

// Lets say you have $1000 and want to trade bitcoin
// Put a short order in with all which is $1000 and a stop loss at $24,000
await buy({ position: "short", stopLoss: 24000 })
// The application is smart enough to know that its a short and only sell if a candles high goes above $24,000
// Lets say you bought bitcoin in a long and a short but only want to sell some of the shorted amount
// Put in a sell order to sell 50% of the shorted amount
await sell({ position: "short", amount "50%"})

Regular: How to specify base amount

// Lets say you have $1000 and bitcoin is currently worth $2000
// Put a long order in of .25 bitcoin which is $500 worth
await buy({ baseAmount: 0.25 })
// This can also be achieved by doing
await buy({ amount: 500 })
// You cannot use amount with baseAmount in the same buy / sell call
// Lets say you bought bitcoin and are worth $1000 and bitcoin is worth $2000
// Put a short order in of .25 bitcoin which is $500 worth
await sell({ baseAmount: 0.25 })
// This can also be achieved by doing
await sell({ amount: 500 })

Advanced: How to place an order at a specific price

// Lets say you have $1000 and bitcoins close was $2100 but you had a trigger to buy at $2000
// Put a long order in of $1000 worth but bitcoin at a price of $2000
await buy({ price: 2000 })
// Lets say you bought and bitcoin is worth $2200 but you had a trigger to sell at $2100
// Put a sell order in where bitcoin is worth $2100
await sell({ price: 2100 })

Examples: strategy

Beginner: The simplest strategy

Below is an example of a simple 3 over 45 SMA strategy. You buy once the 3 crosses the 45 and sell otherwise. In this example, we don’t use the power of params.

import { BTH } from '@backtest/framework'
import { indicatorSMA } from '../indicators/moving-averages'

export async function runStrategy(bth: BTH) {
  const lowSMACandles = await bth.getCandles('close', 0, 3)
  const highSMACandles = await bth.getCandles('close', 0, 45)

  // Calculate low and high SMA
  const lowSMA = await indicatorSMA(lowSMACandles, 3)
  const highSMA = await indicatorSMA(highSMACandles, 45)

  // Buy if lowSMA crosses over the highSMA
  if (lowSMA > highSMA) {
    await bth.buy()
  }

  // Sell if lowSMA crosses under the highSMA
  else {
    await bth.sell()
  }
}

Pay attention: hard-coded parameters will prevent you from running multiple tests simultaneously!

Advanced: the same strategy with parameters

Below is an example of a simple SMA strategy like above but it’s not hard-coded to the 3 over 45. When you run the strategy through the CLI, you will be asked to provide a low and high SMA. You can even provide multiple lows and multiple highs, and all the variations will be tested in one run.

import { BTH } from '@backtest/framework'
import { indicatorSMA } from '../indicators/moving-averages'

export const properties = {
  params: ['lowSMA', 'highSMA'],
  dynamicParams: false
}

export async function runStrategy(bth: BTH) {
  const lowSMAInput = bth.params.lowSMA
  const highSMAInput = bth.params.highSMA

  // Get last candles
  const lowSMACandles = await bth.getCandles('close', 0, lowSMAInput)
  const highSMACandles = await bth.getCandles('close', 0, highSMAInput)

  // Calculate low and high SMA
  const lowSMA = await indicatorSMA(lowSMACandles, lowSMAInput)
  const highSMA = await indicatorSMA(highSMACandles, highSMAInput)

  // Buy if lowSMA crosses over the highSMA
  if (lowSMA > highSMA) {
    await bth.buy()
  }

  // Sell if lowSMA crosses under the highSMA
  else {
    await bth.sell()
  }
}

Visualize Results

BacktestJS not only delivers performance insights but also visualizes your strategy’s effectiveness through comprehensive charts and statistics.

Income Results, Buy/Sell Locations, and More

Explore the visual representation of your trading outcomes, from income results to buy/sell locations, offering you a clear view of your strategy’s performance.

Multi Value Results

Examine permutation results and heatmap visualizations to refine your strategies across different values all in one run.

Multi Symbol Results

See if that killer strategy works across the board on many symbols and timeframes with ease. Get all your results in one shot with blazing fast results.

Import Candle Data from CSV

Although there is an option to download data from binance for crypto assets there is no automatic download available for traditional symbols such as apple or tesla stock as well as forex symbols such as usdyen.

This candle data can be downloaded from third party sites such as yahoo finance and can then be easily imported to the Backtest database to use with any strategy.

How to prepare CSV file

The CSV file must have the following fields:

• Close time of the candle: closeTime or date
• Open price of the candle: open
• High price of the candle: high
• Low price of the candle: low
• Close price of the candle: close

The CSV file can have the following optional fields:

• Open time of the candle: openTime, openTime
• Volume in the candle: volume
• Asset volume of the candle: assetVolume
• Number of trades done in the candle: numberOfTrades

Pay attention: follow these rules:

• Each field can be written without considering case sensitivity.
• The order of the fields in the CSV file is not important.
• Any additional fields will not cause an error but won't be added to the database.

Thanks to

The original project is currently on hold. However, thanks to the permissive license, we aim to continue the author’s work. We express our gratitude and recognition for creating a usable product under a license that allows for external adoption and support.

So, our thanks to Andrew Baronick ( GitHub / LinkedIn )