fee/slippage/funding cost models

crypto_eval/costs.py

@@ -0,0 +1,53 @@
+"""Fee, slippage and funding models for institutional-grade crypto backtests.
+
+Conventions (Binance USDT-M VIP0, verified 2026-10):
+  - taker fee 5 bps, maker fee 2 bps
+  - funding: charged at 8h ticks, cost = funding_rate * notional, sign
+    follows the position side (longs pay when rate > 0)
+  - slippage: square-root impact model k * sqrt(notional / ADV), floor 2 bps
+
+Everything here is a COST function: positive output = money lost.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+TAKER_FEE = 0.0005
+MAKER_FEE = 0.0002
+SLIPPAGE_FLOOR_BPS = 2.0
+IMPACT_K = 0.5  # calibrated against Binance 20-level books; conservative
+
+
+def fee(notional: float, side: str = "taker") -> float:
+    return abs(notional) * (TAKER_FEE if side == "taker" else MAKER_FEE)
+
+
+def slippage_cost(notional: float, adv_notional: float) -> float:
+    """Square-root impact cost in quote currency."""
+    if adv_notional <= 0:
+        raise ValueError("adv_notional must be positive")
+    bps = max(SLIPPAGE_FLOOR_BPS, IMPACT_K * np.sqrt(abs(notional) / adv_notional) * 1e4)
+    return abs(notional) * bps / 1e4
+
+
+def funding_cost(
+    positions: pd.Series,
+    funding: pd.Series,
+    prices: pd.Series,
+) -> pd.Series:
+    """Per-bar funding cost series, accrued only at funding timestamps.
+
+    positions: position in units of base asset, indexed by bar start time.
+    funding: funding_rate at each 8h tick.
+    prices: mark/close price at each bar, for notional valuation.
+
+    A bar starting at t covers [t, t+1h); a funding tick at t charges that
+    tick to the position held entering the tick, i.e. the position at t.
+    """
+    tick_times = funding.index
+    pos_at_tick = positions.reindex(tick_times, method="ffill")
+    price_at_tick = prices.reindex(tick_times, method="ffill")
+    cost = pos_at_tick * price_at_tick * funding  # longs pay positive funding
+    return cost.reindex(positions.index, fill_value=0.0).fillna(0.0)