bitsentry 0.1.0__py3-none-any.whl

bitsentry/bgc_client.py

@@ -0,0 +1,153 @@
+import json
+import os
+import subprocess
+from typing import Any
+
+
+class BGCError(Exception):
+    """Raised when a bgc CLI call fails."""
+
+
+class BGCClient:
+    """
+    Wraps the bgc CLI via subprocess.
+
+    demo=True appends --paper-trading to every call and requires
+    Demo API Key credentials in the environment.
+    """
+
+    def __init__(self, demo: bool = False):
+        self.demo = demo
+        self._verify_credentials()
+
+    def _verify_credentials(self) -> None:
+        missing = [
+            v for v in ("BITGET_API_KEY", "BITGET_SECRET_KEY", "BITGET_PASSPHRASE")
+            if not os.environ.get(v)
+        ]
+        if missing:
+            raise BGCError(f"Missing environment variables: {', '.join(missing)}")
+
+        # Quick connectivity check — public endpoint, no auth needed
+        try:
+            self.run("spot", "spot_get_ticker", symbol="BTCUSDT")
+            mode = "DEMO/paper-trading" if self.demo else "LIVE"
+            print(f"[bitsentry] BGCClient connected successfully ({mode})")
+        except BGCError as exc:
+            raise BGCError(f"BGCClient connection check failed: {exc}") from exc
+
+    def run(self, module: str, tool: str, **params: Any) -> Any:
+        """
+        Execute: bgc [--paper-trading] <module> <tool> [--key value ...]
+
+        Returns the parsed `data` field from the JSON response.
+        Raises BGCError on non-zero exit code or error JSON.
+        """
+        cmd = ["bgc"]
+        if self.demo:
+            cmd.append("--paper-trading")
+        cmd += [module, tool]
+        for key, value in params.items():
+            cmd += [f"--{key}", str(value)]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            env=os.environ.copy(),
+        )
+
+        raw = result.stdout.strip() or result.stderr.strip()
+
+        if result.returncode != 0:
+            # Try to parse structured error JSON from stderr
+            try:
+                payload = json.loads(result.stderr.strip())
+                msg = payload.get("error", {}).get("message", result.stderr.strip())
+                err_type = payload.get("error", {}).get("type", "Unknown")
+                raise BGCError(f"[{err_type}] {msg}")
+            except (json.JSONDecodeError, AttributeError):
+                raise BGCError(result.stderr.strip() or f"bgc exited {result.returncode}")
+
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise BGCError(f"bgc returned non-JSON output: {raw[:200]}") from exc
+
+        # Structured error inside a 200-exit response
+        if isinstance(payload, dict) and payload.get("ok") is False:
+            err = payload.get("error", {})
+            raise BGCError(f"[{err.get('type', 'Error')}] {err.get('message', 'unknown error')}")
+
+        return payload.get("data", payload)
+
+    # ── High-level convenience methods ─────────────────────────────────────
+
+    def get_ticker(self, symbol: str) -> dict:
+        """Return spot ticker data for *symbol* (e.g. 'BTCUSDT')."""
+        data = self.run("spot", "spot_get_ticker", symbol=symbol)
+        # data is a list; return the first match
+        if isinstance(data, list):
+            for item in data:
+                if item.get("symbol") == symbol:
+                    return item
+            return data[0] if data else {}
+        return data
+
+    def get_account_balance(self) -> list[dict]:
+        """
+        Return account asset balances.
+
+        Note: the Bitget demo environment does not support the
+        /api/v2/account/all-account-balance endpoint (returns 404).
+        In that case a descriptive dict is returned instead of raising.
+        """
+        try:
+            data = self.run("account", "get_account_assets")
+            return data if isinstance(data, list) else [data]
+        except BGCError as exc:
+            if "404" in str(exc) or "NOT FOUND" in str(exc):
+                return [
+                    {
+                        "warning": "account balance endpoint not available in demo environment",
+                        "detail": str(exc),
+                        "suggestion": "Use get_positions() for futures PnL or switch to a live key.",
+                    }
+                ]
+            raise
+
+    def get_positions(self, product_type: str = "USDT-FUTURES") -> list[dict]:
+        """Return open futures positions for *product_type*."""
+        data = self.run("futures", "futures_get_positions", productType=product_type)
+        return data if isinstance(data, list) else []
+
+    def get_order_history(self, symbol: str | None = None, product_type: str = "USDT-FUTURES") -> list[dict]:
+        """
+        Return recent open orders.
+
+        Fetches spot unfilled orders (symbol required) and futures
+        pending orders and combines them.
+        """
+        orders: list[dict] = []
+
+        # Spot orders — symbol required
+        if symbol:
+            try:
+                spot_data = self.run("spot", "spot_get_orders", symbol=symbol)
+                if isinstance(spot_data, list):
+                    orders.extend(spot_data)
+            except BGCError:
+                pass
+
+        # Futures pending orders
+        try:
+            futures_data = self.run("futures", "futures_get_orders", productType=product_type)
+            if isinstance(futures_data, dict):
+                entries = futures_data.get("entrustedList") or []
+                orders.extend(entries)
+            elif isinstance(futures_data, list):
+                orders.extend(futures_data)
+        except BGCError:
+            pass
+
+        return orders

bitsentry/cli.py

@@ -0,0 +1,10 @@
+def main():
+    import uvicorn
+    import os
+    from dotenv import load_dotenv
+    load_dotenv()
+    print("Starting BitSentry server on http://127.0.0.1:8000")
+    uvicorn.run("bitsentry.api.server:app", host="127.0.0.1", port=8000, reload=False)
+
+if __name__ == "__main__":
+    main()

bitsentry/mcp/__init__.py

@@ -0,0 +1,3 @@
+from bitsentry.mcp.server import mcp
+
+__all__ = ["mcp"]

bitsentry/mcp/server.py

@@ -0,0 +1,169 @@
+"""
+BitSentry MCP Server
+
+Exposes BitSentry risk, position, strategy, and audit tools
+so any MCP-compatible agent (Claude, Agent Hub, etc.) can call them.
+
+Run standalone:
+  python -m bitsentry.mcp.server
+
+Or as stdio MCP server (Claude Code config):
+  command: /opt/miniconda3/bin/python3.13 -m bitsentry.mcp.server
+"""
+from __future__ import annotations
+
+import dataclasses
+import os
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from bitsentry.audit_engine import AuditEngine
+from bitsentry.bgc_client import BGCClient, BGCError
+from bitsentry.position_monitor import PositionMonitor
+from bitsentry.risk_guardian import RiskGuardian
+from bitsentry.strategy_evaluator import StrategyEvaluator
+
+# ── Server instance ───────────────────────────────────────────────────────────
+
+mcp = FastMCP("bitsentry")
+
+# ── Component initialisation ──────────────────────────────────────────────────
+
+demo = os.environ.get("BITGET_DEMO_MODE", "true").lower() == "true"
+
+try:
+    _client = BGCClient(demo=demo)
+except BGCError as exc:
+    print(f"[bitsentry-mcp] WARNING: BGCClient init failed: {exc}")
+    _client = None
+
+_audit    = AuditEngine()
+_guardian = RiskGuardian(audit_engine=_audit)
+_monitor  = PositionMonitor(bgc_client=_client, audit_engine=_audit) if _client else None
+_evaluator = StrategyEvaluator(audit_engine=_audit)
+
+print(f"[bitsentry-mcp] Ready. demo={demo}, bgc={'ok' if _client else 'unavailable'}")
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _asdict(obj: Any) -> Any:
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return {k: _asdict(v) for k, v in dataclasses.asdict(obj).items()}
+    if isinstance(obj, list):
+        return [_asdict(i) for i in obj]
+    return obj
+
+
+# ── Tool 1: check_risk ────────────────────────────────────────────────────────
+
+@mcp.tool()
+def check_risk(
+    symbol: str,
+    side: str,
+    size_usdt: float,
+    leverage: float,
+    account_balance_usdt: float,
+    daily_pnl_usdt: float,
+    consecutive_losses: int,
+) -> dict:
+    """Check if a trade is safe to execute according to BitSentry risk rules.
+    Call this before placing any order on Bitget."""
+    result = _guardian.check(
+        symbol=symbol,
+        side=side,
+        size_usdt=size_usdt,
+        leverage=leverage,
+        account_balance_usdt=account_balance_usdt,
+        daily_pnl_usdt=daily_pnl_usdt,
+        consecutive_losses=consecutive_losses,
+    )
+    return _asdict(result)
+
+
+# ── Tool 2: get_position_safety ───────────────────────────────────────────────
+
+@mcp.tool()
+def get_position_safety() -> dict:
+    """Get safety ratings for all open Bitget positions.
+    Returns GREEN/YELLOW/RED rating for each position."""
+    if not _monitor:
+        return {"error": "PositionMonitor unavailable — BGCClient failed to initialize"}
+    positions = _monitor.get_positions()
+    summary   = _monitor.get_account_summary()
+    return {
+        "overall_safety": summary["overall_safety"],
+        "positions": _asdict(positions),
+    }
+
+
+# ── Tool 3: get_account_summary ───────────────────────────────────────────────
+
+@mcp.tool()
+def get_account_summary() -> dict:
+    """Get a summary of current account safety status including position counts
+    by safety rating."""
+    if not _monitor:
+        return {"error": "PositionMonitor unavailable — BGCClient failed to initialize"}
+    return _monitor.get_account_summary()
+
+
+# ── Tool 4: evaluate_strategy ─────────────────────────────────────────────────
+
+@mcp.tool()
+def evaluate_strategy(strategy_tag: str) -> dict:
+    """Evaluate the performance of a trading strategy.
+    Returns PERFORMING, DEGRADING, or DEAD verdict."""
+    health = _evaluator.evaluate(strategy_tag)
+    return _asdict(health)
+
+
+# ── Tool 5: record_trade ──────────────────────────────────────────────────────
+
+@mcp.tool()
+def record_trade(
+    strategy_tag: str,
+    symbol: str,
+    side: str,
+    entry_price: float,
+    exit_price: float,
+    size_usdt: float,
+    market_condition: str = "",
+) -> dict:
+    """Record a completed trade result for strategy performance tracking."""
+    trade_id = _evaluator.record_trade_result(
+        strategy_tag=strategy_tag,
+        symbol=symbol,
+        side=side,
+        entry_price=entry_price,
+        exit_price=exit_price,
+        size_usdt=size_usdt,
+        market_condition=market_condition,
+    )
+    # Re-evaluate to get updated outcome in response
+    pnl_usdt, _ = _evaluator._calc_pnl(side, entry_price, exit_price, size_usdt)
+    outcome = "WIN" if pnl_usdt > 0 else "LOSS"
+    health = _evaluator.evaluate(strategy_tag)
+    return {
+        "recorded": True,
+        "trade_id": trade_id,
+        "outcome": outcome,
+        "pnl_usdt": round(pnl_usdt, 4),
+        "strategy_verdict": health.verdict,
+        "win_rate_30d": health.win_rate_30d,
+    }
+
+
+# ── Tool 6: get_audit_report ──────────────────────────────────────────────────
+
+@mcp.tool()
+def get_audit_report() -> dict:
+    """Get the full BitSentry audit report with SHA-256 integrity hash.
+    Use this to verify all trading decisions are logged."""
+    return _audit.generate_audit_report()
+
+
+# ── Entrypoint ────────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    mcp.run()

bitsentry/position_monitor.py

@@ -0,0 +1,223 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bitsentry.audit_engine import AuditEngine
+    from bitsentry.bgc_client import BGCClient
+
+
+@dataclass
+class PositionSnapshot:
+    symbol: str
+    side: str               # "long" or "short"
+    size: float             # base-asset size
+    entry_price: float
+    mark_price: float
+    unrealized_pnl: float
+    unrealized_pnl_pct: float   # as % of margin_used
+    margin_used: float
+    leverage: int
+    safety_rating: str      # GREEN / YELLOW / RED
+    safety_message: str
+    timestamp: str
+
+
+def _safe_float(val, default: float = 0.0) -> float:
+    try:
+        return float(val)
+    except (TypeError, ValueError):
+        return default
+
+
+def _safe_int(val, default: int = 1) -> int:
+    try:
+        return int(float(val))
+    except (TypeError, ValueError):
+        return default
+
+
+class PositionMonitor:
+    """
+    Fetches live Bitget futures positions and assigns safety ratings.
+
+    Safety tiers:
+      GREEN  — unrealized_pnl_pct > -3 % AND margin_ratio ≤ 0.5
+      YELLOW — pnl_pct in [-7, -3) OR margin_ratio in (0.5, 0.8]
+      RED    — pnl_pct < -7 % OR margin_ratio > 0.8
+    """
+
+    def __init__(
+        self,
+        bgc_client: "BGCClient",
+        audit_engine: "AuditEngine | None" = None,
+        poll_interval_seconds: int = 30,
+    ):
+        self._client = bgc_client
+        self._audit = audit_engine
+        self.poll_interval_seconds = poll_interval_seconds
+
+    # ── Safety rating ────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _rate(pnl_pct: float, margin_ratio: float) -> tuple[str, str]:
+        """Return (rating, message) for a position."""
+        if pnl_pct < -7.0 or margin_ratio > 0.8:
+            if pnl_pct < -7.0:
+                msg = f"Unrealized loss {pnl_pct:.2f}% exceeds 7% danger threshold"
+            else:
+                msg = f"Margin ratio {margin_ratio:.2f} exceeds 0.80 — liquidation risk"
+            return "RED", msg
+
+        if pnl_pct < -3.0 or margin_ratio > 0.5:
+            if pnl_pct < -3.0:
+                msg = f"Unrealized loss {pnl_pct:.2f}% in caution zone (-3% to -7%)"
+            else:
+                msg = f"Margin ratio {margin_ratio:.2f} elevated (above 0.50)"
+            return "YELLOW", msg
+
+        return "GREEN", f"Position healthy: PnL {pnl_pct:.2f}%, margin ratio {margin_ratio:.2f}"
+
+    # ── Position parsing ─────────────────────────────────────────────────────
+
+    def _parse(self, raw: dict) -> PositionSnapshot:
+        """
+        Convert a raw Bitget v2 position dict into a PositionSnapshot.
+
+        Bitget v2 field names for /api/v2/mix/position/all-position:
+          holdSide, total, openPriceAvg, markPrice, unrealizedPL,
+          marginSize, leverage, marginRatio
+        """
+        symbol = raw.get("symbol", "UNKNOWN")
+        side = raw.get("holdSide", "unknown")
+
+        size = _safe_float(raw.get("total", raw.get("size", 0)))
+        entry_price = _safe_float(raw.get("openPriceAvg", raw.get("openPrice", 0)))
+        mark_price = _safe_float(raw.get("markPrice", entry_price))
+        unrealized_pnl = _safe_float(raw.get("unrealizedPL", raw.get("unrealisedPnl", 0)))
+        margin_used = _safe_float(raw.get("marginSize", raw.get("margin", 0)))
+        leverage = _safe_int(raw.get("leverage", 1))
+
+        # PnL as % of margin_used — avoids division-by-zero
+        pnl_pct = (unrealized_pnl / margin_used * 100) if margin_used > 0 else 0.0
+
+        # Bitget may supply marginRatio directly; otherwise estimate from keepMarginRate
+        margin_ratio = _safe_float(
+            raw.get("marginRatio", raw.get("keepMarginRate", 0.0))
+        )
+
+        rating, message = self._rate(pnl_pct, margin_ratio)
+
+        return PositionSnapshot(
+            symbol=symbol,
+            side=side,
+            size=size,
+            entry_price=entry_price,
+            mark_price=mark_price,
+            unrealized_pnl=unrealized_pnl,
+            unrealized_pnl_pct=round(pnl_pct, 4),
+            margin_used=margin_used,
+            leverage=leverage,
+            safety_rating=rating,
+            safety_message=message,
+            timestamp=datetime.now(timezone.utc).isoformat(),
+        )
+
+    # ── Public API ───────────────────────────────────────────────────────────
+
+    def get_positions(self, product_type: str = "USDT-FUTURES") -> list[PositionSnapshot]:
+        """Fetch all open futures positions and return rated snapshots."""
+        raw_list = self._client.get_positions(product_type=product_type)
+        snapshots = [self._parse(r) for r in raw_list]
+
+        if self._audit and snapshots:
+            for snap in snapshots:
+                self._audit.log_risk_check(
+                    symbol=snap.symbol,
+                    layer_name="position_monitor",
+                    passed=snap.safety_rating != "RED",
+                    reason=snap.safety_message,
+                    value_checked=snap.unrealized_pnl_pct,
+                    threshold=-7.0,
+                )
+
+        return snapshots
+
+    def get_account_summary(self, product_type: str = "USDT-FUTURES") -> dict:
+        """Return aggregate safety summary across all open positions."""
+        positions = self.get_positions(product_type=product_type)
+
+        counts = {"GREEN": 0, "YELLOW": 0, "RED": 0}
+        total_pnl = 0.0
+        for p in positions:
+            counts[p.safety_rating] += 1
+            total_pnl += p.unrealized_pnl
+
+        # Worst-of-all: RED > YELLOW > GREEN
+        if counts["RED"] > 0:
+            overall = "RED"
+        elif counts["YELLOW"] > 0:
+            overall = "YELLOW"
+        else:
+            overall = "GREEN"
+
+        return {
+            "total_positions": len(positions),
+            "green_count": counts["GREEN"],
+            "yellow_count": counts["YELLOW"],
+            "red_count": counts["RED"],
+            "overall_safety": overall,
+            "total_unrealized_pnl": round(total_pnl, 4),
+        }
+
+    def get_safe_to_trade(self, symbol: str, direction: str) -> dict:
+        """
+        Check whether opening a new position on *symbol* is safe.
+
+        Returns:
+          safe: bool
+          reason: str
+          current_exposure: float  (total margin in open positions for symbol)
+        """
+        positions = self.get_positions()
+
+        symbol_positions = [p for p in positions if p.symbol == symbol]
+        current_exposure = sum(p.margin_used for p in symbol_positions)
+
+        # Block if there is already a RED-rated position on the same symbol
+        red_positions = [p for p in symbol_positions if p.safety_rating == "RED"]
+        if red_positions:
+            return {
+                "safe": False,
+                "reason": (
+                    f"{symbol} already has a RED-rated position — "
+                    "resolve it before adding more exposure"
+                ),
+                "current_exposure": current_exposure,
+            }
+
+        # Block if opening in the same direction as an existing position with negative PnL
+        same_side = [
+            p for p in symbol_positions
+            if p.side == direction and p.unrealized_pnl_pct < -3.0
+        ]
+        if same_side:
+            return {
+                "safe": False,
+                "reason": (
+                    f"Existing {direction} position on {symbol} is down "
+                    f"{same_side[0].unrealized_pnl_pct:.2f}% — averaging down blocked"
+                ),
+                "current_exposure": current_exposure,
+            }
+
+        return {
+            "safe": True,
+            "reason": (
+                f"No blocking positions on {symbol}. "
+                f"Current {symbol} exposure: ${current_exposure:.2f}"
+            ),
+            "current_exposure": current_exposure,
+        }