@backtest-kit/sidekick

🧿 @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.

📚 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

New to backtest-kit? The fastest way to get a real, production-ready setup is to clone the reference implementation — a fully working news-sentiment AI trading system with LLM forecasting, multi-timeframe data, and a documented February 2026 backtest. Start there instead of from scratch.

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

• Backtest Kit Documentation
• GitHub Repository
• Demo Projects
• API Reference

🤝 Contribute

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

📜 License

MIT © tripolskypetr