# txocap

BTC multi-venue flow trading research with a single strategy engine.

## What this repo is now

The codebase has one trusted trading path:

- **Strategy logic:** `src/core/strategy.ts`
- **Replay runner:** `src/runners/replay.ts --replay <session-dir>`
- **Batch profile comparison:** `src/research/compare-profiles.ts`
- **Demo execution benchmark:** `src/runners/demo-benchmark.ts`
- **Dashboard:** `src/runners/dashboard.ts`

There is no separate legacy stream/tape/sim runtime anymore.

## Modes

Only these modes matter now:

- **replay** — recorded trades + recorded orderbook replayed through the engine, with emulated maker chase fills
- **demo** — live market data + real maker chase orders on Bybit demo
- **live** — reserved for live market data + real maker chase orders on Bybit mainnet

## Core design

### One strategy engine
All strategy decisions come from `StrategyEngine` in `src/core/strategy.ts`:

- signal computation
- volatility/range gates
- sizing
- cooldowns / streak logic
- entry generation
- exit generation
- capital / fees / PnL tracking

### One fill model concept
The execution intent is always the same: **maker chase limit**.

What changes by mode is only the fill provider:

- **replay:** emulated chase against recorded orderbook snapshots
- **demo:** real chase against Bybit demo API
- **live:** real chase against Bybit live API

## Current honest replay / backtest result

Using the unified replay path with orderbook-based chase fill emulation:

- **Profile:** `MAKER_OPT`
- **Return:** **+$109.81** on $500
- **Win rate:** **85.7%**
- **Trades:** **21**
- **Max drawdown:** **1.88%**

This is the realistic result after removing the old optimistic fill assumptions.

## Commands

### Dashboard
```bash
txocap-dashboard
```
Consumes IPC from a running engine producer (`txocap-demo-benchmark` today, replay/live producers later).

### Replay one recorded session
```bash
txocap-replay data/sessions/<session-dir>
```

### Compare profiles across all sessions
```bash
node dist/research/compare-profiles.js
```

### Research / edge search
```bash
txocap-edge-search
```
Exploratory statistical analysis over recorded sessions. Not part of the trading runtime.

### Demo benchmark
```bash
txocap-demo-benchmark
```
Uses:
- live market data
- real demo API orders
- maker chase limits
- strategy-sized risk
- IPC broadcast for the dashboard

### Demo account check
```bash
txocap-account-check
```

### Demo funding
```bash
txocap-demo-fund USDT:10000 BTC:1
```

### One-off demo order
```bash
txocap-order-place --side Buy --qty 0.001 --category linear --symbol BTCUSDT
```

## Environment

Copy:
```bash
cp .env.example .env
```

Main variables still used:

- `BYBIT_DEMO_API_KEY`
- `BYBIT_DEMO_API_SECRET`
- `BYBIT_TESTNET_API_KEY`
- `BYBIT_TESTNET_API_SECRET`
- `BYBIT_TESTNET`
- `BYBIT_RECV_WINDOW`
- `BYBIT_DEFAULT_CATEGORY`
- `BYBIT_DEFAULT_SYMBOL`
- `ENABLED_EXCHANGES`
- `BYBIT_SYMBOL_PREFIX`
- `BYBIT_PUBLIC_CATEGORIES`
- `BYBIT_SUBSCRIPTION_CHUNK_SIZE`
- `BINANCE_INCLUDE_FUTURES`
- `SIGNAL_FAST_WINDOW_MS`
- `SIGNAL_SLOW_WINDOW_MS`
- `SIGNAL_EMIT_INTERVAL_MS`
- `SIGNAL_LARGE_TRADE_USD`

## Important docs

- `docs/system-guide.md` — current architecture and runtime model
- `docs/tape-and-signals.md` — current signal / replay / fill model
- `docs/maker-opt-strategy.md` — strategy profile details
- `docs/statistical-edge-analysis.md` — multi-session statistical findings
- `docs/live-run-analysis.md` — historical live/demo investigations and fixes
- `docs/hyro-backtest.md` — HyroTrader prop-firm challenge/funded-rule backtester
- `docs/preemptive-entry-validation.md` — preemptive entry research and rejection decision
- `docs/edge-analysis.md` — earlier research notes

## Current cleanup status

Purged from active use:

- old `actionables` entry path
- old standalone stream runtime
- old standalone tape server runtime
- old paper-trade dashboard model
- old `SimAccount`
- old optimistic bar-touch fill assumption

## Development note

This repo is in heavy development. Compatibility with older runtime paths is not a goal.
The code should prefer clarity, one execution path, and explicit mode differences.