quantbt-engine 1.0.7__py3-none-any.whl

quantbt/options/fees.py

@@ -0,0 +1,135 @@
+"""
+Option fee schedules.
+
+Phase 5 implements deterministic per-leg capped fees. There is intentionally no
+package-level cap because real venues cap option fees per contract/leg.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Union
+
+from ..core.orders import Fill
+from ..core.schema import LiquiditySide
+from .schema import OptionInstrumentSpec, PremiumConvention
+
+
+@dataclass(frozen=True)
+class OptionFeeResult:
+    fee: float
+    currency: str
+    raw_fee: float
+    cap: float
+    capped: bool
+    schedule_id: str
+
+
+@dataclass(frozen=True)
+class OptionFeeSchedule:
+    schedule_id: str
+    fee_currency: str
+    maker_rate: float = 0.0
+    taker_rate: float = 0.0
+    cap_premium_fraction: float = 0.125
+    per_contract_fee: float = 0.0
+    premium_convention: Union[PremiumConvention, str] = PremiumConvention.LINEAR_QUOTE
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "premium_convention", _coerce_premium(self.premium_convention))
+        object.__setattr__(self, "fee_currency", str(self.fee_currency).upper())
+        if not self.schedule_id:
+            raise ValueError("schedule_id is required")
+        if not self.fee_currency:
+            raise ValueError("fee_currency is required")
+        if self.maker_rate < 0.0 or self.taker_rate < 0.0:
+            raise ValueError("maker_rate and taker_rate must be >= 0")
+        if self.cap_premium_fraction < 0.0:
+            raise ValueError("cap_premium_fraction must be >= 0")
+        if self.per_contract_fee < 0.0:
+            raise ValueError("per_contract_fee must be >= 0")
+
+    def rate_for(self, liquidity: LiquiditySide) -> float:
+        return self.maker_rate if liquidity is LiquiditySide.MAKER else self.taker_rate
+
+
+def deribit_inverse_fee_schedule(
+    *,
+    base_currency: str = "BTC",
+    per_contract_fee: float = 0.0003,
+    cap_premium_fraction: float = 0.125,
+) -> OptionFeeSchedule:
+    return OptionFeeSchedule(
+        schedule_id=f"deribit_{base_currency.lower()}_inverse_options_phase5",
+        fee_currency=base_currency,
+        per_contract_fee=per_contract_fee,
+        cap_premium_fraction=cap_premium_fraction,
+        premium_convention=PremiumConvention.INVERSE_BASE,
+    )
+
+
+def deribit_linear_usdc_fee_schedule(
+    *,
+    taker_rate: float = 0.0003,
+    maker_rate: float = 0.0003,
+    cap_premium_fraction: float = 0.125,
+) -> OptionFeeSchedule:
+    return OptionFeeSchedule(
+        schedule_id="deribit_linear_usdc_options_phase5",
+        fee_currency="USDC",
+        maker_rate=maker_rate,
+        taker_rate=taker_rate,
+        cap_premium_fraction=cap_premium_fraction,
+        premium_convention=PremiumConvention.LINEAR_QUOTE,
+    )
+
+
+def calculate_option_fee(
+    fill: Fill,
+    instrument: OptionInstrumentSpec,
+    schedule: OptionFeeSchedule,
+    *,
+    reference_price: float,
+) -> OptionFeeResult:
+    """
+    Calculate a per-leg capped option fee.
+
+    For inverse options the common venue-like form is a base-currency fee per
+    contract capped by a fraction of option premium. For linear options the raw
+    fee is reference notional times rate, also capped by option premium.
+    """
+    if schedule.premium_convention != instrument.premium_convention:
+        raise ValueError("fee schedule premium convention does not match instrument")
+    if schedule.fee_currency != instrument.premium_currency:
+        raise ValueError("fee schedule currency must match option premium currency in Phase 5")
+    if reference_price <= 0.0:
+        raise ValueError("reference_price must be > 0")
+    premium_notional = float(fill.qty) * float(fill.price) * float(instrument.multiplier)
+    cap = premium_notional * float(schedule.cap_premium_fraction)
+    if instrument.premium_convention is PremiumConvention.INVERSE_BASE:
+        raw_fee = float(fill.qty) * float(instrument.multiplier) * float(schedule.per_contract_fee)
+    else:
+        raw_fee = (
+            float(fill.qty)
+            * float(instrument.multiplier)
+            * float(reference_price)
+            * float(schedule.rate_for(fill.liquidity))
+        )
+    fee = min(raw_fee, cap) if schedule.cap_premium_fraction > 0.0 else raw_fee
+    return OptionFeeResult(
+        fee=float(fee),
+        currency=schedule.fee_currency,
+        raw_fee=float(raw_fee),
+        cap=float(cap),
+        capped=bool(fee < raw_fee),
+        schedule_id=schedule.schedule_id,
+    )
+
+
+def _coerce_premium(value: Union[PremiumConvention, str]) -> PremiumConvention:
+    if isinstance(value, PremiumConvention):
+        return value
+    try:
+        return PremiumConvention(str(value))
+    except ValueError as exc:
+        raise ValueError("premium_convention is invalid") from exc

quantbt/options/greeks.py

@@ -0,0 +1,173 @@
+"""
+Option Greeks with explicit units.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+from typing import Union
+
+from .pricing import (
+    black76_d1_d2,
+    black76_price,
+    normal_cdf,
+    normal_pdf,
+    _coerce_kind,
+    _non_negative_float,
+    _positive_float,
+)
+from .schema import OptionKind
+
+
+@dataclass(frozen=True)
+class OptionGreeks:
+    price: float
+    delta: float
+    gamma: float
+    vega: float
+    theta: float
+    currency: str
+    unit: str
+
+    @property
+    def vega_per_vol_point(self) -> float:
+        """Return vega for a 1 vol-point change, not a 1.0 vol change."""
+        return self.vega / 100.0
+
+
+def linear_black76_greeks(
+    forward: float,
+    strike: float,
+    time_to_expiry: float,
+    volatility: float,
+    option_kind: Union[OptionKind, str],
+    *,
+    discount: float = 1.0,
+    currency: str = "QUOTE",
+) -> OptionGreeks:
+    """Return Black-76 Greeks in quote currency per 1 underlying."""
+    kind = _coerce_kind(option_kind)
+    fwd, strike_, tau, vol, df = _validated_greek_inputs(forward, strike, time_to_expiry, volatility, discount)
+    price = black76_price(fwd, strike_, tau, vol, kind, discount=df)
+    if tau <= 0.0 or vol <= 0.0:
+        delta = df if (kind is OptionKind.CALL and fwd > strike_) else 0.0
+        if kind is OptionKind.PUT and fwd < strike_:
+            delta = -df
+        return OptionGreeks(price=price, delta=delta, gamma=0.0, vega=0.0, theta=0.0, currency=currency, unit="quote")
+    d1, _ = black76_d1_d2(fwd, strike_, tau, vol)
+    pdf = normal_pdf(d1)
+    if kind is OptionKind.CALL:
+        delta = df * normal_cdf(d1)
+    else:
+        delta = df * (normal_cdf(d1) - 1.0)
+    gamma = df * pdf / (fwd * vol * math.sqrt(tau))
+    vega = df * fwd * pdf * math.sqrt(tau)
+    theta = -0.5 * df * fwd * pdf * vol / math.sqrt(tau)
+    return OptionGreeks(
+        price=price,
+        delta=delta,
+        gamma=gamma,
+        vega=vega,
+        theta=theta,
+        currency=str(currency).upper(),
+        unit="quote",
+    )
+
+
+def inverse_black76_greeks_base(
+    forward: float,
+    strike: float,
+    time_to_expiry: float,
+    volatility: float,
+    option_kind: Union[OptionKind, str],
+    *,
+    discount: float = 1.0,
+    currency: str = "BASE",
+) -> OptionGreeks:
+    """Return inverse option Greeks in native base settlement currency."""
+    fwd = _positive_float(forward, "forward")
+    linear = linear_black76_greeks(fwd, strike, time_to_expiry, volatility, option_kind, discount=discount)
+    price = linear.price / fwd
+    delta = linear.delta / fwd - linear.price / (fwd * fwd)
+    gamma = linear.gamma / fwd - 2.0 * linear.delta / (fwd * fwd) + 2.0 * linear.price / (fwd * fwd * fwd)
+    vega = linear.vega / fwd
+    theta = linear.theta / fwd
+    return OptionGreeks(
+        price=price,
+        delta=delta,
+        gamma=gamma,
+        vega=vega,
+        theta=theta,
+        currency=str(currency).upper(),
+        unit="base",
+    )
+
+
+def inverse_black76_greeks_quote(
+    forward: float,
+    strike: float,
+    time_to_expiry: float,
+    volatility: float,
+    option_kind: Union[OptionKind, str],
+    *,
+    discount: float = 1.0,
+    currency: str = "QUOTE",
+) -> OptionGreeks:
+    """
+    Return inverse option Greeks converted to quote reporting currency.
+
+    Under the Phase 2 inverse convention, quote-reporting value equals the
+    corresponding linear Black-76 value, so Greeks match the linear Greeks.
+    """
+    return linear_black76_greeks(
+        forward,
+        strike,
+        time_to_expiry,
+        volatility,
+        option_kind,
+        discount=discount,
+        currency=currency,
+    )
+
+
+def scale_greeks_to_reporting_currency(
+    greeks: OptionGreeks,
+    conversion_rate: float,
+    *,
+    reporting_currency: str,
+    vega_per_vol_point: bool = False,
+) -> OptionGreeks:
+    """
+    Statically scale Greeks into a reporting currency.
+
+    This is a pure currency conversion helper. It does not add chain-rule delta
+    from a conversion rate that itself depends on the underlying.
+    """
+    rate = _positive_float(conversion_rate, "conversion_rate")
+    vega_scale = 0.01 if vega_per_vol_point else 1.0
+    return OptionGreeks(
+        price=greeks.price * rate,
+        delta=greeks.delta * rate,
+        gamma=greeks.gamma * rate,
+        vega=greeks.vega * rate * vega_scale,
+        theta=greeks.theta * rate,
+        currency=str(reporting_currency).upper(),
+        unit=f"{greeks.unit}_reported",
+    )
+
+
+def _validated_greek_inputs(
+    forward: float,
+    strike: float,
+    time_to_expiry: float,
+    volatility: float,
+    discount: float,
+) -> tuple[float, float, float, float, float]:
+    return (
+        _positive_float(forward, "forward"),
+        _positive_float(strike, "strike"),
+        _non_negative_float(time_to_expiry, "time_to_expiry"),
+        _non_negative_float(volatility, "volatility"),
+        _positive_float(discount, "discount"),
+    )

quantbt/options/hedging.py

@@ -0,0 +1,232 @@
+"""
+Option hedge policy primitives.
+
+Hedge accounting is intentionally explicit about ordering: hedge PnL for a
+price move is earned by the hedge quantity held before that move; rebalance
+decisions are evaluated after option package fills and Greek recomputation.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, Optional, Sequence
+
+import numpy as np
+import pandas as pd
+
+from .greeks import OptionGreeks
+from .ledger import OptionLedger
+from .schema import OptionInstrumentSpec
+
+
+class OptionHedgePolicyType(str, Enum):
+    FIXED_THRESHOLD = "fixed_threshold"
+    HYSTERESIS_BAND = "hysteresis_band"
+    TIME_BASED = "time_based"
+    REALIZED_VOL_SCALED_BAND = "realized_vol_scaled_band"
+
+
+@dataclass(frozen=True)
+class OptionHedgeConfig:
+    policy: OptionHedgePolicyType = OptionHedgePolicyType.FIXED_THRESHOLD
+    target_delta: float = 0.0
+    threshold: float = 0.05
+    enter_band: float = 0.10
+    exit_band: float = 0.03
+    rebalance_interval_ns: int = 0
+    realized_vol_window: int = 20
+    realized_vol_multiplier: float = 1.0
+    min_band: float = 0.01
+    hedge_contract_multiplier: float = 1.0
+    metadata: Dict = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "policy", _coerce_policy(self.policy))
+        if self.threshold < 0.0 or self.enter_band < 0.0 or self.exit_band < 0.0:
+            raise ValueError("threshold and bands must be >= 0")
+        if self.exit_band > self.enter_band:
+            raise ValueError("exit_band must be <= enter_band")
+        if self.rebalance_interval_ns < 0:
+            raise ValueError("rebalance_interval_ns must be >= 0")
+        if self.realized_vol_window <= 1:
+            raise ValueError("realized_vol_window must be > 1")
+        if self.realized_vol_multiplier < 0.0 or self.min_band < 0.0:
+            raise ValueError("realized_vol_multiplier and min_band must be >= 0")
+        if self.hedge_contract_multiplier <= 0.0:
+            raise ValueError("hedge_contract_multiplier must be > 0")
+
+
+@dataclass(frozen=True)
+class HedgeDecision:
+    timestamp_ns: int
+    net_option_delta: float
+    previous_hedge_qty: float
+    target_hedge_qty: float
+    trade_qty: float
+    should_rebalance: bool
+    reason: str
+    band: float
+
+
+@dataclass(frozen=True)
+class HedgePathResult:
+    hedge_report: pd.DataFrame
+    final_hedge_qty: float
+    hedge_pnl: float
+    decisions: tuple[HedgeDecision, ...]
+    metadata: Dict
+
+
+def compute_net_option_delta(
+    ledger: OptionLedger,
+    greeks_by_symbol: Dict[str, OptionGreeks],
+    instruments: Dict[str, OptionInstrumentSpec],
+) -> float:
+    """Return portfolio option delta after package fills and Greek recompute."""
+    total = 0.0
+    for symbol, position in ledger.positions.items():
+        if position.is_flat:
+            continue
+        greek = greeks_by_symbol.get(symbol)
+        instrument = instruments.get(symbol)
+        if greek is None or instrument is None:
+            raise ValueError(f"missing Greek or instrument for {symbol}")
+        total += float(position.qty) * float(greek.delta) * float(instrument.multiplier)
+    return float(total)
+
+
+def hedge_decision(
+    *,
+    timestamp_ns: int,
+    net_option_delta: float,
+    current_hedge_qty: float,
+    config: OptionHedgeConfig,
+    last_rebalance_timestamp_ns: Optional[int] = None,
+    underlying_prices: Optional[Sequence[float]] = None,
+    currently_active: bool = False,
+) -> HedgeDecision:
+    """Decide whether to rebalance the hedge after Greek recomputation."""
+    target_qty = (float(config.target_delta) - float(net_option_delta)) / float(config.hedge_contract_multiplier)
+    trade_qty = target_qty - float(current_hedge_qty)
+    band = _active_band(config, underlying_prices)
+    reason = "within_band"
+    should = False
+    abs_trade = abs(trade_qty)
+    if config.policy is OptionHedgePolicyType.FIXED_THRESHOLD:
+        should = abs_trade >= config.threshold
+        reason = "fixed_threshold" if should else reason
+    elif config.policy is OptionHedgePolicyType.HYSTERESIS_BAND:
+        threshold = config.exit_band if currently_active else config.enter_band
+        should = abs_trade >= threshold
+        reason = "hysteresis_exit_band" if currently_active and should else ("hysteresis_enter_band" if should else reason)
+        band = threshold
+    elif config.policy is OptionHedgePolicyType.TIME_BASED:
+        due = last_rebalance_timestamp_ns is None or int(timestamp_ns) - int(last_rebalance_timestamp_ns) >= config.rebalance_interval_ns
+        should = due and abs_trade > 1e-12
+        reason = "time_based_due" if should else "time_based_not_due"
+    elif config.policy is OptionHedgePolicyType.REALIZED_VOL_SCALED_BAND:
+        should = abs_trade >= band
+        reason = "realized_vol_scaled_band" if should else reason
+    return HedgeDecision(
+        timestamp_ns=int(timestamp_ns),
+        net_option_delta=float(net_option_delta),
+        previous_hedge_qty=float(current_hedge_qty),
+        target_hedge_qty=float(target_qty),
+        trade_qty=float(trade_qty if should else 0.0),
+        should_rebalance=bool(should),
+        reason=reason,
+        band=float(band),
+    )
+
+
+def run_delta_hedge_path(
+    timestamps_ns: Sequence[int],
+    underlying_prices: Sequence[float],
+    net_option_deltas: Sequence[float],
+    config: OptionHedgeConfig,
+    *,
+    initial_hedge_qty: float = 0.0,
+) -> HedgePathResult:
+    """
+    Simulate hedge PnL and rebalances over a path.
+
+    At bar `t`, PnL from `price[t-1] -> price[t]` uses the hedge quantity held
+    at `t-1`. Only after that move do we evaluate the new option delta and
+    rebalance.
+    """
+    ts = np.asarray(timestamps_ns, dtype=np.int64)
+    prices = np.asarray(underlying_prices, dtype=np.float64)
+    deltas = np.asarray(net_option_deltas, dtype=np.float64)
+    if len(ts) == 0 or len(ts) != len(prices) or len(ts) != len(deltas):
+        raise ValueError("timestamps, prices and deltas must be non-empty and equal length")
+    if bool((prices <= 0.0).any()) or bool((~np.isfinite(prices)).any()):
+        raise ValueError("underlying prices must be finite and > 0")
+    hedge_qty = float(initial_hedge_qty)
+    hedge_pnl = 0.0
+    last_rebalance_ts: Optional[int] = None
+    active = abs(hedge_qty) > 1e-12
+    rows = []
+    decisions = []
+    for i in range(len(ts)):
+        pnl = 0.0
+        if i > 0:
+            pnl = hedge_qty * (prices[i] - prices[i - 1]) * config.hedge_contract_multiplier
+            hedge_pnl += pnl
+        decision = hedge_decision(
+            timestamp_ns=int(ts[i]),
+            net_option_delta=float(deltas[i]),
+            current_hedge_qty=hedge_qty,
+            config=config,
+            last_rebalance_timestamp_ns=last_rebalance_ts,
+            underlying_prices=prices[max(0, i - config.realized_vol_window + 1) : i + 1],
+            currently_active=active,
+        )
+        if decision.should_rebalance:
+            hedge_qty += decision.trade_qty
+            last_rebalance_ts = int(ts[i])
+            active = abs(hedge_qty) > 1e-12
+        decisions.append(decision)
+        rows.append(
+            {
+                "timestamp_ns": int(ts[i]),
+                "underlying_price": float(prices[i]),
+                "prior_hedge_qty": decision.previous_hedge_qty,
+                "net_option_delta": decision.net_option_delta,
+                "hedge_pnl_for_prior_move": float(pnl),
+                "cumulative_hedge_pnl": float(hedge_pnl),
+                "target_hedge_qty": decision.target_hedge_qty,
+                "trade_qty": decision.trade_qty,
+                "hedge_qty_after": float(hedge_qty),
+                "should_rebalance": decision.should_rebalance,
+                "reason": decision.reason,
+                "band": decision.band,
+            }
+        )
+    return HedgePathResult(
+        hedge_report=pd.DataFrame(rows),
+        final_hedge_qty=float(hedge_qty),
+        hedge_pnl=float(hedge_pnl),
+        decisions=tuple(decisions),
+        metadata={"policy": config.policy.value, "hedge_contract_multiplier": config.hedge_contract_multiplier},
+    )
+
+
+def _active_band(config: OptionHedgeConfig, prices: Optional[Sequence[float]]) -> float:
+    if config.policy is not OptionHedgePolicyType.REALIZED_VOL_SCALED_BAND:
+        return float(config.threshold)
+    if prices is None or len(prices) < 2:
+        return float(config.min_band)
+    arr = np.asarray(prices, dtype=np.float64)
+    returns = np.diff(np.log(arr))
+    realized = float(np.std(returns, ddof=1)) if len(returns) > 1 else abs(float(returns[0]))
+    return max(float(config.min_band), realized * float(config.realized_vol_multiplier))
+
+
+def _coerce_policy(value) -> OptionHedgePolicyType:
+    if isinstance(value, OptionHedgePolicyType):
+        return value
+    try:
+        return OptionHedgePolicyType(str(value))
+    except ValueError as exc:
+        raise ValueError("invalid option hedge policy") from exc