pmwallets 0.1.2__tar.gz → 0.3.0__tar.gz

{pmwallets-0.1.2 → pmwallets-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pmwallets
-Version: 0.1.2
+Version: 0.3.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
@@ -53,6 +53,8 @@ async def main():
             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"]),
+            on_event=lambda e: e["type"] == "fatal" and print(e["error"]),   # e.g. another bot already holds the stream
+            # takeover=True,   # replace whichever API client holds this account's stream (it stops with "replaced")
         )
         await stream.run()
 
@@ -67,9 +69,29 @@ asyncio.run(main())
 | `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. An API-key connection takes priority over the pmwallets.com feed page (the page never takes the stream from it); between two API connections the newest wins, so run one consumer per account. `HTTPS_PROXY` is honoured.
+One stream per account:
 
-PMWallets' servers are in the United Kingdom: a consumer hosted in the UK or elsewhere in Europe receives fills soonest.
+- An API-key connection takes priority over the pmwallets.com feed page (the page never takes the stream from it).
+- Between two API connections **the first one keeps the stream**. A second one — another key of the same account, or the same bot started twice — is refused: `blocked`, then `fatal`, and the stream stops. Pass `takeover=True` to replace the holder instead; the holder gets `replaced`, then `fatal`, and stops (it does not fight back).
+- A `FillStream` identifies itself with a random `client_id`, so its own reconnects after a network drop replace its own dead connection without needing `takeover`.
+- When the server restarts it closes the socket with `1012`; the stream reconnects at once (event `restarting`) and replays anything it missed.
+
+`HTTPS_PROXY` is honoured.
+
+PMWallets' servers are in the United Kingdom. A consumer that also trades on Polymarket should run from Ireland (AWS eu-west-1): Polymarket does not accept API orders from the UK, the US and several EU countries.
+
+## Trade-history exports
+
+A purchase is access to files: one zstd-compressed CSV per wallet per UTC day, downloadable at once and again later.
+
+```python
+order = client.create_export(["0x…"], "2026-09-01", "2026-09-30")
+for f in client.export_files(order["id"])["files"]:
+    data = client.download_export_file(f["wallet"], f["day"])  # .csv.zst
+    # pandas: pd.read_csv(io.BytesIO(data), compression="zstd")
+```
+
+`export_file_url(wallet, day)` returns the short-lived link instead; the API key is never sent to the storage host.
 
 ## Resources
 

{pmwallets-0.1.2 → pmwallets-0.3.0}/README.md

@@ -35,6 +35,8 @@ async def main():
             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"]),
+            on_event=lambda e: e["type"] == "fatal" and print(e["error"]),   # e.g. another bot already holds the stream
+            # takeover=True,   # replace whichever API client holds this account's stream (it stops with "replaced")
         )
         await stream.run()
 
@@ -49,9 +51,29 @@ asyncio.run(main())
 | `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. An API-key connection takes priority over the pmwallets.com feed page (the page never takes the stream from it); between two API connections the newest wins, so run one consumer per account. `HTTPS_PROXY` is honoured.
+One stream per account:
 
-PMWallets' servers are in the United Kingdom: a consumer hosted in the UK or elsewhere in Europe receives fills soonest.
+- An API-key connection takes priority over the pmwallets.com feed page (the page never takes the stream from it).
+- Between two API connections **the first one keeps the stream**. A second one — another key of the same account, or the same bot started twice — is refused: `blocked`, then `fatal`, and the stream stops. Pass `takeover=True` to replace the holder instead; the holder gets `replaced`, then `fatal`, and stops (it does not fight back).
+- A `FillStream` identifies itself with a random `client_id`, so its own reconnects after a network drop replace its own dead connection without needing `takeover`.
+- When the server restarts it closes the socket with `1012`; the stream reconnects at once (event `restarting`) and replays anything it missed.
+
+`HTTPS_PROXY` is honoured.
+
+PMWallets' servers are in the United Kingdom. A consumer that also trades on Polymarket should run from Ireland (AWS eu-west-1): Polymarket does not accept API orders from the UK, the US and several EU countries.
+
+## Trade-history exports
+
+A purchase is access to files: one zstd-compressed CSV per wallet per UTC day, downloadable at once and again later.
+
+```python
+order = client.create_export(["0x…"], "2026-09-01", "2026-09-30")
+for f in client.export_files(order["id"])["files"]:
+    data = client.download_export_file(f["wallet"], f["day"])  # .csv.zst
+    # pandas: pd.read_csv(io.BytesIO(data), compression="zstd")
+```
+
+`export_file_url(wallet, day)` returns the short-lived link instead; the API key is never sent to the storage host.
 
 ## Resources
 

{pmwallets-0.1.2 → pmwallets-0.3.0}/README.zh.md

@@ -26,7 +26,20 @@ pip install pmwallets     # Python ≥ 3.10
 
 每个账户只有一条推送流。API key 建立的连接优先于 pmwallets.com 的推送页；两条 API 连接之间仍是后连的顶掉先连的。支持 `HTTPS_PROXY`。
 
-PMWallets 的服务器在英国：消费者部署在英国或欧洲其他地区，收到成交最快。
+PMWallets 的服务器在英国。若还要在 Polymarket 下单，请部署在爱尔兰（AWS eu-west-1）：Polymarket 不接受来自英国、美国及部分欧盟国家的 API 订单。
+
+## 历史成交导出
+
+购买得到的是文件的访问权:每个钱包每个 UTC 日一个 zstd 压缩的 CSV,付款后立即可下载,之后也能再下。
+
+```python
+order = client.create_export(["0x…"], "2026-09-01", "2026-09-30")
+for f in client.export_files(order["id"])["files"]:
+    data = client.download_export_file(f["wallet"], f["day"])  # .csv.zst
+    # pandas: pd.read_csv(io.BytesIO(data), compression="zstd")
+```
+
+`export_file_url(wallet, day)` 只返回短时效链接;API key 不会发给存储服务。
 
 ## 相关链接
 

{pmwallets-0.1.2 → pmwallets-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pmwallets"
-version = "0.1.2"
+version = "0.3.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"

pmwallets-0.3.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 CLOSE_API_SEAT_TAKEN, CLOSE_SERVICE_RESTART, 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",
+    "CLOSE_API_SEAT_TAKEN", "CLOSE_SERVICE_RESTART", "FileStateStore", "FillMeta", "FillStream", "MemoryStateStore", "StreamState", "UpgradeRefused", "websockets_connector",
+    "Fill", "FillCursor", "FillsPage", "verify_webhook",
+]
+__version__ = "0.2.0"

{pmwallets-0.1.2 → pmwallets-0.3.0}/src/pmwallets/client.py

@@ -63,6 +63,15 @@ class _Base:
             raise PmwError(res.status_code, body)
         return body if text else None
 
+    @classmethod
+    def _location(cls, res: httpx.Response) -> str:
+        """The redirect target of a purchased-file request; anything else is raised as PmwError."""
+        loc = res.headers.get("location")
+        if 300 <= res.status_code < 400 and loc:
+            return loc
+        cls._parse(res)
+        raise PmwError(res.status_code, res.text, "expected a redirect to the file")
+
     @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}
@@ -154,9 +163,22 @@ class Client(_Base):
     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")
+    def export_files(self, export_id: str) -> dict[str, Any]:
+        """The daily files an export grants: one per wallet per UTC day."""
+        return self.request("GET", f"/v1/account/exports/{_q(export_id)}/files")
+
+    def export_file_url(self, wallet: str, day: str) -> str:
+        """A short-lived (5 minute) link to one purchased daily file. The redirect is read, not followed,
+        so the API key is never sent to the storage host."""
+        res = self._http.request("GET", self.base_url + f"/v1/account/data/{_q(wallet)}/{_q(day)}", headers=self._headers, follow_redirects=False)
+        return self._location(res)
+
+    def download_export_file(self, wallet: str, day: str) -> bytes:
+        """One purchased daily file: zstd-compressed CSV bytes (.csv.zst)."""
+        res = self._http.get(self.export_file_url(wallet, day), timeout=max(self.timeout, 60.0))
+        if res.status_code != 200:
+            raise PmwError(res.status_code, res.text)
+        return res.content
 
 
 class AsyncClient(_Base):
@@ -233,5 +255,15 @@ class AsyncClient(_Base):
     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")
+    async def export_files(self, export_id: str) -> dict[str, Any]:
+        return await self.request("GET", f"/v1/account/exports/{_q(export_id)}/files")
+
+    async def export_file_url(self, wallet: str, day: str) -> str:
+        res = await self._http.request("GET", self.base_url + f"/v1/account/data/{_q(wallet)}/{_q(day)}", headers=self._headers, follow_redirects=False)
+        return self._location(res)
+
+    async def download_export_file(self, wallet: str, day: str) -> bytes:
+        res = await self._http.get(await self.export_file_url(wallet, day), timeout=max(self.timeout, 60.0))
+        if res.status_code != 200:
+            raise PmwError(res.status_code, res.text)
+        return res.content

{pmwallets-0.1.2 → pmwallets-0.3.0}/src/pmwallets/stream.py

@@ -5,14 +5,22 @@ import contextlib
 import json
 import math
 import os
+import re
+import secrets
 from collections import OrderedDict
 from dataclasses import asdict, dataclass
 from pathlib import Path
 from typing import Any, AsyncContextManager, Awaitable, Callable, Optional, Protocol, Union
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
 
 from .client import AsyncClient
 from .types import Fill
 
+# close codes the server uses (see the WebSocket section of the API docs)
+CLOSE_SERVICE_RESTART = 1012  # the server is restarting: reconnect at once
+CLOSE_API_SEAT_TAKEN = 4411  # another API client of this account holds the stream
+_CLIENT_ID = re.compile(r"[A-Za-z0-9_-]{8,64}")
+
 
 @dataclass
 class StreamState:
@@ -135,6 +143,8 @@ class FillStream:
         ws_options: Optional[dict[str, Any]] = None,
         replay_without_cursor: bool = False,
         anchor_lag_blocks: int = 200,
+        takeover: bool = False,
+        client_id: Optional[str] = None,
     ) -> None:
         self.client = client
         self.on_fill = on_fill
@@ -152,6 +162,16 @@ class FillStream:
         # 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
+        # One stream per account, and the API client that connected FIRST keeps it: a second one is refused
+        # ("blocked", then "fatal"). takeover=True replaces whichever client holds it — that client is told
+        # "replaced" and stops. Only the first connection asks; our own reconnects are recognised by client_id.
+        self.takeover = takeover
+        self._ask_takeover = takeover
+        # Identifies this stream so its own reconnects replace its own dead connection instead of being refused
+        # by it. Default: random per FillStream.
+        self.client_id = client_id if client_id is not None else secrets.token_urlsafe(16)
+        if not _CLIENT_ID.fullmatch(self.client_id):
+            raise ValueError("client_id must be 8-64 characters of [A-Za-z0-9_-]")
         self.connector = connector or websockets_connector(ping_interval, **(ws_options or {}))
         self.state = StreamState()
         self._seen: "OrderedDict[str, bool]" = OrderedDict()
@@ -203,17 +223,29 @@ class FillStream:
     async def _loop(self) -> None:
         backoff = self.min_backoff
         while self._running:
-            healthy = await self._connect_once()
+            healthy, code = await self._connect_once()
             if not self._running:
                 break
+            if code == CLOSE_SERVICE_RESTART:  # the server's replacement is taking over now: reconnect at once
+                backoff = self.min_backoff
+                continue
             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
+    def _url(self) -> str:
+        """The stream URL with this client's identity (and, before the first hello, the takeover request)."""
+        u = urlsplit(self.client.ws_url)
+        q = [(k, v) for k, v in parse_qsl(u.query) if k not in ("clientId", "takeover")]
+        q.append(("clientId", self.client_id))
+        if self._ask_takeover:
+            q.append(("takeover", "1"))
+        return urlunsplit(u._replace(query=urlencode(q)))
+
+    async def _connect_once(self) -> tuple[bool, int]:
+        """One connection's life: (got as far as a hello and did not fail, the close code)."""
+        url = self._url()
         self._emit({"type": "connecting", "url": url})
         greeted = False
         failed = False
@@ -248,16 +280,25 @@ class FillStream:
                 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
+            return False, 0
         except Exception as e:
             self._emit({"type": "error", "error": e})
-            return False
+            return False, 0
         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
+        if code == 1000 and "replaced" in reason.lower() and self._running:
+            # another client took over: reconnecting would take the stream back and the two would fight
+            self._running = False
+            self._emit({"type": "replaced"})
+            self._emit({"type": "fatal", "error": RuntimeError("another API client of this account took the stream over (takeover); this stream has stopped")})
+        elif code == CLOSE_API_SEAT_TAKEN and self._running:
+            self._running = False
+            self._emit({"type": "blocked"})
+            self._emit({"type": "fatal", "error": RuntimeError("another API client of this account already holds the stream (one per account; the first one keeps it). Stop it, or pass takeover=True to replace it")})
+        elif code == CLOSE_SERVICE_RESTART:
+            self._emit({"type": "restarting"})
+        return greeted and not failed, code
 
     async def _handle_frame(self, m: dict[str, Any]) -> None:
         if m.get("type") == "hello" and isinstance(m.get("session"), str):
@@ -270,6 +311,7 @@ class FillStream:
             self.state.session = m["session"]
             self.state.seq = int(m.get("seq") or 0)
             await self.store.save(self.state)
+            self._ask_takeover = False  # seated: from here on our own client_id is what gets us back in
             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):

{pmwallets-0.1.2 → pmwallets-0.3.0}/tests/test_client.py

@@ -56,3 +56,38 @@ def test_verify_webhook():
     assert not verify_webhook(body, sig, "other")
     assert not verify_webhook(body, "zz", "sec")
     assert not verify_webhook(body, None, "sec")
+
+
+W = "0x" + "ab" * 20
+
+
+def _file_transport(calls):
+    def handler(req: httpx.Request):
+        calls.append(req)
+        if req.url.host == "api.example.com":
+            return httpx.Response(302, headers={"location": "https://r2.example/signed"})
+        return httpx.Response(200, content=b"\x01\x02\x03")
+    return httpx.MockTransport(handler)
+
+
+def test_download_reads_the_redirect_and_never_sends_the_key_to_storage():
+    calls = []
+    c = Client("pmw_a_b", "https://api.example.com", http=httpx.Client(transport=_file_transport(calls)))
+    assert c.download_export_file(W, "2026-09-25") == b"\x01\x02\x03"
+    assert str(calls[0].url) == f"https://api.example.com/v1/account/data/{W}/2026-09-25"
+    assert str(calls[1].url) == "https://r2.example/signed"
+    assert "x-api-key" not in calls[1].headers
+
+
+async def test_async_download_reads_the_redirect():
+    calls = []
+    c = AsyncClient("pmw_a_b", "https://api.example.com", http=httpx.AsyncClient(transport=_file_transport(calls)))
+    assert await c.download_export_file(W, "2026-09-25") == b"\x01\x02\x03"
+    assert "x-api-key" not in calls[1].headers
+
+
+def test_no_purchased_file_is_pmw_error():
+    c = Client("k", http=httpx.Client(transport=transport([{"statusCode": 404, "message": "no purchased file for this wallet and day"}], 404)))
+    with pytest.raises(PmwError) as e:
+        c.export_file_url(W, "2026-09-25")
+    assert e.value.status == 404

{pmwallets-0.1.2 → pmwallets-0.3.0}/tests/test_stream.py

@@ -2,6 +2,9 @@ import asyncio
 import contextlib
 import json
 
+import pytest
+from urllib.parse import parse_qs, urlsplit
+
 from pmwallets.stream import FileStateStore, FillStream, MemoryStateStore, UpgradeRefused
 
 
@@ -68,13 +71,14 @@ class FakeClient:
                 yield f
 
 
-def harness(ledger, fail_on=None, refuse=None, head=209):
-    sockets, delivered, events = [], [], []
+def harness(ledger, fail_on=None, refuse=None, head=209, takeover=False, min_backoff=0.001):
+    sockets, delivered, events, urls = [], [], [], []
     client = FakeClient(ledger, head)
     state = {"fail": fail_on}
 
     @contextlib.asynccontextmanager
     async def connector(url, headers):
+        urls.append(parse_qs(urlsplit(url).query))
         if refuse:
             raise UpgradeRefused(refuse)
         s = FakeSocket()
@@ -90,8 +94,9 @@ def harness(ledger, fail_on=None, refuse=None, head=209):
             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)
+    stream = FillStream(client, on_fill, on_event=events.append, store=MemoryStateStore(), min_backoff=min_backoff,
+                        max_backoff=max(min_backoff, 0.002), connector=connector, takeover=takeover)
+    stream.urls = urls
     return stream, sockets, client, delivered, events
 
 
@@ -171,15 +176,68 @@ async def test_401_is_fatal():
     assert [e["type"] for e in events].count("connecting") == 1
 
 
-async def test_reports_takeover():
+async def test_replaced_by_takeover_stops_for_good():
     stream, sockets, _, _, events = harness([])
     await stream.start(); await tick()
     sockets[0].remote_close(1000, "replaced by a newer connection")
+    await asyncio.wait_for(stream.wait(), 1)
+    types = [e["type"] for e in events]
+    assert "replaced" in types and "fatal" in types
+    assert len(sockets) == 1  # reconnecting would take the stream back and the two would fight
+
+
+async def test_refused_4411_stops_and_says_how_to_take_over():
+    stream, sockets, _, _, events = harness([])
+    await stream.start(); await tick()
+    sockets[0].send({"type": "blocked", "reason": "api_seat_taken"})
+    sockets[0].remote_close(4411, "another API client is connected")
+    await asyncio.wait_for(stream.wait(), 1)
+    assert any(e["type"] == "blocked" for e in events)
+    fatal = [e for e in events if e["type"] == "fatal"]
+    assert fatal and "takeover" in str(fatal[0]["error"])
+    assert len(sockets) == 1
+
+
+async def test_server_restart_1012_reconnects_at_once():
+    stream, sockets, _, _, events = harness([], min_backoff=60)  # a backoff the test would time out waiting for
+    await stream.start(); await tick()
+    sockets[0].send({"type": "hello", "session": "A", "seq": 0})
     await tick()
-    assert any(e["type"] == "replaced" for e in events)
+    sockets[0].remote_close(1012, "service restart; reconnect now")
+    await tick(); await tick()
+    assert any(e["type"] == "restarting" for e in events)
+    assert len(sockets) == 2
     await stream.stop()
 
 
+async def test_client_id_on_every_connection_takeover_only_until_seated():
+    stream, sockets, _, _, _ = harness([], takeover=True)
+    await stream.start(); await tick()
+    sockets[0].send({"type": "hello", "session": "A", "seq": 0})
+    await tick()
+    sockets[0].remote_close(1006, "")
+    await tick(); await tick()
+    assert len(stream.urls) == 2
+    cid = stream.urls[0]["clientId"][0]
+    assert 8 <= len(cid) <= 64
+    assert stream.urls[1]["clientId"] == [cid]  # the same id, so the server knows it is us coming back
+    assert stream.urls[0]["takeover"] == ["1"]
+    assert "takeover" not in stream.urls[1]  # a reconnect must not snatch the stream from a client that took it meanwhile
+    await stream.stop()
+
+
+async def test_never_asks_to_take_over_unless_told():
+    stream, sockets, _, _, _ = harness([])
+    await stream.start(); await tick()
+    assert "takeover" not in stream.urls[0]
+    await stream.stop()
+
+
+def test_malformed_client_id_is_refused():
+    with pytest.raises(ValueError, match="client_id"):
+        FillStream(FakeClient([]), lambda f, m: None, client_id="short")
+
+
 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).