🧿 @backtest-kit/sidekick

The easiest way to create a new Backtest Kit trading bot project. Scaffolds a multi-timeframe crypto trading strategy with Pine Script indicators via PineTS runtime, 4H trend filter + 15m signal generator, partial profit taking, breakeven trailing stops, and risk validation.

screenshot

Ask DeepWiki npm License

📚 Backtest Kit Docs | 🌟 GitHub

✨ Features

  • 🚀 Zero Config: Get started with one command - no setup required
  • 📊 Multi-timeframe analysis — 4H daily trend filter (RSI + MACD + ADX) combined with 15m entry signals (EMA crossover + volume spike + momentum)
  • 📜 Pine Script indicators — strategies written in TradingView Pine Script v5, executed locally via @backtest-kit/pinets
  • 🛡️ Risk management — SL/TP distance validation, Kelly-optimized partial profit taking (33/33/34%), breakeven trailing stop
  • 🔄 Position lifecycle — full monitoring with scheduled/opened/closed/cancelled event logging
  • 🔌 Binance integration — OHLCV candles, order book depth, tick-precise price/quantity formatting via CCXT
  • 🕐 Historical frames — predefined backtest periods covering bull runs, sharp drops, and sideways markets
  • 🎨 Web UI dashboard — interactive charting via @backtest-kit/ui
  • 💾 Persistent storage — crash-safe state with atomic persistence for both backtest and live modes

🚀 Quick Start

Create a New Project

npx -y @backtest-kit/sidekick my-trading-bot
cd my-trading-bot
npm start

That's it! You now have a working trading bot with:

  • Multi-timeframe Pine Script strategy (4H trend + 15m signals)
  • Risk management validation (SL/TP distance checks)
  • Partial profit taking and breakeven trailing stops
  • Cache utilities and debug scripts
  • CLAUDE.md for AI-assisted strategy iteration
  • Environment configuration

🏗️ Generated Project Structure

my-trading-bot/
├── src/
│   ├── index.mjs                  # Entry point — loads config, logic, bootstrap
│   ├── main/bootstrap.mjs         # Mode dispatcher (backtest / paper / live)
│   ├── config/
│   │   ├── setup.mjs              # Logger, storage, notifications, UI server
│   │   ├── validate.mjs           # Schema validation for all enums
│   │   ├── params.mjs             # Environment variables (Ollama API key)
│   │   └── ccxt.mjs               # Binance exchange singleton via CCXT
│   ├── logic/
│   │   ├── strategy/main.strategy.mjs    # Main strategy — multi-TF signal logic
│   │   ├── exchange/binance.exchange.mjs # Exchange schema — candles, order book, formatting
│   │   ├── frame/*.frame.mjs             # Backtest time frames (Feb 2024, Oct–Dec 2025)
│   │   ├── risk/sl_distance.risk.mjs     # Stop-loss distance validation (≥0.2%)
│   │   ├── risk/tp_distance.risk.mjs     # Take-profit distance validation (≥0.2%)
│   │   └── action/
│   │       ├── backtest_partial_profit_taking.action.mjs
│   │       ├── backtest_lower_stop_on_breakeven.action.mjs
│   │       └── backtest_position_monitor.action.mjs
│   ├── classes/
│   │   ├── BacktestPartialProfitTakingAction.mjs  # Scale out at 3 TP levels
│   │   ├── BacktestLowerStopOnBreakevenAction.mjs # Trailing stop on breakeven
│   │   └── BacktestPositionMonitorAction.mjs      # Position event logger
│   ├── math/
│   │   ├── timeframe_4h.math.mjs   # 4H trend data — RSI, MACD, ADX, DI+/DI-
│   │   └── timeframe_15m.math.mjs  # 15m signal data — EMA, ATR, volume, momentum
│   ├── enum/                        # String constants for type-safe schema refs
│   └── utils/getArgs.mjs            # CLI argument parser with defaults
├── config/source/
│   ├── timeframe_4h.pine    # Pine Script v5 — Daily Trend Filter (RSI/MACD/ADX)
│   └── timeframe_15m.pine   # Pine Script v5 — Signal Strategy (EMA/ATR/Volume)
├── scripts/
│   ├── run_timeframe_15m.mjs # Standalone 15m Pine Script runner
│   ├── run_timeframe_4h.mjs  # Standalone 4H Pine Script runner
│   └── cache/
│       ├── cache_candles.mjs     # Pre-download OHLCV candles (1m/15m/4h)
│       ├── validate_candles.mjs  # Verify cached candle data integrity
│       └── cache_model.mjs       # Pull Ollama LLM model with progress bar
├── docker/ollama/
│   ├── docker-compose.yaml   # Ollama GPU container setup
│   └── watch.sh              # nvidia-smi monitor
├── CLAUDE.md                 # AI strategy development guide
├── .env                      # Environment variables
└── package.json              # Dependencies

💡 Strategy Overview

🎯 4H Trend Filter (timeframe_4h.pine)

Determines the market regime using three indicators:

Regime Condition
AllowLong ADX > 25, MACD histogram > 0, DI+ > DI-, RSI > 50
AllowShort ADX > 25, MACD histogram < 0, DI- > DI+, RSI < 50
AllowBoth Strong trend but no clear bull/bear regime
NoTrades ADX ≤ 25 (weak trend)

⚡ 15m Signal Generator (timeframe_15m.pine)

Generates entry signals with EMA crossover confirmed by volume and momentum:

  • Long: EMA(5) crosses above EMA(13), RSI 40–65, price above EMA(50), volume spike (>1.5x MA), positive momentum
  • Short: EMA(5) crosses below EMA(13), RSI 35–60, price below EMA(50), volume spike, negative momentum
  • SL/TP: Static 2%/3% from entry price
  • Signal expiry: 5 bars

🛡️ Risk Filters

  • Reject signals where SL distance < 0.2% (slippage protection)
  • Reject signals where TP distance < 0.2% (slippage protection)
  • Trend alignment: long signals rejected in bear regime, short signals rejected in bull regime

💹 Position Management

  • Partial profit taking: Scale out at 3 levels — 33% at TP3, 33% at TP2, 34% at TP1
  • Breakeven trailing stop: When breakeven is reached, lower trailing stop by 3 points

🕐 Backtest Frames

Frame Period Market Note
February2024 Feb 1–29, 2024 Bull run
October2025 Oct 1–31, 2025 Sharp drop Oct 9–11
November2025 Nov 1–30, 2025 Sideways with downtrend
December2025 Dec 1–31, 2025 Sideways, no clear direction

💡 CLI Options

# Create project with custom name
npx -y @backtest-kit/sidekick my-bot

# Create in current directory (must be empty)
npx -y @backtest-kit/sidekick .

📋 Dependencies

Package Purpose
backtest-kit Core backtesting/trading framework
@backtest-kit/pinets Pine Script v5 runtime for Node.js
@backtest-kit/ui Interactive charting dashboard
@backtest-kit/ollama LLM inference integration
ccxt Binance exchange connectivity
functools-kit singleshot, randomString utilities
pinolog File-based structured logging
openai OpenAI API client
ollama Ollama local LLM client

🔗 Links

🤝 Contribute

Found a bug or want to add a feature? Open an issue or submit a PR!

📜 License

MIT © tripolskypetr

Settings

Member Visibility

On This Page

🧿 @backtest-kit/sidekick