pmwallets 0.4.0__tar.gz → 0.5.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: pmwallets
3
- Version: 0.4.0
3
+ Version: 0.5.1
4
4
  Summary: Official PMWallets SDK: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks and exports.
5
5
  Project-URL: Homepage, https://pmwallets.com/docs
6
6
  Project-URL: Repository, https://github.com/polymarketwallets/pmwallets-python
@@ -44,6 +44,7 @@ from pmwallets import AsyncClient, Client, FillStream, FileStateStore
44
44
  # synchronous REST
45
45
  with Client(api_key="pmw_...") as pmw:
46
46
  board = pmw.leaderboard(minWinLo=0.55, minEligible=30, style="taker", status="active", limit=50)
47
+ cheap = pmw.leaderboard(bands=[0, 1], minWinLo=0.55) # address unlocks free or in the $1 band (0 = free ... 5)
47
48
  pmw.subscribe(board["rows"][0]["entityId"], channels=["ws"]) # billed per entity per hour
48
49
 
49
50
  # every fill of every entity you follow
@@ -65,7 +66,7 @@ asyncio.run(main())
65
66
 
66
67
  | | |
67
68
  |---|---|
68
- | `Client` / `AsyncClient` | leaderboard, entities, address unlocks, your unlocked addresses (`my_addresses`), subscriptions, fills replay (`fills`, `fills_since`), trade-history exports |
69
+ | `Client` / `AsyncClient` | leaderboard, entities, address unlocks (balance or plan), your unlocked addresses (`my_addresses`), plan and balance, subscriptions, webhook status and deliveries, fills replay (`fills`, `fills_since`), trade-history exports |
69
70
  | `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 |
70
71
  | `verify_webhook(raw_body, signature, secret)` | checks `x-pmw-signature` (HMAC-SHA256 of the raw body) |
71
72
 
@@ -103,6 +104,20 @@ for f in client.export_files(order["id"])["files"]:
103
104
  - [Ways to follow Polymarket wallets, compared](https://pmwallets.com/compare) — official leaderboard, free trackers, SQL dashboards
104
105
  - [FAQ](https://pmwallets.com/faq) · [中文站](https://pmwallets.com/zh)
105
106
 
107
+ **Guides**
108
+
109
+ - [PMWallets SDKs](https://pmwallets.com/sdk) — Node.js and Python clients, side by side
110
+ - [Polymarket data in Python](https://pmwallets.com/guides/polymarket-api-python) — markets, a wallet's trades, and live fills
111
+ - [How to get a Polymarket wallet's trades in real time](https://pmwallets.com/guides/polymarket-real-time-trades-api) — polling the Data API, reading OrderFilled events on Polygon, or a pushed fill stream with replay
112
+ - [Polymarket WebSocket API](https://pmwallets.com/guides/polymarket-websocket-api) — what the market and user channels give you, and what they don't
113
+ - [Polymarket trade alerts by webhook](https://pmwallets.com/guides/polymarket-trade-alerts-webhook) — verify the HMAC-SHA256 signature, answer fast, deduplicate on eventId
114
+ - [How to export a Polymarket wallet's full trade history](https://pmwallets.com/guides/polymarket-trade-history-export) — past the Data API's 10,000-trade cap: every fill from the chain, one CSV per wallet per day
115
+ - [Polymarket token IDs, condition IDs and slugs](https://pmwallets.com/guides/polymarket-token-ids) — how they connect
116
+ - [How to calculate a Polymarket wallet's PnL](https://pmwallets.com/guides/polymarket-pnl-explained) — and why sites disagree
117
+ - [Polymarket leaderboards by category](https://pmwallets.com/leaderboard) — sports, crypto, politics, esports and more, ranked from on-chain PnL
118
+ - [Busiest Polymarket markets](https://pmwallets.com/markets) — the 1,000 most-traded markets of the last 30 days and how their traders did
119
+ - [All guides](https://pmwallets.com/guides) · [llms.txt](https://pmwallets.com/llms.txt)
120
+
106
121
  ## License
107
122
 
108
123
  MIT
@@ -26,6 +26,7 @@ from pmwallets import AsyncClient, Client, FillStream, FileStateStore
26
26
  # synchronous REST
27
27
  with Client(api_key="pmw_...") as pmw:
28
28
  board = pmw.leaderboard(minWinLo=0.55, minEligible=30, style="taker", status="active", limit=50)
29
+ cheap = pmw.leaderboard(bands=[0, 1], minWinLo=0.55) # address unlocks free or in the $1 band (0 = free ... 5)
29
30
  pmw.subscribe(board["rows"][0]["entityId"], channels=["ws"]) # billed per entity per hour
30
31
 
31
32
  # every fill of every entity you follow
@@ -47,7 +48,7 @@ asyncio.run(main())
47
48
 
48
49
  | | |
49
50
  |---|---|
50
- | `Client` / `AsyncClient` | leaderboard, entities, address unlocks, your unlocked addresses (`my_addresses`), subscriptions, fills replay (`fills`, `fills_since`), trade-history exports |
51
+ | `Client` / `AsyncClient` | leaderboard, entities, address unlocks (balance or plan), your unlocked addresses (`my_addresses`), plan and balance, subscriptions, webhook status and deliveries, fills replay (`fills`, `fills_since`), trade-history exports |
51
52
  | `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 |
52
53
  | `verify_webhook(raw_body, signature, secret)` | checks `x-pmw-signature` (HMAC-SHA256 of the raw body) |
53
54
 
@@ -85,6 +86,20 @@ for f in client.export_files(order["id"])["files"]:
85
86
  - [Ways to follow Polymarket wallets, compared](https://pmwallets.com/compare) — official leaderboard, free trackers, SQL dashboards
86
87
  - [FAQ](https://pmwallets.com/faq) · [中文站](https://pmwallets.com/zh)
87
88
 
89
+ **Guides**
90
+
91
+ - [PMWallets SDKs](https://pmwallets.com/sdk) — Node.js and Python clients, side by side
92
+ - [Polymarket data in Python](https://pmwallets.com/guides/polymarket-api-python) — markets, a wallet's trades, and live fills
93
+ - [How to get a Polymarket wallet's trades in real time](https://pmwallets.com/guides/polymarket-real-time-trades-api) — polling the Data API, reading OrderFilled events on Polygon, or a pushed fill stream with replay
94
+ - [Polymarket WebSocket API](https://pmwallets.com/guides/polymarket-websocket-api) — what the market and user channels give you, and what they don't
95
+ - [Polymarket trade alerts by webhook](https://pmwallets.com/guides/polymarket-trade-alerts-webhook) — verify the HMAC-SHA256 signature, answer fast, deduplicate on eventId
96
+ - [How to export a Polymarket wallet's full trade history](https://pmwallets.com/guides/polymarket-trade-history-export) — past the Data API's 10,000-trade cap: every fill from the chain, one CSV per wallet per day
97
+ - [Polymarket token IDs, condition IDs and slugs](https://pmwallets.com/guides/polymarket-token-ids) — how they connect
98
+ - [How to calculate a Polymarket wallet's PnL](https://pmwallets.com/guides/polymarket-pnl-explained) — and why sites disagree
99
+ - [Polymarket leaderboards by category](https://pmwallets.com/leaderboard) — sports, crypto, politics, esports and more, ranked from on-chain PnL
100
+ - [Busiest Polymarket markets](https://pmwallets.com/markets) — the 1,000 most-traded markets of the last 30 days and how their traders did
101
+ - [All guides](https://pmwallets.com/guides) · [llms.txt](https://pmwallets.com/llms.txt)
102
+
88
103
  ## License
89
104
 
90
105
  MIT
@@ -20,7 +20,7 @@ pip install pmwallets # Python ≥ 3.10
20
20
 
21
21
  | | |
22
22
  |---|---|
23
- | `Client` / `AsyncClient` | 排行榜、实体、地址解锁、我的地址(`my_addresses`)、订阅、成交补发(`fills`、`fills_since`)、交易历史导出 |
23
+ | `Client` / `AsyncClient` | 排行榜、实体、地址解锁(余额或套餐额度)、我的地址(`my_addresses`)、套餐与余额、订阅、webhook 状态与投递记录、成交补发(`fills`、`fills_since`)、交易历史导出 |
24
24
  | `FillStream` | asyncio WebSocket,自动重连与保活;按 `session`/`seq` 发现漏帧并从最后送达的成交补发;按 `eventId` 去重;首次启动锚定在链头之后;游标持久化 |
25
25
  | `verify_webhook(raw_body, signature, secret)` | 校验 `x-pmw-signature`(原始 body 的 HMAC-SHA256) |
26
26
 
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pmwallets"
7
- version = "0.4.0"
7
+ version = "0.5.1"
8
8
  description = "Official PMWallets SDK: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks and exports."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -10,4 +10,4 @@ __all__ = [
10
10
  "CLOSE_API_SEAT_TAKEN", "CLOSE_SERVICE_RESTART", "FileStateStore", "FillMeta", "FillStream", "MemoryStateStore", "StreamState", "UpgradeRefused", "websockets_connector",
11
11
  "Fill", "FillCursor", "FillsPage", "verify_webhook",
12
12
  ]
13
- __version__ = "0.2.0"
13
+ __version__ = "0.5.1"
@@ -47,7 +47,12 @@ class _Base:
47
47
  for k, v in (query or {}).items():
48
48
  if v is None:
49
49
  continue
50
- out[k] = ("true" if v else "false") if isinstance(v, bool) else v
50
+ if isinstance(v, bool):
51
+ out[k] = "true" if v else "false"
52
+ elif isinstance(v, (list, tuple)):
53
+ out[k] = ",".join(str(x) for x in v) # one comma-separated value, e.g. bands=0,2
54
+ else:
55
+ out[k] = v
51
56
  return out
52
57
 
53
58
  @staticmethod
@@ -100,6 +105,8 @@ class Client(_Base):
100
105
 
101
106
  # ── the board
102
107
  def leaderboard(self, **query: Any) -> Leaderboard:
108
+ """The board, filtered by any of the API's figures (minPnl, minWinLo, style, category, ...). `bands=[0, 1]`
109
+ keeps wallets whose address unlocks in those price bands (0 = free ... 5; the ladder is `pricing.bands`)."""
103
110
  return self.request("GET", "/v1/leaderboard", query)
104
111
 
105
112
  def my_addresses(self, **query: Any) -> Leaderboard:
@@ -116,11 +123,53 @@ class Client(_Base):
116
123
  def latency(self) -> dict[str, Any]:
117
124
  return self.request("GET", "/v1/latency")
118
125
 
126
+ def periods(self) -> list[dict[str, Any]]:
127
+ """The published statistics windows (e.g. 30d, 7d) and when each was computed."""
128
+ return self.request("GET", "/v1/periods")
129
+
130
+ # ── account
131
+ def plan(self) -> dict[str, Any]:
132
+ """Your monthly plan (Base / Pro / Max), its period dates and what is used of its allowances."""
133
+ return self.request("GET", "/v1/account/plan")
134
+
135
+ def plans(self) -> dict[str, Any]:
136
+ """The plans on sale: price and allowances of Base / Pro / Max."""
137
+ return self.request("GET", "/v1/plans")
138
+
139
+ def billing(self) -> dict[str, Any]:
140
+ """Balance and top-up options."""
141
+ return self.request("GET", "/v1/account/billing")
142
+
143
+ def ledger(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> dict[str, Any]:
144
+ """One page of the balance statement, newest first; pass the previous page's `next` as `cursor`."""
145
+ return self.request("GET", "/v1/account/ledger", {"limit": limit, "cursor": cursor})
146
+
147
+ # ── webhooks
148
+ def webhooks(self) -> list[dict[str, Any]]:
149
+ """Your webhook endpoint. With an API key the URL comes back as its origin only; adding or removing one needs the website."""
150
+ return self.request("GET", "/v1/account/webhooks")
151
+
152
+ def reactivate_webhook(self, webhook_id: str) -> dict[str, Any]:
153
+ """Re-enable an endpoint that was disabled after a day of failures, and resume the subscriptions it paused."""
154
+ return self.request("POST", f"/v1/account/webhooks/{_q(webhook_id)}/reactivate")
155
+
156
+ def deliveries(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> dict[str, Any]:
157
+ """One page of delivery attempts (webhook and WebSocket), newest first."""
158
+ return self.request("GET", "/v1/account/deliveries", {"limit": limit, "cursor": cursor})
159
+
160
+ def delivery_stats(self, hours: Optional[int] = None) -> dict[str, Any]:
161
+ """Delivery success and latency over the last `hours`."""
162
+ return self.request("GET", "/v1/account/delivery-stats", {"hours": hours})
163
+
119
164
  # ── addresses
120
165
  def buy_reveal(self, entity_id: str, max_price_cents: int) -> dict[str, Any]:
121
166
  """Buy the address behind a handle. `max_price_cents` is a ceiling: the charge never exceeds it."""
122
167
  return self.request("POST", "/v1/account/reveals", body={"entityId": entity_id, "maxPriceCents": max_price_cents})
123
168
 
169
+ def unlock_with_plan(self, entity_id: str) -> dict[str, Any]:
170
+ """Unlock with your plan's allowance instead of the balance: never charges (409 when the allowance is used up)."""
171
+ return self.request("POST", "/v1/account/reveals", body={"entityId": entity_id, "maxPriceCents": 0, "viaPlan": True})
172
+
124
173
  def reveals(self) -> list[dict[str, Any]]:
125
174
  return self.request("GET", "/v1/account/reveals")
126
175
 
@@ -164,6 +213,18 @@ class Client(_Base):
164
213
  """Charges the balance; the price is recomputed server-side."""
165
214
  return self.request("POST", "/v1/account/exports", body={"entityIds": entity_ids, "from": from_, "to": to})
166
215
 
216
+ def create_plan_export(self, entity_ids: list[str]) -> dict[str, Any]:
217
+ """From a Max plan's monthly allowance: the whole sellable window, nothing charged."""
218
+ return self.request("POST", "/v1/account/exports", body={"entityIds": entity_ids, "viaPlan": True})
219
+
220
+ def export_window(self) -> dict[str, Any]:
221
+ """The days that can be bought right now (a contiguous range ending at the latest published day)."""
222
+ return self.request("GET", "/v1/account/exports/window")
223
+
224
+ def export_rate_card(self) -> dict[str, Any]:
225
+ """The per-day prices exports are charged at."""
226
+ return self.request("GET", "/v1/exports/rate-card")
227
+
167
228
  def exports(self) -> list[dict[str, Any]]:
168
229
  return self.request("GET", "/v1/account/exports")
169
230
 
@@ -222,9 +283,51 @@ class AsyncClient(_Base):
222
283
  async def latency(self) -> dict[str, Any]:
223
284
  return await self.request("GET", "/v1/latency")
224
285
 
286
+ async def periods(self) -> list[dict[str, Any]]:
287
+ """The published statistics windows (e.g. 30d, 7d) and when each was computed."""
288
+ return await self.request("GET", "/v1/periods")
289
+
290
+ # ── account
291
+ async def plan(self) -> dict[str, Any]:
292
+ """Your monthly plan (Base / Pro / Max), its period dates and what is used of its allowances."""
293
+ return await self.request("GET", "/v1/account/plan")
294
+
295
+ async def plans(self) -> dict[str, Any]:
296
+ """The plans on sale: price and allowances of Base / Pro / Max."""
297
+ return await self.request("GET", "/v1/plans")
298
+
299
+ async def billing(self) -> dict[str, Any]:
300
+ """Balance and top-up options."""
301
+ return await self.request("GET", "/v1/account/billing")
302
+
303
+ async def ledger(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> dict[str, Any]:
304
+ """One page of the balance statement, newest first; pass the previous page's `next` as `cursor`."""
305
+ return await self.request("GET", "/v1/account/ledger", {"limit": limit, "cursor": cursor})
306
+
307
+ # ── webhooks
308
+ async def webhooks(self) -> list[dict[str, Any]]:
309
+ """Your webhook endpoint. With an API key the URL comes back as its origin only; adding or removing one needs the website."""
310
+ return await self.request("GET", "/v1/account/webhooks")
311
+
312
+ async def reactivate_webhook(self, webhook_id: str) -> dict[str, Any]:
313
+ """Re-enable an endpoint that was disabled after a day of failures, and resume the subscriptions it paused."""
314
+ return await self.request("POST", f"/v1/account/webhooks/{_q(webhook_id)}/reactivate")
315
+
316
+ async def deliveries(self, limit: Optional[int] = None, cursor: Optional[str] = None) -> dict[str, Any]:
317
+ """One page of delivery attempts (webhook and WebSocket), newest first."""
318
+ return await self.request("GET", "/v1/account/deliveries", {"limit": limit, "cursor": cursor})
319
+
320
+ async def delivery_stats(self, hours: Optional[int] = None) -> dict[str, Any]:
321
+ """Delivery success and latency over the last `hours`."""
322
+ return await self.request("GET", "/v1/account/delivery-stats", {"hours": hours})
323
+
225
324
  async def buy_reveal(self, entity_id: str, max_price_cents: int) -> dict[str, Any]:
226
325
  return await self.request("POST", "/v1/account/reveals", body={"entityId": entity_id, "maxPriceCents": max_price_cents})
227
326
 
327
+ async def unlock_with_plan(self, entity_id: str) -> dict[str, Any]:
328
+ """Unlock with your plan's allowance instead of the balance: never charges (409 when the allowance is used up)."""
329
+ return await self.request("POST", "/v1/account/reveals", body={"entityId": entity_id, "maxPriceCents": 0, "viaPlan": True})
330
+
228
331
  async def reveals(self) -> list[dict[str, Any]]:
229
332
  return await self.request("GET", "/v1/account/reveals")
230
333
 
@@ -260,6 +363,18 @@ class AsyncClient(_Base):
260
363
  async def create_export(self, entity_ids: list[str], from_: str, to: str) -> dict[str, Any]:
261
364
  return await self.request("POST", "/v1/account/exports", body={"entityIds": entity_ids, "from": from_, "to": to})
262
365
 
366
+ async def create_plan_export(self, entity_ids: list[str]) -> dict[str, Any]:
367
+ """From a Max plan's monthly allowance: the whole sellable window, nothing charged."""
368
+ return await self.request("POST", "/v1/account/exports", body={"entityIds": entity_ids, "viaPlan": True})
369
+
370
+ async def export_window(self) -> dict[str, Any]:
371
+ """The days that can be bought right now (a contiguous range ending at the latest published day)."""
372
+ return await self.request("GET", "/v1/account/exports/window")
373
+
374
+ async def export_rate_card(self) -> dict[str, Any]:
375
+ """The per-day prices exports are charged at."""
376
+ return await self.request("GET", "/v1/exports/rate-card")
377
+
263
378
  async def exports(self) -> list[dict[str, Any]]:
264
379
  return await self.request("GET", "/v1/account/exports")
265
380
 
@@ -38,6 +38,15 @@ async def test_walks_every_page():
38
38
  assert "sinceBlock=2&sinceLogIndex=0&limit=2" in str(calls[1].url)
39
39
 
40
40
 
41
+ def test_bands_go_out_as_one_comma_separated_value():
42
+ calls = []
43
+ c = Client("k", "https://api.example.com", http=httpx.Client(transport=transport([{"rows": []}, {"rows": []}], calls=calls)))
44
+ c.leaderboard(bands=[0, 2], limit=5)
45
+ c.leaderboard(bands="1,3")
46
+ assert str(calls[0].url) == "https://api.example.com/v1/leaderboard?bands=0%2C2&limit=5"
47
+ assert str(calls[1].url) == "https://api.example.com/v1/leaderboard?bands=1%2C3"
48
+
49
+
41
50
  def test_my_addresses_asks_the_board_for_mine():
42
51
  calls = []
43
52
  c = Client("k", "https://api.example.com", http=httpx.Client(transport=transport([{"periodId": "30d", "tracked": 2, "rows": []}], calls=calls)))
@@ -52,6 +61,39 @@ async def test_async_my_addresses():
52
61
  assert str(calls[0].url) == "https://api.example.com/v1/leaderboard?mine=1"
53
62
 
54
63
 
64
+ CASES = [
65
+ (lambda c: c.periods(), "GET", "/v1/periods", None),
66
+ (lambda c: c.plan(), "GET", "/v1/account/plan", None),
67
+ (lambda c: c.plans(), "GET", "/v1/plans", None),
68
+ (lambda c: c.billing(), "GET", "/v1/account/billing", None),
69
+ (lambda c: c.ledger(limit=10, cursor="x|1"), "GET", "/v1/account/ledger?limit=10&cursor=x%7C1", None),
70
+ (lambda c: c.unlock_with_plan("H1"), "POST", "/v1/account/reveals", {"entityId": "H1", "maxPriceCents": 0, "viaPlan": True}),
71
+ (lambda c: c.create_plan_export(["H1"]), "POST", "/v1/account/exports", {"entityIds": ["H1"], "viaPlan": True}),
72
+ (lambda c: c.export_window(), "GET", "/v1/account/exports/window", None),
73
+ (lambda c: c.export_rate_card(), "GET", "/v1/exports/rate-card", None),
74
+ (lambda c: c.webhooks(), "GET", "/v1/account/webhooks", None),
75
+ (lambda c: c.reactivate_webhook("w 1"), "POST", "/v1/account/webhooks/w%201/reactivate", None),
76
+ (lambda c: c.deliveries(limit=5), "GET", "/v1/account/deliveries?limit=5", None),
77
+ (lambda c: c.delivery_stats(hours=24), "GET", "/v1/account/delivery-stats?hours=24", None),
78
+ ]
79
+
80
+
81
+ @pytest.mark.parametrize("call,method,path,body", CASES)
82
+ def test_account_calls_map_to_endpoints(call, method, path, body):
83
+ calls = []
84
+ call(Client("k", "https://api.example.com", http=httpx.Client(transport=transport([{}], calls=calls))))
85
+ assert f"{calls[0].method} {calls[0].url}" == f"{method} https://api.example.com{path}"
86
+ if body is not None:
87
+ assert json.loads(calls[0].content) == body
88
+
89
+
90
+ @pytest.mark.parametrize("call,method,path,body", CASES)
91
+ async def test_async_account_calls_map_to_endpoints(call, method, path, body):
92
+ calls = []
93
+ await call(AsyncClient("k", "https://api.example.com", http=httpx.AsyncClient(transport=transport([{}], calls=calls))))
94
+ assert f"{calls[0].method} {calls[0].url}" == f"{method} https://api.example.com{path}"
95
+
96
+
55
97
  def test_non_2xx_is_pmw_error():
56
98
  calls = []
57
99
  c = Client("k", http=httpx.Client(transport=transport([{"statusCode": 402, "message": "insufficient balance"}], 402, calls)))
@@ -134,7 +134,7 @@ wheels = [
134
134
 
135
135
  [[package]]
136
136
  name = "pmwallets"
137
- version = "0.3.0"
137
+ version = "0.5.1"
138
138
  source = { editable = "." }
139
139
  dependencies = [
140
140
  { name = "httpx" },
File without changes
File without changes