moomoo-project

Trading analysis tools built on the moomoo OpenAPI Python SDK.

Prerequisites

Requirement	Version
Python	>= 3.12
uv	any
moomoo OpenD	>= 10.5.6508 (running locally)

Install dependencies:

uv sync

Project Structure

moomoo/
├── analysis/            # stock monitoring & visualisation app
│   └── orderflow.py     #   order flow analyzer (GUI + headless CLI)
├── backtest/            # backtesting framework (strategy-agnostic engine)
│   ├── engine.py        #   run_backtest(), BacktestParams, Trade, BacktestResult
│   ├── smc.py           #   SMC helpers used by the engine (trend, FVG depth, …)
│   ├── fetcher.py       #   kline data fetcher (wraps moomoo SDK)
│   └── strategy_walkthrough.ipynb  # step-by-step SMC decision visualisation
├── core/                # shared utilities (logging, config, time helpers)
├── db/                  # local database access (read/write persisted klines)
├── store/               # data fetching & caching from moomoo OpenD
├── strategy/            # trading strategy implementations
│   └── smc/             #   Smart Money Concepts (SMC) strategy
│       ├── market_structure.py  # find_swings(), detect_bos_choch()
│       ├── fvg.py               # detect_fvg() — Fair Value Gap detection
│       └── order_blocks.py      # detect_order_blocks()
├── tests/
│   ├── test_orderflow.py
│   └── outputs/         # chart PNGs generated by tests / headless runs
├── main.py              # unified entry point
└── pyproject.toml

Module responsibilities

Module	Role
analysis/	End-user apps: charts, live monitoring
backtest/	Framework only: run trades against historical data, compute metrics
strategy/	Strategy logic: signal detection, entry/exit rules
core/	Cross-cutting utilities shared by all modules
db/ + store/	Data layer: fetch from OpenD, persist and query locally

Tools

Order Flow Analyzer (analysis/orderflow.py)

Candlestick chart with a volume / order-flow profile panel attached to the right edge.

Two modes:

Mode	Description
Live	Subscribe to real-time ticks via OpenD; profile updates every N seconds
Historical	Fetch OHLCV for a past date; approximate Volume Profile from candle data

Profile panel (Historical): volume distributed uniformly across each candle's [low, high] range. The gold dashed line marks the POC (Point of Control — price level with highest volume). Hover over any bar to see price and volume.

Profile panel (Live): buy / neutral / sell volume stacked per price level for the current candle. Hover to see the full breakdown including net buy/sell.

---

Open the GUI (interactive)

# defaults: US.SNDK, 15m, Live mode
uv run main.py orderflow

# or run the script directly
uv run analysis/orderflow.py

Pre-fill GUI fields from the command line:

# historical mode, SNDK 15m, May 15
uv run analysis/orderflow.py --code US.SNDK --mode Historical --date 2026-05-15

# AAPL 5-min, last 30 candles
uv run analysis/orderflow.py --code US.AAPL --tf 5m --num 30 --mode Historical --date 2026-05-15

# live mode, refresh every 30 seconds
uv run analysis/orderflow.py --code US.TSLA --tf 1m --refresh 30

Headless mode (save PNG, no window)

--output implies --mode Historical. Useful for batch generation or CI.

# save SNDK 15m profile for May 15
uv run analysis/orderflow.py --code US.SNDK --date 2026-05-15 --output sndk_15m.png

# AAPL 5-min, 30 candles → specific output directory
uv run analysis/orderflow.py --code US.AAPL --tf 5m --num 30 --date 2026-05-15 \
    --output tests/outputs/aapl_5m.png

# HK stock — Tencent 1h
uv run analysis/orderflow.py --code HK.00700 --tf 1h --date 2026-05-15 \
    --output tests/outputs/tencent_1h.png

All options

usage: orderflow [--code CODE] [--tf {1m,5m,15m,30m,1h}] [--num NUM]
                 [--mode {Live,Historical}] [--date YYYY-MM-DD]
                 [--refresh REFRESH] [--host HOST] [--port PORT]
                 [--output FILE.png]

  --code      stock code               default: US.SNDK
  --tf        timeframe                default: 15m
  --num       number of candles        default: 26
  --mode      Live or Historical       default: Live
  --date      date (YYYY-MM-DD)        default: 3 days ago
  --refresh   live refresh (seconds)   default: 15
  --host      OpenD host               default: 127.0.0.1
  --port      OpenD port               default: 11111
  --output    output PNG path          enables headless mode

---

Running Tests

uv run pytest tests/ -v

Tests cover:

Test class	What it checks
TestCandleStart	time alignment for all supported timeframes
TestTimeframeMap	all TF entries present with correct candle minutes
TestTickBucketing	buy/sell/neutral aggregation, cross-candle splits
TestOhlcvProfile	volume distribution, POC detection, edge cases
TestChartOutput	headless chart rendering saves a valid PNG

Chart outputs from tests are saved to tests/outputs/.