quantframe

quantframe is a lightweight Python backtesting framework extracted from the deribit-arb backtest engine.

It provides:

• backtest(weights, prices, config) for DataFrame-based target weights.
• run_strategy(strategy, prices, config) for event-style strategies, with optional metadata for explicit symbol lifetimes.
• TWAP and VWAP execution models.
• gross PnL, fee PnL, optional funding PnL, and common performance metrics.
• BacktestResult.plot() for quick result inspection.

Install

uv sync

Yahoo Finance downloads are optional:

pip install quantframe-lib[yfinance]

Run Tests

uv run pytest

Minimal Usage

import pandas as pd

from quantframe.backtest import BacktestConfig, backtest

prices = pd.DataFrame(
    {
        "timestamp": pd.date_range("2024-01-01", periods=3, freq="1min", tz="UTC"),
        "symbol": ["ETH-PERPETUAL"] * 3,
        "close": [100.0, 101.0, 102.0],
    }
)
weights = pd.DataFrame(
    {
        "timestamp": [pd.Timestamp("2024-01-01", tz="UTC")],
        "symbol": ["ETH-PERPETUAL"],
        "weight": [1.0],
    }
)

result = backtest(weights, prices, BacktestConfig(exec_horizon=1))
print(result.metrics)

Use compound cumulative returns and CAGR-style APR when needed:

result = backtest(
    weights,
    prices,
    BacktestConfig(exec_horizon=1, return_mode="compound"),
)

Loading Bar Data

from quantframe.data.yfinance import YahooFinanceProvider
from quantframe.data import prices

bars = YahooFinanceProvider().load_bars(
    ["BTC-USD", "GC=F"],
    start="2016-01-01",
    end="2026-04-30",
    interval="1d",
)

aligned = prices.merge(bars, symbols=["BTC-USD", "GC=F"], how="inner")

Custom providers can subclass DataProvider and implement fetch_bars(). Returned bars are validated and normalized before use. Use prices.merge(..., how="outer") when you want to keep the union of trading calendars and handle missing market bars yourself.