stock-bot

A self-contained reinforcement learning trading bot engine written in pure TypeScript. No ML framework dependencies — just math.

Features

• Deep Q-Network (DQN) with Double DQN, Prioritized Experience Replay (PER), n-step returns, and Polyak-averaged target networks
• Pure TypeScript neural network — flat Float64Array buffers, He initialization, Adam optimizer, gradient clipping
• 8-action extended action space: HOLD, BUY_LO/MD/HI, SELL_LO/MD/HI, CLOSE with leverage tiers
• Fractal market simulator using fBM (Hosking method) + GARCH(1,1) + Merton jump-diffusion + Markov regime switching
• 14 technical indicators with both batch and incremental (O(1) per candle) computation
• Genetic algorithm hyperparameter optimization with tournament selection, crossover, and mutation
• Trading constraints system — reverse-only, min-hold, cooldown, conviction threshold, loss budget, asymmetric sizing
• Provider interfaces for plugging in live market feeds, trade executors, L2 data, and storage backends
• Zero runtime dependencies — only typescript and vitest as dev dependencies

Installation

npm install @sschepis/stock-bot

Quick Start

import { DQNAgent, Market, TickSimulator, MemoryStorageProvider } from '@sschepis/stock-bot';

// Create a DQN agent
const agent = new DQNAgent({
  stateSize: 21,
  hiddenLayers: [48, 32],
  learningRate: 0.001,
  gamma: 0.95,
});

// Create a simulated market
const market = new Market();

// Run a training loop
for (let tick = 0; tick < 1000; tick++) {
  market.tick();
  const state = market.getFeatures(null);
  const action = agent.getAction(state, false, 0);
  const reward = 0; // compute your reward
  const nextState = market.getFeatures(null);
  agent.store(state, action, reward, nextState, false);
  agent.train();
}

// Save the trained agent
const storage = new MemoryStorageProvider();
agent.saveToStorage(storage, 'my-agent');

Architecture

stock-bot/
├── src/
│   ├── core/           # RL engine, neural net, market sim, indicators
│   ├── engines/        # Physics-based market analysis engines
│   ├── trading/        # Orchestrator logic, step functions, fast training
│   └── providers/      # Pluggable interfaces for external services
├── tests/              # 252 tests across 12 files
├── docs/               # Detailed documentation
└── examples/           # Ready-to-run usage examples

Core Modules

| Module | Description | |--------|-------------| | NeuralNet | Feedforward MLP with flat Float64Array storage, ReLU hidden layers, Adam optimizer | | DQNAgent | Double DQN with PER, n-step returns, Welford z-score normalization, streak scaling | | PrioritizedReplayBuffer | Sum-tree based O(log n) prioritized sampling with importance-weight correction | | Market | Market simulator with candle formation, regime detection, L2 book features | | TickSimulator | Fractal price generator: fBM + GARCH + jumps + regime switching | | TradingConstraints | Behavioral constraint system with 10 configurable rules | | IncrementalIndicators | O(1) per-candle incremental RSI, MACD, Bollinger, ATR, Stochastic, ADX, VWAP, OBV | | BayesianOptimizer | GA-based hyperparameter optimization with elitism and tournament selection |

Provider Interfaces

The library uses a provider pattern to decouple from external services:

• StorageProvider — Replaces localStorage. Ships with MemoryStorageProvider (in-memory Map).
• MarketFeedProvider — Interface for live price/candle feeds
• TradeExecutorProvider — Interface for executing trades on an exchange
• L2DataProvider — Interface for Level 2 order book data

Action Space

The agent operates over 8 actions with leverage tiers:

| Index | Action | Leverage | |-------|--------|----------| | 0 | HOLD | 0x | | 1 | BUY_LO | 0.25x | | 2 | BUY_MD | 0.60x | | 3 | BUY_HI | 1.00x | | 4 | SELL_LO | 0.25x | | 5 | SELL_MD | 0.60x | | 6 | SELL_HI | 1.00x | | 7 | CLOSE | 0x |

Market Regimes

The tick simulator supports 8 preset regimes:

• trending_up / trending_down — Hurst > 0.5, directional drift
• mean_revert — Hurst < 0.5, gravity toward equilibrium
• volatile — High GARCH alpha, frequent jumps
• calm — Low volatility, tight spread
• random_walk — Hurst = 0.5, no drift
• liquidation_cascade — Extreme vol + negative drift
• accumulation — Low vol mean-reversion
• cycle — Auto-rotates through trending → volatile → trending_down → mean_revert

Testing

npm test           # Run all 252 tests
npm run test:watch # Watch mode

Tests cover:

• Unit tests for every core module
• Integration tests for end-to-end training loops
• Learning convergence tests (XOR learning, directional preference, danger avoidance)
• Serialization round-trip tests
• Provider interface tests

Documentation

See the docs/ folder:

• Getting Started — Installation and first training loop
• Core Concepts — DQN, PER, n-step returns, feature engineering
• Provider Guide — Implementing custom providers for live trading
• API Reference — Complete API documentation

Examples

See the examples/ folder:

• basic-training.ts — Train an agent on simulated data
• custom-provider.ts — Implement a custom storage provider
• hyperopt.ts — Run hyperparameter optimization

License

MIT