Skip to content

"Vibe-Trading: Your Personal Trading Agent"

feat(backtest): add USD-M account reconciliation contracts

zygora9c2975396bb3
diff --git a/agent/backtest/binance_account_reconciliation.py b/agent/backtest/binance_account_reconciliation.py
new file mode 100644
index 000000000..df7bfc80c
--- /dev/null
+++ b/agent/backtest/binance_account_reconciliation.py
@@ -0,0 +1,347 @@
+"""Pure comparison of Binance USD-M observations with local risk state.
+
+This module is deliberately offline. It owns no connector, credential, file,
+or network path, and an exchange observation never becomes an accounting input.
+The comparison covers reported account and position fields only; it does not
+validate Binance liquidation sequencing.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import re
+from typing import Literal
+
+import pandas as pd
+
+from backtest.perpetual_risk import AccountState, PositionRisk, PositionState, RiskSnapshot
+
+
+SnapshotStatus = Literal["complete", "incomplete", "unsupported"]
+ComparisonStatus = Literal["comparison_complete"]
+_CANONICAL_USDM_SYMBOL = re.compile(r"^[A-Z0-9]+-USDT-PERP$")
+
+
+def _require_finite(name: str, value: float, *, non_negative: bool = False) -> None:
+ if not math.isfinite(value):
+ raise ValueError(f"{name} must be finite")
+ if non_negative and value < 0:
+ raise ValueError(f"{name} must be non-negative")
+
+
+def _require_utc_timestamp(value: pd.Timestamp, name: str) -> pd.Timestamp:
+ if not isinstance(value, pd.Timestamp) or pd.isna(value) or value.tzinfo is None:
+ raise ValueError(f"{name} must be a timezone-aware pandas Timestamp")
+ return value.tz_convert("UTC")
+
+
+@dataclass(frozen=True)
+class BinancePositionSnapshot:
+ """One normalized USD-M position reported by the exchange read layer."""
+
+ symbol: str
+ quantity: float
+ entry_price: float
+ leverage: float
+ margin_mode: Literal["isolated", "cross"]
+ isolated_margin: float | None
+ unrealized_pnl: float
+ initial_margin: float
+ maintenance_margin: float
+
+ def __post_init__(self) -> None:
+ if not _CANONICAL_USDM_SYMBOL.fullmatch(self.symbol):
+ raise ValueError("symbol must use canonical *-USDT-PERP form")
+ _require_finite("quantity", self.quantity)
+ if self.quantity == 0:
+ raise ValueError("quantity must be non-zero")
+ _require_finite("entry_price", self.entry_price)
+ if self.entry_price <= 0:
+ raise ValueError("entry_price must be positive")
+ _require_finite("leverage", self.leverage)
+ if self.leverage <= 0:
+ raise ValueError("leverage must be positive")
+ if self.margin_mode not in {"isolated", "cross"}:
+ raise ValueError("margin_mode must be 'isolated' or 'cross'")
+ if self.margin_mode == "isolated":
+ if self.isolated_margin is None:
+ raise ValueError("isolated positions require isolated_margin")
+ _require_finite("isolated_margin", self.isolated_margin)
+ if self.isolated_margin <= 0:
+ raise ValueError("isolated_margin must be positive")
+ elif self.isolated_margin is not None:
+ raise ValueError("cross positions must not have isolated_margin")
+ _require_finite("unrealized_pnl", self.unrealized_pnl)
+ _require_finite("initial_margin", self.initial_margin, non_negative=True)
+ _require_finite("maintenance_margin", self.maintenance_margin, non_negative=True)
+
+
+@dataclass(frozen=True)
+class BinanceAccountSnapshot:
+ """Immutable, normalized evidence from a Binance USD-M account read."""
+
+ schema_version: str
+ observed_at: pd.Timestamp
+ source: str
+ source_profile: str
+ configuration_hash: str
+ data_status: SnapshotStatus
+ wallet_balance: float
+ margin_balance: float
+ available_balance: float
+ total_unrealized_pnl: float
+ total_initial_margin: float
+ total_maintenance_margin: float
+ positions: tuple[BinancePositionSnapshot, ...]
+ fidelity_flags: tuple[str, ...] = ()
+
+ def __post_init__(self) -> None:
+ if not self.schema_version:
+ raise ValueError("schema_version must not be empty")
+ _require_utc_timestamp(self.observed_at, "observed_at")
+ if self.source != "binance-usdm":
+ raise ValueError("source must be 'binance-usdm'")
+ if not self.source_profile:
+ raise ValueError("source_profile must not be empty")
+ if not self.configuration_hash:
+ raise ValueError("configuration_hash must not be empty")
+ if self.data_status not in {"complete", "incomplete", "unsupported"}:
+ raise ValueError("unsupported data_status")
+ for name in (
+ "wallet_balance",
+ "margin_balance",
+ "available_balance",
+ "total_unrealized_pnl",
+ ):
+ _require_finite(name, getattr(self, name))
+ _require_finite("total_initial_margin", self.total_initial_margin, non_negative=True)
+ _require_finite(
+ "total_maintenance_margin",
+ self.total_maintenance_margin,
+ non_negative=True,
+ )
+ symbols = tuple(position.symbol for position in self.positions)
+ if len(symbols) != len(set(symbols)):
+ raise ValueError("duplicate position symbol")
+ if any(not flag for flag in self.fidelity_flags):
+ raise ValueError("fidelity flags must not be empty")
+ if len(self.fidelity_flags) != len(set(self.fidelity_flags)):
+ raise ValueError("fidelity flags must be unique")
+
+
+@dataclass(frozen=True)
+class ReconciliationTolerance:
+ """Versioned numeric and timestamp tolerances for one comparison."""
+
+ absolute: float = 1e-8
+ relative: float = 1e-8
+ max_timestamp_skew_seconds: float = 0.0
+ version: str = "reconciliation-tolerance-v1"
+
+ def __post_init__(self) -> None:
+ for name in ("absolute", "relative", "max_timestamp_skew_seconds"):
+ _require_finite(name, getattr(self, name), non_negative=True)
+ if not self.version:
+ raise ValueError("tolerance version must not be empty")
+
+
+@dataclass(frozen=True)
+class NumericComparison:
+ """One deterministic local-versus-exchange numeric comparison."""
+
+ field: str
+ local_value: float
+ exchange_value: float
+ absolute_delta: float
+ allowed_delta: float
+ within_tolerance: bool
+ symbol: str | None = None
+
+
+@dataclass(frozen=True)
+class ReconciliationReport:
+ """Comparison evidence; never an exchange-engine validation verdict."""
+
+ status: ComparisonStatus
+ has_drift: bool
+ observed_at: pd.Timestamp
+ source: str
+ source_profile: str
+ snapshot_schema_version: str
+ snapshot_configuration_hash: str
+ tolerance_version: str
+ comparisons: tuple[NumericComparison, ...]
+ missing_on_exchange: tuple[str, ...]
+ unexpected_on_exchange: tuple[str, ...]
+ structural_differences: tuple[str, ...]
+ fidelity_flags: tuple[str, ...]
+ comparison_scope: Literal["account_snapshot_fields_only"] = "account_snapshot_fields_only"
+ liquidation_engine_assessment: Literal["not_assessed"] = "not_assessed"
+
+
+def _comparison(
+ field: str,
+ local_value: float,
+ exchange_value: float,
+ tolerance: ReconciliationTolerance,
+ *,
+ symbol: str | None = None,
+) -> NumericComparison:
+ absolute_delta = abs(local_value - exchange_value)
+ allowed_delta = max(
+ tolerance.absolute,
+ tolerance.relative * max(abs(local_value), abs(exchange_value)),
+ )
+ return NumericComparison(
+ field=field,
+ local_value=local_value,
+ exchange_value=exchange_value,
+ absolute_delta=absolute_delta,
+ allowed_delta=allowed_delta,
+ within_tolerance=absolute_delta <= allowed_delta,
+ symbol=symbol,
+ )
+
+
+def _position_maps(
+ account: AccountState,
+ risk: RiskSnapshot,
+ exchange: BinanceAccountSnapshot,
+) -> tuple[
+ dict[str, PositionState],
+ dict[str, PositionRisk],
+ dict[str, BinancePositionSnapshot],
+]:
+ local_positions = {position.symbol: position for position in account.positions}
+ local_risks = {position.symbol: position for position in risk.per_position}
+ if set(local_positions) != set(local_risks):
+ raise ValueError("local account and risk snapshot symbols must match")
+ exchange_positions = {position.symbol: position for position in exchange.positions}
+ return local_positions, local_risks, exchange_positions
+
+
+def reconcile_binance_account(
+ local_account: AccountState,
+ local_risk: RiskSnapshot,
+ exchange_snapshot: BinanceAccountSnapshot,
+ *,
+ expected_timestamp: pd.Timestamp,
+ tolerance: ReconciliationTolerance = ReconciliationTolerance(),
+) -> ReconciliationReport:
+ """Compare immutable local state with one complete USD-M observation.
+
+ Raises:
+ ValueError: If the source is incomplete, timestamps are incoherent, or
+ the local account and risk snapshot do not describe the same symbols.
+ """
+ if exchange_snapshot.data_status != "complete":
+ raise ValueError("exchange snapshot data_status must be complete")
+ expected = _require_utc_timestamp(expected_timestamp, "expected_timestamp")
+ observed = _require_utc_timestamp(exchange_snapshot.observed_at, "observed_at")
+ skew = abs((observed - expected).total_seconds())
+ if skew > tolerance.max_timestamp_skew_seconds:
+ raise ValueError("exchange snapshot timestamp skew exceeds tolerance")
+
+ local_positions, local_risks, exchange_positions = _position_maps(local_account, local_risk, exchange_snapshot)
+ local_symbols = set(local_positions)
+ exchange_symbols = set(exchange_positions)
+ missing = tuple(sorted(local_symbols - exchange_symbols))
+ unexpected = tuple(sorted(exchange_symbols - local_symbols))
+ shared = tuple(sorted(local_symbols & exchange_symbols))
+
+ account_values = (
+ ("wallet_balance", local_account.wallet_balance, exchange_snapshot.wallet_balance),
+ ("margin_balance", local_risk.margin_balance, exchange_snapshot.margin_balance),
+ ("available_balance", local_risk.available_balance, exchange_snapshot.available_balance),
+ (
+ "total_unrealized_pnl",
+ sum(position.unrealized_pnl for position in local_risk.per_position),
+ exchange_snapshot.total_unrealized_pnl,
+ ),
+ ("total_initial_margin", local_risk.initial_margin, exchange_snapshot.total_initial_margin),
+ (
+ "total_maintenance_margin",
+ local_risk.maintenance_margin,
+ exchange_snapshot.total_maintenance_margin,
+ ),
+ )
+ comparisons = [_comparison(field, local, exchange, tolerance) for field, local, exchange in account_values]
+ structural: list[str] = []
+ for symbol in shared:
+ local_position = local_positions[symbol]
+ local_position_risk = local_risks[symbol]
+ exchange_position = exchange_positions[symbol]
+ if local_account.margin_mode != exchange_position.margin_mode:
+ structural.append(
+ f"{symbol}:margin_mode:local={local_account.margin_mode}:exchange={exchange_position.margin_mode}"
+ )
+ local_isolated = local_position.isolated_margin
+ exchange_isolated = exchange_position.isolated_margin
+ if (local_isolated is None) != (exchange_isolated is None):
+ structural.append(f"{symbol}:isolated_margin_presence")
+ elif local_isolated is not None and exchange_isolated is not None:
+ comparisons.append(
+ _comparison(
+ "isolated_margin",
+ local_isolated,
+ exchange_isolated,
+ tolerance,
+ symbol=symbol,
+ )
+ )
+ position_values = (
+ ("quantity", local_position.quantity, exchange_position.quantity),
+ ("entry_price", local_position.entry_price, exchange_position.entry_price),
+ ("leverage", local_position.leverage, exchange_position.leverage),
+ ("unrealized_pnl", local_position_risk.unrealized_pnl, exchange_position.unrealized_pnl),
+ ("initial_margin", local_position_risk.initial_margin, exchange_position.initial_margin),
+ (
+ "maintenance_margin",
+ local_position_risk.maintenance_margin,
+ exchange_position.maintenance_margin,
+ ),
+ )
+ for field, local, exchange in position_values:
+ comparisons.append(
+ _comparison(
+ field,
+ float(local),
+ float(exchange),
+ tolerance,
+ symbol=symbol,
+ )
+ )
+
+ ordered_comparisons = tuple(comparisons)
+ structural_differences = tuple(structural)
+ has_drift = bool(
+ missing
+ or unexpected
+ or structural_differences
+ or any(not item.within_tolerance for item in ordered_comparisons)
+ )
+ fidelity_flags = tuple(
+ dict.fromkeys(
+ (
+ *local_risk.fidelity_flags,
+ *exchange_snapshot.fidelity_flags,
+ "account_snapshot_comparison_only",
+ )
+ )
+ )
+ return ReconciliationReport(
+ status="comparison_complete",
+ has_drift=has_drift,
+ observed_at=observed,
+ source=exchange_snapshot.source,
+ source_profile=exchange_snapshot.source_profile,
+ snapshot_schema_version=exchange_snapshot.schema_version,
+ snapshot_configuration_hash=exchange_snapshot.configuration_hash,
+ tolerance_version=tolerance.version,
+ comparisons=ordered_comparisons,
+ missing_on_exchange=missing,
+ unexpected_on_exchange=unexpected,
+ structural_differences=structural_differences,
+ fidelity_flags=fidelity_flags,
+ )
diff --git a/agent/tests/test_binance_account_reconciliation.py b/agent/tests/test_binance_account_reconciliation.py
new file mode 100644
index 000000000..f235bf0db
--- /dev/null
+++ b/agent/tests/test_binance_account_reconciliation.py
@@ -0,0 +1,228 @@
+"""Offline contracts and reconciliation for Binance USD-M account observations."""
+
+from __future__ import annotations
+
+import ast
+from dataclasses import FrozenInstanceError
+import inspect
+
+import pandas as pd
+import pytest
+
+import backtest.binance_account_reconciliation as reconciliation_module
+from backtest.binance_account_reconciliation import (
+ BinanceAccountSnapshot,
+ BinancePositionSnapshot,
+ ReconciliationTolerance,
+ reconcile_binance_account,
+)
+from backtest.perpetual_risk import (
+ AccountState,
+ PositionRisk,
+ PositionState,
+ RiskSnapshot,
+)
+
+
+OBSERVED_AT = pd.Timestamp("2026-08-15T08:00:00Z")
+
+
+def _local_cross() -> tuple[AccountState, RiskSnapshot]:
+ position = PositionState("BTC-USDT-PERP", 0.1, 60_000.0, 10.0, 3.0, None)
+ account = AccountState(1_000.0, (position,), "cross")
+ risk = PositionRisk("BTC-USDT-PERP", 61_000.0, 6_100.0, 100.0, 610.0, 24.4, None)
+ return account, RiskSnapshot(1_100.0, 610.0, 24.4, 490.0, (risk,), "healthy", (), ())
+
+
+def _exchange_cross(**changes: object) -> BinanceAccountSnapshot:
+ values: dict[str, object] = {
+ "schema_version": "binance-usdm-account-snapshot-v1",
+ "observed_at": OBSERVED_AT,
+ "source": "binance-usdm",
+ "source_profile": "fixture-readonly",
+ "configuration_hash": "synthetic-config-v1",
+ "data_status": "complete",
+ "wallet_balance": 1_000.0,
+ "margin_balance": 1_100.0,
+ "available_balance": 490.0,
+ "total_unrealized_pnl": 100.0,
+ "total_initial_margin": 610.0,
+ "total_maintenance_margin": 24.4,
+ "positions": (
+ BinancePositionSnapshot(
+ symbol="BTC-USDT-PERP",
+ quantity=0.1,
+ entry_price=60_000.0,
+ leverage=10.0,
+ margin_mode="cross",
+ isolated_margin=None,
+ unrealized_pnl=100.0,
+ initial_margin=610.0,
+ maintenance_margin=24.4,
+ ),
+ ),
+ "fidelity_flags": ("synthetic_fixture",),
+ }
+ values.update(changes)
+ return BinanceAccountSnapshot(**values) # type: ignore[arg-type]
+
+
+def test_snapshot_contracts_are_frozen_and_reject_spot_sources() -> None:
+ snapshot = _exchange_cross()
+
+ with pytest.raises(FrozenInstanceError):
+ snapshot.wallet_balance = 0.0 # type: ignore[misc]
+ with pytest.raises(ValueError, match="source must be 'binance-usdm'"):
+ _exchange_cross(source="binance-spot")
+ with pytest.raises(ValueError, match="canonical .*USDT-PERP"):
+ _exchange_cross(
+ positions=(BinancePositionSnapshot("BTC", 0.1, 60_000.0, 10.0, "cross", None, 100.0, 610.0, 24.4),)
+ )
+
+
+def test_matching_snapshot_completes_comparison_without_validation_claim() -> None:
+ account, risk = _local_cross()
+
+ report = reconcile_binance_account(
+ account,
+ risk,
+ _exchange_cross(),
+ expected_timestamp=OBSERVED_AT,
+ )
+
+ assert report.status == "comparison_complete"
+ assert report.has_drift is False
+ assert report.source == "binance-usdm"
+ assert report.source_profile == "fixture-readonly"
+ assert report.snapshot_schema_version == "binance-usdm-account-snapshot-v1"
+ assert report.snapshot_configuration_hash == "synthetic-config-v1"
+ assert report.liquidation_engine_assessment == "not_assessed"
+ assert report.comparison_scope == "account_snapshot_fields_only"
+ assert report.missing_on_exchange == ()
+ assert report.unexpected_on_exchange == ()
+ assert report.structural_differences == ()
+ assert all(item.within_tolerance for item in report.comparisons)
+ assert "account_snapshot_comparison_only" in report.fidelity_flags
+
+
+def test_matching_isolated_snapshot_compares_position_collateral() -> None:
+ position = PositionState("BTC-USDT-PERP", 0.1, 60_000.0, 10.0, 3.0, 700.0)
+ account = AccountState(1_000.0, (position,), "isolated")
+ position_risk = PositionRisk("BTC-USDT-PERP", 61_000.0, 6_100.0, 100.0, 610.0, 24.4, 800.0)
+ risk = RiskSnapshot(1_100.0, 610.0, 24.4, 490.0, (position_risk,), "healthy", (), ())
+ exchange_position = BinancePositionSnapshot(
+ "BTC-USDT-PERP", 0.1, 60_000.0, 10.0, "isolated", 700.0, 100.0, 610.0, 24.4
+ )
+
+ report = reconcile_binance_account(
+ account,
+ risk,
+ _exchange_cross(positions=(exchange_position,)),
+ expected_timestamp=OBSERVED_AT,
+ )
+
+ isolated = next(item for item in report.comparisons if item.field == "isolated_margin")
+ assert isolated.within_tolerance is True
+ assert report.has_drift is False
+
+
+def test_reconciliation_reports_numeric_structural_and_symbol_drift() -> None:
+ account, risk = _local_cross()
+ eth = BinancePositionSnapshot("ETH-USDT-PERP", -1.0, 3_000.0, 5.0, "isolated", 600.0, 0.0, 600.0, 12.0)
+ exchange = _exchange_cross(
+ wallet_balance=999.0,
+ positions=(
+ BinancePositionSnapshot(
+ "BTC-USDT-PERP",
+ 0.2,
+ 60_000.0,
+ 10.0,
+ "isolated",
+ 610.0,
+ 100.0,
+ 610.0,
+ 24.4,
+ ),
+ eth,
+ ),
+ )
+
+ report = reconcile_binance_account(
+ account,
+ risk,
+ exchange,
+ expected_timestamp=OBSERVED_AT,
+ tolerance=ReconciliationTolerance(absolute=0.01, relative=0.0),
+ )
+
+ assert report.has_drift is True
+ assert report.unexpected_on_exchange == ("ETH-USDT-PERP",)
+ assert report.missing_on_exchange == ()
+ assert report.structural_differences == (
+ "BTC-USDT-PERP:margin_mode:local=cross:exchange=isolated",
+ "BTC-USDT-PERP:isolated_margin_presence",
+ )
+ drifted = {(item.symbol, item.field) for item in report.comparisons if not item.within_tolerance}
+ assert (None, "wallet_balance") in drifted
+ assert ("BTC-USDT-PERP", "quantity") in drifted
+
+ missing = reconcile_binance_account(
+ account,
+ risk,
+ _exchange_cross(positions=()),
+ expected_timestamp=OBSERVED_AT,
+ )
+ assert missing.missing_on_exchange == ("BTC-USDT-PERP",)
+ assert missing.has_drift is True
+
+
+ ("snapshot", "expected_timestamp", "match"),
+ [
+ (_exchange_cross(data_status="incomplete"), OBSERVED_AT, "data_status"),
+ (
+ _exchange_cross(),
+ pd.Timestamp("2026-08-15T08:00:02Z"),
+ "timestamp skew",
+ ),
+ ],
+)
+def test_reconciliation_fails_closed_on_incomplete_or_stale_observations(
+ snapshot: BinanceAccountSnapshot,
+ expected_timestamp: pd.Timestamp,
+ match: str,
+) -> None:
+ account, risk = _local_cross()
+
+ with pytest.raises(ValueError, match=match):
+ reconcile_binance_account(
+ account,
+ risk,
+ snapshot,
+ expected_timestamp=expected_timestamp,
+ tolerance=ReconciliationTolerance(max_timestamp_skew_seconds=1.0),
+ )
+
+
+def test_reconciliation_is_read_only_and_module_cannot_reach_live_connectors() -> None:
+ account, risk = _local_cross()
+ before = (account, risk)
+
+ reconcile_binance_account(account, risk, _exchange_cross(), expected_timestamp=OBSERVED_AT)
+
+ assert (account, risk) == before
+ tree = ast.parse(inspect.getsource(reconciliation_module))
+ forbidden_imports = ("src.live", "src.trading", "backtest.engines")
+ for node in ast.walk(tree):
+ if isinstance(node, ast.Import):
+ assert not any(alias.name.startswith(forbidden_imports) for alias in node.names)
+ if isinstance(node, ast.ImportFrom) and node.module:
+ assert not node.module.startswith(forbidden_imports)
+ if isinstance(node, (ast.Assign, ast.AnnAssign, ast.AugAssign)):
+ targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+ assert not any(isinstance(target, (ast.Attribute, ast.Subscript)) for target in targets)
+ if isinstance(node, ast.Call):
+ name = node.func.id if isinstance(node.func, ast.Name) else None
+ attr = node.func.attr if isinstance(node.func, ast.Attribute) else None
+ assert name not in {"setattr", "delattr", "exec", "eval", "__import__"}
+ assert attr != "__setattr__"