Overfitting (Futures Backtesting)
Overfitting simulates a realistic crypto futures trading environment including
- Liquidation, Margin, Leverage for stress testing
- Multiple Currency Trading (e.g., backtesting BTC PERP & ETH PERP at the same time)
- Four Different Order Types: LIMIT, MARKET, STOP_LIMIT, STOP_MARKET
- Slippage/Commission Setting
Installation
$ pip install overfitting
Usage
Run from the repository root; the example reads the sample data in examples/data/.
import pandas as pd
from overfitting import Strategy
from overfitting.indicators import sma, crossover, crossunder
def load_data():
df = pd.read_csv('examples/data/BTCUSDT.csv')
benchamrk_df = pd.read_csv('examples/data/BTCUSDT.csv') # BTC buy and Hold
df['timestamp'] = pd.to_datetime(df['timestamp'], unit='ms')
df.set_index('timestamp', inplace=True)
start_time = pd.to_datetime('2023-01-01 00:00:00')
df = df.loc[start_time:]
return df, benchamrk_df
class MyStrategy(Strategy):
def init(self):
self.asset = 'BTC'
self.set_leverage(self.asset, 1)
close = self.data[self.asset].close
self.fast = self.I(sma, close, 20)
self.slow = self.I(sma, close, 50)
def next(self):
position = self.get_position(self.asset)
# Golden cross (entry)
if crossover(self.fast, self.slow) and position.qty == 0:
price = self.price(self.asset)
lot_size = self.get_balance() // price
self.limit_order(self.asset, lot_size, price)
# Death cross (exit)
elif crossunder(self.fast, self.slow) and position.qty > 0:
self.market_order(self.asset, -position.qty)
price_df, benchmark_data = load_data()
strategy = MyStrategy(
data={"BTC": price_df},
benchmark=benchmark_data, # Default = None Optional
initial_capital=100_000, # Default Optional
commission_rate=0.0002, # Default Optional
maint_margin_rate=0.005, # Default Optional
maint_amount=50 # Default Optional
)
returns = strategy.run()
strategy.plot(returns)
Results
Performance Summary
Overview
Start Date 2023-01-01 00:00
End Date 2024-08-29 00:00
Number of Years 1.663
Initial Balance 100,000.00
Final Balance 205,328.91
Total Return 105.33%
CAGR 54.13%
Returns
Best Day 10.08%
Worst Day -5.38%
Best Month 27.88%
Worst Month -13.71%
Positive Days 34.93%
Positive Months 70.00%
Average Up Day 1.59%
Average Down Day -0.95%
Longest Winning Streak (days) 7
Longest Losing Streak (days) 7
Risk
Volatility (annualized) 33.08%
Downside Deviation (annualized) 17.38%
Sharpe Ratio 1.470
Sortino Ratio 2.799
Calmar Ratio 2.040
Omega Ratio 1.316
Gain to Pain Ratio 0.316
Tail Ratio 1.569
Common Sense Ratio 2.064
Daily Value at Risk (95%) -2.19%
Daily Expected Shortfall (95%) -3.16%
Skew (daily) 1.804
Excess Kurtosis (daily) 7.538
Drawdown
Max Drawdown -26.53%
Current Drawdown -20.56%
Average Drawdown -4.91%
Longest Drawdown (days) 219
Time Underwater 93.41%
Ulcer Index 12.12%
Recovery Factor 3.970
Sharpe Ratio Reliability
Sharpe 95% Range 0.05 to 2.89
Probability Sharpe Above 0 97.86%
Benchmark
Alpha (annualized) 3.44%
Beta 0.509
Correlation 0.758
Tracking Error (annualized) 32.39%
Information Ratio -1.238
Excess Return (annualized) -61.21%
Up Capture 0.493
Down Capture 0.479
Trades
Total Trades 182
Long Trades 182
Short Trades 0
Win Rate 37.36%
Win Rate (long) 37.36%
Win Rate (short) n/a
Average Win 5,837.17
Average Loss -2,557.89
Largest Win 27,402.74
Largest Loss -10,211.93
Payoff Ratio 2.282
Profit Factor 1.361
Expectancy per Trade 578.73
Average Holding Time (bars) 43.352
Average Holding Time, Winners (bars) 73.294
Average Holding Time, Losers (bars) 25.491
Longest Winning Streak (trades) 7
Longest Losing Streak (trades) 8
Trades per Month 9.233
Profit From Best Trade 26.02%
Net Profit Without Best 5 Trades -20,822.32
Gross Profit 396,927.83
Gross Loss -291,598.92
Net Profit 105,328.91
Trade Quality
Average Adverse Excursion -1.85%
Average Favourable Excursion 3.08%
Liquidations 0
Costs
Total Commission 11,407.29
Total Slippage 0.00
Funding Paid 0.00
Funding Received 0.00
Total Costs 11,407.29
Profit Before Costs 116,736.20
Costs as Share of Profit Before Costs 9.77%
Traded Value 57,036,444.00
Turnover (times equity per year) 196.244
Exposure and Margin
Time in Market 54.25%
Average Leverage 0.491
Average Leverage in Market 0.906
Maximum Leverage 0.991
Average Margin Usage 48.02%
Peak Margin Usage 102.54%
Closest Distance to Liquidation 99.50%
Orders
Orders Placed 364
Orders Filled 364
Orders Cancelled 0
Orders Rejected 0
Orders Still Open 0
Fill Rate 100.00%
Average Slippage per Fill 0.00%
By Symbol
Trades Win rate Net PnL Average PnL Profit factor Share of profit Time held
Symbol
BTC 182 37.4% 105,328.91 578.73 1.36 100.0% 54.2%
Worst Drawdowns
Net drawdown in % Peak date Valley date Recovery date Duration (days)
0 26.533797 2024-03-13 2024-06-28 NaT 169
1 20.996185 2023-03-17 2023-09-12 2023-10-23 219
2 7.051091 2023-12-05 2024-01-22 2024-02-09 65
3 5.980692 2023-01-21 2023-02-13 2023-02-15 24
4 5.578214 2023-02-15 2023-03-07 2023-03-12 24
5 5.550106 2024-03-04 2024-03-06 2024-03-11 6
6 4.538401 2023-11-10 2023-11-16 2023-12-04 23
7 2.530832 2023-11-01 2023-11-03 2023-11-09 7
8 2.162228 2024-02-18 2024-02-23 2024-02-27 8
9 1.603446 2024-02-28 2024-02-29 2024-03-04 4
Market Data
load() downloads candles (and, if asked, funding rates) from an exchange, saves them on your machine, and returns them ready for a backtest. Later calls read from the local copy and only download what is missing, such as bars that have closed since.
from overfitting import Strategy
from overfitting.market import load
data = load(["BTC/USDT", "ETH/USDT"], "1h", start="2023-01-01", exchange="binance", funding=True)
strategy = MyStrategy(data, funding=True)
Downloading binance BTC/USDT 1h candles 2023-01-01 00:00 to 2026-11-18 21:00
34,029 bars saved
Downloading binance BTC/USDT funding rates 2023-01-01 00:00 to 2026-11-18 21:00
4,254 funding payments saved
Downloading binance ETH/USDT 1h candles 2023-01-01 00:00 to 2026-11-18 21:00
34,029 bars saved
Downloading binance ETH/USDT funding rates 2023-01-01 00:00 to 2026-11-18 21:00
4,254 funding payments saved
Each symbol comes back as a DataFrame with open, high, low, close, volume and, with funding=True, funding_rate (the rate paid at that bar's open, 0 on other bars), indexed by bar open time in UTC. Only bars that have closed are returned.
| Argument | Meaning |
|---|---|
symbols |
"BTC/USDT" or a list, written BASE/QUOTE as in ccxt. The result is keyed the same way: data["BTC/USDT"] |
timeframe |
1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 6h, 12h, 1d |
start, end |
Dates such as "2023-01-01", in UTC. end defaults to now |
exchange |
Any of the 19 below (default "binance") |
funding |
Also download funding rates and add the funding_rate column (default False) |
data_dir |
Where the data is kept. Default ~/.overfitting/data, or the OVERFITTING_DATA_DIR environment variable |
Exchanges. Each serves its own linear perpetuals, quoted in the currency shown: load("BTC/USDC", exchange="hyperliquid"), load("BTC/USD", exchange="dydx"). Asking for the wrong quote raises an error that names the right one. History is how far back the exchange serves data today; data you download is kept, so the local store can hold more.
exchange |
Quote | Timeframes | Candle history | Funding |
|---|---|---|---|---|
binance |
USDT | all | full | full |
aster |
USDT | all | from 2021 | full |
bingx |
USDT | 1m 30m 1h 2h 4h 6h 12h 1d | 1m about a year, 1h from 2024, 2h+ from 2022 | none |
bitfinex |
USDT | 1m 5m 15m 30m 1h 6h 12h 1d | from 2019; minutes without trades have no bar | full (from snapshots) |
bitget |
USDT | all but 2h | from 2019 | none |
blofin |
USDT | all | from 2023 | full |
bybit |
USDT | all | full | full |
cryptocom |
USD | all but 3m | from 2021 | full, hourly |
deribit |
USDC | 1m to 2h | from 2022 | full, hourly |
dydx |
USD | 1m 5m 15m 30m 1h 4h 1d | from October 2023 | full, hourly |
gate |
USDT | all | latest 10,000 bars (1m: about a week) | last 180 days |
htx |
USDT | 1m 5m 15m 30m 1h 4h | from 2021 | none |
hyperliquid |
USDC | all but 6h | latest ~5,000 bars (1m: about 3.5 days, 1h: about 7 months) | from 2023, hourly |
kraken |
USD | 1m 5m 15m 30m 1h 4h 12h 1d | from 2022 | last year, hourly |
kucoin |
USDT | all but 3m and 6h | 1m from late 2024, 1h from mid 2024, 1d from 2020 | full |
mexc |
USDT | 1m 5m 15m 30m 1h 4h 1d | 1m about 30 days, 30m+ from 2020 | none |
okx |
USDT | all | full | about 3 months |
phemex |
USDT | all | from 2022 | full |
woo |
USDT | all | 1m and 1h+ from 2022; 3m to 30m kept for a limited time | full |
Where an exchange has no funding history, funding_rate is 0 and load() warns. It also warns when data starts later than the requested start, and when the exchange is missing bars.
- The data is kept as Parquet files outside your project and virtual environment, so every project on the machine shares it:
binance/candles/1m/BTC-USDT/2024-01.parquet(one file per month below 1h, per year above). A year of 1-minute bars is about 15 MB and loads in a few hundredths of a second. - With several symbols, only the bars all of them have are kept, so their timelines match. A symbol listed later trims the others, with a warning.
- Gaps in the exchange's own data, and funding history that starts later than the candles (OKX only serves recent funding), are reported as warnings.
- An interrupted download resumes where it stopped.
- A catalog (
catalog.sqlitein the same folder) records what has been downloaded and logs every change.overfitting.market.stored()lists what is saved;overfitting.market.downloads()shows the log. - Files deleted by hand are downloaded again on the next
load(). Parquet files you put in the folder yourself (named like the others, with columnstime,open,high,low,close,volume) are checked and used instead of downloading. A file that fails the checks is renamed to*.invalidwith a warning.
Indicators
An indicator is a plain function that takes price series and returns one value per bar. Declare it in init() with self.I, then read it in next() relative to the current bar:
from overfitting.indicators import sma, rsi, bollinger, crossover
def init(self):
bars = self.data["BTC"]
self.fast = self.I(sma, bars.close, 20)
self.rsi = self.I(rsi, bars.close, 14)
self.bands = self.I(bollinger, bars.close, 20, 2) # several outputs
def next(self):
self.fast[-1] # value at the last completed bar
self.fast[-2] # the bar before
self.bands.upper[-1] # one output of a multi-output indicator
crossover(self.rsi, 30) # True when RSI just moved above 30
- Inside
next(), an indicator only shows bars that have finished. The bar being traded and later bars cannot be read, so there is no look-ahead to guard against. - Before there is enough history the value is
NaN, andcrossover/crossunderreturnFalse. self.price("BTC")is the open of the current bar, the price a market order placed now fills at.- Built in:
sma,ema,wma,rsi,macd,stochastic,bollinger,atr,donchian. - A custom indicator is any function of the same shape; see
examples/donchian_breakout.py.
next(self, i) with the bar index is also supported.
Slippage
MyStrategy(data, slippage=0.001) # every fill is 0.1% worse than the order price
from overfitting.slippage import skewed
MyStrategy(data, slippage=skewed(0.15)) # slips 15% of the way from the open to the bar's extreme
MyStrategy(data, slippage=lambda order, bar: order.theoretical_price + 0.5) # your own model
A slippage model is a function (order, bar) -> executed price. order.qty is positive for a buy, and bar has open, high, low and close.
Parameter Optimization
A strategy's parameters are its class attributes. optimize runs the strategy once for every combination of the values you give and reports the best one:
from overfitting import Strategy, optimize
from overfitting.indicators import sma, crossover, crossunder
class SmaCross(Strategy):
fast = 20
slow = 50
def init(self):
close = self.data["BTC"].close
self.fast_ma = self.I(sma, close, self.fast)
self.slow_ma = self.I(sma, close, self.slow)
def next(self):
position = self.get_position("BTC")
if crossover(self.fast_ma, self.slow_ma) and position.qty == 0:
price = self.price("BTC")
self.limit_order("BTC", self.get_balance() // price, price)
elif crossunder(self.fast_ma, self.slow_ma) and position.qty > 0:
self.market_order("BTC", -position.qty)
result = optimize(
SmaCross, {"BTC": price_df},
params={"fast": range(5, 55, 5), "slow": range(20, 220, 20)},
maximize="sharpe_ratio",
constraint=lambda p: p.fast < p.slow,
train=("2023-01-01", "2024-01-01"), # search on 2023 only
slippage=0.001, # any Strategy argument can be passed
)
print(result)
Optimization of SmaCross
Trials 90 (grid)
Maximized sharpe_ratio
Trained on 2023-01-01 to 2023-12-31
Best parameters fast=45, slow=100
Full backtest 2023-01-01 to 2024-08-29
Total Return 141.01%
CAGR 69.72%
Volatility 32.08%
Sharpe Ratio 1.807
Sortino Ratio 3.403
Max Drawdown -15.80%
Calmar Ratio 4.411
Fills 158
The search runs on the train window; the winner is then backtested over all the data.
result.best_params # {"fast": 45, "slow": 100}
result.metrics # the full backtest's metrics
result.table # every combination tried, best first (scored on the training window)
result.heatmap("fast", "slow") # the metric as a grid of two parameters
result.strategy # the winner, run over all the data
result.strategy.plot(result.returns)
| Argument | Meaning |
|---|---|
maximize |
total_return, cagr, volatility, sharpe_ratio, sortino_ratio, max_drawdown, calmar_ratio, fills, or a function of those, e.g. lambda m: m["cagr"] / abs(m["max_drawdown"]) |
constraint |
Function returning False for combinations to skip |
method, n, seed |
"grid" tries everything; "random" tries n combinations |
train |
The data the search uses: a share of the most recent data, e.g. 0.6, or a date range ("2024-01-01", "2025-01-01") (end not included). Default 1.0, all of it |
workers |
Processes to use. Default is all cores; 1 runs in the current process |
Combinations run in parallel on macOS and Linux. On the example above, 1,000 combinations of 14,500 hourly bars take about 6 seconds on a 10-core laptop.
For a full walkthrough (grid and random search, a custom objective, the heatmap, and the winner's report), see examples/optimize_sma_cross.ipynb.
Report and Charts
The summary has eleven sections: overview, returns, risk, drawdown, Sharpe ratio reliability, benchmark, trades, trade quality, costs, exposure and margin, and orders, followed by a per-symbol table and the worst drawdowns.
strategy.plot(returns) prints the summary above and shows 13 charts, one after another.
- In a Jupyter or VS Code notebook the charts appear inline.
- In a script each opens in a matplotlib window.
strategy.plot(returns) # print the summary and show the charts
strategy.plot(returns, save_path="results") # also save each chart as a PNG in results/
strategy.plot(returns, title="SMA cross") # name used on the charts
| Chart | Function in overfitting.analysis.plots |
Needs |
|---|---|---|
| Cumulative returns | cumulative_returns |
|
| Cumulative returns, log scale | cumulative_returns_log |
|
| Monthly returns heatmap | monthly_heatmap |
|
| Yearly returns | yearly_returns |
|
| Distribution of monthly returns | monthly_distribution |
|
| Return quantiles (box plot of daily, weekly, monthly returns) | return_quantiles |
|
| Rolling Sharpe | rolling_sharpe |
|
| Rolling volatility | rolling_volatility |
|
| Drawdown | drawdown |
|
| Rolling beta | rolling_beta |
a benchmark |
| Profit per trade | profit_per_trade |
|
| Cost breakdown | cost_breakdown |
|
| Distance to liquidation | liquidation_distance |
Rolling beta is skipped when no benchmark is given. Each chart is also available on its own, and every number behind them is in overfitting.analysis.metrics:
from overfitting.analysis import metrics, plots
daily = metrics.aggregate_returns(returns, "D")
plots.drawdown(daily).savefig("drawdown.png")
plots.profit_per_trade(strategy.fetch_round_trips())
metrics.summary(daily) # 49 metrics as a pandas Series
metrics.trade_summary(strategy.fetch_round_trips()) # win rate, expectancy, streaks ...
metrics.by_symbol(strategy.fetch_round_trips()) # results per symbol
metrics.by_weekday(strategy.fetch_round_trips()) # results by entry weekday
The 13 charts, from the example above:
Trade and Account Data
After strategy.run(), everything that happened is available as pandas DataFrames:
strategy.fetch_round_trips() # one row per completed trade
strategy.fetch_trades() # one row per fill
strategy.fetch_orders() # every order placed, with its status
strategy.fetch_account_history() # the account on every bar
strategy.fetch_position_history("BTC") # one symbol's position on every bar
strategy.fetch_funding() # funding payments
- Round trips run from opening a position until it is flat again or flips sides. Each row has entry and exit time and price, holding time, gross PnL, commission, funding, net PnL, and
mae/mfe: how far the price moved against and in favour of the position while it was open, as a fraction of the entry price. - Orders carry a
statusofOPEN,FILLED,CANCELLEDorREJECTED, areject_reasonwhen rejected, and theslippagecost of each fill. - Account history has cash, equity, margin in use, gross and net exposure, and leverage.
- Position history has size, entry price, close, exposure, margin, liquidation price and unrealized PnL.
Liquidation Handling
The liquidation logic is based on isolated margin mode:
- Initial Margin = Entry Price × Quantity / Leverage
- Maintenance Margin = Entry Price × Quantity × Maintenance Margin Rate − Maintenance Amount
- Liquidation Price is then calculated based on whether the position is long or short.
- Long Position Liquidation Price => Entry Price - (Initial Margin - Maintenance Margin)
- Short Position Liquidation Price => Entry Price + (Initial Margin - Maintenance Margin)
When the price crosses the calculated liquidation level, the position is force-closed and the entire initial margin is lost. Nothing more is charged on top, so an isolated position can never lose more than the margin posted for it. Liquidations are marked in the trade log with is_liquidation_order = True.
Margin Check
An order that opens or increases a position needs price × quantity / leverage of free margin, where free margin is the cash balance minus the margin locked in open positions.
- If the account cannot afford the order when it is placed,
InsufficientMarginis raised. - If the account can no longer afford a resting order when it fills, the order is dropped and listed in
strategy.fetch_rejected_orders(). - Orders that reduce or close a position are always accepted.
Equity Curve
strategy.run() returns are based on equity: cash plus the unrealized PnL of open positions, marked at each bar's close. Drawdown and Sharpe therefore include losses on positions that are still open.
returns = strategy.run() # mark-to-market (default)
returns = strategy.run(mark_to_market=False) # realized only: moves when trades close
strategy.equity_curve # cash + unrealized PnL per bar
strategy.realized_balances # cash per bar
Funding Rate
Funding is off by default. To simulate it, give a symbol's DataFrame a funding_rate column (load(..., funding=True) adds one) and pass funding=True to the strategy:
strategy = MyStrategy(data, funding=True)
A non-zero value on a bar means funding is settled at that bar's open, on the position held into it:
payment = -position quantity × open price × funding rate
Longs pay and shorts receive when the rate is positive. Bars with 0 or NaN settle nothing. Payments change the cash balance and are listed in strategy.fetch_funding().
Supported Order Types
Supports four order types: LIMIT, MARKET, STOP LIMIT, and STOP MARKET. Each behaves according to standard trading conventions.
[NOTE] Rules
- For MAKRET Orders, the system will automatically execute the trade with "open" price.
- For STOP Orders, the system will automatically trigger the order when:
- Long: Price (High) >= Stop Price
- Short: Price (Low) <= Stop Price
- A triggered STOP MARKET order fills at the stop price, or at the open if the bar opened past it.
- A triggered STOP LIMIT order becomes a limit order at that price. If the limit leaves room (a buy limit at or above it, a sell limit at or below it), it fills there at once; otherwise it waits for the price to trade through the limit.
- Stop Order Immediate Rejection Rule: If a STOP LIMIT or STOP MARKET order would trigger immediately upon creation (because the current price already breaches the stop price), the system rejects the order with "STOP order would Immediately Trigger" message.
limit_order(symbol: str, qty: float, price: float)
market_order(symbol: str, qty: float)
stop_limit_order(symbol: str, qty: float, price: float, stop_price: float)
stop_market_order(symbol: str, qty: float, stop_price: float)
Multiple Currency Backtesting
You can simply test multiple currencies by passing data as dict[str, pd.DataFrame]. For examples, please refer to "multi_currency_sma_corss.ipynb" under "examples" folder.
Upcoming Features
- Overfitting checks
Deflated Sharpe ratio, walk-forward testing and a random-entry baseline, to tell whether a backtest result is likely to hold up.
💡 Got feedback or suggestions? Feel free to open an issue or contribute via pull request.
Metadata
Release files for overfitting 0.7.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| overfitting-0.7.0.tar.gz | 130.0 kB | Without provenance | Details for overfitting-0.7.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| overfitting-0.7.0-py3-none-any.whl | Python 3 | none | any | Details for overfitting-0.7.0-py3-none-any.whl |
Total release size: 215.8 kB
Release files / overfitting-0.7.0.tar.gz
| Download URL | overfitting-0.7.0.tar.gz |
|---|---|
| Size | 130.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
68625502a3f49120e83169030e76dc6e2a81c8bbf2447dba016da0cb2eed00d1
|
|
BLAKE2b-256 checksum How to use checksums |
40e7194d74ebddd4ae86a6a14ab5ea5e3d0f4db3ca6fdadc5404a5606cb69374
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.3
|
Release files / overfitting-0.7.0-py3-none-any.whl
| Download URL | overfitting-0.7.0-py3-none-any.whl |
|---|---|
| Size | 85.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63f438a4328854785404a90dbbc6aac6fbaff181007a2aa5a35ca4073fae6648
|
|
BLAKE2b-256 checksum How to use checksums |
5c51242cab31ed4cf1fc25892bd797c15787f64194ea47f0b7f271940eb6312e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.3
|
Security for overfitting 0.7.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.