pmwallets 0.1.0__py3-none-any.whl

pmwallets/__init__.py

@@ -0,0 +1,13 @@
+"""Official PMWallets SDK — https://pmwallets.com/docs"""
+
+from .client import DEFAULT_BASE_URL, AsyncClient, Client, PmwError
+from .stream import FileStateStore, FillMeta, FillStream, MemoryStateStore, StreamState, UpgradeRefused, websockets_connector
+from .types import Fill, FillCursor, FillsPage
+from .webhook import verify_webhook
+
+__all__ = [
+    "DEFAULT_BASE_URL", "AsyncClient", "Client", "PmwError",
+    "FileStateStore", "FillMeta", "FillStream", "MemoryStateStore", "StreamState", "UpgradeRefused", "websockets_connector",
+    "Fill", "FillCursor", "FillsPage", "verify_webhook",
+]
+__version__ = "0.1.0"

pmwallets/client.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Iterator, Optional
+from urllib.parse import quote
+
+import httpx
+
+from .types import Fill, FillCursor, FillsPage, Leaderboard, Subscription
+
+DEFAULT_BASE_URL = "https://api.pmwallets.com"
+
+
+class PmwError(Exception):
+    """A non-2xx answer from the API. `body` is the parsed JSON body when there was one."""
+
+    def __init__(self, status: int, body: Any, message: Optional[str] = None):
+        self.status = status
+        self.body = body
+        super().__init__(message or f"PMWallets API {status}: {body if isinstance(body, str) else json.dumps(body)}")
+
+
+def _q(v: str) -> str:
+    return quote(v, safe="")
+
+
+class _Base:
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0):
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    @property
+    def ws_url(self) -> str:
+        """The WebSocket URL derived from the base URL (https → wss)."""
+        return ("ws" + self.base_url[4:] if self.base_url.startswith("http") else self.base_url) + "/v1/ws"
+
+    @property
+    def _headers(self) -> dict[str, str]:
+        return {"x-api-key": self.api_key, "accept": "application/json"}
+
+    @staticmethod
+    def _params(query: Optional[dict[str, Any]]) -> dict[str, Any]:
+        out: dict[str, Any] = {}
+        for k, v in (query or {}).items():
+            if v is None:
+                continue
+            out[k] = ("true" if v else "false") if isinstance(v, bool) else v
+        return out
+
+    @staticmethod
+    def _parse(res: httpx.Response) -> Any:
+        text = res.text
+        body: Any = text
+        if text:
+            try:
+                body = json.loads(text)
+            except ValueError:
+                pass
+        if res.status_code < 200 or res.status_code >= 300:
+            raise PmwError(res.status_code, body)
+        return body if text else None
+
+    @staticmethod
+    def _fills_query(since_block: int, since_log_index: int, limit: int) -> dict[str, Any]:
+        return {"sinceBlock": since_block, "sinceLogIndex": since_log_index, "limit": limit}
+
+
+class Client(_Base):
+    """Synchronous REST client for https://api.pmwallets.com. Every method authenticates with the API key."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0, http: Optional[httpx.Client] = None):
+        super().__init__(api_key, base_url, timeout)
+        self._http = http or httpx.Client(timeout=timeout)
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def request(self, method: str, path: str, query: Optional[dict[str, Any]] = None, body: Any = None) -> Any:
+        res = self._http.request(method, self.base_url + path, params=self._params(query), headers=self._headers,
+                                 json=body if body is not None else None)
+        return self._parse(res)
+
+    # ── the board
+    def leaderboard(self, **query: Any) -> Leaderboard:
+        return self.request("GET", "/v1/leaderboard", query)
+
+    def entity(self, entity_id: str, period: Optional[str] = None) -> dict[str, Any]:
+        """One entity by handle or address. The full address comes back only for entities you own."""
+        return self.request("GET", f"/v1/entities/{_q(entity_id)}", {"period": period})
+
+    def latency(self) -> dict[str, Any]:
+        return self.request("GET", "/v1/latency")
+
+    # ── addresses
+    def buy_reveal(self, entity_id: str, max_price_cents: int) -> dict[str, Any]:
+        """Buy the address behind a handle. `max_price_cents` is a ceiling: the charge never exceeds it."""
+        return self.request("POST", "/v1/account/reveals", body={"entityId": entity_id, "maxPriceCents": max_price_cents})
+
+    def reveals(self) -> list[dict[str, Any]]:
+        return self.request("GET", "/v1/account/reveals")
+
+    # ── subscriptions
+    def subscriptions(self) -> list[Subscription]:
+        """Active and paused subscriptions, newest first."""
+        return self.request("GET", "/v1/account/subscriptions")
+
+    def subscribe(self, entity_id: str, channels: Optional[list[str]] = None, accept_inactive: Optional[bool] = None) -> Subscription:
+        """Starts billing per hour. 402 = balance too low, 409 = dormant entity (resend with accept_inactive)."""
+        body: dict[str, Any] = {"channels": channels or ["ws"], "entityId": entity_id}
+        if accept_inactive is not None:
+            body["acceptInactive"] = accept_inactive
+        return self.request("POST", "/v1/account/subscriptions", body=body)
+
+    def cancel_subscription(self, sub_id: str) -> Any:
+        return self.request("DELETE", f"/v1/account/subscriptions/{_q(sub_id)}")
+
+    def resume_subscription(self, sub_id: str) -> Subscription:
+        """Charges another hour and resumes from the current head (the paused gap is not backfilled)."""
+        return self.request("POST", f"/v1/account/subscriptions/{_q(sub_id)}/resume")
+
+    # ── fills
+    def fills(self, since_block: int = 0, since_log_index: int = 0, limit: int = 500) -> FillsPage:
+        """One page of fills strictly after the cursor, oldest first (all active subscriptions)."""
+        return self.request("GET", "/v1/account/fills", self._fills_query(since_block, since_log_index, limit))
+
+    def fills_since(self, cursor: FillCursor, limit: int = 500) -> Iterator[Fill]:
+        """Every fill after the cursor, walking pages until the end."""
+        at: Optional[FillCursor] = cursor
+        while at:
+            page = self.fills(at["sinceBlock"], at["sinceLogIndex"], limit)
+            yield from page["rows"]
+            at = page["next"]
+
+    # ── trade-history exports
+    def export_quote(self, entity_ids: list[str], from_: str, to: str) -> dict[str, Any]:
+        return self.request("POST", "/v1/account/exports/quote", body={"entityIds": entity_ids, "from": from_, "to": to})
+
+    def create_export(self, entity_ids: list[str], from_: str, to: str) -> dict[str, Any]:
+        """Charges the balance; the price is recomputed server-side."""
+        return self.request("POST", "/v1/account/exports", body={"entityIds": entity_ids, "from": from_, "to": to})
+
+    def exports(self) -> list[dict[str, Any]]:
+        return self.request("GET", "/v1/account/exports")
+
+    def get_export(self, export_id: str) -> dict[str, Any]:
+        return self.request("GET", f"/v1/account/exports/{_q(export_id)}")
+
+    def export_download(self, export_id: str) -> dict[str, Any]:
+        """A presigned download URL, valid 15 minutes."""
+        return self.request("GET", f"/v1/account/exports/{_q(export_id)}/download")
+
+
+class AsyncClient(_Base):
+    """asyncio twin of Client (the FillStream uses it for replays)."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL, timeout: float = 15.0, http: Optional[httpx.AsyncClient] = None):
+        super().__init__(api_key, base_url, timeout)
+        self._http = http or httpx.AsyncClient(timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def request(self, method: str, path: str, query: Optional[dict[str, Any]] = None, body: Any = None) -> Any:
+        res = await self._http.request(method, self.base_url + path, params=self._params(query), headers=self._headers,
+                                       json=body if body is not None else None)
+        return self._parse(res)
+
+    async def leaderboard(self, **query: Any) -> Leaderboard:
+        return await self.request("GET", "/v1/leaderboard", query)
+
+    async def entity(self, entity_id: str, period: Optional[str] = None) -> dict[str, Any]:
+        return await self.request("GET", f"/v1/entities/{_q(entity_id)}", {"period": period})
+
+    async def latency(self) -> dict[str, Any]:
+        return await self.request("GET", "/v1/latency")
+
+    async def buy_reveal(self, entity_id: str, max_price_cents: int) -> dict[str, Any]:
+        return await self.request("POST", "/v1/account/reveals", body={"entityId": entity_id, "maxPriceCents": max_price_cents})
+
+    async def reveals(self) -> list[dict[str, Any]]:
+        return await self.request("GET", "/v1/account/reveals")
+
+    async def subscriptions(self) -> list[Subscription]:
+        return await self.request("GET", "/v1/account/subscriptions")
+
+    async def subscribe(self, entity_id: str, channels: Optional[list[str]] = None, accept_inactive: Optional[bool] = None) -> Subscription:
+        body: dict[str, Any] = {"channels": channels or ["ws"], "entityId": entity_id}
+        if accept_inactive is not None:
+            body["acceptInactive"] = accept_inactive
+        return await self.request("POST", "/v1/account/subscriptions", body=body)
+
+    async def cancel_subscription(self, sub_id: str) -> Any:
+        return await self.request("DELETE", f"/v1/account/subscriptions/{_q(sub_id)}")
+
+    async def resume_subscription(self, sub_id: str) -> Subscription:
+        return await self.request("POST", f"/v1/account/subscriptions/{_q(sub_id)}/resume")
+
+    async def fills(self, since_block: int = 0, since_log_index: int = 0, limit: int = 500) -> FillsPage:
+        return await self.request("GET", "/v1/account/fills", self._fills_query(since_block, since_log_index, limit))
+
+    async def fills_since(self, cursor: FillCursor, limit: int = 500) -> AsyncIterator[Fill]:
+        at: Optional[FillCursor] = cursor
+        while at:
+            page = await self.fills(at["sinceBlock"], at["sinceLogIndex"], limit)
+            for row in page["rows"]:
+                yield row
+            at = page["next"]
+
+    async def export_quote(self, entity_ids: list[str], from_: str, to: str) -> dict[str, Any]:
+        return await self.request("POST", "/v1/account/exports/quote", body={"entityIds": entity_ids, "from": from_, "to": to})
+
+    async def create_export(self, entity_ids: list[str], from_: str, to: str) -> dict[str, Any]:
+        return await self.request("POST", "/v1/account/exports", body={"entityIds": entity_ids, "from": from_, "to": to})
+
+    async def exports(self) -> list[dict[str, Any]]:
+        return await self.request("GET", "/v1/account/exports")
+
+    async def get_export(self, export_id: str) -> dict[str, Any]:
+        return await self.request("GET", f"/v1/account/exports/{_q(export_id)}")
+
+    async def export_download(self, export_id: str) -> dict[str, Any]:
+        return await self.request("GET", f"/v1/account/exports/{_q(export_id)}/download")

pmwallets/stream.py

@@ -0,0 +1,324 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import math
+import os
+from collections import OrderedDict
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any, AsyncContextManager, Awaitable, Callable, Optional, Protocol, Union
+
+from .client import AsyncClient
+from .types import Fill
+
+
+@dataclass
+class StreamState:
+    """The WebSocket numbering last accepted and the ledger position of the last delivered fill.
+    Persist it (FileStateStore) and a restart resumes exactly where it stopped."""
+
+    session: Optional[str] = None
+    seq: int = 0
+    block: int = 0
+    logIndex: int = 0
+
+
+class StateStore(Protocol):
+    async def load(self) -> Optional[StreamState]: ...
+    async def save(self, state: StreamState) -> None: ...
+
+
+class MemoryStateStore:
+    def __init__(self) -> None:
+        self._state: Optional[StreamState] = None
+
+    async def load(self) -> Optional[StreamState]:
+        return StreamState(**asdict(self._state)) if self._state else None
+
+    async def save(self, state: StreamState) -> None:
+        self._state = StreamState(**asdict(state))
+
+
+class FileStateStore:
+    """JSON file, replaced atomically (temp file + os.replace) so a crash never leaves half a file.
+    Same format as the Node SDK's FileStateStore — the two are interchangeable."""
+
+    def __init__(self, path: Union[str, Path]) -> None:
+        self.path = Path(path)
+
+    async def load(self) -> Optional[StreamState]:
+        try:
+            s = json.loads(self.path.read_text("utf8"))
+        except FileNotFoundError:
+            return None
+        return StreamState(session=s.get("session"), seq=s.get("seq", 0), block=s.get("block", 0), logIndex=s.get("logIndex", 0))
+
+    async def save(self, state: StreamState) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self.path.with_name(self.path.name + ".tmp")
+        tmp.write_text(json.dumps(asdict(state), separators=(",", ":")))
+        os.replace(tmp, self.path)
+
+
+@dataclass(frozen=True)
+class FillMeta:
+    source: str  # "ws" | "replay"
+
+
+class UpgradeRefused(Exception):
+    """The server answered the WebSocket upgrade with an HTTP status instead of 101."""
+
+    def __init__(self, status_code: int):
+        super().__init__(f"WebSocket upgrade refused with {status_code}")
+        self.status_code = status_code
+
+
+class SocketLike(Protocol):
+    close_code: Optional[int]
+    close_reason: Optional[str]
+
+    def __aiter__(self) -> Any: ...
+    async def close(self, code: int = 1000, reason: str = "") -> None: ...
+
+
+Connector = Callable[[str, dict[str, str]], AsyncContextManager[SocketLike]]
+OnFill = Callable[[Fill, FillMeta], Union[None, Awaitable[None]]]
+OnEvent = Callable[[dict[str, Any]], None]
+
+
+def websockets_connector(ping_interval: float = 20.0, **ws_options: Any) -> Connector:
+    """The real transport: `websockets` asyncio client. websockets>=15 picks up HTTPS_PROXY by itself."""
+    from websockets.asyncio.client import connect
+    from websockets.exceptions import InvalidStatus
+
+    @contextlib.asynccontextmanager
+    async def _connect(url: str, headers: dict[str, str]):
+        try:
+            cm = connect(url, additional_headers=headers, ping_interval=ping_interval, ping_timeout=ping_interval, **ws_options)
+            ws = await cm.__aenter__()
+        except InvalidStatus as e:
+            raise UpgradeRefused(e.response.status_code) from e
+        try:
+            yield ws
+        finally:
+            await cm.__aexit__(None, None, None)
+
+    return _connect
+
+
+class FillStream:
+    """The fills of every entity your account subscribes to, delivered exactly once and in order.
+
+    The WebSocket is best effort: a frame dropped for a slow consumer, or everything sent while you were
+    reconnecting, is not resent. Every frame carries `session` + a consecutive `seq`, so a skip is
+    detectable — and on any skip or new session this stream pulls the gap from GET /v1/account/fills
+    (keyset-paged from the last delivered fill) before it moves on. Duplicates are dropped by eventId.
+
+    `on_fill(fill, meta)` is called once per fill, in ledger order, never concurrently. A fill counts as
+    delivered only after it returns: if it raises, the connection is dropped and the fill is offered again
+    after the reconnect's replay — make it idempotent on eventId, or never raise.
+    """
+
+    def __init__(
+        self,
+        client: AsyncClient,
+        on_fill: OnFill,
+        on_event: Optional[OnEvent] = None,
+        store: Optional[StateStore] = None,
+        ping_interval: float = 20.0,
+        min_backoff: float = 1.0,
+        max_backoff: float = 30.0,
+        seen_capacity: int = 10_000,
+        connector: Optional[Connector] = None,
+        ws_options: Optional[dict[str, Any]] = None,
+        replay_without_cursor: bool = False,
+        anchor_lag_blocks: int = 200,
+    ) -> None:
+        self.client = client
+        self.on_fill = on_fill
+        self.on_event = on_event
+        self.store: StateStore = store or MemoryStateStore()
+        self.min_backoff = min_backoff
+        self.max_backoff = max_backoff
+        self.seen_capacity = seen_capacity
+        # Where to start when there is no saved position. Default False: at the first connection the cursor
+        # is anchored at the current chain head, so a disconnect before the first fill is still replayed —
+        # but the history from before you started is not. True: start from zero and receive every fill
+        # since each subscription began.
+        self.replay_without_cursor = replay_without_cursor
+        # How far behind the chain head to anchor (~5 min). The head can run ahead of the fills already indexed for
+        # your account; anchoring exactly at it could exclude a fill mined earlier but not yet pushed. The extra
+        # blocks are replayed at most once more and dropped by eventId.
+        self.anchor_lag_blocks = anchor_lag_blocks
+        self.connector = connector or websockets_connector(ping_interval, **(ws_options or {}))
+        self.state = StreamState()
+        self._seen: "OrderedDict[str, bool]" = OrderedDict()
+        self._running = False
+        self._task: Optional[asyncio.Task[None]] = None
+        self._socket: Optional[SocketLike] = None
+        self._wake = asyncio.Event()
+
+    @property
+    def position(self) -> StreamState:
+        return StreamState(**asdict(self.state))
+
+    async def start(self) -> None:
+        """Loads the saved state and starts connecting. Returns immediately; call stop() to end."""
+        if self._running:
+            return
+        self.state = (await self.store.load()) or self.state
+        self._running = True
+        self._task = asyncio.create_task(self._loop())
+
+    async def stop(self) -> None:
+        """Closes the socket and waits for the fill being handled (if any) to finish."""
+        self._running = False
+        self._wake.set()
+        if self._socket is not None:
+            with contextlib.suppress(Exception):
+                await self._socket.close(1000)
+        if self._task is not None:
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+
+    async def run(self) -> None:
+        """start() and block until the stream stops."""
+        await self.start()
+        await self.wait()
+
+    async def wait(self) -> None:
+        """Block until the stream stops (stop() or a fatal error)."""
+        if self._task is not None:
+            with contextlib.suppress(asyncio.CancelledError):
+                await self._task
+
+    def _emit(self, event: dict[str, Any]) -> None:
+        if self.on_event is None:
+            return
+        with contextlib.suppress(Exception):  # a listener must not break the stream
+            self.on_event(event)
+
+    async def _loop(self) -> None:
+        backoff = self.min_backoff
+        while self._running:
+            healthy = await self._connect_once()
+            if not self._running:
+                break
+            backoff = self.min_backoff if healthy else min(backoff * 2, self.max_backoff)
+            self._wake.clear()
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(self._wake.wait(), backoff)
+
+    async def _connect_once(self) -> bool:
+        """One connection's life; True when it got as far as a hello and did not fail."""
+        url = self.client.ws_url
+        self._emit({"type": "connecting", "url": url})
+        greeted = False
+        failed = False
+        code, reason = 1006, ""
+        try:
+            async with self.connector(url, {"x-api-key": self.client.api_key}) as ws:
+                self._socket = ws
+                self._emit({"type": "connected"})
+                try:
+                    async for raw in ws:
+                        try:
+                            frame = json.loads(raw)
+                        except (ValueError, TypeError):
+                            continue
+                        if not isinstance(frame, dict):
+                            continue
+                        try:
+                            await self._handle_frame(frame)
+                        except Exception as e:  # leave the position where it is; the next hello replays from it
+                            failed = True
+                            self._emit({"type": "error", "error": e})
+                            break
+                        if frame.get("type") == "hello":
+                            greeted = True
+                except Exception as e:  # ConnectionClosedError and friends
+                    self._emit({"type": "error", "error": e})
+                code = getattr(ws, "close_code", None) or 1006
+                reason = getattr(ws, "close_reason", None) or ""
+        except UpgradeRefused as e:
+            if e.status_code in (401, 403):
+                self._running = False
+                self._emit({"type": "fatal", "error": RuntimeError(f"WebSocket upgrade refused with {e.status_code}: check the API key")})
+            else:
+                self._emit({"type": "error", "error": e})
+            return False
+        except Exception as e:
+            self._emit({"type": "error", "error": e})
+            return False
+        finally:
+            self._socket = None
+        if code == 1000 and "replaced" in reason.lower():
+            self._emit({"type": "replaced"})
+        self._emit({"type": "disconnected", "code": code, "reason": reason})
+        return greeted and not failed
+
+    async def _handle_frame(self, m: dict[str, Any]) -> None:
+        if m.get("type") == "hello" and isinstance(m.get("session"), str):
+            # A new session means the socket (or this process) was down: replay BEFORE adopting it —
+            # adopting first is what silently swallows an outage.
+            if self.state.block == 0 and not self.replay_without_cursor:
+                await self._anchor()
+            elif self.state.session is not None and m["session"] != self.state.session:
+                await self._replay("new_session")
+            self.state.session = m["session"]
+            self.state.seq = int(m.get("seq") or 0)
+            await self.store.save(self.state)
+            self._emit({"type": "hello", "session": m["session"], "seq": self.state.seq})
+            return
+        if m.get("type") != "fill" or not m.get("data") or not isinstance(m.get("seq"), int):
+            return
+        if m.get("session") != self.state.session or m["seq"] != self.state.seq + 1:
+            await self._replay("seq_skip")
+        await self._deliver(m["data"], "ws")
+        # only once the fill is handled: a position that ran ahead of a failed delivery would hide the gap
+        self.state.session = m.get("session")
+        self.state.seq = m["seq"]
+        await self.store.save(self.state)
+
+    async def _anchor(self) -> None:
+        """No position yet: take the chain head as the starting point. Without it a disconnect before the first
+        fill could not be replayed, and replaying from zero would hand over every fill since each subscription began."""
+        r = await self.client.latency()
+        raw = (r.get("head") or {}).get("block") if isinstance(r, dict) else None
+        try:
+            head = float(raw) if raw is not None and not isinstance(raw, bool) else math.nan
+        except (TypeError, ValueError):
+            head = math.nan
+        if not (math.isfinite(head) and head == int(head) and head > 0):
+            raise RuntimeError("could not read the chain head to anchor the stream")
+        head = int(head)
+        # strictly-after semantics: everything from (head − lag) on; never 0, which means "no position"
+        self.state.block = max(1, head - self.anchor_lag_blocks - 1)
+        self.state.logIndex = 0xFFFFFFFF
+        self._emit({"type": "anchored", "block": self.state.block + 1})
+
+    async def _replay(self, reason: str) -> None:
+        self._emit({"type": "gap", "reason": reason, "fromBlock": self.state.block, "fromLogIndex": self.state.logIndex})
+        delivered = 0
+        async for fill in self.client.fills_since({"sinceBlock": self.state.block, "sinceLogIndex": self.state.logIndex}):
+            if await self._deliver(fill, "replay"):
+                delivered += 1
+        await self.store.save(self.state)
+        self._emit({"type": "replayed", "delivered": delivered})
+
+    async def _deliver(self, fill: Fill, source: str) -> bool:
+        if fill["eventId"] in self._seen:
+            return False
+        r = self.on_fill(fill, FillMeta(source))
+        if asyncio.iscoroutine(r) or isinstance(r, asyncio.Future):
+            await r
+        self._seen[fill["eventId"]] = True
+        if len(self._seen) > self.seen_capacity:
+            self._seen.popitem(last=False)
+        # never move backwards: a live frame can be older than what the replay just walked past
+        if fill["block"] > self.state.block or (fill["block"] == self.state.block and fill["logIndex"] > self.state.logIndex):
+            self.state.block = fill["block"]
+            self.state.logIndex = fill["logIndex"]
+        return True

pmwallets/types.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any, Literal, Optional, TypedDict
+
+
+class Fill(TypedDict):
+    """One fill of an entity you subscribe to, exactly as the WebSocket frame and GET /v1/account/fills carry it."""
+
+    eventId: str  # chain:block:blockHash:txHash:logIndex — deduplicate on it
+    chain: int
+    entityId: str  # the subscribed entity (0x address)
+    wallet: str  # the address inside the entity that traded
+    ts: str  # block time, UTC, "YYYY-MM-DD HH:MM:SS"
+    block: int
+    blockHash: str
+    txHash: str
+    logIndex: int
+    exchange: str
+    side: Literal["BUY", "SELL"]
+    role: Literal["maker", "taker"]
+    tokenId: str  # Polymarket outcome token id (uint256, decimal string)
+    price: str  # decimal string, e.g. "0.570000"
+    shares: str  # integer string, 1e-6 share units
+    usdc: str  # integer string, 1e-6 USDC units
+    fee: str  # integer string, 1e-6 USDC units
+
+
+class FillCursor(TypedDict):
+    sinceBlock: int
+    sinceLogIndex: int
+
+
+class FillsPage(TypedDict):
+    rows: list[Fill]
+    next: Optional[FillCursor]
+    subscriptions: int
+
+
+Subscription = dict[str, Any]
+Leaderboard = dict[str, Any]

pmwallets/webhook.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+from typing import Optional, Union
+
+_HEX = re.compile(r"^[0-9a-fA-F]+$")
+
+
+def verify_webhook(raw_body: Union[bytes, str], signature_hex: Optional[str], secret: str) -> bool:
+    """Verify `x-pmw-signature`: hex HMAC-SHA256 of the RAW request body, keyed with your webhook secret.
+
+    Pass the raw bytes, before any JSON parsing — re-serialising changes them and every check fails.
+    """
+    if not signature_hex or not secret or not _HEX.match(signature_hex) or len(signature_hex) % 2:
+        return False
+    body = raw_body.encode() if isinstance(raw_body, str) else raw_body
+    mine = hmac.new(secret.encode(), body, hashlib.sha256).digest()
+    return hmac.compare_digest(bytes.fromhex(signature_hex), mine)

pmwallets-0.1.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: pmwallets
+Version: 0.1.0
+Summary: Official PMWallets SDK: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks and exports.
+Project-URL: Homepage, https://pmwallets.com/docs
+Project-URL: Repository, https://github.com/polymarketwallets/pmwallets-python
+Project-URL: Issues, https://github.com/polymarketwallets/pmwallets-python/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: copy-trading,pmwallets,polymarket,prediction-markets,smart-money,wallet-tracker
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: websockets>=15
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# pmwallets — Python SDK for PMWallets
+
+[![PyPI](https://img.shields.io/pypi/v/pmwallets.svg)](https://pypi.org/project/pmwallets/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+Official Python client for [PMWallets](https://pmwallets.com): the **Polymarket smart-money leaderboard** computed
+from the Polygon chain, and the **real-time fills of the Polymarket wallets you follow** — delivered in order,
+exactly once, with every gap replayed.
+
+[中文说明](README.zh.md) · Node.js SDK: [pmwallets-node](https://github.com/polymarketwallets/pmwallets-node) ·
+Ready-to-run copy-trading bot built on it: [polymarket-copy-trading-bot-python](https://github.com/polymarketwallets/polymarket-copy-trading-bot-python)
+
+## Install
+
+```bash
+pip install pmwallets     # Python ≥ 3.10
+```
+
+Create an API key on [pmwallets.com/keys](https://pmwallets.com/keys).
+
+## Usage
+
+```python
+import asyncio
+from pmwallets import AsyncClient, Client, FillStream, FileStateStore
+
+# synchronous REST
+with Client(api_key="pmw_...") as pmw:
+    board = pmw.leaderboard(minWinLo=0.55, minEligible=30, style="taker", status="active", limit=50)
+    pmw.subscribe(board["rows"][0]["entityId"], channels=["ws"])   # billed per entity per hour
+
+# every fill of every entity you follow
+async def main():
+    async with AsyncClient(api_key="pmw_...") as pmw:
+        stream = FillStream(
+            client=pmw,
+            store=FileStateStore("stream.json"),     # a restart resumes exactly where it stopped
+            on_fill=lambda fill, meta: print(meta.source, fill["side"], fill["price"], fill["tokenId"]),
+        )
+        await stream.run()
+
+asyncio.run(main())
+```
+
+## What is in it
+
+| | |
+|---|---|
+| `Client` / `AsyncClient` | leaderboard, entities, address unlocks, subscriptions, fills replay (`fills`, `fills_since`), trade-history exports |
+| `FillStream` | asyncio WebSocket with reconnect and keep-alive; detects missed frames by `session`/`seq` and replays them from the last fill delivered; de-duplicates by `eventId`; anchors behind the chain head on first start; persisted cursor |
+| `verify_webhook(raw_body, signature, secret)` | checks `x-pmw-signature` (HMAC-SHA256 of the raw body) |
+
+One stream per account: the newest connection wins, so run one consumer per API account. `HTTPS_PROXY` is honoured.
+
+## Resources
+
+- [Polymarket smart-money leaderboard](https://pmwallets.com) — profitable Polymarket traders scored from the Polygon chain, with win-rate confidence intervals
+- [Polymarket copy trading guide](https://pmwallets.com/copy-trading) — which wallets are worth following and how to get their fills in time
+- [How to learn from Polymarket smart money](https://pmwallets.com/learn) — reading a trader's record: confidence intervals, maker vs taker, market specialism
+- [PMWallets API documentation](https://pmwallets.com/docs) — WebSocket and webhook fill push, fills replay, trade-history exports
+- [Measured fill-push latency](https://pmwallets.com/latency) — block-to-push p50 / p95, published live
+- [Ways to follow Polymarket wallets, compared](https://pmwallets.com/compare) — official leaderboard, free trackers, SQL dashboards
+- [FAQ](https://pmwallets.com/faq) · [中文站](https://pmwallets.com/zh)
+
+## License
+
+MIT

pmwallets-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pmwallets/__init__.py,sha256=2DKRRc521D10ThunksJ21MkRht5sMiLSCXs8fWB1NJE,618
+pmwallets/client.py,sha256=HNruqJpsUw50-zJI7fhEiFvX5qyO3OvrLhvPhB9MNvw,10821
+pmwallets/stream.py,sha256=BXyrjQRI_O_1gPddLGx8TvPtHIucjp4084biFx_OuO0,14135
+pmwallets/types.py,sha256=SgWBRE6js1QJOvoCdxZLi_DMgWW3dk0E2rDJckYm03Q,1166
+pmwallets/webhook.py,sha256=YV0t8YEqg5WSbIkF3u2Uuy33fVoAkl-34gNa0sBBjAg,793
+pmwallets-0.1.0.dist-info/METADATA,sha256=cbrUv6O_WJ0scjDGTmwSIdJk-qIymbDHlBhgL4yvXOA,4069
+pmwallets-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pmwallets-0.1.0.dist-info/licenses/LICENSE,sha256=nwgseDA8QSmr2yXioOFDRfUAqAw6ZZ85NTWBC6luvEg,1066
+pmwallets-0.1.0.dist-info/RECORD,,

pmwallets-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pmwallets-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PMWallets
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.