pmwallets 0.1.0__tar.gz

pmwallets-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e '.[dev]'
+      - run: pytest -q

pmwallets-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+# Publishes to PyPI through a Trusted Publisher (OIDC): no token is stored anywhere.
+# Release = push a tag v<version> matching pyproject.toml.
+name: publish
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: tag must match the package version
+        run: |
+          v=$(python -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "v$v" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != v$v"; exit 1; }
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

pmwallets-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.egg-info/
+.venv/
+.pytest_cache/
+build/
+dist/
+.env
+config.yaml
+pmw-data/

pmwallets-0.1.0/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.

pmwallets-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,66 @@
+# 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/README.zh.md

@@ -0,0 +1,41 @@
+# pmwallets —— PMWallets Python SDK
+
+[![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)
+
+[PMWallets](https://pmwallets.com/zh) 官方 Python 客户端：从 Polygon 链上计算的 **Polymarket 聪明钱排行榜**，以及**你所跟踪的
+Polymarket 钱包的实时成交** —— 按顺序、只送一次、漏掉的自动补发。
+
+[English](README.md) · Node.js SDK：[pmwallets-node](https://github.com/polymarketwallets/pmwallets-node) ·
+基于它的开箱即用跟单机器人：[polymarket-copy-trading-bot-python](https://github.com/polymarketwallets/polymarket-copy-trading-bot-python)
+
+## 安装
+
+```bash
+pip install pmwallets     # Python ≥ 3.10
+```
+
+在 [pmwallets.com/keys](https://pmwallets.com/keys) 创建 API key。用法示例见 [README.md](README.md#usage)。
+
+## 包含什么
+
+| | |
+|---|---|
+| `Client` / `AsyncClient` | 排行榜、实体、地址解锁、订阅、成交补发（`fills`、`fills_since`）、交易历史导出 |
+| `FillStream` | asyncio WebSocket，自动重连与保活；按 `session`/`seq` 发现漏帧并从最后送达的成交补发；按 `eventId` 去重；首次启动锚定在链头之后；游标持久化 |
+| `verify_webhook(raw_body, signature, secret)` | 校验 `x-pmw-signature`（原始 body 的 HMAC-SHA256） |
+
+每个账户只有一条推送流，后连上的会顶掉先连的。支持 `HTTPS_PROXY`。
+
+## 相关链接
+
+- [Polymarket 聪明钱排行榜](https://pmwallets.com/zh) —— 从 Polygon 链上计算的 Polymarket 盈利交易者，胜率带置信区间
+- [Polymarket 跟单指南](https://pmwallets.com/zh/copy-trading) —— 哪些钱包值得跟，以及怎样及时拿到他们的成交
+- [怎样向 Polymarket 聪明钱学习](https://pmwallets.com/zh/learn) —— 读懂一份战绩：置信区间、挂单与吃单、擅长的市场
+- [PMWallets API 文档](https://pmwallets.com/zh/docs) —— WebSocket 与 Webhook 成交推送、补发接口、交易历史导出
+- [成交推送实测延迟](https://pmwallets.com/zh/latency) —— 出块到推送的 p50 / p95，实时公布
+- [追踪 Polymarket 钱包的几种做法对比](https://pmwallets.com/zh/compare) —— 官方榜单、免费追踪器、SQL 看板
+- [常见问题](https://pmwallets.com/zh/faq) · [English site](https://pmwallets.com)
+
+## 许可证
+
+MIT

pmwallets-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pmwallets"
+version = "0.1.0"
+description = "Official PMWallets SDK: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks and exports."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = ["polymarket", "copy-trading", "wallet-tracker", "smart-money", "pmwallets", "prediction-markets"]
+dependencies = ["httpx>=0.27", "websockets>=15"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://pmwallets.com/docs"
+Repository = "https://github.com/polymarketwallets/pmwallets-python"
+Issues = "https://github.com/polymarketwallets/pmwallets-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pmwallets"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

pmwallets-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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/tests/test_client.py

@@ -0,0 +1,58 @@
+import hashlib
+import hmac
+import json
+
+import httpx
+import pytest
+
+from pmwallets import AsyncClient, Client, PmwError, verify_webhook
+
+
+def transport(pages, status=200, calls=None):
+    def handler(req: httpx.Request):
+        if calls is not None:
+            calls.append(req)
+        body = pages.pop(0) if pages else None
+        return httpx.Response(status, text="" if body is None else json.dumps(body))
+    return httpx.MockTransport(handler)
+
+
+def test_sends_key_builds_query_and_ws_url():
+    calls = []
+    c = Client("pmw_a_b", "https://api.example.com/", http=httpx.Client(transport=transport([{"rows": [], "next": None, "subscriptions": 0}], calls=calls)))
+    c.fills(5, 2)
+    assert str(calls[0].url) == "https://api.example.com/v1/account/fills?sinceBlock=5&sinceLogIndex=2&limit=500"
+    assert calls[0].headers["x-api-key"] == "pmw_a_b"
+    assert c.ws_url == "wss://api.example.com/v1/ws"
+
+
+async def test_walks_every_page():
+    calls = []
+    pages = [
+        {"rows": [{"eventId": "a"}, {"eventId": "b"}], "next": {"sinceBlock": 2, "sinceLogIndex": 0}, "subscriptions": 1},
+        {"rows": [{"eventId": "c"}], "next": None, "subscriptions": 1},
+    ]
+    c = AsyncClient("k", http=httpx.AsyncClient(transport=transport(pages, calls=calls)))
+    ids = [r["eventId"] async for r in c.fills_since({"sinceBlock": 0, "sinceLogIndex": 0}, 2)]
+    assert ids == ["a", "b", "c"]
+    assert "sinceBlock=2&sinceLogIndex=0&limit=2" in str(calls[1].url)
+
+
+def test_non_2xx_is_pmw_error():
+    calls = []
+    c = Client("k", http=httpx.Client(transport=transport([{"statusCode": 402, "message": "insufficient balance"}], 402, calls)))
+    with pytest.raises(PmwError) as e:
+        c.subscribe("0xabc")
+    assert e.value.status == 402 and e.value.body["message"] == "insufficient balance"
+    assert json.loads(calls[0].content) == {"channels": ["ws"], "entityId": "0xabc"}
+
+
+def test_verify_webhook():
+    body = '{"type":"fill","data":{}}'
+    sig = hmac.new(b"sec", body.encode(), hashlib.sha256).hexdigest()
+    assert verify_webhook(body, sig, "sec")
+    assert verify_webhook(body.encode(), sig, "sec")
+    assert not verify_webhook(body + " ", sig, "sec")
+    assert not verify_webhook(body, sig, "other")
+    assert not verify_webhook(body, "zz", "sec")
+    assert not verify_webhook(body, None, "sec")

pmwallets-0.1.0/tests/test_real_socket.py

@@ -0,0 +1,53 @@
+import asyncio
+import json
+
+import httpx
+
+from websockets.asyncio.server import serve
+from websockets.http11 import Response
+from websockets.datastructures import Headers
+
+from pmwallets import AsyncClient, FillStream
+
+
+async def _server():
+    def process_request(conn, request):
+        if request.path.startswith("/v1/latency"):
+            return Response(200, "OK", Headers([("Content-Type", "application/json")]), b'{"head":{"block":1}}')
+        if request.headers.get("x-api-key") != "good":
+            return Response(401, "Unauthorized", Headers([("Content-Length", "0")]), b"")
+        return None
+
+    async def handler(ws):
+        await ws.send(json.dumps({"type": "hello", "userId": "u", "session": "S", "seq": 0}))
+        await ws.send(json.dumps({"type": "fill", "session": "S", "seq": 1, "data": {"eventId": "e1", "block": 2, "logIndex": 0}}))
+        await ws.wait_closed()
+
+    server = await serve(handler, "127.0.0.1", 0, process_request=process_request)
+    port = server.sockets[0].getsockname()[1]
+    return server, f"http://127.0.0.1:{port}"
+
+
+async def test_receives_frames_with_a_good_key():
+    server, base = await _server()
+    got = []
+    stream = FillStream(AsyncClient("good", base, http=httpx.AsyncClient(trust_env=False)), lambda f, m: got.append(f["eventId"]), ws_options={"proxy": None})
+    await stream.start()
+    for _ in range(50):
+        if got:
+            break
+        await asyncio.sleep(0.02)
+    await stream.stop()
+    server.close()
+    assert got == ["e1"]
+
+
+async def test_fatal_on_401():
+    server, base = await _server()
+    events = []
+    stream = FillStream(AsyncClient("bad", base), lambda f, m: None, on_event=events.append, min_backoff=0.005, ws_options={"proxy": None})
+    await stream.start()
+    await asyncio.wait_for(stream.wait(), 2)
+    server.close()
+    types = [e["type"] for e in events]
+    assert types.count("fatal") == 1 and types.count("connecting") == 1

pmwallets-0.1.0/tests/test_stream.py

@@ -0,0 +1,207 @@
+import asyncio
+import contextlib
+import json
+
+from pmwallets.stream import FileStateStore, FillStream, MemoryStateStore, UpgradeRefused
+
+
+def fill(block, log_index):
+    return {
+        "eventId": f"137:{block}:0xh:0xt{block}:{log_index}", "chain": 137, "entityId": "0xe", "wallet": "0xw",
+        "ts": "2026-09-24 00:00:00", "block": block, "blockHash": "0xh", "txHash": f"0xt{block}", "logIndex": log_index,
+        "exchange": "pm_ctf_v2", "side": "BUY", "role": "taker", "tokenId": "1", "price": "0.5", "shares": "1000000",
+        "usdc": "500000", "fee": "0",
+    }
+
+
+_END = object()
+
+
+class FakeSocket:
+    """a scripted socket: the test pushes frames and closes it"""
+
+    def __init__(self):
+        self.q: asyncio.Queue = asyncio.Queue()
+        self.close_code = None
+        self.close_reason = None
+        self.closed = False
+
+    def send(self, frame):
+        self.q.put_nowait(json.dumps(frame))
+
+    def remote_close(self, code=1006, reason=""):
+        self.close_code, self.close_reason = code, reason
+        self.q.put_nowait(_END)
+
+    async def close(self, code=1000, reason=""):
+        self.closed = True
+        if self.close_code is None:
+            self.close_code, self.close_reason = code, reason
+        self.q.put_nowait(_END)
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        item = await self.q.get()
+        if item is _END:
+            raise StopAsyncIteration
+        return item
+
+
+class FakeClient:
+    api_key = "pmw_x_y"
+    ws_url = "wss://example/v1/ws"
+
+    def __init__(self, ledger, head=209):
+        self.ledger = ledger
+        self.replays = []
+        self.head = head
+
+    async def latency(self):
+        return {"head": {"block": self.head}}
+
+    async def fills_since(self, c):
+        self.replays.append(dict(c))
+        for f in self.ledger:
+            if f["block"] > c["sinceBlock"] or (f["block"] == c["sinceBlock"] and f["logIndex"] > c["sinceLogIndex"]):
+                yield f
+
+
+def harness(ledger, fail_on=None, refuse=None, head=209):
+    sockets, delivered, events = [], [], []
+    client = FakeClient(ledger, head)
+    state = {"fail": fail_on}
+
+    @contextlib.asynccontextmanager
+    async def connector(url, headers):
+        if refuse:
+            raise UpgradeRefused(refuse)
+        s = FakeSocket()
+        sockets.append(s)
+        try:
+            yield s
+        finally:
+            s.closed = True
+
+    def on_fill(f, meta):
+        if state["fail"] == f["eventId"]:
+            state["fail"] = None
+            raise RuntimeError("handler failed")
+        delivered.append((f["eventId"], meta.source))
+
+    stream = FillStream(client, on_fill, on_event=events.append, store=MemoryStateStore(), min_backoff=0.001,
+                        max_backoff=0.002, connector=connector)
+    return stream, sockets, client, delivered, events
+
+
+async def tick():
+    await asyncio.sleep(0.02)
+
+
+async def test_delivers_consecutive_frames_in_order():
+    stream, sockets, client, delivered, _ = harness([])
+    await stream.start(); await tick()
+    s = sockets[0]
+    s.send({"type": "hello", "session": "A", "seq": 0})
+    s.send({"type": "fill", "session": "A", "seq": 1, "data": fill(10, 1)})
+    s.send({"type": "fill", "session": "A", "seq": 2, "data": fill(10, 2)})
+    await tick()
+    assert [d[0] for d in delivered] == [fill(10, 1)["eventId"], fill(10, 2)["eventId"]]
+    assert client.replays == []
+    p = stream.position
+    assert (p.session, p.seq, p.block, p.logIndex) == ("A", 2, 10, 2)
+    await stream.stop()
+
+
+async def test_seq_skip_replays_and_drops_duplicate():
+    ledger = [fill(10, 1), fill(11, 1), fill(12, 1)]
+    stream, sockets, client, delivered, _ = harness(ledger)
+    await stream.start(); await tick()
+    s = sockets[0]
+    s.send({"type": "hello", "session": "A", "seq": 0})
+    s.send({"type": "fill", "session": "A", "seq": 1, "data": ledger[0]})
+    s.send({"type": "fill", "session": "A", "seq": 3, "data": ledger[2]})
+    await tick()
+    assert client.replays == [{"sinceBlock": 10, "sinceLogIndex": 1}]
+    assert delivered == [(ledger[0]["eventId"], "ws"), (ledger[1]["eventId"], "replay"), (ledger[2]["eventId"], "replay")]
+    assert stream.position.seq == 3 and stream.position.block == 12
+    await stream.stop()
+
+
+async def test_new_session_replays_what_was_missed():
+    ledger = [fill(10, 1), fill(11, 1)]
+    stream, sockets, client, delivered, _ = harness(ledger)
+    await stream.start(); await tick()
+    sockets[0].send({"type": "hello", "session": "A", "seq": 0})
+    sockets[0].send({"type": "fill", "session": "A", "seq": 1, "data": ledger[0]})
+    await tick()
+    sockets[0].remote_close(1006)
+    await tick()
+    sockets[1].send({"type": "hello", "session": "B", "seq": 0})
+    await tick()
+    assert client.replays == [{"sinceBlock": 10, "sinceLogIndex": 1}]
+    assert [d[0] for d in delivered] == [ledger[0]["eventId"], ledger[1]["eventId"]]
+    assert stream.position.session == "B"
+    await stream.stop()
+
+
+async def test_throwing_handler_is_redelivered_after_reconnect():
+    ledger = [fill(10, 1), fill(11, 1)]
+    stream, sockets, client, delivered, _ = harness(ledger, fail_on=ledger[1]["eventId"])
+    await stream.start(); await tick()
+    s = sockets[0]
+    s.send({"type": "hello", "session": "A", "seq": 0})
+    s.send({"type": "fill", "session": "A", "seq": 1, "data": ledger[0]})
+    s.send({"type": "fill", "session": "A", "seq": 2, "data": ledger[1]})
+    await tick()
+    assert s.closed
+    assert stream.position.seq == 1 and stream.position.block == 10
+    sockets[1].send({"type": "hello", "session": "B", "seq": 0})
+    await tick()
+    assert [d[0] for d in delivered] == [ledger[0]["eventId"], ledger[1]["eventId"]]
+    await stream.stop()
+
+
+async def test_401_is_fatal():
+    stream, sockets, _, _, events = harness([], refuse=401)
+    await stream.start()
+    await asyncio.wait_for(stream.wait(), 1)
+    assert [e["type"] for e in events].count("fatal") == 1
+    assert [e["type"] for e in events].count("connecting") == 1
+
+
+async def test_reports_takeover():
+    stream, sockets, _, _, events = harness([])
+    await stream.start(); await tick()
+    sockets[0].remote_close(1000, "replaced by a newer connection")
+    await tick()
+    assert any(e["type"] == "replaced" for e in events)
+    await stream.stop()
+
+
+async def test_anchors_behind_the_chain_head_on_first_hello():
+    # head 300, lag 200 → replay covers blocks ≥ 100. Block 99 is history; block 150 was mined before we connected
+    # but had not been pushed yet (the head ran ahead of the fill index).
+    ledger = [fill(99, 3), fill(150, 1), fill(301, 1)]
+    stream, sockets, client, delivered, events = harness(ledger, head=300)
+    await stream.start(); await tick()
+    sockets[0].send({"type": "hello", "session": "A", "seq": 0})
+    await tick()
+    assert (stream.position.block, stream.position.logIndex) == (99, 0xFFFFFFFF)
+    assert {"type": "anchored", "block": 100} in events
+    sockets[0].remote_close(1006); await tick()
+    sockets[1].send({"type": "hello", "session": "B", "seq": 0})
+    await tick()
+    assert client.replays == [{"sinceBlock": 99, "sinceLogIndex": 0xFFFFFFFF}]
+    assert [d[0] for d in delivered] == [ledger[1]["eventId"], ledger[2]["eventId"]]
+    await stream.stop()
+
+
+async def test_file_state_store_roundtrip(tmp_path):
+    from pmwallets.stream import StreamState
+    store = FileStateStore(tmp_path / "sub" / "state.json")
+    assert await store.load() is None
+    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}