"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
"""Tests for CryptoEngine market rules.
Validates:
- 24/7 execution (no direction/time restrictions)
- Fractional position sizing
- Maker/Taker fee separation
- Funding fee settlement (every 8 hours)
- Forced liquidation (maintenance margin check)
- Tiered maintenance margin rates
"""
from __future__ import annotations
import json
import math
import pandas as pd
import pytest
from backtest.engines.crypto import CryptoEngine
from backtest.engines._market_hooks import (
FUNDING_HOURS as _FUNDING_HOURS,
_maintenance_rate,
)
from backtest.models import Position
_BRACKETS = (
'[{"bracket_tier":1,"notional_cap":1000000.0,'
'"maintenance_rate":0.004,"cumulative_maintenance_amount":0.0}]'
)
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
def _make_bar(close: float = 60000.0, open_: float | None = None) -> pd.Series:
return pd.Series({"close": close, "open": open_ or close})
def _make_engine(**overrides) -> CryptoEngine:
config = {
"initial_cash": 100_000,
"leverage": 10.0,
"maker_rate": 0.0002,
"taker_rate": 0.0005,
"funding_rate": 0.0001,
}
config.update(overrides)
return CryptoEngine(config)
def _strict_engine(**overrides) -> CryptoEngine:
config = {
"initial_cash": 1_000.0,
"leverage": 10.0,
"maker_rate": 0.0002,
"taker_rate": 0.0005,
"slippage": 0.0,
"perpetual_strict": True,
"funding_mode": "data",
"margin_mode": "isolated",
}
config.update(overrides)
return CryptoEngine(config)
def _strict_frame(
dates: pd.DatetimeIndex,
*,
price: float = 100.0,
mark: list[float] | None = None,
execution_open: list[float] | None = None,
mark_open: list[float] | None = None,
mark_high: list[float] | None = None,
mark_low: list[float] | None = None,
mark_close: list[float] | None = None,
funding_rate: list[float] | None = None,
settlements: list[pd.Timestamp | None] | None = None,
) -> pd.DataFrame:
base = [price] * len(dates)
marks = mark or base
return pd.DataFrame(
{
"execution_open": execution_open or base,
"mark_open": mark_open or marks,
"mark_high": mark_high or marks,
"mark_low": mark_low or marks,
"mark_close": mark_close or marks,
"funding_rate": funding_rate or [0.0] * len(dates),
"funding_settlement_time": settlements or [pd.NaT] * len(dates),
"maintenance_brackets": [_BRACKETS] * len(dates),
"maintenance_bracket_version": ["fixture-v1"] * len(dates),
},
index=dates,
)
def _run_strict(
engine: CryptoEngine,
data_map: dict[str, pd.DataFrame],
targets: dict[str, list[float]],
) -> None:
dates = next(iter(data_map.values())).index
codes = list(data_map)
engine._execute_bars(
dates,
data_map,
pd.DataFrame(index=dates),
pd.DataFrame(targets, index=dates),
codes,
)
def _write_strict_artifacts(
engine: CryptoEngine,
data_map: dict[str, pd.DataFrame],
targets: dict[str, list[float]],
run_dir,
) -> dict:
dates = next(iter(data_map.values())).index
equity = pd.Series(
[snapshot.equity for snapshot in engine.equity_snapshots],
index=[snapshot.timestamp for snapshot in engine.equity_snapshots],
)
benchmark_return = pd.Series(0.0, index=dates)
metrics: dict = {}
engine._write_artifacts(
run_dir,
data_map,
dates,
equity,
pd.Series(engine.initial_capital, index=dates),
benchmark_return,
pd.DataFrame(targets, index=dates),
metrics,
list(data_map),
)
return metrics
def _read_strict_evidence(run_dir) -> tuple[list[dict], dict]:
artifacts = run_dir / "artifacts"
events = [
json.loads(line)
for line in (artifacts / "perpetual_events.jsonl")
.read_text(encoding="utf-8")
.splitlines()
]
summary = json.loads(
(artifacts / "perpetual_summary.json").read_text(encoding="utf-8")
)
return events, summary
def _run_liquidation_case(margin_mode: str):
dates = pd.date_range("2026-01-01", periods=2, freq="h", tz="UTC")
frames = {
symbol: _strict_frame(dates, mark_low=[100.0, low])
for symbol, low in (
("BTC-USDT-PERP", 80.0),
("ETH-USDT-PERP", 100.0),
)
}
engine = _strict_engine(
initial_cash=2_000.0,
interval="1H",
taker_rate=0.0,
maker_rate=0.0,
liquidation_fee_rate=0.01,
margin_mode=margin_mode,
)
targets = {symbol: [0.5, 0.5] for symbol in frames}
_run_strict(engine, frames, targets)
return engine, frames, targets
# ---------------------------------------------------------------------------
# can_execute: no restrictions
# ---------------------------------------------------------------------------
class TestCanExecute:
def test_long_allowed(self) -> None:
engine = _make_engine()
assert engine.can_execute("BTC-USDT", 1, _make_bar()) is True
def test_short_allowed(self) -> None:
engine = _make_engine()
assert engine.can_execute("BTC-USDT", -1, _make_bar()) is True
def test_close_allowed(self) -> None:
engine = _make_engine()
assert engine.can_execute("BTC-USDT", 0, _make_bar()) is True
# ---------------------------------------------------------------------------
# round_size: fractional
# ---------------------------------------------------------------------------
class TestRoundSize:
def test_fractional_preserved(self) -> None:
engine = _make_engine()
assert engine.round_size(0.123456, 60000.0) == 0.123456
def test_six_decimal_precision(self) -> None:
engine = _make_engine()
assert engine.round_size(0.1234567890, 60000.0) == pytest.approx(0.123457, abs=1e-7)
def test_negative_clamps_to_zero(self) -> None:
engine = _make_engine()
assert engine.round_size(-0.5, 60000.0) == 0.0
# ---------------------------------------------------------------------------
# calc_commission: maker/taker
# ---------------------------------------------------------------------------
class TestCommission:
def test_open_uses_taker(self) -> None:
engine = _make_engine(taker_rate=0.0005, maker_rate=0.0002)
comm = engine.calc_commission(1.0, 60000.0, 1, is_open=True)
# 1 BTC × $60000 × 0.0005 = $30
assert comm == pytest.approx(30.0)
def test_close_uses_maker(self) -> None:
engine = _make_engine(taker_rate=0.0005, maker_rate=0.0002)
comm = engine.calc_commission(1.0, 60000.0, 1, is_open=False)
# 1 BTC × $60000 × 0.0002 = $12
assert comm == pytest.approx(12.0)
def test_taker_higher_than_maker(self) -> None:
engine = _make_engine()
open_comm = engine.calc_commission(1.0, 60000.0, 1, is_open=True)
close_comm = engine.calc_commission(1.0, 60000.0, 1, is_open=False)
assert open_comm > close_comm
# ---------------------------------------------------------------------------
# apply_slippage
# ---------------------------------------------------------------------------
class TestSlippage:
def test_long_slippage_increases_price(self) -> None:
engine = _make_engine(slippage=0.001)
assert engine.apply_slippage(60000.0, 1) == pytest.approx(60060.0)
def test_short_slippage_decreases_price(self) -> None:
engine = _make_engine(slippage=0.001)
assert engine.apply_slippage(60000.0, -1) == pytest.approx(59940.0)
# ---------------------------------------------------------------------------
# Funding fee
# ---------------------------------------------------------------------------
class TestFundingFee:
def test_funding_deducted_at_settlement_hour(self) -> None:
engine = _make_engine(funding_rate=0.0001, interval="1H")
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
initial_capital = engine.capital
bar = _make_bar(close=60000.0)
ts = pd.Timestamp("2025-01-01 08:00:00") # settlement hour
engine.on_bar("BTC-USDT", bar, ts)
# Long pays: 1.0 × 60000 × 0.0001 × 1(long) = $6
assert engine.capital == pytest.approx(initial_capital - 6.0)
def test_non_settlement_hour_applies_daily_fallback(self) -> None:
"""Daily interval settles 3x per day (span-based count, #1290)."""
engine = _make_engine(funding_rate=0.0001)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
initial_capital = engine.capital
bar = _make_bar(close=60000.0)
ts = pd.Timestamp("2025-01-01 05:00:00") # not settlement hour
engine.on_bar("BTC-USDT", bar, ts)
# Daily bars settle 3x per bar regardless of which hour the bar prints
assert engine.capital == pytest.approx(initial_capital - 18.0)
def test_short_receives_funding(self) -> None:
engine = _make_engine(funding_rate=0.0001)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", -1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
initial_capital = engine.capital
bar = _make_bar(close=60000.0)
ts = pd.Timestamp("2025-01-01 08:00:00")
engine.on_bar("BTC-USDT", bar, ts)
# Short: direction=-1, fee = notional × rate × direction = negative → capital increases
assert engine.capital > initial_capital
def test_no_double_settlement(self) -> None:
engine = _make_engine(funding_rate=0.0001)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
bar = _make_bar(close=60000.0)
ts = pd.Timestamp("2025-01-01 08:00:00")
engine.on_bar("BTC-USDT", bar, ts)
capital_after_first = engine.capital
# Call again at same hour — should not deduct again
engine.on_bar("BTC-USDT", bar, ts)
assert engine.capital == capital_after_first
def test_no_funding_without_position(self) -> None:
engine = _make_engine()
initial_capital = engine.capital
bar = _make_bar()
ts = pd.Timestamp("2025-01-01 08:00:00")
engine.on_bar("BTC-USDT", bar, ts)
assert engine.capital == initial_capital
def test_daily_bars_apply_each_day(self) -> None:
"""Regression: daily bars (all hour=0) must apply funding every day, not just day 1."""
engine = _make_engine(funding_rate=0.0001)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
bar = _make_bar(close=60000.0)
initial = engine.capital
# Day 1
engine.on_bar("BTC-USDT", bar, pd.Timestamp("2025-01-01"))
after_day1 = engine.capital
assert after_day1 < initial # fee deducted
# Day 2 (same hour=0, different date)
engine.on_bar("BTC-USDT", bar, pd.Timestamp("2025-01-02"))
after_day2 = engine.capital
assert after_day2 < after_day1 # fee deducted again
# Day 3
engine.on_bar("BTC-USDT", bar, pd.Timestamp("2025-01-03"))
after_day3 = engine.capital
assert after_day3 < after_day2 # fee deducted again
# Each day: 3 × 60000 × 0.0001 = $18; three days = $54
assert initial - after_day3 == pytest.approx(54.0)
def test_intraday_four_hour_bars_keep_slot_and_fallback(self) -> None:
"""4H bars are below the span threshold: slot + daily fallback, as before."""
engine = _make_engine(funding_rate=0.0001, interval="4H")
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
initial = engine.capital
bar = _make_bar(close=60000.0)
# 00:00 slot, 04:00 fallback, 08:00 slot, 16:00 slot -> 4 settlements
for hour in (0, 4, 8, 12, 16, 20):
engine.on_bar("BTC-USDT", bar, pd.Timestamp(f"2025-01-01 {hour:02d}:00:00"))
assert initial - engine.capital == pytest.approx(4 * 6.0)
def test_interval_span_hours_parser(self) -> None:
from backtest.engines._market_hooks import _interval_span_hours
assert _interval_span_hours("1m") == pytest.approx(1 / 60)
assert _interval_span_hours("30m") == pytest.approx(0.5)
assert _interval_span_hours("1H") == 1.0
assert _interval_span_hours("4H") == 4.0
assert _interval_span_hours("1D") == 24.0
assert _interval_span_hours("nonsense") is None
def test_multi_symbol_funding(self) -> None:
"""Each symbol gets independent funding settlement."""
engine = _make_engine(funding_rate=0.0001, interval="1H")
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
engine.positions["ETH-USDT"] = Position(
"ETH-USDT", 1, 3000.0, pd.Timestamp("2025-01-01"), 10.0, leverage=10.0,
)
initial = engine.capital
bar_btc = _make_bar(close=60000.0)
bar_eth = _make_bar(close=3000.0)
ts = pd.Timestamp("2025-01-01 08:00:00")
engine.on_bar("BTC-USDT", bar_btc, ts)
after_btc = engine.capital
engine.on_bar("ETH-USDT", bar_eth, ts)
after_both = engine.capital
# BTC: 1 × 60000 × 0.0001 = $6
# ETH: 10 × 3000 × 0.0001 = $3
assert initial - after_btc == pytest.approx(6.0)
assert initial - after_both == pytest.approx(9.0)
def test_funding_hours_correct(self) -> None:
assert _FUNDING_HOURS == {0, 8, 16}
# ---------------------------------------------------------------------------
# Liquidation
# ---------------------------------------------------------------------------
class TestLiquidation:
def test_liquidation_on_large_loss(self) -> None:
"""Position wiped when equity drops below maintenance margin."""
engine = _make_engine(leverage=10.0)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
# Margin = 1.0 × 60000 / 10 = $6000
# If price drops to 54500: unrealized = 1 × (54500 - 60000) = -$5500
# equity_in_pos = 6000 + (-5500) = $500
# Notional = 1 × 54500 = 54500, maint_rate(54500) = 0.004
# Maint margin = 54500 × 0.004 = $218
# $500 > $218 → no liquidation
# But if price drops to 54000:
# unrealized = -6000, equity = 0 → clearly liquidated
bar = _make_bar(close=54000.0)
ts = pd.Timestamp("2025-01-02")
engine.on_bar("BTC-USDT", bar, ts)
assert "BTC-USDT" not in engine.positions
assert len(engine.trades) == 1
assert engine.trades[0].exit_reason == "liquidation"
def test_no_liquidation_when_profitable(self) -> None:
engine = _make_engine(leverage=10.0)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
bar = _make_bar(close=65000.0)
ts = pd.Timestamp("2025-01-02")
engine.on_bar("BTC-USDT", bar, ts)
assert "BTC-USDT" in engine.positions
def test_no_liquidation_for_spot(self) -> None:
"""Spot (leverage=1) should never get liquidated."""
engine = _make_engine(leverage=1.0)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=1.0,
)
bar = _make_bar(close=30000.0) # 50% drop
ts = pd.Timestamp("2025-01-02")
engine.on_bar("BTC-USDT", bar, ts)
assert "BTC-USDT" in engine.positions
def test_short_liquidation(self) -> None:
"""Short position liquidated when price rises sharply."""
engine = _make_engine(leverage=10.0)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", -1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
# Margin = $6000, unrealized = -1 × 1 × (66500 - 60000) = -$6500
# equity_in_pos = 6000 - 6500 = -$500 < 0 → liquidated
bar = _make_bar(close=66500.0)
ts = pd.Timestamp("2025-01-02")
engine.on_bar("BTC-USDT", bar, ts)
assert "BTC-USDT" not in engine.positions
def test_wick_only_trigger_liquidates(self) -> None:
"""A levered long whose low pierces maintenance is liquidated even when
the close recovers; the fill is priced at the adverse mark (bar low)."""
engine = _make_engine(leverage=2.0, slippage=0.0)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", 1, 100.0, pd.Timestamp("2025-01-01"), 10.0, leverage=2.0,
)
# Hook marks at low=30: margin 500, unrealized -700 -> equity -200,
# <= maint (300 * 0.004 = 1.2), so liquidation fires on the wick alone.
bar = pd.Series({"close": 100.0, "high": 101.0, "low": 30.0})
ts = pd.Timestamp("2025-01-02")
engine.on_bar("BTC-USDT", bar, ts)
assert "BTC-USDT" not in engine.positions
assert len(engine.trades) == 1
assert engine.trades[0].exit_reason == "liquidation"
assert engine.trades[0].exit_price == pytest.approx(30.0)
def test_1x_short_liquidates_through_twice_the_entry_price(self) -> None:
"""#1291: a 1x short must be liquidated, not exempted at 2x adverse."""
engine = _make_engine(leverage=1.0, slippage=0.0)
engine.positions["BTC-USDT"] = Position(
"BTC-USDT", -1, 100.0, pd.Timestamp("2025-01-01"), 10.0, leverage=1.0,
)
# Margin is the full notional (1000); the 2x adverse bar zeroes it:
# equity 0 <= maint (2000 * 0.004 = 8), filled at the adverse high.
bar = pd.Series({"close": 200.0, "high": 200.0, "low": 101.0})
ts = pd.Timestamp("2025-01-02")
engine.on_bar("BTC-USDT", bar, ts)
assert "BTC-USDT" not in engine.positions
assert len(engine.trades) == 1
assert engine.trades[0].exit_reason == "liquidation"
assert engine.trades[0].exit_price == pytest.approx(200.0)
# ---------------------------------------------------------------------------
# Tiered maintenance margin
# ---------------------------------------------------------------------------
class TestMaintenanceRate:
def test_small_position(self) -> None:
assert _maintenance_rate(50_000) == 0.004
def test_medium_position(self) -> None:
assert _maintenance_rate(300_000) == 0.006
def test_large_position(self) -> None:
assert _maintenance_rate(2_000_000) == 0.02
def test_tier_boundaries(self) -> None:
assert _maintenance_rate(100_000) == 0.004
assert _maintenance_rate(100_001) == 0.006
def test_maximum_tier(self) -> None:
assert _maintenance_rate(100_000_000) == 0.10
class TestHistoricalFundingRate:
def test_bar_funding_rate_overrides_fixed_rate(self) -> None:
"""A bar carrying a historical ``funding_rate`` column (USD-M perp
data) must be charged at that rate, not the fixed config rate."""
engine = _make_engine(funding_rate=0.0001, interval="1H")
engine.positions["BTC-USDT-PERP"] = Position(
"BTC-USDT-PERP", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
initial_capital = engine.capital
bar = pd.Series({"close": 60000.0, "open": 60000.0, "funding_rate": 0.0005})
ts = pd.Timestamp("2025-01-01 08:00:00")
engine.on_bar("BTC-USDT-PERP", bar, ts)
# Historical rate: 1.0 × 60000 × 0.0005 = $30 (not $6 from the fixed rate)
assert engine.capital == pytest.approx(initial_capital - 30.0)
def test_negative_historical_funding_pays_longs(self) -> None:
engine = _make_engine(funding_rate=0.0001, interval="1H")
engine.positions["BTC-USDT-PERP"] = Position(
"BTC-USDT-PERP", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
initial_capital = engine.capital
bar = pd.Series({"close": 60000.0, "open": 60000.0, "funding_rate": -0.0002})
ts = pd.Timestamp("2025-01-01 08:00:00")
engine.on_bar("BTC-USDT-PERP", bar, ts)
# Negative funding: longs receive
assert engine.capital == pytest.approx(initial_capital + 12.0)
def test_nan_funding_rate_falls_back_to_fixed(self) -> None:
"""Non-settlement bars carry NaN funding_rate — must fall back to
the fixed config rate (daily-fallback path), not charge NaN."""
engine = _make_engine(funding_rate=0.0001, interval="1H")
engine.positions["BTC-USDT-PERP"] = Position(
"BTC-USDT-PERP", 1, 60000.0, pd.Timestamp("2025-01-01"), 1.0, leverage=10.0,
)
initial_capital = engine.capital
bar = pd.Series({"close": 60000.0, "open": 60000.0, "funding_rate": float("nan")})
ts = pd.Timestamp("2025-01-01 08:00:00")
engine.on_bar("BTC-USDT-PERP", bar, ts)
assert engine.capital == pytest.approx(initial_capital - 6.0)
class TestStrictPerpetualLifecycle:
# "1M" is a month: the old lower-cased comparison read it as "1m" (#1479).
@pytest.mark.parametrize("interval", ["3m", "60m", "4H", "1D", "1W", "1M"])
def test_strict_100x_rejects_unsupported_or_coarse_intervals(
self, interval: str
) -> None:
with pytest.raises(ValueError, match="resolution boundary"):
_strict_engine(leverage=100.0, interval=interval)
@pytest.mark.parametrize("interval", ["1m", "30m", "1H"])
def test_strict_100x_accepts_at_most_one_hour(self, interval: str) -> None:
engine = _strict_engine(leverage=100.0, interval=interval)
assert engine.default_leverage == 100.0
def test_strict_100x_revalidates_run_config_before_loading(
self, tmp_path
) -> None:
class LoaderThatMustNotRun:
def fetch(self, *args, **kwargs):
raise AssertionError("loader ran before strict interval validation")
engine = _strict_engine(leverage=100.0, interval="1H")
run_config = {
**engine.config,
"codes": ["BTC-USDT-PERP"],
"interval": "1D",
}
with pytest.raises(ValueError, match="resolution boundary"):
engine.run_backtest(run_config, LoaderThatMustNotRun(), object(), tmp_path)
def test_market_fills_use_execution_open_and_taker_rate(self) -> None:
dates = pd.date_range("2026-01-01", periods=2, freq="h", tz="UTC")
frame = _strict_frame(
dates,
execution_open=[60_123.0, 60_234.0],
mark_open=[60_000.0, 60_100.0],
mark_high=[60_200.0, 60_300.0],
mark_low=[59_900.0, 60_000.0],
mark_close=[60_100.0, 60_200.0],
)
engine = _strict_engine()
_run_strict(engine, {"BTC-USDT-PERP": frame}, {"BTC-USDT-PERP": [1.0, 0.0]})
trade = engine.trades[0]
assert trade.entry_price == 60_123.0
assert trade.exit_price == 60_234.0
assert trade.commission == pytest.approx(
trade.size * (trade.entry_price + trade.exit_price) * engine.taker_rate
)
def test_funding_applies_only_to_position_open_before_settlement(self) -> None:
dates = pd.date_range("2026-01-01", periods=2, freq="8h", tz="UTC")
frame = _strict_frame(
dates,
price=60_000.0,
funding_rate=[0.001, 0.001],
settlements=list(dates),
)
engine = _strict_engine(taker_rate=0.0, maker_rate=0.0)
_run_strict(engine, {"BTC-USDT-PERP": frame}, {"BTC-USDT-PERP": [1.0, 0.0]})
assert engine.capital == pytest.approx(990.0, abs=0.001)
def test_isolated_liquidation_closes_only_breached_position(self) -> None:
dates = pd.date_range("2026-01-01", periods=2, freq="h", tz="UTC")
btc = _strict_frame(
dates,
mark_low=[90.0, 100.0],
mark_close=[95.0, 100.0],
)
eth = _strict_frame(dates)
engine = _strict_engine(
initial_cash=2_000.0,
taker_rate=0.0,
maker_rate=0.0,
liquidation_fee_rate=0.01,
)
_run_strict(
engine,
{"BTC-USDT-PERP": btc, "ETH-USDT-PERP": eth},
{"BTC-USDT-PERP": [0.5, 0.0], "ETH-USDT-PERP": [0.5, 0.5]},
)
reasons = {trade.symbol: trade.exit_reason for trade in engine.trades}
assert reasons == {
"BTC-USDT-PERP": "position_liquidation",
"ETH-USDT-PERP": "end_of_backtest",
}
assert engine.terminal_status == "completed"
assert engine.capital == pytest.approx(910.0)
def test_open_mark_liquidation_blocks_same_bar_reopen(self) -> None:
dates = pd.date_range("2026-01-01", periods=2, freq="h", tz="UTC")
frame = _strict_frame(
dates,
mark=[100.0, 90.0],
)
engine = _strict_engine(taker_rate=0.0, maker_rate=0.0)
_run_strict(engine, {"BTC-USDT-PERP": frame}, {"BTC-USDT-PERP": [1.0, 1.0]})
assert [trade.exit_reason for trade in engine.trades] == [
"position_liquidation"
]
assert not engine.positions
def test_cross_liquidation_closes_account_and_stops_later_bars(self) -> None:
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
frames = {
symbol: _strict_frame(
dates,
mark_low=[100.0, low, 100.0],
)
for symbol, low in (
("BTC-USDT-PERP", 80.0),
("ETH-USDT-PERP", 100.0),
)
}
engine = _strict_engine(
initial_cash=2_000.0,
taker_rate=0.0,
maker_rate=0.0,
margin_mode="cross",
)
_run_strict(
engine,
frames,
{symbol: [0.5] * 3 for symbol in frames},
)
assert {trade.exit_reason for trade in engine.trades} == {
"account_liquidation"
}
assert engine.terminal_status == "account_liquidation"
assert len(engine.equity_snapshots) == 2
assert engine.equity_snapshots[-1].timestamp == dates[1]
def test_evidence_records_funding_before_fill_and_separate_fee_totals(
self, tmp_path
) -> None:
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
frame = _strict_frame(
dates,
funding_rate=[0.0, 0.001, 0.0],
settlements=[None, dates[1], None],
)
engine = _strict_engine(
interval="1H",
taker_rate=0.001,
liquidation_fee_rate=0.02,
)
targets = {"BTC-USDT-PERP": [0.5, 0.0, 0.0]}
_run_strict(engine, {"BTC-USDT-PERP": frame}, targets)
metrics = _write_strict_artifacts(
engine, {"BTC-USDT-PERP": frame}, targets, tmp_path
)
events, summary = _read_strict_evidence(tmp_path)
settlement = next(
event for event in events if event["event_type"] == "funding_settlement"
)
close_fill = next(
event
for event in events
if event["event_type"] == "market_fill" and event["action"] == "close"
)
assert settlement["timestamp"] == dates[1].isoformat()
assert settlement["funding_pnl"] == pytest.approx(-5.0)
assert settlement["sequence"] < close_fill["sequence"]
assert close_fill["execution_price_source"] == "execution_open"
assert summary["funding_settlement_count"] == 1
assert summary["total_funding_pnl"] == pytest.approx(-5.0)
assert summary["total_trading_fee"] == pytest.approx(10.0)
assert summary["total_liquidation_fee"] == 0.0
assert summary["leverage"] == 10.0
assert summary["taker_rate"] == 0.001
assert summary["liquidation_fee_rate"] == 0.02
assert summary["fee_model"] == {
"market_fill_rate": "taker_rate",
"maker_rate_used": False,
"funding_separate": True,
"liquidation_separate": True,
}
assert metrics["perpetual_funding_pnl"] == pytest.approx(-5.0)
assert metrics["perpetual_trading_fees"] == pytest.approx(10.0)
def test_evidence_records_cross_liquidation_and_intrabar_limitation(
self, tmp_path
) -> None:
engine, frames, targets = _run_liquidation_case("cross")
metrics = _write_strict_artifacts(engine, frames, targets, tmp_path)
events, summary = _read_strict_evidence(tmp_path)
liquidation = next(
event for event in events if event["event_type"] == "account_liquidation"
)
assert liquidation["symbols"] == ["BTC-USDT-PERP", "ETH-USDT-PERP"]
assert liquidation["price_source"] == "adverse_mark_extrema"
assert liquidation["liquidation_fee"] == pytest.approx(180.0)
assert summary["terminal_status"] == "account_liquidation"
assert summary["liquidation_event_count"] == 1
assert summary["liquidated_position_count"] == 2
assert summary["total_liquidation_fee"] == pytest.approx(180.0)
assert summary["maintenance_bracket_versions"] == {
"BTC-USDT-PERP": "fixture-v1",
"ETH-USDT-PERP": "fixture-v1",
}
assert summary["fidelity_flags"] == ["conservative_intrabar_assumption"]
assert "not guaranteed" in summary["resolution_limitation"]
assert metrics["perpetual_liquidation_events"] == 1
assert metrics["perpetual_liquidation_fees"] == pytest.approx(180.0)
def test_evidence_keeps_isolated_liquidation_position_scoped(
self, tmp_path
) -> None:
engine, frames, targets = _run_liquidation_case("isolated")
_write_strict_artifacts(engine, frames, targets, tmp_path)
events, _ = _read_strict_evidence(tmp_path)
liquidations = [
event
for event in events
if event["event_type"]
in {
"position_liquidation",
"account_liquidation",
}
]
assert [event["event_type"] for event in liquidations] == [
"position_liquidation"
]
assert liquidations[0]["symbol"] == "BTC-USDT-PERP"
assert liquidations[0]["liquidation_fee"] == pytest.approx(80.0)
assert engine.terminal_status == "completed"
assert {trade.symbol: trade.exit_reason for trade in engine.trades} == {
"BTC-USDT-PERP": "position_liquidation",
"ETH-USDT-PERP": "end_of_backtest",
}
@pytest.mark.parametrize("margin_mode", ["isolated", "cross"])
def test_rebalance_matches_hand_computed_collateral_and_fill_accounting(
self, margin_mode: str
) -> None:
class StateCaptureEngine(CryptoEngine):
def __init__(self, config: dict) -> None:
super().__init__(config)
self.states: list[dict] = []
def after_rebalance_bar(self, timestamp, data_map, codes) -> bool:
stop = super().after_rebalance_bar(timestamp, data_map, codes)
position = self.positions["BTC-USDT-PERP"]
account = self._account_state()
self.states.append(
{
"size": position.size,
"entry_price": position.entry_price,
"entry_fee": position.entry_commission,
"capital": self.capital,
"isolated_margin": self._isolated_margins.get(position.symbol),
"wallet_balance": account.wallet_balance,
}
)
return stop
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
engine = StateCaptureEngine(
{
"initial_cash": 1_000.0,
"leverage": 10.0,
"maker_rate": 0.0002,
"taker_rate": 0.001,
"slippage": 0.0,
"perpetual_strict": True,
"funding_mode": "data",
"margin_mode": margin_mode,
"position_adjustment": "rebalance",
}
)
_run_strict(
engine,
{"BTC-USDT-PERP": _strict_frame(dates)},
{"BTC-USDT-PERP": [0.25, 0.50, 0.20]},
)
assert [state["size"] for state in engine.states] == pytest.approx(
[25.0, 49.875, 19.90025]
)
assert [state["entry_price"] for state in engine.states] == pytest.approx(
[100.0, 100.0, 100.0]
)
assert [state["entry_fee"] for state in engine.states] == pytest.approx(
[2.5, 4.9875, 1.990025]
)
assert [state["capital"] for state in engine.states] == pytest.approx(
[747.5, 496.2625, 793.012525]
)
assert [state["wallet_balance"] for state in engine.states] == pytest.approx(
[997.5, 995.0125, 992.015025]
)
isolated_margins = [state["isolated_margin"] for state in engine.states]
if margin_mode == "isolated":
assert isolated_margins == pytest.approx([250.0, 498.75, 199.0025])
else:
assert isolated_margins == [None, None, None]
fills = [
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill"
]
assert [event["action"] for event in fills] == [
"open",
"increase",
"reduce",
"close",
]
assert [event["signed_quantity"] for event in fills[:3]] == pytest.approx(
[25.0, 24.875, -29.97475]
)
assert [event["trading_fee"] for event in fills[:3]] == pytest.approx(
[2.5, 2.4875, 2.997475]
)
assert fills[2]["realized_pnl"] == pytest.approx(0.0)
assert fills[2]["released_margin"] == pytest.approx(299.7475)
def test_rebalance_funding_precedes_increase_at_preincrease_size(self) -> None:
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
engine = _strict_engine(position_adjustment="rebalance", taker_rate=0.001)
frame = _strict_frame(
dates,
funding_rate=[0.0, 0.001, 0.0],
settlements=[None, dates[1], None],
)
_run_strict(
engine,
{"BTC-USDT-PERP": frame},
{"BTC-USDT-PERP": [0.25, 0.50, 0.20]},
)
funding = next(
event
for event in engine._perpetual_events
if event["event_type"] == "funding_settlement"
)
increase = next(
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill" and event["action"] == "increase"
)
assert funding["signed_quantity"] == pytest.approx(25.0)
assert funding["sequence"] < increase["sequence"]
def test_isolated_reduction_keeps_funding_pnl_and_collateral_consistent(
self,
) -> None:
class StateCaptureEngine(CryptoEngine):
def __init__(self, config: dict) -> None:
super().__init__(config)
self.states: list[dict] = []
def after_rebalance_bar(self, timestamp, data_map, codes) -> bool:
stop = super().after_rebalance_bar(timestamp, data_map, codes)
position = self.positions["BTC-USDT-PERP"]
self.states.append(
{
"capital": self.capital,
"wallet_balance": self._account_state().wallet_balance,
"isolated_margin": self._isolated_margins[position.symbol],
"size": position.size,
}
)
return stop
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
engine = StateCaptureEngine(
{
**_strict_engine(
position_adjustment="rebalance",
taker_rate=0.001,
).config
}
)
frame = _strict_frame(
dates,
execution_open=[100.0, 100.0, 110.0],
mark=[100.0, 100.0, 110.0],
funding_rate=[0.0, 0.001, 0.0],
settlements=[None, dates[1], None],
)
_run_strict(
engine,
{"BTC-USDT-PERP": frame},
{"BTC-USDT-PERP": [0.25, 0.50, 0.20]},
)
after_increase, after_reduction = engine.states[1:]
assert after_increase == pytest.approx(
{
"capital": 495.025,
"wallet_balance": 992.525,
"isolated_margin": 495.0,
"size": 49.75,
}
)
assert after_reduction == pytest.approx(
{
"capital": 945.7052772727273,
"wallet_balance": 1216.6189136363636,
"isolated_margin": 269.5522613065327,
"size": 27.0913636363636,
}
)
reduction = next(
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill" and event["action"] == "reduce"
)
assert reduction["realized_pnl"] == pytest.approx(226.5863636363636)
assert reduction["released_margin"] == pytest.approx(226.5863636363636)
assert reduction["trading_fee"] == pytest.approx(2.49245)
assert after_reduction["wallet_balance"] == pytest.approx(
1_000.0
- 2.5 # opening fee
- 2.5 # funding paid before the increase
- 2.475 # increase fee
+ reduction["realized_pnl"]
- reduction["trading_fee"]
)
def test_cross_rebalance_reduces_before_addition_and_then_checks_risk(self) -> None:
dates = pd.date_range("2026-01-01", periods=2, freq="h", tz="UTC")
engine = _strict_engine(
position_adjustment="rebalance",
margin_mode="cross",
taker_rate=0.0,
maker_rate=0.0,
)
frames = {
symbol: _strict_frame(dates)
for symbol in ("BTC-USDT-PERP", "ETH-USDT-PERP")
}
_run_strict(
engine,
frames,
{
"BTC-USDT-PERP": [0.40, 0.10],
"ETH-USDT-PERP": [0.40, 0.70],
},
)
second_bar = [
event
for event in engine._perpetual_events
if event["timestamp"] == dates[1].isoformat()
]
reduce_event = next(event for event in second_bar if event.get("action") == "reduce")
increase_event = next(
event for event in second_bar if event.get("action") == "increase"
)
risk_events = [
event
for event in second_bar
if event["event_type"] == "risk_snapshot" and event["phase"] == "post_fill"
]
assert reduce_event["symbol"] == "BTC-USDT-PERP"
assert increase_event["symbol"] == "ETH-USDT-PERP"
assert len(risk_events) == 2
assert (
reduce_event["sequence"]
< risk_events[0]["sequence"]
< increase_event["sequence"]
< risk_events[1]["sequence"]
)
assert [event["status"] for event in risk_events] == ["healthy", "healthy"]
def test_strict_100x_rebalance_stays_finite_without_breach(self) -> None:
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
engine = _strict_engine(
interval="1H",
leverage=100.0,
position_adjustment="rebalance",
taker_rate=0.001,
)
_run_strict(
engine,
{"BTC-USDT-PERP": _strict_frame(dates)},
{"BTC-USDT-PERP": [0.02, 0.03, 0.01]},
)
assert {
event["action"]
for event in engine._perpetual_events
if event["event_type"] == "market_fill"
} >= {"increase", "reduce"}
assert all(
math.isfinite(value)
for snapshot in engine.equity_snapshots
for value in (snapshot.equity, snapshot.capital)
)
assert all(
math.isfinite(float(event[field]))
for event in engine._perpetual_events
if event["event_type"] == "risk_snapshot"
for field in (
"margin_balance",
"initial_margin",
"maintenance_margin",
"available_balance",
)
)
def test_strict_rebalance_fills_use_raw_execution_open(self) -> None:
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
engine = _strict_engine(
position_adjustment="rebalance",
slippage=0.10,
taker_rate=0.0,
maker_rate=0.0,
)
frame = _strict_frame(
dates,
execution_open=[101.0, 102.0, 103.0],
mark=[113.3, 113.3, 113.3],
)
_run_strict(
engine,
{"BTC-USDT-PERP": frame},
{"BTC-USDT-PERP": [0.25, 0.50, 0.20]},
)
fills = {
event["action"]: event["execution_price"]
for event in engine._perpetual_events
if event["event_type"] == "market_fill"
and event["action"] in {"open", "increase", "reduce"}
}
assert fills == {"open": 101.0, "increase": 102.0, "reduce": 103.0}
def test_strict_hold_keeps_configured_slippage_behavior(self) -> None:
dates = pd.date_range("2026-01-01", periods=2, freq="h", tz="UTC")
engine = _strict_engine(
position_adjustment="hold",
slippage=0.10,
taker_rate=0.0,
maker_rate=0.0,
)
_run_strict(
engine,
{"BTC-USDT-PERP": _strict_frame(dates)},
{"BTC-USDT-PERP": [0.25, 0.25]},
)
fills = [
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill"
]
assert [event["action"] for event in fills] == ["open", "close"]
assert [event["execution_price"] for event in fills] == pytest.approx(
[110.0, 90.0]
)
def test_cross_atomic_liquidation_stops_remaining_additions(self) -> None:
dates = pd.date_range("2026-01-01", periods=1, freq="h", tz="UTC")
engine = _strict_engine(
position_adjustment="rebalance",
margin_mode="cross",
taker_rate=0.0,
maker_rate=0.0,
)
frames = {
"BTC-USDT-PERP": _strict_frame(dates, mark_low=[80.0]),
"ETH-USDT-PERP": _strict_frame(dates),
}
_run_strict(
engine,
frames,
{
"BTC-USDT-PERP": [0.50],
"ETH-USDT-PERP": [0.25],
},
)
fills = [
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill" and event["action"] == "open"
]
assert [event["symbol"] for event in fills] == ["BTC-USDT-PERP"]
assert engine.terminal_status == "account_liquidation"
assert not engine.positions
def test_isolated_atomic_liquidation_allows_other_symbol_to_continue(self) -> None:
dates = pd.date_range("2026-01-01", periods=1, freq="h", tz="UTC")
engine = _strict_engine(
position_adjustment="rebalance",
margin_mode="isolated",
taker_rate=0.0,
maker_rate=0.0,
)
frames = {
"BTC-USDT-PERP": _strict_frame(dates, mark_low=[90.0]),
"ETH-USDT-PERP": _strict_frame(dates),
}
_run_strict(
engine,
frames,
{
"BTC-USDT-PERP": [0.50],
"ETH-USDT-PERP": [0.25],
},
)
fills = [
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill" and event["action"] == "open"
]
assert [event["symbol"] for event in fills] == [
"BTC-USDT-PERP",
"ETH-USDT-PERP",
]
liquidation = next(
event
for event in engine._perpetual_events
if event["event_type"] == "position_liquidation"
)
assert liquidation["symbol"] == "BTC-USDT-PERP"
assert engine.terminal_status == "completed"
def test_isolated_liquidation_rejects_now_unfunded_addition(self) -> None:
dates = pd.date_range("2026-01-01", periods=1, freq="h", tz="UTC")
engine = _strict_engine(
position_adjustment="rebalance",
margin_mode="isolated",
taker_rate=0.0,
maker_rate=0.0,
)
frames = {
"BTC-USDT-PERP": _strict_frame(dates, mark_low=[80.0]),
"ETH-USDT-PERP": _strict_frame(dates),
}
_run_strict(
engine,
frames,
{
"BTC-USDT-PERP": [0.50],
"ETH-USDT-PERP": [0.25],
},
)
opens = [
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill" and event["action"] == "open"
]
assert [event["symbol"] for event in opens] == ["BTC-USDT-PERP"]
rejected = next(
event
for event in engine._perpetual_events
if event["event_type"] == "order_rejected"
)
assert rejected["symbol"] == "ETH-USDT-PERP"
assert rejected["reason"] == "insufficient_capital_after_liquidation"
assert rejected["required_capital"] == pytest.approx(250.0)
assert rejected["available_capital"] == pytest.approx(0.0)
assert engine.terminal_status == "completed"
def test_cross_rebalance_increase_precedes_adverse_account_liquidation(
self,
) -> None:
dates = pd.date_range("2026-01-01", periods=2, freq="h", tz="UTC")
engine = _strict_engine(
initial_cash=1_000.0,
position_adjustment="rebalance",
taker_rate=0.0,
maker_rate=0.0,
margin_mode="cross",
)
frame = _strict_frame(dates, mark_low=[100.0, 80.0])
_run_strict(
engine,
{"BTC-USDT-PERP": frame},
{"BTC-USDT-PERP": [0.25, 0.50]},
)
increase = next(
event
for event in engine._perpetual_events
if event["event_type"] == "market_fill" and event["action"] == "increase"
)
liquidation = next(
event
for event in engine._perpetual_events
if event["event_type"] == "account_liquidation"
)
assert increase["sequence"] < liquidation["sequence"]
assert not engine.positions
assert engine.terminal_status == "account_liquidation"
def test_rebalance_evidence_artifacts_are_deterministic(self, tmp_path) -> None:
dates = pd.date_range("2026-01-01", periods=3, freq="h", tz="UTC")
frame = _strict_frame(dates)
targets = {"BTC-USDT-PERP": [0.25, 0.50, 0.20]}
results = []
for run_name in ("first", "second"):
engine = _strict_engine(
position_adjustment="rebalance",
taker_rate=0.001,
)
_run_strict(engine, {"BTC-USDT-PERP": frame}, targets)
metrics = _write_strict_artifacts(
engine,
{"BTC-USDT-PERP": frame},
targets,
tmp_path / run_name,
)
events, summary = _read_strict_evidence(tmp_path / run_name)
results.append((events, summary, metrics))
first_events, first_summary, first_metrics = results[0]
second_events, second_summary, second_metrics = results[1]
assert first_events == second_events
assert first_summary == second_summary
assert first_metrics == second_metrics
assert [
event["action"]
for event in first_events
if event["event_type"] == "market_fill"
] == ["open", "increase", "reduce", "close"]
assert first_summary["total_trading_fee"] == pytest.approx(9.975)
assert first_metrics["perpetual_trading_fees"] == pytest.approx(9.975)