Crypto AlgoTrading Framework (TypeScript)

Algorithmic trading toolkit for crypto — backtest, tick-by-tick replay, and simulation modes. Ported from the original Python framework with matching strategy semantics.

  hist-{interval}/*.csv
           │
           ▼
    Entry / exit strategies (SMA cross, …)
           │
           ▼
    Stop-loss + trailing stop
           │
           ▼
    Backtest P&L · optional Redis cache

Quick start

cp .env.example .env
npm install
npm run check                    # typecheck + vitest + smoke backtest
npm run backtest                 # SMA cross on BTC-XRP (default)
npm run tick                     # tick-by-tick replay

Custom market:

npm start -- backtest BTC-SRN

Project structure

algotrading/
├── package.json
├── tsconfig.json
├── .env.example
├── hist-10m/                    # Sample CSV history (BTC-XRP, BTC-SRN)
│
├── src/
│   ├── index.ts                 # Public API exports
│   ├── cli.ts                   # backtest | tick commands
│   ├── config/
│   │   ├── vars.ts              # Env-driven defaults (interval, stops, …)
│   │   └── logger.ts
│   ├── types/market.ts          # MarketRow, EntryFn, ExitFn
│   ├── data/csv.ts              # loadMarketFromFile, listMarketsOnDisk
│   ├── indicators/
│   │   ├── sma.ts               # SMA crossover helpers
│   │   └── bollinger.ts         # Bollinger bands (pandas-compatible)
│   ├── strategies/
│   │   ├── entry.ts             # crossSmas entry
│   │   └── exit.ts              # crossSmas exit
│   ├── risk/stops.ts            # stopLoss, trailingStopLoss
│   ├── engine/
│   │   ├── signals.ts           # isTimeToBuy, isTimeToExit
│   │   ├── backtest.ts          # backtest(), backtestMarket()
│   │   ├── tickByTick.ts        # Candle replay loop
│   │   └── realtime.ts          # Live feed stub (extend for exchanges)
│   └── cache/                   # ioredis-os optional backtest cache
│
├── tests/                       # Vitest — parity with legacy Python tests
├── scripts/smoke-test.ts
│
└── cryptoalgotrading/           # Legacy Python implementation (reference)

Operating modes

Mode	API	Data source
Backtest	`backtest()`	`hist-{interval}/*.csv`
Tick-by-tick	`tickByTick()`	CSV replay with optional delay
Realtime	`realtime()`	Stub — wire exchange WebSocket in `src/engine/realtime.ts`

Example (programmatic)

import { backtest, entry, exit } from './src/index.js';

const total = await backtest({
  markets: ['BTC-XRP'],
  entryFns: [entry.crossSmas],
  exitFns: [exit.crossSmas],
  smas: [15, 40],
  interval: '10m',
  fromFile: true,
});

console.log(`Total P&L: ${total}%`);

Configuration

Variable	Default	Description
`DATA_DIR`	`.`	Root path for `hist-{interval}/` folders
`DEFAULT_INTERVAL`	`10m`	Candle folder suffix
`STOP_TYPE`	`3`	`0` off · `1` fixed · `2` trailing · `3` both
`STOP_LOSS_PCT`	`2`	Fixed stop % below entry
`TRAILING_LOSS_PCT`	`3`	Trailing stop % below peak
`COMMISSION_ENABLED`	`true`	Deduct `BNB_COMMISSION` on exits
`REDIS_URL`	—	Optional backtest result cache

Architecture

flowchart LR
  CSV["hist-10m/*.csv"]
  DATA["data/csv.ts"]
  IND["indicators/sma.ts"]
  STR["strategies entry/exit"]
  SIG["engine/signals.ts"]
  BT["engine/backtest.ts"]
  CACHE[("Redis optional")]

  CSV --> DATA --> BT
  IND --> STR --> SIG --> BT
  BT --> CACHE

Legacy Python

The original Python package lives in cryptoalgotrading/. It required Pandas, Matplotlib, InfluxDB, and Bittrex/Binance clients. The TypeScript edition keeps the same SMA crossover logic and CSV layout but drops matplotlib plotting and DB dependencies for a leaner Node.js runtime.

To run legacy Python tests: pip install -r requirements.txt && python -m pytest test/

Risk disclaimer

USE AT YOUR OWN RISK. This software is not financial advice. Test in simulation before deploying capital.

ai-algotrading-agent