πŸ“Š @backtest-kit/ui

Full-stack UI framework for visualizing cryptocurrency trading signals, backtests, and real-time market data. Combines a Node.js backend server with a React dashboard - all in one package.

screenshot

Ask DeepWiki npm TypeScript

Interactive dashboard for backtest-kit with signal visualization, candle charts, risk analysis, and notification management. Built with React 18, Material-UI, and Lightweight Charts.

πŸ“š Backtest Kit Docs | 🌟 GitHub

✨ Features

  • πŸ“ˆ Interactive Charts: Candlestick visualization with Lightweight Charts (1m, 15m, 1h timeframes)
  • 🎯 Signal Tracking: View opened, closed, scheduled, and cancelled signals with full details
  • πŸ“Š Risk Analysis: Monitor risk rejections and position management
  • πŸ”” Notifications: Real-time notification system for all trading events
  • πŸ’Ή Trailing & Breakeven: Visualize trailing stop/take and breakeven events
  • 🌐 Multi-Exchange: Support for 100+ exchanges via CCXT integration
  • 🎨 Material Design: Beautiful UI with MUI 5 and Mantine components
  • 🌍 i18n Ready: Internationalization support built-in

πŸ“‹ What It Does

@backtest-kit/ui provides both backend API and frontend dashboard:

Component Description
serve() Start HTTP server with REST API endpoints
getRouter() Get expressjs-compatible router for custom middleware integration

πŸš€ Installation

npm install @backtest-kit/ui backtest-kit ccxt

πŸ“– Usage

Quick Start - Launch Dashboard

import { serve } from '@backtest-kit/ui';

// Start the UI server
serve('0.0.0.0', 60050);

// Dashboard available at http://localhost:60050

Custom Logger Integration

import { setLogger } from '@backtest-kit/ui';

setLogger({
  log: (msg) => console.log(`[UI] ${msg}`),
  warn: (msg) => console.warn(`[UI] ${msg}`),
  error: (msg) => console.error(`[UI] ${msg}`),
});

πŸ“ Dashboard Revenue Math

The Revenue metrics on the dashboard are calculated in dollar terms by summing the pnlCost field from all closed signals within each time window.

Dollar PnL formula

revenue[window] = Ξ£ signal.pnl.pnlCost   (for all closed signals in that window)

pnlCost is computed by the backend (toProfitLossDto) as:

pnlCost = (pnlPercentage / 100) Γ— pnlEntries
Field Source Description
pnl.pnlCost IStorageSignalRow Absolute P&L in USD β€” the only value summed for revenue
pnl.pnlPercentage IStorageSignalRow Percentage P&L (accounts for DCA-weighted entry price, slippage, and fees)
pnl.pnlEntries IStorageSignalRow Total invested capital in USD β€” sum of all entry costs (Ξ£ entry.cost)

Example (1 DCA entry at $100, position closed +5%):

DCA entries pnlEntries pnlPercentage pnlCost
1 $100 5 % +$5.00
2 $200 5 % +$10.00
3 $300 5 % +$15.00

Time windows

The anchor point depends on execution mode:

  • Backtest mode β€” latest updatedAt across all closed signals (time windows are relative to the end of the run)
  • Live mode β€” Date.now() (wall-clock time)
Window Range
Today >= startOf(anchorDay)
Yesterday [anchorDay βˆ’ 1d, anchorDay)
7 days >= anchorDay βˆ’ 7d
31 days >= anchorDay βˆ’ 31d

Revenue and signal count are tracked separately for each window and aggregated across all symbols on the Dashboard.

πŸ“ Position PNL Math

Effective entry price (DCA-weighted)

When multiple DCA entries exist, the effective open price is a cost-weighted harmonic mean:

effectivePrice = Ξ£cost / Ξ£(cost / price)

This is the correct formula for fixed-dollar entries (not simple average), because buying $100 worth at different prices gives different coin quantities.

Partial closes (PP/PL)

Each partial stores a costBasisAtClose snapshot β€” the running dollar cost-basis before that partial fired. This avoids replaying the full entry history on every call.

Cost-basis replay:

for each partial[i]:
    closedDollar      += (percent[i] / 100) Γ— costBasisAtClose[i]
    remainingCostBasis = costBasisAtClose[i] Γ— (1 - percent[i] / 100)

# DCA entries added AFTER the last partial are appended:
remainingCostBasis += Ξ£ entry.cost for entries[lastEntryCount..]

totalClosedPercent = closedDollar / totalInvested Γ— 100

Effective price through partials is computed iteratively so that a partial sell does not change the entry price of the remaining coins:

# partial[0]:
  effPrice = costBasisAtClose[0] / Ξ£(cost/price for entries[0..cnt[0]])

# partial[j]:
  remainingCB = prev.costBasisAtClose Γ— (1 - prev.percent / 100)
  oldCoins    = remainingCB / effPrice        ← coins still held
  newCoins    = Ξ£(cost/price for DCA entries between j-1 and j)
  effPrice    = (remainingCB + newCost) / (oldCoins + newCoins)

toProfitLossDto β€” weighted PNL with slippage & fees

Without partials:

priceOpenSlip  = effectivePrice Γ— (1 Β± slippage)
priceCloseSlip = priceClose     Γ— (1 βˆ“ slippage)

pnlPercentage = (priceCloseSlip - priceOpenSlip) / priceOpenSlip Γ— 100
fee           = CC_PERCENT_FEE Γ— (1 + priceCloseSlip / priceOpenSlip)
pnlPercentage -= fee

With partials β€” dollar-weighted sum:

weight[i] = (percent[i] / 100 Γ— costBasisAtClose[i]) / totalInvested

totalWeightedPnl = Ξ£ weight[i] Γ— pnl[i]           # each partial at its own effectivePrice
                 + remainingWeight Γ— pnlRemaining   # rest closed at final priceClose

fee = CC_PERCENT_FEE                                              # open (once)
    + Ξ£ CC_PERCENT_FEE Γ— weight[i] Γ— (closeSlip[i] / openSlip[i])  # per partial
    + CC_PERCENT_FEE Γ— remainingWeight Γ— (closeSlip / openSlip)     # final close

pnlPercentage = totalWeightedPnl - fee
pnlCost       = pnlPercentage / 100 Γ— totalInvested
Field Description
totalInvested Ξ£ entry.cost (or CC_POSITION_ENTRY_COST if no _entry)
weight[i] Real dollar share of each partial relative to totalInvested
effectivePrice at partial i Computed via iterative costBasisAtClose replay up to partials[i]
priceOpen in result getEffectivePriceOpen(signal) β€” DCA-weighted harmonic mean across all entries

πŸ–₯️ Dashboard Views

The frontend provides specialized views for different trading events:

View Description
Signal Opened Entry details with chart visualization
Signal Closed Exit details with PnL analysis
Signal Scheduled Pending orders awaiting activation
Signal Cancelled Cancelled orders with reasons
Risk Rejection Signals rejected by risk management
Partial Profit/Loss Partial position closures
Trailing Stop/Take Trailing adjustments visualization
Breakeven Breakeven level adjustments

Each view includes:

  • πŸ“‹ Detailed information form
  • πŸ“ˆ 1m, 15m, 1h candlestick charts
  • πŸ“₯ JSON export for all data

πŸ’‘ Why Use @backtest-kit/ui?

Instead of building custom dashboards:

Without backtest-kit

// ❌ Without @backtest-kit/ui
// Build your own React app
// Implement chart components
// Create signal visualization
// Handle notifications
// Write API endpoints
// ... weeks of development

With backtest-kit

// βœ… With @backtest-kit/ui
import { serve } from '@backtest-kit/ui';

serve(); // Full dashboard ready!

Benefits:

  • πŸ“Š Production-ready trading dashboard out of the box
  • πŸ“ˆ Professional chart visualization with price lines and markers
  • πŸ”” Complete notification system for all trading events
  • 🎨 Beautiful Material Design interface
  • ⚑ Fast development - focus on strategy, not UI
  • πŸ›‘οΈ Full TypeScript support

🀝 Contribute

Fork/PR on GitHub.

πŸ“œ License

MIT Β© tripolskypetr

Settings

Member Visibility

On This Page

πŸ“Š @backtest-kit/ui