fbtf

Futures Back Testing Framework for TypeScript

---

What is it?

fbtf is a Node-first, ESM-only TypeScript library for deterministic backtesting and live paper trading.

The project is intentionally narrow. It is not trying to be a giant trading platform. The goal is to provide one runtime model that is easy to understand, easy to test, and explicit about how orders, feeds, brokers, and results fit together.

The first practical target is futures. The internals are asset-aware, but the current product story is centered on a clean futures backtesting workflow instead of pretending every asset class is equally mature.

---

Install

npm install @thecommandcat/fbtf

---

Documentation

Longer-form docs live in this repository under docs/content/docs.

Run the docs site locally with:

npm run docs:dev

Build the docs site with:

npm run docs:build

The docs site also includes a roadmap page for the current direction of the project.

---

What fbtf is for

• deterministic historical backtests
• live paper trading with the same mental model
• strategies that benefit from explicit runtime behavior
• TypeScript-first workflows with readable contracts and results

What fbtf is not

• a real-money execution system
• a tick-level simulator
• a multi-market portfolio platform
• a cloud product or managed service
• a giant framework with hidden automation

---

Core ideas

One runtime model

Backtest mode and paper mode should feel like the same system, not two loosely related products.

Deterministic behavior

Runs should be reproducible and explainable. That means explicit state transitions, structured diagnostics, and no hidden concurrency inside the runtime core.

Small public API

The root package intentionally stays small:

• defineStrategy
• createRunner
• createHistoricalFeed
• createLiveFeed
• createPaperBroker
• defineMarket

Everything else lives on explicit subpaths like @thecommandcat/fbtf/data, @thecommandcat/fbtf/markets, @thecommandcat/fbtf/results, and @thecommandcat/fbtf/experiment.

Adapter-based integrations

The runtime core should stay vendor-neutral. Provider-specific behavior belongs in adapters instead of leaking into the core runtime API.

---

Minimal example

import {
  createHistoricalFeed,
  createPaperBroker,
  createRunner,
  defineStrategy,
} from '@thecommandcat/fbtf';
import { normalizeBars } from '@thecommandcat/fbtf/data';
import { mnq } from '@thecommandcat/fbtf/markets';

const bars = normalizeBars(
  [
    {
      startTime: '2024-03-08T14:30:00.000Z',
      open: 18420,
      high: 18425,
      low: 18418,
      close: 18420,
      volume: 120,
    },
    {
      startTime: '2024-03-08T14:35:00.000Z',
      open: 18420,
      high: 18440,
      low: 18420,
      close: 18435,
      volume: 180,
    },
  ],
  {
    defaultMarketId: mnq.id,
    defaultTimeframe: '5m',
  },
);

const strategy = defineStrategy({
  onBar(context) {
    if (context.barIndex === 0) {
      return { action: 'buy', qty: 1 };
    }

    return undefined;
  },
});

const runner = createRunner({
  mode: 'backtest',
  runId: 'demo-run',
  strategyId: 'demo-strategy',
  market: mnq,
  strategy,
  feed: createHistoricalFeed(bars),
  broker: createPaperBroker({ market: mnq, initialCash: 25_000 }),
});

await runner.start();
const result = runner.getResult();

---

Package entrypoints

Root package

Use the root package for the main runtime entrypoints.

Subpaths

Use subpaths when you need more than the small front door:

• @thecommandcat/fbtf/broker
• @thecommandcat/fbtf/context
• @thecommandcat/fbtf/data
• @thecommandcat/fbtf/data/databento
• @thecommandcat/fbtf/diagnostics
• @thecommandcat/fbtf/experiment
• @thecommandcat/fbtf/feeds
• @thecommandcat/fbtf/indicators
• @thecommandcat/fbtf/markets
• @thecommandcat/fbtf/results
• @thecommandcat/fbtf/risk
• @thecommandcat/fbtf/runner
• @thecommandcat/fbtf/services
• @thecommandcat/fbtf/strategy

---

Curated examples

The repository keeps a small example set:

• examples/01-minimal-backtest.ts
• examples/03-cost-slippage-comparison.ts
• examples/07-minimal-experiment.ts
• examples/09-databento-ema-bracket.ts

These examples live in the repository and are not shipped in the npm tarball.

---

Config-first CLI

The CLI expects one required run-config file.

npx @thecommandcat/fbtf run ./my-run.config.json

Example config shape:

{
  "modulePath": "./examples/07-minimal-experiment.ts",
  "reportMode": "human",
  "runId": "minimal-experiment",
  "params": {},
  "config": {}
}

---

Real-data example setup

For the Databento example, store your key in a local ignored file such as .env.local:

DATABENTO_API_KEY=your-key-here

The real-data example is intentionally opt-in.

---

Roadmap

Short version:

• keep tightening the deterministic runtime core
• improve the futures-first workflow and examples
• expand docs and developer ergonomics without turning the project into a giant framework

For the fuller version, see docs/content/docs/roadmap.md in the repository or the roadmap page in the docs site.

---

Development

Requirements

• Node.js 20+
• npm / pnpm

Install dependencies

npm install

Typecheck

npm run typecheck

Unit tests

npm test

Integration tests

npm run test:integration

Release verification

npm run verify:release

---

Status

Still early, but intentionally constrained.

The priority is to make the runtime trustworthy before making it broad.

---

License

MIT