nirium 0.9.2__tar.gz → 0.11.0__tar.gz

{nirium-0.9.2 → nirium-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nirium
-Version: 0.9.2
+Version: 0.11.0
 Summary: Autonomous treasury and agentic-payments infrastructure for Stellar (x402 + MPP) — Python client
 Author: Nirium Team
 Author-email: Nirium Protocol <niriumprotocol@gmail.com>
@@ -15,6 +15,12 @@ Description-Content-Type: text/markdown
 Requires-Dist: aiohttp>=3.9.0
 Requires-Dist: websockets>=13.0
 Requires-Dist: stellar-sdk<16.0.0,>=11.0.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3.0; extra == "langchain"
+Provides-Extra: test
+Requires-Dist: pytest>=8.0.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Requires-Dist: langchain-core>=0.3.0; extra == "test"
 Dynamic: author
 Dynamic: requires-python
 
@@ -50,7 +56,9 @@ async def main():
     market = await agent.get_market()
     print(f"XLM Price: ${market['xlmPrice']:.4f}")
 
-    # Execute a treasury rebalance strategy
+    # Trigger a demo strategy on Nirium's own shared testnet vault — a real,
+    # working transaction, not a simulation, but it moves Nirium's testnet
+    # funds, not yours. To rebalance YOUR OWN vault, see Treasury Rebalance below.
     result = await agent.execute("blend-yield", "USDC", {"amount": 5000})
     print(f"Success: {result['success']} | TX: {result.get('txHash')}")
 
@@ -130,6 +138,33 @@ Licensed for **independent service payments only** — contractors, freelancers,
 
 Mainnet is invite-only during early access and additionally requires `client_info`.
 
+## Treasury Rebalance
+
+Two ways to rebalance a DeFindex vault between idle cash and an invested strategy. Neither is a swap — the contract's `rebalance()` exposes exactly two instructions, `Unwind` and `Invest`, and neither accepts a destination address, so withdrawing anywhere but back into the vault itself is not expressible.
+
+### Propose — you review and sign, available to everyone today
+
+The agent decides what it would do, using the same decision logic as the autonomous signer below, but it never signs. Public, no allowlist, no invite required — works for any vault where you're already the on-chain rebalance manager.
+
+```python
+proposal = await agent.propose_treasury_rebalance(
+    vault="CABC...",
+    caller="GABC...",   # must already be this vault's rebalanceManager on-chain
+    enter_at=2.5,        # your own mandate — Nirium never supplies a default here
+    exit_at=2.0,
+)
+
+if proposal["instructions"]:
+    signed_xdr = sign_with_your_wallet(proposal["xdr"])
+    await agent.submit_treasury_tx(signed_xdr)
+else:
+    print("Nothing to propose:", proposal["reason"])
+```
+
+### Autonomous — Nirium signs, invite-only during legal review
+
+`execute_treasury_rebalance()` has Nirium sign and submit with its own RebalanceManager key — full autonomy, no per-cycle approval. **This is invite-only while a specific legal question stays open**: whether executing on a client's behalf without taking custody still counts as regulated facilitation under Mexican law. It only runs against vaults explicitly allowlisted server-side; calling it against any other vault returns 403, and Nirium's mainnet infrastructure returns 501 for it entirely, since that box holds no signing key by design. Ask if you want autonomous execution today — otherwise, `propose_treasury_rebalance()` above gives you the same decision-making with you as the one who signs.
+
 ## Audit Trail
 
 Anchor evidence to IPFS and get back a CID — an integrity seal, not notarization.
@@ -159,6 +194,7 @@ Anchor a **hash** rather than the data itself: IPFS content cannot be deleted, s
 | Revenue | `get_revenue()`, `get_info()` |
 | Nodes | `get_nodes()` |
 | Payouts | `create_payout_run()`, `submit_payout()`, `onboard_payout_recipient()`, `submit_payout_onboard()`, `get_payout_runs()`, `get_payout_terms()`, `get_payout_info()` |
+| Treasury | `get_treasury_info()`, `get_treasury_vault()`, `get_treasury_vaults()`, `get_treasury_strategy_asset()`, `deploy_treasury_vault()`, `deposit_to_treasury_vault()`, `withdraw_from_treasury_vault()`, `set_treasury_rebalance_manager()`, `build_treasury_rebalance()`, `propose_treasury_rebalance()`, `execute_treasury_rebalance()`, `submit_treasury_tx()` |
 | Audit Trail | `anchor_audit_record()`, `get_audit_info()` |
 | Reporting | `get_reporting_summary()`, `get_reporting_export()` |
 | Admin | `configure_llm()` |

{nirium-0.9.2 → nirium-0.11.0}/README.md

@@ -30,7 +30,9 @@ async def main():
     market = await agent.get_market()
     print(f"XLM Price: ${market['xlmPrice']:.4f}")
 
-    # Execute a treasury rebalance strategy
+    # Trigger a demo strategy on Nirium's own shared testnet vault — a real,
+    # working transaction, not a simulation, but it moves Nirium's testnet
+    # funds, not yours. To rebalance YOUR OWN vault, see Treasury Rebalance below.
     result = await agent.execute("blend-yield", "USDC", {"amount": 5000})
     print(f"Success: {result['success']} | TX: {result.get('txHash')}")
 
@@ -110,6 +112,33 @@ Licensed for **independent service payments only** — contractors, freelancers,
 
 Mainnet is invite-only during early access and additionally requires `client_info`.
 
+## Treasury Rebalance
+
+Two ways to rebalance a DeFindex vault between idle cash and an invested strategy. Neither is a swap — the contract's `rebalance()` exposes exactly two instructions, `Unwind` and `Invest`, and neither accepts a destination address, so withdrawing anywhere but back into the vault itself is not expressible.
+
+### Propose — you review and sign, available to everyone today
+
+The agent decides what it would do, using the same decision logic as the autonomous signer below, but it never signs. Public, no allowlist, no invite required — works for any vault where you're already the on-chain rebalance manager.
+
+```python
+proposal = await agent.propose_treasury_rebalance(
+    vault="CABC...",
+    caller="GABC...",   # must already be this vault's rebalanceManager on-chain
+    enter_at=2.5,        # your own mandate — Nirium never supplies a default here
+    exit_at=2.0,
+)
+
+if proposal["instructions"]:
+    signed_xdr = sign_with_your_wallet(proposal["xdr"])
+    await agent.submit_treasury_tx(signed_xdr)
+else:
+    print("Nothing to propose:", proposal["reason"])
+```
+
+### Autonomous — Nirium signs, invite-only during legal review
+
+`execute_treasury_rebalance()` has Nirium sign and submit with its own RebalanceManager key — full autonomy, no per-cycle approval. **This is invite-only while a specific legal question stays open**: whether executing on a client's behalf without taking custody still counts as regulated facilitation under Mexican law. It only runs against vaults explicitly allowlisted server-side; calling it against any other vault returns 403, and Nirium's mainnet infrastructure returns 501 for it entirely, since that box holds no signing key by design. Ask if you want autonomous execution today — otherwise, `propose_treasury_rebalance()` above gives you the same decision-making with you as the one who signs.
+
 ## Audit Trail
 
 Anchor evidence to IPFS and get back a CID — an integrity seal, not notarization.
@@ -139,6 +168,7 @@ Anchor a **hash** rather than the data itself: IPFS content cannot be deleted, s
 | Revenue | `get_revenue()`, `get_info()` |
 | Nodes | `get_nodes()` |
 | Payouts | `create_payout_run()`, `submit_payout()`, `onboard_payout_recipient()`, `submit_payout_onboard()`, `get_payout_runs()`, `get_payout_terms()`, `get_payout_info()` |
+| Treasury | `get_treasury_info()`, `get_treasury_vault()`, `get_treasury_vaults()`, `get_treasury_strategy_asset()`, `deploy_treasury_vault()`, `deposit_to_treasury_vault()`, `withdraw_from_treasury_vault()`, `set_treasury_rebalance_manager()`, `build_treasury_rebalance()`, `propose_treasury_rebalance()`, `execute_treasury_rebalance()`, `submit_treasury_tx()` |
 | Audit Trail | `anchor_audit_record()`, `get_audit_info()` |
 | Reporting | `get_reporting_summary()`, `get_reporting_export()` |
 | Admin | `configure_llm()` |

{nirium-0.9.2 → nirium-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "nirium"
-version = "0.9.2"
+version = "0.11.0"
 description = "Autonomous treasury and agentic-payments infrastructure for Stellar (x402 + MPP) — Python client"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -17,8 +17,27 @@ dependencies = [
     "stellar-sdk>=11.0.0,<16.0.0",
 ]
 
+[project.optional-dependencies]
+langchain = ["langchain-core>=0.3.0"]
+test = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "langchain-core>=0.3.0",
+]
+
 [project.urls]
 Homepage = "https://nirium.xyz"
 Repository = "https://github.com/nirium-protocol/nirium-sdk"
 Documentation = "https://nirium.xyz/docs"
 "Bug Tracker" = "https://github.com/nirium-protocol/nirium-sdk/issues"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]

{nirium-0.9.2 → nirium-0.11.0}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="nirium",
-    version="0.9.2",
+    version="0.11.0",
     package_dir={"": "src"},
     packages=find_packages(where="src"),
     install_requires=[
@@ -10,6 +10,14 @@ setup(
         "aiohttp>=3.9.0",
         "stellar-sdk>=11.0.0,<16.0.0",
     ],
+    extras_require={
+        "langchain": ["langchain-core>=0.3.0"],
+        "test": [
+            "pytest>=8.0.0",
+            "pytest-asyncio>=0.23.0",
+            "langchain-core>=0.3.0",
+        ],
+    },
     author="Nirium Team",
     description="Autonomous treasury and agentic-payments infrastructure for Stellar (x402 + MPP) — Python client",
     keywords=["nirium", "stellar", "defi", "x402", "mpp", "agentic-payments", "soroban"],

nirium-0.11.0/src/nirium/__init__.py

@@ -0,0 +1,28 @@
+"""Nirium — autonomous treasury and agentic-payments infrastructure for Stellar (x402 + MPP), Python client."""
+
+from typing import TYPE_CHECKING
+
+from .client import Agent, WebSocketMaxRetriesExceeded, WebSocketStatus  # type: ignore
+
+if TYPE_CHECKING:
+    from .langchain_tools import NiriumX402Tool, create_nirium_x402_tool
+
+__version__ = "0.11.0"
+__all__ = [
+    "Agent",
+    "WebSocketMaxRetriesExceeded",
+    "WebSocketStatus",
+    "NiriumX402Tool",
+    "create_nirium_x402_tool",
+]
+
+
+def __getattr__(name: str):
+    if name in {"NiriumX402Tool", "create_nirium_x402_tool"}:
+        from .langchain_tools import NiriumX402Tool, create_nirium_x402_tool
+
+        return {
+            "NiriumX402Tool": NiriumX402Tool,
+            "create_nirium_x402_tool": create_nirium_x402_tool,
+        }[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

{nirium-0.9.2 → nirium-0.11.0}/src/nirium/client.py

@@ -5,8 +5,11 @@
 # Synced with backend API (real Horizon data, Soroban execution)
 # ═══════════════════════════════════════════════════════════════
 import asyncio
+import collections
+import hashlib
 import json
 import logging
+import random
 import aiohttp  # type: ignore
 import websockets  # type: ignore
 from typing import Callable, Dict, Any, List, Optional
@@ -24,6 +27,19 @@ _X402_NULL_ACCOUNT = "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"
 logger = logging.getLogger("nirium.client")
 
 
+class WebSocketMaxRetriesExceeded(Exception):
+    """Raised when consecutive WebSocket reconnection retries exceed the configured limit."""
+    pass
+
+
+class WebSocketStatus:
+    CONNECTING = "connecting"
+    CONNECTED = "connected"
+    RECONNECTING = "reconnecting"
+    DISCONNECTED = "disconnected"
+    CLOSED = "closed"
+
+
 class Agent:
     """
     Nirium Agent — Full API + WebSocket client for the Nirium autonomous agent.
@@ -49,7 +65,18 @@ class Agent:
         elif token_local is not None:
             self.headers["Authorization"] = f"Bearer {token_local}"
 
-        self.callbacks: Dict[str, List[Callable]] = {"signal": [], "log": [], "connected": []}
+        self.callbacks: Dict[str, List[Callable]] = {
+            "signal": [],
+            "log": [],
+            "connected": [],
+            "status": [],
+            "error": [],
+        }
+        self._active_ws: Optional[Any] = None
+        self._ws_running: bool = False
+        self._ws_close_requested: bool = False
+        self._close_event: asyncio.Event = asyncio.Event()
+        self.last_x402_settlement: Optional[Dict[str, Any]] = None
 
     # ─── Decorators ────────────────────────────────────────────
 
@@ -542,6 +569,29 @@ class Agent:
             payload["caller"] = caller
         return await self._post("/api/treasury/rebalance", payload)
 
+    async def propose_treasury_rebalance(
+        self, vault: str, caller: str, enter_at: float, exit_at: float,
+        min_idle: Optional[Any] = None,
+    ) -> Dict[str, Any]:
+        """Ask the agent what it would propose for this vault — the same decision
+        logic the autonomous signer uses (rate vs. your own ``enter_at``/``exit_at``),
+        but this never signs. Returns an unsigned XDR for you to review and sign
+        yourself, or an empty ``instructions`` list with a ``reason`` if there's
+        nothing to do right now. Public: no allowlist, no invite — works for any
+        vault where ``caller`` is already the on-chain rebalanceManager. Unlike
+        ``execute_treasury_rebalance``, Nirium never executes on your behalf here,
+        so this doesn't wait on the same legal review the fully autonomous path does.
+
+        ``enter_at``/``exit_at`` are your mandate, not a Nirium default. ``min_idle``
+        is stroops, as a string or number — omit for no minimum (0).
+        """
+        payload: Dict[str, Any] = {
+            "vault": vault, "caller": caller, "enterAt": enter_at, "exitAt": exit_at,
+        }
+        if min_idle is not None:
+            payload["minIdle"] = str(min_idle)
+        return await self._post("/api/treasury/rebalance/propose", payload)
+
     async def execute_treasury_rebalance(
         self, vault: str, instructions: List[Dict[str, Any]], caller: Optional[str] = None,
     ) -> Dict[str, Any]:
@@ -559,6 +609,7 @@ class Agent:
         """Broadcast an XDR you already signed (deploy/deposit/withdraw/rebalance/set-rebalance-manager) and wait for confirmation."""
         return await self._post("/api/treasury/submit", {"xdr": xdr})
 
+
     # ─── Admin ───────────────────────────────────────────────
 
     async def configure_llm(
@@ -632,13 +683,13 @@ class Agent:
         it settle, each verified against a TypeScript-generated reference:
 
         1. The source account is the NULL account, not the payer. The
-           facilitator replaces it with its own when it submits and pays the
-           fee. Using the payer's account makes the simulator emit
-           source-account credentials, which the facilitator cannot honour.
+            facilitator replaces it with its own when it submits and pays the
+            fee. Using the payer's account makes the simulator emit
+            source-account credentials, which the facilitator cannot honour.
         2. The auth entry must therefore carry ADDRESS credentials, signed with
-           an expiration ledger.
+            an expiration ledger.
         3. The transaction must be re-simulated AFTER signing: the signature
-           adds bytes, and the resource fee computed before it is too low.
+            adds bytes, and the resource fee computed before it is too low.
         """
         extra = accepted.get("extra") or {}
         if not extra.get("areFeesSponsored"):
@@ -685,7 +736,51 @@ class Agent:
         prepared.transaction.fee = 100 + int(sim.min_resource_fee)
         return prepared.to_xdr()
 
-    async def x402_fetch(self, url: str, method: str = "GET") -> Dict[str, Any]:
+    def _x402_http_payload(self, body: Optional[Any]) -> Dict[str, Any]:
+        if body is None:
+            return {}
+        if isinstance(body, (dict, list)):
+            return {"json": body}
+        return {"data": body}
+
+    def _x402_store_settlement(self, headers: Any) -> None:
+        raw = (
+            headers.get("PAYMENT-RESPONSE")
+            or headers.get("payment-response")
+            or headers.get("X-PAYMENT-RESPONSE")
+            or headers.get("x-payment-response")
+            or headers.get("Payment-Receipt")
+            or headers.get("payment-receipt")
+        )
+        if not raw:
+            self.last_x402_settlement = None
+            return
+        try:
+            decoded = json.loads(_b64.b64decode(raw).decode("utf-8"))
+        except (ValueError, json.JSONDecodeError, TypeError):
+            try:
+                decoded = json.loads(raw)
+            except (ValueError, json.JSONDecodeError, TypeError):
+                self.last_x402_settlement = None
+                return
+        self.last_x402_settlement = decoded if isinstance(decoded, dict) else None
+
+    async def _x402_read_payload(self, resp: Any) -> Dict[str, Any]:
+        text = await resp.text()
+        if not text:
+            return {}
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            return {"body": text}
+        return parsed if isinstance(parsed, dict) else {"body": parsed}
+
+    async def x402_fetch(
+        self,
+        url: str,
+        method: str = "GET",
+        body: Optional[Any] = None,
+    ) -> Dict[str, Any]:
         """
         Fetch a paid resource via x402 (protocol v2).
 
@@ -693,15 +788,20 @@ class Agent:
         header, signs a Soroban auth entry for the exact amount, and retries
         with the ``PAYMENT-SIGNATURE`` header.
 
+        ``body`` is forwarded on both the challenge request and the paid retry
+        so POST/PUT callers do not need a second payment client.
+
         Returns the JSON payload from the paid resource.
         """
         if not hasattr(self, "_x402_keypair"):
             raise RuntimeError("x402 client not initialized. Call agent.init_x402() first.")
 
+        payload = self._x402_http_payload(body)
+        self.last_x402_settlement = None
         async with aiohttp.ClientSession() as session:
-            async with session.request(method, url) as resp:
+            async with session.request(method, url, **payload) as resp:
                 if resp.status != 402:
-                    return await resp.json()
+                    return await self._x402_read_payload(resp)
                 # v2 entrega los requirements en un header base64; el body va vacío.
                 raw = resp.headers.get("payment-required")
 
@@ -732,14 +832,15 @@ class Agent:
             # v2 usa PAYMENT-SIGNATURE. X-PAYMENT es de v1: mandarlo hace que el
             # servidor ignore el pago por completo y reemita el 402 sin explicar.
             async with session.request(
-                method, url, headers={"PAYMENT-SIGNATURE": header}
+                method, url, headers={"PAYMENT-SIGNATURE": header}, **payload
             ) as paid:
                 if paid.status >= 400:
-                    body = await paid.text()
+                    rejected = await paid.text()
                     raise RuntimeError(
-                        f"x402 payment rejected (HTTP {paid.status}): {body[:300]}"
+                        f"x402 payment rejected (HTTP {paid.status}): {rejected[:300]}"
                     )
-                return await paid.json()
+                self._x402_store_settlement(paid.headers)
+                return await self._x402_read_payload(paid)
 
     # ─── MPP Protocol (Charge Mode) ─────────────────────────
 
@@ -818,25 +919,156 @@ class Agent:
 
     # ─── WebSocket ───────────────────────────────────────────
 
-    async def subscribe(self, callback: Optional[Callable] = None):
-        """Start real-time WebSocket connection for signals."""
+    async def close(self):
+        """
+        Gracefully close active WebSocket connection and stop subscriptions.
+        """
+        self._ws_close_requested = True
+        self._ws_running = False
+        self._close_event.set()
+        if self._active_ws is not None:
+            try:
+                await self._active_ws.close()
+            except Exception:
+                pass
+            self._active_ws = None
+        await self._emit("status", WebSocketStatus.CLOSED)
+
+    async def subscribe(
+        self,
+        callback: Optional[Callable] = None,
+        max_retries: Optional[int] = None,
+        initial_delay: float = 1.0,
+        max_delay: float = 30.0,
+        backoff_factor: float = 2.0,
+        jitter: float = 0.2,
+        dedupe_size: int = 1000,
+    ):
+        """
+        Start real-time WebSocket connection for signals with resilient exponential backoff,
+        jitter, retry capping, deduplication, and typed event channels.
+
+        Args:
+            callback: Optional callback for "signal" events (preserves legacy API).
+            max_retries: Maximum consecutive reconnection attempts before raising WebSocketMaxRetriesExceeded.
+            initial_delay: Initial reconnect delay in seconds (default: 1.0).
+            max_delay: Maximum reconnect delay in seconds (default: 30.0).
+            backoff_factor: Multiplier for exponential backoff (default: 2.0).
+            jitter: Fractional random jitter factor applied to delay (default: 0.2, i.e. +/- 20%).
+            dedupe_size: Number of recent message IDs to track for deduplication.
+        """
         if callback:
             self.callbacks.setdefault("signal", []).append(callback)
 
         auth_query = f"?token={self.token}" if self.token else ""
         url = f"{self.ws_url}{auth_query}"
 
-        while True:
+        self._ws_running = True
+        self._ws_close_requested = False
+        self._close_event.clear()
+        attempt = 0
+        seen_ids: collections.deque = collections.deque(maxlen=dedupe_size)
+        seen_set: set = set()
+
+        def _dedupe_check(msg_data: Dict[str, Any]) -> bool:
+            """Returns True if message is a new unseen signal, False if duplicate."""
+            msg_id = (
+                msg_data.get("id")
+                or msg_data.get("signal_id")
+                or msg_data.get("txHash")
+            )
+            if not msg_id:
+                raw_str = json.dumps(msg_data, sort_keys=True)
+                msg_id = hashlib.sha256(raw_str.encode("utf-8")).hexdigest()
+
+            if msg_id in seen_set:
+                return False
+
+            if len(seen_ids) >= dedupe_size and seen_ids:
+                oldest = seen_ids.popleft()
+                seen_set.discard(oldest)
+
+            seen_ids.append(msg_id)
+            seen_set.add(msg_id)
+            return True
+
+        while self._ws_running and not self._ws_close_requested:
             try:
+                await self._emit(
+                    "status",
+                    WebSocketStatus.CONNECTING if attempt == 0 else WebSocketStatus.RECONNECTING,
+                )
                 async with websockets.connect(url) as ws:
+                    self._active_ws = ws
                     logger.info("Connected to Nirium Signal Stream")
+                    await self._emit("status", WebSocketStatus.CONNECTED)
                     await self._emit("connected", None)
 
                     async for message in ws:
+                        if self._ws_close_requested:
+                            break
+                        # Reset retry counter upon successful message exchange
+                        attempt = 0
                         data = json.loads(message)
-                        event = data.get("type")
+                        event = data.get("type", "signal")
+
+                        # Deduplicate only signal messages
+                        if event == "signal":
+                            if not _dedupe_check(data):
+                                logger.debug(f"Dropped duplicate signal: {data.get('id')}")
+                                continue
+
                         if event in self.callbacks:
                             await self._emit(event, data)
+                        if (
+                            event != "signal"
+                            and len(self.callbacks.get("signal", [])) > 0
+                            and event not in ("connected", "status", "error", "log")
+                        ):
+                            await self._emit("signal", data)
+
+                    if not self._ws_close_requested:
+                        raise ConnectionResetError("WebSocket connection closed by remote server")
+
             except Exception as e:
-                logger.error(f"WS Disconnected: {e}. Reconnecting in 5s...")
-                await asyncio.sleep(5)
+                self._active_ws = None
+                if self._ws_close_requested:
+                    logger.info("WebSocket connection closed by user request.")
+                    await self._emit("status", WebSocketStatus.CLOSED)
+                    break
+
+                attempt += 1
+                await self._emit("status", WebSocketStatus.DISCONNECTED)
+                await self._emit(
+                    "error",
+                    {"error": str(e), "exception": e, "attempt": attempt},
+                )
+
+                if max_retries is not None and attempt >= max_retries:
+                    logger.error(
+                        f"WS Reconnect failed after {attempt} attempts. Max retries exceeded."
+                    )
+                    await self._emit("status", WebSocketStatus.CLOSED)
+                    raise WebSocketMaxRetriesExceeded(
+                        f"WebSocket connection failed after {attempt} consecutive attempts: {e}"
+                    ) from e
+
+                # Calculate exponential backoff with jitter
+                base_delay = min(
+                    max_delay, initial_delay * (backoff_factor ** (attempt - 1))
+                )
+                jitter_range = base_delay * jitter
+                actual_delay = max(
+                    0.05, base_delay + random.uniform(-jitter_range, jitter_range)
+                )
+
+                logger.warning(
+                    f"WS Disconnected: {e}. Reconnecting (attempt {attempt}/{max_retries or 'inf'}) in {actual_delay:.2f}s..."
+                )
+                try:
+                    await asyncio.wait_for(self._close_event.wait(), timeout=actual_delay)
+                    # If close event was triggered during backoff sleep, terminate immediately
+                    break
+                except asyncio.TimeoutError:
+                    # Backoff sleep elapsed normally, proceed to reconnect
+                    pass