🌐 Languages: English | 繁體中文

madtrader

A trading research and backtesting toolkit that integrates libraries such as VectorBT, Polars, and CCXT. It includes multiple technical-indicator strategy examples, data loaders, and Jupyter notebooks for computing and analyzing backtest results.

---

Key Features

• Provides a backtesting framework built on vectorbt (see src/madtrader/core.py).
• Includes multiple built-in strategy examples (src/madtrader/strategy/), such as BBAND, MACD, RSI, STOCH_RSI, etc.
• Data loading and preprocessing utilities are located in src/madtrader/data/loader.py.
• Supports interactive exploration in Jupyter notebooks, designed specifically for research and strategy development.
• Displays strategy statistics such as: Total Return [%], Win Rate [%], Time in Position [%], Profit Factor [%], Average Profit, Number of Trades, Annualized Volatility [%], Max Drawdown [%], Total Fees, Sharpe ratio, Calmar ratio, Sortino ratio.
• Adjustable parameters: initial capital (USDT), order size per entry (USDT), tp, sl, trading symbol, and backtesting mode (normal, grid).
• Normal mode: each variable (window, lower than, higher than, etc.) is fixed.
• Grid mode: variables (window, lower than, higher than, etc.) are tested across multiple combinations.

---

Requirements

• Python >= 3.12
• For main dependencies, see pyproject.toml (includes vectorbt, polars, ccxt, yfinance, xgboost, etc.).

Quick Start

1. Installation:

git clone https://github.com/kevinwudev/madtrader.git
cd madtrader

# python
pip install -e .

# uv
uv lock
uc sync

(Optional)

2. It is recommended to create a virtual environment and install packages (development mode):

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

3. If you want a dedicated Jupyter kernel (optional):

python -m pip install ipykernel
python -m ipykernel install --user --name=madtrader --display-name "Python (madtrader)"

4. Open the example notebooks under example/ in Jupyter Lab / Notebook.

Examples & Usage

• Example notebooks: check the example/ folder (contains multiple notebooks for technical indicators and strategies, such as BBAND.ipynb, MACD.ipynb, etc.).

Step-by-step Quick Backtest

Check example/kdj.ipynb to run a backtest using the KDJ indicator.

from madtrader.data.loader import load_data
from madtrader.strategy.KDJ import get_kdj_event
from madtrader.utils import check_parquet

removes = [
	""
]

check_parquet(removes)

check_parquet will return a list of available raw price datasets:

['BTC-USDT_2021-01-01_2025-01-01_1d_okx.parquet',
 'BTC-USDT_2025-01-01_2025-12-01_1d_okx.parquet']

How to remove data: add the filename into removes and run again. Example:

removes = ["BTC-USDT_2025-01-01_2025-12-01_1d_okx.parquet"]

How to add new data:

df_test = load_data(symbol = 'BTC-USDT', # trading pair
			start_date="2022-01-01", 	 # start date
			end_date="2024-01-01",   	 # end date
			interval='1d', 				 # timefrrame (1m, 5m, 1d, 4d, etc)
			exchange = 'okx')			 # exchange (OKX)
df_test

Backtest Settings (Normal Mode):

file_is = "BTC-USDT_2021-01-01_2025-01-01_1d_okx.parquet" # load a specific dataset file
params_info_grid = {
                'upper' : 40, # go long when J > 40
                'lower' : 60, # exit long when J < 60
            }

pf, info_df = get_kdj_event(params_info_grid, 
							file_is = file_is, 			# price data file
							isgrid = False,				# backtest mode (normal)
							is_accumulate = True,   	# allow consecutive trades in the same direction (long/short)
							size = 100,					# 100 USDT per entry
							is_short = False,			# allow shorting or not
							sort_by = "sortino_ratio",	# sort info_df by sortino_ratio (descending)
                               							# available: Total Return [%], Win Rate [%], Average Profit, Profit Factor [%], etc.
							freq = '1d'					# daily timeframe
							)

Plot the performance (normal mode only):

fig = pf.plot()
    
fig.update_xaxes(tickformat="%Y-%m-%d")

fig.show()

Backtest Settings (Grid Mode):

file_is = "BTC-USDT_2021-01-01_2025-01-01_1d_okx.parquet"
params_info_grid = {
                'upper' : np.arange(-10, 120, 4),	# upper from -10 to 119 with step=4 (-10, -6, -2, 2, ...)
                'lower' : np.arange(-10, 120, 4),	# lower from -10 to 119 with step=4 (-10, -6, -2, 2, ...)
            }


pf, info_df = get_kdj_event(params_info_grid, 
							file_is = file_is, 
							isgrid = True,			# backtest mode (grid)
							is_accumulate = True,
							size = 100,
							is_short = False,
							sort_by = "sortino_ratio",
							freq = '1d'
							)

info_df

Contributing

PRs (new strategies), issues, and contributions of strategy/indicator examples are welcome. Please read and follow the code style of this project before contributing.

Strategies can be found in src/madtrader/strategy/<strategy>.py, corresponding to notebooks in example/<strategy>.ipynb.

License

MIT LICENSE