pmwallets 0.7.0__tar.gz → 0.8.0__tar.gz

{pmwallets-0.7.0 → pmwallets-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pmwallets
-Version: 0.7.0
+Version: 0.8.0
 Summary: Official PMWallets SDK and CLI: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks, exports — and a CLI + MCP server so AI agents (Claude Code, Codex, Cursor, …) can follow traders and act on their fills.
 Project-URL: Homepage, https://pmwallets.com/docs
 Project-URL: Repository, https://github.com/polymarketwallets/pmwallets-python
@@ -46,7 +46,7 @@ big = client.radar(minUsd=25000, smart=True)
 client.save_signal_rule("signal", {"enabled": True, "scope": "official", "minWallets": 3, "windowMin": 30, "minUsd": 5000, "channels": ["ws", "webhook"]})
 ```
 
-Live alerts arrive on `wss://api.pmwallets.com/v1/signals/ws` as `{type: 'signal' | 'radar', data}`. Amounts keep two significant figures, times the minute, and traders are named by handle.
+For live alerts use `SignalStream(client, on_alert).start()`, or `pmwallets alerts` on the command line. Amounts keep two significant figures, times the minute, and traders are named by handle.
 
 ## Usage
 

{pmwallets-0.7.0 → pmwallets-0.8.0}/README.md

@@ -28,7 +28,7 @@ big = client.radar(minUsd=25000, smart=True)
 client.save_signal_rule("signal", {"enabled": True, "scope": "official", "minWallets": 3, "windowMin": 30, "minUsd": 5000, "channels": ["ws", "webhook"]})
 ```
 
-Live alerts arrive on `wss://api.pmwallets.com/v1/signals/ws` as `{type: 'signal' | 'radar', data}`. Amounts keep two significant figures, times the minute, and traders are named by handle.
+For live alerts use `SignalStream(client, on_alert).start()`, or `pmwallets alerts` on the command line. Amounts keep two significant figures, times the minute, and traders are named by handle.
 
 ## Usage
 

{pmwallets-0.7.0 → pmwallets-0.8.0}/README.zh.md

@@ -25,7 +25,7 @@ big = client.radar(minUsd=25000, smart=True)
 client.save_signal_rule("signal", {"enabled": True, "scope": "official", "minWallets": 3, "windowMin": 30, "minUsd": 5000, "channels": ["ws", "webhook"]})
 ```
 
-实时告警走 `wss://api.pmwallets.com/v1/signals/ws`,帧为 `{type: 'signal' | 'radar', data}`。金额保留两位有效数字,时间到分钟,交易者只给代号。
+实时告警用 `SignalStream(client, on_alert).start()`,或命令行 `pmwallets alerts`。金额保留两位有效数字,时间到分钟,交易者只给代号。
 
 ## 包含什么
 

{pmwallets-0.7.0 → pmwallets-0.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pmwallets"
-version = "0.7.0"
+version = "0.8.0"
 description = "Official PMWallets SDK and CLI: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks, exports — and a CLI + MCP server so AI agents (Claude Code, Codex, Cursor, …) can follow traders and act on their fills."
 readme = "README.md"
 requires-python = ">=3.10"

{pmwallets-0.7.0 → pmwallets-0.8.0}/src/pmwallets/__init__.py

@@ -3,7 +3,7 @@
 from .client import DEFAULT_BASE_URL, AsyncClient, Client, PmwError
 from .market import MarketInfo, MarketLookup, micro_to_decimal
 from .mcp import MCP_PROTOCOL_VERSIONS, McpTool, serve_mcp
-from .stream import CLOSE_API_SEAT_TAKEN, CLOSE_SERVICE_RESTART, FileStateStore, FillMeta, FillStream, MemoryStateStore, StreamState, UpgradeRefused, websockets_connector
+from .stream import CLOSE_API_SEAT_TAKEN, CLOSE_SERVICE_RESTART, CLOSE_SIGNALS_REPLACED, SignalStream, FileStateStore, FillMeta, FillStream, MemoryStateStore, StreamState, UpgradeRefused, websockets_connector
 from .tools import MCP_INSTRUCTIONS, CursorFile, describe_fill, new_fills, pmwallets_tools
 from .types import Fill, FillCursor, FillsPage
 from .version import VERSION
@@ -11,6 +11,8 @@ from .watch import Watcher
 from .webhook import verify_webhook
 
 __all__ = [
+    "SignalStream",
+    "CLOSE_SIGNALS_REPLACED",
     "DEFAULT_BASE_URL", "AsyncClient", "Client", "PmwError",
     "CLOSE_API_SEAT_TAKEN", "CLOSE_SERVICE_RESTART", "FileStateStore", "FillMeta", "FillStream", "MemoryStateStore", "StreamState", "UpgradeRefused", "websockets_connector",
     "Fill", "FillCursor", "FillsPage", "verify_webhook",

{pmwallets-0.7.0 → pmwallets-0.8.0}/src/pmwallets/cli.py

@@ -21,6 +21,7 @@ import time
 from importlib import resources
 from typing import Any, Optional, Union
 
+from .stream import SignalStream
 from .client import DEFAULT_BASE_URL, AsyncClient
 from .market import MarketLookup
 from .mcp import serve_mcp
@@ -49,6 +50,7 @@ Set PMW_API_KEY (create one on https://pmwallets.com/keys). Every command prints
   pmwallets account                        plan and balance
   pmwallets signals [--source mine] [--category sports] [--q fed]   smart-money signals (Pro and Max)
   pmwallets radar [--minUsd 25000] [--side BUY] [--smart]           large fills, whole market (Pro and Max)
+  pmwallets alerts                         live alerts of your rules, one JSON line each (Pro and Max)
   pmwallets mcp                            MCP server on stdio (tools: leaderboard, entity, subscribe, new_fills, …)
   pmwallets skill                          print the guide for AI agents (SKILL.md)
 
@@ -123,6 +125,14 @@ async def _main(argv: list[str]) -> int:
             markets = MarketLookup()
             await serve_mcp(name="pmwallets", version=VERSION, tools=pmwallets_tools(client, markets=markets), instructions=MCP_INSTRUCTIONS)
             return 0
+        if cmd == "alerts":
+            if client is None:
+                raise ValueError("set PMW_API_KEY (create a key on https://pmwallets.com/keys)")
+            stream = SignalStream(client, lambda a: print(json.dumps(a), flush=True),
+                                  on_event=lambda e: print(e["reason"], file=sys.stderr) if e["type"] == "stopped" else None)
+            stream.start()
+            await stream.wait()
+            return 0
         if cmd == "watch":
             if flags.get("exec") is True:
                 raise ValueError("--exec needs a command, e.g. --exec \"claude -p '…'\"")

{pmwallets-0.7.0 → pmwallets-0.8.0}/src/pmwallets/stream.py

@@ -364,3 +364,64 @@ class FillStream:
             self.state.block = fill["block"]
             self.state.logIndex = fill["logIndex"]
         return True
+
+
+# this socket was replaced by a newer one past the account's limit: reconnecting would evict another
+CLOSE_SIGNALS_REPLACED = 4412
+
+
+class SignalStream:
+    """The live alerts of your rules (Pro and Max): connects, reconnects with backoff, stops when told not to come back.
+    Best effort: GET /v1/signals and /v1/radar hold what a gap missed. `on_alert` gets {"type": "signal" | "radar", "data": ...}."""
+
+    def __init__(self, client: AsyncClient, on_alert: Callable[[dict[str, Any]], Any], on_event: Optional[OnEvent] = None,
+                 connector: Optional[Connector] = None, max_backoff: float = 15.0) -> None:
+        self._client, self._on_alert, self._on_event = client, on_alert, on_event or (lambda e: None)
+        self._connector = connector or websockets_connector()
+        self._max_backoff = max_backoff
+        self._task: Optional[asyncio.Task[None]] = None
+
+    def start(self) -> None:
+        self._task = asyncio.create_task(self._run())
+
+    async def stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+
+    async def wait(self) -> None:
+        if self._task:
+            await self._task
+
+    async def _run(self) -> None:
+        backoff = 1.0
+        while True:
+            code = None
+            try:
+                async with self._connector(self._client.signals_ws_url, {"x-api-key": self._client.api_key}) as ws:
+                    self._on_event({"type": "connected"})
+                    backoff = 1.0
+                    async for raw in ws:
+                        try:
+                            f = json.loads(raw)
+                        except ValueError:
+                            continue
+                        if isinstance(f, dict) and f.get("type") in ("signal", "radar") and f.get("data"):
+                            r = self._on_alert({"type": f["type"], "data": f["data"]})
+                            if asyncio.iscoroutine(r):
+                                await r
+                    code = getattr(ws, "close_code", None)
+            except UpgradeRefused as e:
+                if e.status_code in (401, 403):
+                    reason = "signals are part of the Pro and Max plans" if e.status_code == 403 else "the API key was refused"
+                    return self._on_event({"type": "stopped", "reason": reason})
+            except asyncio.CancelledError:
+                raise
+            except Exception as e:
+                code = getattr(getattr(e, "rcvd", None), "code", None)
+            self._on_event({"type": "disconnected", "code": code})
+            if code == CLOSE_SIGNALS_REPLACED:
+                return self._on_event({"type": "stopped", "reason": "replaced by a newer connection"})
+            await asyncio.sleep(0 if code == CLOSE_SERVICE_RESTART else backoff)
+            backoff = min(backoff * 2, self._max_backoff)

pmwallets-0.8.0/src/pmwallets/version.py

@@ -0,0 +1 @@
+VERSION = "0.8.0"

{pmwallets-0.7.0 → pmwallets-0.8.0}/tests/test_stream.py

@@ -263,3 +263,51 @@ async def test_file_state_store_roundtrip(tmp_path):
     await store.save(StreamState("s", 3, 9, 2))
     assert await store.load() == StreamState("s", 3, 9, 2)
     assert json.loads((tmp_path / "sub" / "state.json").read_text()) == {"session": "s", "seq": 3, "block": 9, "logIndex": 2}
+
+
+class _Sock:
+    def __init__(self, frames, code=None):
+        self.frames, self.close_code = frames, code
+
+    def __aiter__(self):
+        async def gen():
+            for f in self.frames:
+                yield f
+        return gen()
+
+
+def _connector(socks, urls):
+    @contextlib.asynccontextmanager
+    async def connect(url, headers):
+        urls.append(url)
+        s = socks.pop(0)
+        if isinstance(s, Exception):
+            raise s
+        yield s
+    return connect
+
+
+class _Key:
+    api_key = "pmw_a_b"
+    signals_ws_url = "wss://x/v1/signals/ws"
+
+
+async def test_signal_stream_delivers_alerts_and_stops_when_replaced():
+    from pmwallets import SignalStream
+    seen, urls, events = [], [], []
+    socks = [_Sock(['{"type":"hello"}', "not json", '{"type":"radar","data":{"usd":52000}}'], 1006), _Sock([], 4412)]
+    s = SignalStream(_Key(), seen.append, events.append, connector=_connector(socks, urls), max_backoff=0.01)
+    s.start()
+    await asyncio.wait_for(s.wait(), 5)
+    assert seen == [{"type": "radar", "data": {"usd": 52000}}]
+    assert len(urls) == 2 and events[-1]["type"] == "stopped"
+
+
+async def test_signal_stream_stops_on_a_plan_without_signals():
+    from pmwallets import SignalStream
+    from pmwallets.stream import UpgradeRefused
+    urls, events = [], []
+    s = SignalStream(_Key(), lambda a: None, events.append, connector=_connector([UpgradeRefused(403)], urls))
+    s.start()
+    await asyncio.wait_for(s.wait(), 5)
+    assert len(urls) == 1 and "Pro and Max" in events[-1]["reason"]

{pmwallets-0.7.0 → pmwallets-0.8.0}/uv.lock

@@ -134,7 +134,7 @@ wheels = [
 
 [[package]]
 name = "pmwallets"
-version = "0.7.0"
+version = "0.8.0"
 source = { editable = "." }
 dependencies = [
     { name = "httpx" },

pmwallets-0.7.0/src/pmwallets/version.py

@@ -1 +0,0 @@
-VERSION = "0.7.0"