📊 @backtest-kit/signals

> Technical analysis and trading signal generation library for AI-powered trading systems. Computes 50+ indicators across 4 timeframes and generates markdown reports for LLM consumption.

!screenshot

![TypeScript]()

Transform raw market data into actionable trading insights with multi-timeframe technical analysis, order book depth, and AI-ready markdown reports.

📚 Backtest Kit Docs | 🌟 GitHub

✨ Features

- 📈 Multi-Timeframe Analysis: 1m, 15m, 30m, 1h with synchronized indicator computation
- 🎯 50+ Technical Indicators: RSI, MACD, Bollinger Bands, Stochastic, ADX, ATR, CCI, Fibonacci, Support/Resistance
- 📊 Order Book Analysis: Bid/ask depth, spread, liquidity imbalance, top 20 levels
- 🤖 AI-Ready Output: Markdown reports formatted for LLM context injection
- ⚡ Performance Optimized: Intelligent caching with configurable TTL per timeframe
- 🧮 Custom Algorithms: Fibonacci retracements, support/resistance detection, volume analysis
- 📦 Zero Config: Works out-of-the-box with backtest-kit

📋 What It Does

@backtest-kit/signals analyzes market data and generates comprehensive technical reports across multiple timeframes:

| Timeframe | Candles | Indicators | Use Case |
|-----------|---------|------------|----------|
| MicroTerm (1m) | 60 | RSI(9,14), MACD(8,21,5), Stochastic, ADX(9), Bollinger(8,2), ATR, CCI, Volume, Squeeze | Scalping, ultra-short entries |
| ShortTerm (15m) | 144 | RSI(9), MACD(8,21,5), Stochastic(5,3,3), ADX(14), Bollinger(10,2), Fibonacci | Day trading |
| SwingTerm (30m) | 96 | RSI(14), MACD(12,26,9), Stochastic(14,3,3), Bollinger(20,2), Support/Resistance | Swing trading |
| LongTerm (1h) | 100 | RSI(14), MACD(12,26,9), ADX(14), Bollinger(20,2), SMA(50), DEMA, WMA, Volume Trend | Trend analysis |

Plus: Real-time order book analysis with bid/ask depth and imbalance metrics.

🚀 Installation

``bash
npm install @backtest-kit/signals backtest-kit
`

📖 Usage

$3

The easiest way to inject technical analysis into your LLM strategy:

`typescript
import { commitHistorySetup } from '@backtest-kit/signals';
import { getCandles } from 'backtest-kit';

// In your strategy's getSignal function:
const messages = [];

// Add all technical analysis + order book + candle history
await commitHistorySetup('BTCUSDT', messages);

// Now messages contains:
// - Order book analysis (bids/asks, spread, imbalance)
// - Candle history (1m, 15m, 30m, 1h)
// - Technical indicators for all 4 timeframes
// - System info (symbol, price, timestamp)

// Send to LLM
const signal = await llm(messages);
`

$3

For fine-grained control over what data to include:

`typescript
import {
commitBookDataReport,
commitOneMinuteHistory,
commitFifteenMinuteHistory,
commitThirtyMinuteHistory,
commitHourHistory,
commitMicroTermMath,
commitShortTermMath,
commitSwingTermMath,
commitLongTermMath,
} from '@backtest-kit/signals';

const messages = [];

// Order book analysis
await commitBookDataReport('BTCUSDT', messages);

// Candle histories
await commitOneMinuteHistory('BTCUSDT', messages); // Last 15 candles
await commitFifteenMinuteHistory('BTCUSDT', messages); // Last 8 candles
await commitThirtyMinuteHistory('BTCUSDT', messages); // Last 6 candles
await commitHourHistory('BTCUSDT', messages); // Last 6 candles

// Technical indicators
await commitMicroTermMath('BTCUSDT', messages); // 1m indicators
await commitShortTermMath('BTCUSDT', messages); // 15m indicators
await commitSwingTermMath('BTCUSDT', messages); // 30m indicators
await commitLongTermMath('BTCUSDT', messages); // 1h indicators

// Send to LLM
const signal = await llm(messages);
`

$3

`typescript
import { v4 as uuid } from 'uuid';
import { addStrategy, dumpSignal } from 'backtest-kit';
import { commitHistorySetup } from '@backtest-kit/signals';
import { json } from './utils/json.mjs'; // Your LLM wrapper

addStrategy({
strategyName: 'llm-strategy',
interval: '5m',
riskName: 'demo',
getSignal: async (symbol) => {
const messages = [
{
role: 'system',
content: 'You are a trading bot. Analyze technical indicators and generate signals.'
}
];

// Inject all technical analysis
await commitHistorySetup(symbol, messages);

// Add trading instructions
messages.push({
role: 'user',
content: [
'Based on the technical analysis above, generate a trading signal.',
'Use position: "wait" if signals are unclear or contradictory.',
'Return JSON: { position: "long"|"short"|"wait", priceTakeProfit: number, priceStopLoss: number }'
].join('\n')
});

// Generate signal via LLM
const resultId = uuid();
const signal = await json(messages);

// Save conversation for debugging
await dumpSignal(resultId, messages, signal);

return { ...signal, id: resultId };
}
});
`

$3

By default, signals uses a no-op logger. To enable logging:

`typescript
import { setLogger } from '@backtest-kit/signals';

setLogger({
log: console.log,
debug: console.debug,
info: console.info,
warn: console.warn,
});
`

📊 Generated Report Structure

$3

`markdown

Order Book Analysis

Symbol: BTCUSDT
Best Bid: 50000.00 | Best Ask: 50001.00
Mid Price: 50000.50 | Spread: 1.00
Depth Imbalance: +5.2% (buy pressure)

$3

| Price | Volume | % Total |
|-------|--------|---------|
| 50000.00 | 1.234 | 15.5% |
...

$3

| Price | Volume | % Total |
|-------|--------|---------|
| 50001.00 | 0.987 | 12.3% |
...
`

$3

`markdown

1-Minute Candle History (Last 15)

| Timestamp | Open | High | Low | Close | Volume | Volatility | Body Size |
|-----------|------|------|-----|-------|--------|------------|-----------|
| 2025-01-13 10:00 | 50000 | 50050 | 49990 | 50020 | 123.45 | 0.12% | 0.04% |
...
`

$3

`markdown

MicroTerm Analysis (1-Minute Timeframe)

| Time | Price | RSI(9) | RSI(14) | MACD | Signal | Histogram | Stoch %K | Stoch %D | ADX | +DI | -DI | BB Upper | BB Middle | BB Lower | ATR(5) | ATR(9) | CCI(9) | Volume | Vol Trend | Momentum | ROC | Support | Resistance | Squeeze | Pressure |
|------|-------|--------|---------|------|--------|-----------|----------|----------|-----|-----|-----|----------|-----------|----------|--------|--------|--------|--------|-----------|----------|-----|---------|------------|---------|----------|
| 10:00 | 50020 | 55.2 | 52.8 | 12.5 | 8.3 | 4.2 | 45.6 | 42.1 | 28.5 | 22.3 | 18.7 | 50100 | 50000 | 49900 | 15.2 | 18.9 | 45.7 | 123.45 | increasing | 0.8% | 1.2% | 49950 | 50100 | 0.85 | 15.2 |
...

Data Sources:
- RSI periods: 9, 14
- MACD: Fast=8, Slow=21, Signal=5
- Stochastic: K=3, D=3, Smooth=3 (primary), K=5, D=3, Smooth=3 (secondary)
...
`

🔄 Caching Strategy

Reports are cached to avoid redundant calculations:

| Timeframe | Cache Duration |
|-----------|----------------|
| 1-minute data | 1 minute |
| 15-minute data | 5 minutes |
| 30-minute data | 15 minutes |
| 1-hour data | 30 minutes |
| Order book | 5 minutes |

Cache is automatically cleared on errors.

🧮 Key Algorithms

$3

- MicroTerm/SwingTerm: Looks back N candles for significant highs/lows (±0.3% threshold)
- LongTerm: 4-candle pivot point method

$3

- Calculates levels: 0%, 23.6%, 38.2%, 50%, 61.8%, 78.6%, 100%
- Extensions: 127.2%, 161.8%, 261.8%
- Finds nearest level to current price (1.5% tolerance)

$3

- MicroTerm: SMA(5) volume with increasing/decreasing/stable trend (±20% threshold)
- LongTerm: 6-candle average comparison (±10% threshold)

$3

Imbalance = (bid_volume - ask_volume) / (bid_volume + ask_volume)

Positive = buy pressure, Negative = sell pressure

🎯 Use Cases

$3

Inject technical analysis into your LLM's context for intelligent signal generation.

$3

Combine indicators from different timeframes to filter false signals.

$3

Provide comprehensive market state to AI agents making trading decisions.

$3

Save generated reports for post-analysis and strategy improvement.

💡 Why Use @backtest-kit/signals?

Instead of manually calculating indicators and formatting data for your LLM:

`typescript
// ❌ Without signals (manual work)
const candles = await getCandles('BTCUSDT', '1m', 60);
const rsi = calculateRSI(candles, 14);
const macd = calculateMACD(candles, 12, 26, 9);
const bb = calculateBollingerBands(candles, 20, 2);
// ... 40+ more indicators
const report = formatToMarkdown(rsi, macd, bb, ...);
messages.push({ role: 'user', content: report });
`

`typescript
// ✅ With signals (one line)
await commitHistorySetup('BTCUSDT', messages);
``

Benefits:
- ⚡ Pre-computed, cached, optimized
- 📊 50+ indicators across 4 timeframes
- 🎨 Formatted markdown tables ready for LLM
- 🔄 Synchronized with backtest timeline
- 🛡️ Error handling and validation built-in

🤝 Contribute

Fork/PR on GitHub.

📜 License

MIT © tripolskypetr