pmwallets 0.5.1__tar.gz → 0.7.0__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.
Files changed (28) hide show
  1. pmwallets-0.5.1/README.md → pmwallets-0.7.0/PKG-INFO +72 -1
  2. pmwallets-0.5.1/PKG-INFO → pmwallets-0.7.0/README.md +54 -19
  3. {pmwallets-0.5.1 → pmwallets-0.7.0}/README.zh.md +37 -1
  4. pmwallets-0.7.0/SKILL.md +97 -0
  5. pmwallets-0.7.0/glama.json +4 -0
  6. {pmwallets-0.5.1 → pmwallets-0.7.0}/pyproject.toml +6 -3
  7. pmwallets-0.7.0/src/pmwallets/SKILL.md +97 -0
  8. {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/__init__.py +9 -1
  9. pmwallets-0.7.0/src/pmwallets/cli.py +222 -0
  10. {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/client.py +67 -0
  11. pmwallets-0.7.0/src/pmwallets/market.py +101 -0
  12. pmwallets-0.7.0/src/pmwallets/mcp.py +126 -0
  13. pmwallets-0.7.0/src/pmwallets/tools.py +277 -0
  14. pmwallets-0.7.0/src/pmwallets/version.py +1 -0
  15. pmwallets-0.7.0/src/pmwallets/watch.py +803 -0
  16. pmwallets-0.7.0/tests/test_agent.py +335 -0
  17. pmwallets-0.7.0/tests/test_watch.py +857 -0
  18. {pmwallets-0.5.1 → pmwallets-0.7.0}/uv.lock +1 -1
  19. {pmwallets-0.5.1 → pmwallets-0.7.0}/.github/workflows/ci.yml +0 -0
  20. {pmwallets-0.5.1 → pmwallets-0.7.0}/.github/workflows/publish.yml +0 -0
  21. {pmwallets-0.5.1 → pmwallets-0.7.0}/.gitignore +0 -0
  22. {pmwallets-0.5.1 → pmwallets-0.7.0}/LICENSE +0 -0
  23. {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/stream.py +0 -0
  24. {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/types.py +0 -0
  25. {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/webhook.py +0 -0
  26. {pmwallets-0.5.1 → pmwallets-0.7.0}/tests/test_client.py +0 -0
  27. {pmwallets-0.5.1 → pmwallets-0.7.0}/tests/test_real_socket.py +0 -0
  28. {pmwallets-0.5.1 → pmwallets-0.7.0}/tests/test_stream.py +0 -0
@@ -1,6 +1,26 @@
1
+ Metadata-Version: 2.5
2
+ Name: pmwallets
3
+ Version: 0.7.0
4
+ Summary: Official PMWallets SDK and CLI: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks, exports — and a CLI + MCP server so AI agents (Claude Code, Codex, Cursor, …) can follow traders and act on their fills.
5
+ Project-URL: Homepage, https://pmwallets.com/docs
6
+ Project-URL: Repository, https://github.com/polymarketwallets/pmwallets-python
7
+ Project-URL: Issues, https://github.com/polymarketwallets/pmwallets-python/issues
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: ai-agent,claude-code,codex,copy-trading,mcp,pmwallets,polymarket,prediction-markets,smart-money,wallet-tracker
11
+ Requires-Python: >=3.10
12
+ Requires-Dist: httpx>=0.27
13
+ Requires-Dist: websockets>=15
14
+ Provides-Extra: dev
15
+ Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
16
+ Requires-Dist: pytest>=8; extra == 'dev'
17
+ Description-Content-Type: text/markdown
18
+
1
19
  # pmwallets — Python SDK for PMWallets
2
20
 
3
- [![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)
21
+ <!-- mcp-name: io.github.polymarketwallets/pmwallets -->
22
+
23
+ [![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) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/Xy5uTTb3gN)
4
24
 
5
25
  Official Python client for [PMWallets](https://pmwallets.com): the **Polymarket smart-money leaderboard** computed
6
26
  from the Polygon chain, and the **real-time fills of the Polymarket wallets you follow** — delivered in order,
@@ -17,6 +37,17 @@ pip install pmwallets # Python ≥ 3.10
17
37
 
18
38
  Create an API key on [pmwallets.com/keys](https://pmwallets.com/keys).
19
39
 
40
+
41
+ ## Signals and radar (Pro and Max)
42
+
43
+ ```python
44
+ entries = client.signals(category="sports")["entries"]
45
+ big = client.radar(minUsd=25000, smart=True)
46
+ client.save_signal_rule("signal", {"enabled": True, "scope": "official", "minWallets": 3, "windowMin": 30, "minUsd": 5000, "channels": ["ws", "webhook"]})
47
+ ```
48
+
49
+ Live alerts arrive on `wss://api.pmwallets.com/v1/signals/ws` as `{type: 'signal' | 'radar', data}`. Amounts keep two significant figures, times the minute, and traders are named by handle.
50
+
20
51
  ## Usage
21
52
 
22
53
  ```python
@@ -63,6 +94,46 @@ One stream per account:
63
94
 
64
95
  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.
65
96
 
97
+ ## AI agents: command line and MCP
98
+
99
+ The package installs a `pmwallets` command that prints JSON — for scripts, and for AI agents (Claude Code, Codex,
100
+ Gemini CLI, Cursor, WorkBuddy, …) that act on the fills of the traders you follow.
101
+
102
+ ```bash
103
+ export PMW_API_KEY=pmw_…
104
+ pmwallets leaderboard --minWinLo 0.55 --category politics --limit 20
105
+ pmwallets subscribe <handle> # billed per hour
106
+ pmwallets new-fills # fills since the previous call, each once (poll it)
107
+ pmwallets watch # live: one JSON line per fill, with its market and decimal amounts
108
+ pmwallets watch --batch-sec 30 --exec 'claude -p "Fills from traders I follow are on stdin. …"'
109
+ pmwallets mcp # the same as MCP tools
110
+ pmwallets skill # the guide to give your agent (SKILL.md)
111
+ ```
112
+
113
+ - `watch --exec` runs the command once per batch, the fills on its stdin as JSON lines (and in `$PMW_BATCH_FILE`);
114
+ fills that arrive while it runs make the next batch. A batch is handed over **at most once**: one whose command
115
+ fails, times out or is interrupted is kept in `pmw-watch/failed/` and never re-run — the agent may already have
116
+ placed an order. Restarts resume from where the stream stopped.
117
+ - To trade, give the agent [pmwallets-copytrade](https://github.com/polymarketwallets/polymarket-copy-trading-bot-python):
118
+ `order buy <tokenId> --usdc 5 --key <eventId>` (the same key never orders twice), `market`, `balance`, `positions`.
119
+ - Platforms without a shell (Dify, Coze, n8n, GPT Actions): import [openapi.json](https://pmwallets.com/openapi.json).
120
+ - `HTTPS_PROXY` / `NO_PROXY` are honoured by the command line.
121
+
122
+ MCP config (Claude Desktop, Cursor, Windsurf, WorkBuddy, …):
123
+
124
+ ```json
125
+ {
126
+ "mcpServers": {
127
+ "pmwallets": {
128
+ "command": "uvx",
129
+ "args": ["pmwallets", "mcp"],
130
+ "env": { "PMW_API_KEY": "pmw_..." }
131
+ }
132
+ }
133
+ }
134
+ ```
135
+ - The same pieces are importable: `Watcher`, `MarketLookup`, `serve_mcp` / `McpTool`, `pmwallets_tools`.
136
+
66
137
  ## Trade-history exports
67
138
 
68
139
  A purchase is access to files: one zstd-compressed CSV per wallet per UTC day, downloadable at once and again later.
@@ -1,24 +1,8 @@
1
- Metadata-Version: 2.5
2
- Name: pmwallets
3
- Version: 0.5.1
4
- Summary: Official PMWallets SDK: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks and exports.
5
- Project-URL: Homepage, https://pmwallets.com/docs
6
- Project-URL: Repository, https://github.com/polymarketwallets/pmwallets-python
7
- Project-URL: Issues, https://github.com/polymarketwallets/pmwallets-python/issues
8
- License-Expression: MIT
9
- License-File: LICENSE
10
- Keywords: copy-trading,pmwallets,polymarket,prediction-markets,smart-money,wallet-tracker
11
- Requires-Python: >=3.10
12
- Requires-Dist: httpx>=0.27
13
- Requires-Dist: websockets>=15
14
- Provides-Extra: dev
15
- Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
16
- Requires-Dist: pytest>=8; extra == 'dev'
17
- Description-Content-Type: text/markdown
18
-
19
1
  # pmwallets — Python SDK for PMWallets
20
2
 
21
- [![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)
3
+ <!-- mcp-name: io.github.polymarketwallets/pmwallets -->
4
+
5
+ [![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) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/Xy5uTTb3gN)
22
6
 
23
7
  Official Python client for [PMWallets](https://pmwallets.com): the **Polymarket smart-money leaderboard** computed
24
8
  from the Polygon chain, and the **real-time fills of the Polymarket wallets you follow** — delivered in order,
@@ -35,6 +19,17 @@ pip install pmwallets # Python ≥ 3.10
35
19
 
36
20
  Create an API key on [pmwallets.com/keys](https://pmwallets.com/keys).
37
21
 
22
+
23
+ ## Signals and radar (Pro and Max)
24
+
25
+ ```python
26
+ entries = client.signals(category="sports")["entries"]
27
+ big = client.radar(minUsd=25000, smart=True)
28
+ client.save_signal_rule("signal", {"enabled": True, "scope": "official", "minWallets": 3, "windowMin": 30, "minUsd": 5000, "channels": ["ws", "webhook"]})
29
+ ```
30
+
31
+ Live alerts arrive on `wss://api.pmwallets.com/v1/signals/ws` as `{type: 'signal' | 'radar', data}`. Amounts keep two significant figures, times the minute, and traders are named by handle.
32
+
38
33
  ## Usage
39
34
 
40
35
  ```python
@@ -81,6 +76,46 @@ One stream per account:
81
76
 
82
77
  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.
83
78
 
79
+ ## AI agents: command line and MCP
80
+
81
+ The package installs a `pmwallets` command that prints JSON — for scripts, and for AI agents (Claude Code, Codex,
82
+ Gemini CLI, Cursor, WorkBuddy, …) that act on the fills of the traders you follow.
83
+
84
+ ```bash
85
+ export PMW_API_KEY=pmw_…
86
+ pmwallets leaderboard --minWinLo 0.55 --category politics --limit 20
87
+ pmwallets subscribe <handle> # billed per hour
88
+ pmwallets new-fills # fills since the previous call, each once (poll it)
89
+ pmwallets watch # live: one JSON line per fill, with its market and decimal amounts
90
+ pmwallets watch --batch-sec 30 --exec 'claude -p "Fills from traders I follow are on stdin. …"'
91
+ pmwallets mcp # the same as MCP tools
92
+ pmwallets skill # the guide to give your agent (SKILL.md)
93
+ ```
94
+
95
+ - `watch --exec` runs the command once per batch, the fills on its stdin as JSON lines (and in `$PMW_BATCH_FILE`);
96
+ fills that arrive while it runs make the next batch. A batch is handed over **at most once**: one whose command
97
+ fails, times out or is interrupted is kept in `pmw-watch/failed/` and never re-run — the agent may already have
98
+ placed an order. Restarts resume from where the stream stopped.
99
+ - To trade, give the agent [pmwallets-copytrade](https://github.com/polymarketwallets/polymarket-copy-trading-bot-python):
100
+ `order buy <tokenId> --usdc 5 --key <eventId>` (the same key never orders twice), `market`, `balance`, `positions`.
101
+ - Platforms without a shell (Dify, Coze, n8n, GPT Actions): import [openapi.json](https://pmwallets.com/openapi.json).
102
+ - `HTTPS_PROXY` / `NO_PROXY` are honoured by the command line.
103
+
104
+ MCP config (Claude Desktop, Cursor, Windsurf, WorkBuddy, …):
105
+
106
+ ```json
107
+ {
108
+ "mcpServers": {
109
+ "pmwallets": {
110
+ "command": "uvx",
111
+ "args": ["pmwallets", "mcp"],
112
+ "env": { "PMW_API_KEY": "pmw_..." }
113
+ }
114
+ }
115
+ }
116
+ ```
117
+ - The same pieces are importable: `Watcher`, `MarketLookup`, `serve_mcp` / `McpTool`, `pmwallets_tools`.
118
+
84
119
  ## Trade-history exports
85
120
 
86
121
  A purchase is access to files: one zstd-compressed CSV per wallet per UTC day, downloadable at once and again later.
@@ -1,6 +1,6 @@
1
1
  # pmwallets —— PMWallets Python SDK
2
2
 
3
- [![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)
3
+ [![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) [![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/Xy5uTTb3gN)
4
4
 
5
5
  [PMWallets](https://pmwallets.com/zh) 官方 Python 客户端:从 Polygon 链上计算的 **Polymarket 聪明钱排行榜**,以及**你所跟踪的
6
6
  Polymarket 钱包的实时成交** —— 按顺序、只送一次、漏掉的自动补发。
@@ -16,6 +16,17 @@ pip install pmwallets # Python ≥ 3.10
16
16
 
17
17
  在 [pmwallets.com/keys](https://pmwallets.com/keys) 创建 API key。用法示例见 [README.md](README.md#usage)。
18
18
 
19
+
20
+ ## 信号与雷达(Pro 和 Max)
21
+
22
+ ```python
23
+ entries = client.signals(category="sports")["entries"]
24
+ big = client.radar(minUsd=25000, smart=True)
25
+ client.save_signal_rule("signal", {"enabled": True, "scope": "official", "minWallets": 3, "windowMin": 30, "minUsd": 5000, "channels": ["ws", "webhook"]})
26
+ ```
27
+
28
+ 实时告警走 `wss://api.pmwallets.com/v1/signals/ws`,帧为 `{type: 'signal' | 'radar', data}`。金额保留两位有效数字,时间到分钟,交易者只给代号。
29
+
19
30
  ## 包含什么
20
31
 
21
32
  | | |
@@ -28,6 +39,31 @@ pip install pmwallets # Python ≥ 3.10
28
39
 
29
40
  PMWallets 的服务器在英国。若还要在 Polymarket 下单,请部署在爱尔兰(AWS eu-west-1):Polymarket 不接受来自英国、美国及部分欧盟国家的 API 订单。
30
41
 
42
+ ## AI agent:命令行与 MCP
43
+
44
+ 安装后带一个 `pmwallets` 命令,全部输出 JSON——给脚本用,也给 AI agent(Claude Code、Codex、Gemini CLI、Cursor、
45
+ WorkBuddy……)用,让它对你关注的交易者的成交做出反应。
46
+
47
+ ```bash
48
+ export PMW_API_KEY=pmw_…
49
+ pmwallets leaderboard --minWinLo 0.55 --category politics --limit 20
50
+ pmwallets subscribe <handle> # 按小时计费
51
+ pmwallets new-fills # 上次调用之后的新成交,每笔只给一次(定时拉取)
52
+ pmwallets watch # 实时:每笔成交一行 JSON,带市场信息和十进制金额
53
+ pmwallets watch --batch-sec 30 --exec 'claude -p "stdin 里是我关注的交易者的成交。……"'
54
+ pmwallets mcp # 同样的能力,作为 MCP 工具
55
+ pmwallets skill # 交给 agent 的使用说明(SKILL.md)
56
+ ```
57
+
58
+ - `watch --exec` 每一批成交运行一次命令,成交以 JSON 行写进它的 stdin(同时在 `$PMW_BATCH_FILE` 文件里);命令运行
59
+ 期间到达的成交组成下一批。每批**最多交出一次**:命令失败、超时或被中断的批次保存在 `pmw-watch/failed/`,不会重跑
60
+ ——agent 可能已经下过单。重启后从上次停下的位置继续。
61
+ - 要下单,给 agent 配上 [pmwallets-copytrade](https://github.com/polymarketwallets/polymarket-copy-trading-bot-python):
62
+ `order buy <tokenId> --usdc 5 --key <eventId>`(同一个 key 永远不会下第二单)、`market`、`balance`、`positions`。
63
+ - MCP 配置(Claude Desktop、Cursor 等):`{"command": "uvx", "args": ["pmwallets", "mcp"], "env": {"PMW_API_KEY": "pmw_…"}}`。
64
+ - 没有命令行的平台(Dify、Coze、n8n、GPT Actions):导入 [openapi.json](https://pmwallets.com/openapi.json)。
65
+ - 命令行会读取 `HTTPS_PROXY` / `NO_PROXY`。
66
+
31
67
  ## 历史成交导出
32
68
 
33
69
  购买得到的是文件的访问权:每个钱包每个 UTC 日一个 zstd 压缩的 CSV,付款后立即可下载,之后也能再下。
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: pmwallets
3
+ description: Follow profitable Polymarket traders with PMWallets and act on their trades — find traders on the smart-money leaderboard, subscribe to their live fills, read each fill with its market, and (with pmwallets-copytrade) place your own Polymarket orders. Use when the user mentions PMWallets, Polymarket copy trading, smart money, whale tracking, or reacting to a trader's fills.
4
+ ---
5
+
6
+ # PMWallets for AI agents
7
+
8
+ PMWallets scores every Polymarket trader from the Polygon chain and streams the fills of the traders an account
9
+ follows. Two command-line tools, both printing JSON:
10
+
11
+ - `pmwallets` (npm `pmwallets` / PyPI `pmwallets`) — the data: leaderboard, traders, subscriptions, live fills.
12
+ Needs `PMW_API_KEY` (create one on https://pmwallets.com/keys).
13
+ - `pmwallets-copytrade` (npm / PyPI `pmwallets-copytrade`) — the trading: market and order book, balance,
14
+ positions, orders on Polymarket. Reads a `config.yaml` (`pmwallets-copytrade init` writes one; Polymarket keys go
15
+ in environment variables it names). Its `mode` decides everything: `dry-run` simulates each order against the live
16
+ book and sends nothing; `live` trades real money.
17
+
18
+ Both also run as MCP servers (`pmwallets mcp`, `pmwallets-copytrade mcp --config <path>`) with the same tools.
19
+
20
+ ## Find and follow traders
21
+
22
+ ```bash
23
+ pmwallets leaderboard --period 30d --minWinLo 0.55 --category politics --limit 20
24
+ pmwallets signals --category sports # Pro and Max: several smart wallets buying one side
25
+ pmwallets radar --minUsd 25000 --smart # Pro and Max: large fills across the market
26
+ pmwallets entity <handle> # one trader's stats; a handle is 12 characters, e.g. 7KQ2MF9X4B1C
27
+ pmwallets subscribe <handle> # BILLS the account per hour (or uses the plan); 402 = balance too low
28
+ pmwallets subscriptions
29
+ pmwallets unsubscribe <subscription-id>
30
+ ```
31
+
32
+ `minWinLo` is the lower bound of the 95% win-rate interval: a high value means the record is unlikely to be luck.
33
+
34
+ ## Receive fills
35
+
36
+ Every fill carries `eventId` (unique; use it as an idempotency key), `side` (BUY/SELL), `price` (0–1 per share),
37
+ `tokenId` (the outcome), `usdcAmount` / `sharesAmount` (decimals; the raw `usdc` / `shares` are 1e-6 integer
38
+ units), and `market` (`question`, `outcome`, `endDate`) when Polymarket could be asked.
39
+
40
+ - **Pull** (any agent, no long-running process): `pmwallets new-fills` returns the fills since the previous call,
41
+ each once. Call it on a schedule. The position lives in `~/.pmwallets/mcp-cursor.json` (or `$PMW_MCP_STATE`),
42
+ shared with the MCP tool `new_fills`: one consumer per file — give each agent its own `PMW_MCP_STATE`.
43
+ - **Push**: `pmwallets watch` keeps a live connection and prints one JSON line per fill. With `--exec "<command>"` it
44
+ runs the command for each batch of fills, the fills on its stdin as JSON lines (also in `$PMW_BATCH_FILE`); fills
45
+ that arrive while the command runs make the next batch; `--batch-sec N` waits N seconds to collect a batch. A batch
46
+ is handed over at most once: a failed or interrupted one is kept in `pmw-watch/failed/`, never re-run.
47
+ One live connection per PMWallets account — a second `watch` (or the copy-trading bot) on the same account is
48
+ refused unless `--takeover`.
49
+
50
+ ## Trade
51
+
52
+ ```bash
53
+ pmwallets-copytrade market <tokenId> # question, outcomes, prices, order book: read before deciding
54
+ pmwallets-copytrade balance
55
+ pmwallets-copytrade positions
56
+ pmwallets-copytrade trades --limit 20
57
+ pmwallets-copytrade order buy <tokenId> --usdc 5 --max-price 0.45 --key <eventId>
58
+ pmwallets-copytrade order sell <tokenId> --all --min-price 0.40 --key <eventId>:exit
59
+ ```
60
+
61
+ - BUY is fill-or-kill: all of it at `--max-price` or better, or nothing. `--usdc` is a ceiling — the size is
62
+ `usdc / max-price`, so the order can never cost more; set `--max-price` close to the ask to spend close to `--usdc`.
63
+ Without `--max-price` the limit is the best ask now.
64
+ - SELL is fill-and-kill: as much as crosses at `--min-price` or better, the rest cancelled; capped at what the
65
+ account holds.
66
+ - **Always pass `--key`.** The same key never sends a second order, so a retry after a timeout is safe.
67
+ - `status`: `filled`, `none` (nothing matched), `skipped` (price outside your limit, market closed — nothing sent),
68
+ `failed` (rejected), `dry_run`, or `unknown` / `verify: true` — the order MAY have filled: check `trades` before
69
+ sending another. Exit code 0 = filled or dry_run, 2 = not traded, 3 = unknown.
70
+ - Polymarket refuses orders from some countries (the UK, the US and others); `pmwallets-copytrade check` tells.
71
+
72
+ ## Recipes
73
+
74
+ React to every fill with an agent CLI (any agent that takes a prompt and reads stdin works the same way):
75
+
76
+ ```bash
77
+ export PMW_API_KEY=pmw_…
78
+ pmwallets watch --batch-sec 30 --exec 'claude -p "Fills from traders I follow are on stdin. For each BUY above $1000 in a market ending after 2026-12-31, read the market with pmwallets-copytrade market, then buy $5 with --key <eventId> if the price is below 0.6. One line per fill: what you did." --allowedTools "Bash(pmwallets-copytrade:*)"'
79
+ # Codex: --exec 'codex exec --sandbox danger-full-access "…same instructions…"' (its default sandbox has no network)
80
+ # Gemini: --exec 'gemini -p "…" --yolo'
81
+ ```
82
+
83
+ MCP (Claude Desktop, Cursor, Windsurf, Cline, WorkBuddy, …):
84
+
85
+ ```json
86
+ {
87
+ "mcpServers": {
88
+ "pmwallets": { "command": "npx", "args": ["-y", "pmwallets", "mcp"], "env": { "PMW_API_KEY": "pmw_…" } },
89
+ "copytrade": { "command": "npx", "args": ["-y", "pmwallets-copytrade", "mcp", "--config", "/abs/path/config.yaml"] }
90
+ }
91
+ }
92
+ ```
93
+
94
+ No shell or MCP (Dify, Coze, n8n, GPT Actions): import https://pmwallets.com/openapi.json and call the REST API with
95
+ the `x-api-key` header, or receive fills as signed webhooks (set one up on https://pmwallets.com/feed).
96
+
97
+ Docs: https://pmwallets.com/docs · Python: `pip install pmwallets pmwallets-copytrade` gives the same commands.
@@ -0,0 +1,4 @@
1
+ {
2
+ "$schema": "https://glama.ai/mcp/schemas/server.json",
3
+ "maintainers": ["pmwallets"]
4
+ }
@@ -4,14 +4,17 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "pmwallets"
7
- version = "0.5.1"
8
- description = "Official PMWallets SDK: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks and exports."
7
+ version = "0.7.0"
8
+ description = "Official PMWallets SDK and CLI: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks, exports — and a CLI + MCP server so AI agents (Claude Code, Codex, Cursor, …) can follow traders and act on their fills."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
11
11
  license = "MIT"
12
- keywords = ["polymarket", "copy-trading", "wallet-tracker", "smart-money", "pmwallets", "prediction-markets"]
12
+ keywords = ["polymarket", "copy-trading", "wallet-tracker", "smart-money", "pmwallets", "prediction-markets", "mcp", "ai-agent", "claude-code", "codex"]
13
13
  dependencies = ["httpx>=0.27", "websockets>=15"]
14
14
 
15
+ [project.scripts]
16
+ pmwallets = "pmwallets.cli:main"
17
+
15
18
  [project.optional-dependencies]
16
19
  dev = ["pytest>=8", "pytest-asyncio>=0.23"]
17
20
 
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: pmwallets
3
+ description: Follow profitable Polymarket traders with PMWallets and act on their trades — find traders on the smart-money leaderboard, subscribe to their live fills, read each fill with its market, and (with pmwallets-copytrade) place your own Polymarket orders. Use when the user mentions PMWallets, Polymarket copy trading, smart money, whale tracking, or reacting to a trader's fills.
4
+ ---
5
+
6
+ # PMWallets for AI agents
7
+
8
+ PMWallets scores every Polymarket trader from the Polygon chain and streams the fills of the traders an account
9
+ follows. Two command-line tools, both printing JSON:
10
+
11
+ - `pmwallets` (npm `pmwallets` / PyPI `pmwallets`) — the data: leaderboard, traders, subscriptions, live fills.
12
+ Needs `PMW_API_KEY` (create one on https://pmwallets.com/keys).
13
+ - `pmwallets-copytrade` (npm / PyPI `pmwallets-copytrade`) — the trading: market and order book, balance,
14
+ positions, orders on Polymarket. Reads a `config.yaml` (`pmwallets-copytrade init` writes one; Polymarket keys go
15
+ in environment variables it names). Its `mode` decides everything: `dry-run` simulates each order against the live
16
+ book and sends nothing; `live` trades real money.
17
+
18
+ Both also run as MCP servers (`pmwallets mcp`, `pmwallets-copytrade mcp --config <path>`) with the same tools.
19
+
20
+ ## Find and follow traders
21
+
22
+ ```bash
23
+ pmwallets leaderboard --period 30d --minWinLo 0.55 --category politics --limit 20
24
+ pmwallets signals --category sports # Pro and Max: several smart wallets buying one side
25
+ pmwallets radar --minUsd 25000 --smart # Pro and Max: large fills across the market
26
+ pmwallets entity <handle> # one trader's stats; a handle is 12 characters, e.g. 7KQ2MF9X4B1C
27
+ pmwallets subscribe <handle> # BILLS the account per hour (or uses the plan); 402 = balance too low
28
+ pmwallets subscriptions
29
+ pmwallets unsubscribe <subscription-id>
30
+ ```
31
+
32
+ `minWinLo` is the lower bound of the 95% win-rate interval: a high value means the record is unlikely to be luck.
33
+
34
+ ## Receive fills
35
+
36
+ Every fill carries `eventId` (unique; use it as an idempotency key), `side` (BUY/SELL), `price` (0–1 per share),
37
+ `tokenId` (the outcome), `usdcAmount` / `sharesAmount` (decimals; the raw `usdc` / `shares` are 1e-6 integer
38
+ units), and `market` (`question`, `outcome`, `endDate`) when Polymarket could be asked.
39
+
40
+ - **Pull** (any agent, no long-running process): `pmwallets new-fills` returns the fills since the previous call,
41
+ each once. Call it on a schedule. The position lives in `~/.pmwallets/mcp-cursor.json` (or `$PMW_MCP_STATE`),
42
+ shared with the MCP tool `new_fills`: one consumer per file — give each agent its own `PMW_MCP_STATE`.
43
+ - **Push**: `pmwallets watch` keeps a live connection and prints one JSON line per fill. With `--exec "<command>"` it
44
+ runs the command for each batch of fills, the fills on its stdin as JSON lines (also in `$PMW_BATCH_FILE`); fills
45
+ that arrive while the command runs make the next batch; `--batch-sec N` waits N seconds to collect a batch. A batch
46
+ is handed over at most once: a failed or interrupted one is kept in `pmw-watch/failed/`, never re-run.
47
+ One live connection per PMWallets account — a second `watch` (or the copy-trading bot) on the same account is
48
+ refused unless `--takeover`.
49
+
50
+ ## Trade
51
+
52
+ ```bash
53
+ pmwallets-copytrade market <tokenId> # question, outcomes, prices, order book: read before deciding
54
+ pmwallets-copytrade balance
55
+ pmwallets-copytrade positions
56
+ pmwallets-copytrade trades --limit 20
57
+ pmwallets-copytrade order buy <tokenId> --usdc 5 --max-price 0.45 --key <eventId>
58
+ pmwallets-copytrade order sell <tokenId> --all --min-price 0.40 --key <eventId>:exit
59
+ ```
60
+
61
+ - BUY is fill-or-kill: all of it at `--max-price` or better, or nothing. `--usdc` is a ceiling — the size is
62
+ `usdc / max-price`, so the order can never cost more; set `--max-price` close to the ask to spend close to `--usdc`.
63
+ Without `--max-price` the limit is the best ask now.
64
+ - SELL is fill-and-kill: as much as crosses at `--min-price` or better, the rest cancelled; capped at what the
65
+ account holds.
66
+ - **Always pass `--key`.** The same key never sends a second order, so a retry after a timeout is safe.
67
+ - `status`: `filled`, `none` (nothing matched), `skipped` (price outside your limit, market closed — nothing sent),
68
+ `failed` (rejected), `dry_run`, or `unknown` / `verify: true` — the order MAY have filled: check `trades` before
69
+ sending another. Exit code 0 = filled or dry_run, 2 = not traded, 3 = unknown.
70
+ - Polymarket refuses orders from some countries (the UK, the US and others); `pmwallets-copytrade check` tells.
71
+
72
+ ## Recipes
73
+
74
+ React to every fill with an agent CLI (any agent that takes a prompt and reads stdin works the same way):
75
+
76
+ ```bash
77
+ export PMW_API_KEY=pmw_…
78
+ pmwallets watch --batch-sec 30 --exec 'claude -p "Fills from traders I follow are on stdin. For each BUY above $1000 in a market ending after 2026-12-31, read the market with pmwallets-copytrade market, then buy $5 with --key <eventId> if the price is below 0.6. One line per fill: what you did." --allowedTools "Bash(pmwallets-copytrade:*)"'
79
+ # Codex: --exec 'codex exec --sandbox danger-full-access "…same instructions…"' (its default sandbox has no network)
80
+ # Gemini: --exec 'gemini -p "…" --yolo'
81
+ ```
82
+
83
+ MCP (Claude Desktop, Cursor, Windsurf, Cline, WorkBuddy, …):
84
+
85
+ ```json
86
+ {
87
+ "mcpServers": {
88
+ "pmwallets": { "command": "npx", "args": ["-y", "pmwallets", "mcp"], "env": { "PMW_API_KEY": "pmw_…" } },
89
+ "copytrade": { "command": "npx", "args": ["-y", "pmwallets-copytrade", "mcp", "--config", "/abs/path/config.yaml"] }
90
+ }
91
+ }
92
+ ```
93
+
94
+ No shell or MCP (Dify, Coze, n8n, GPT Actions): import https://pmwallets.com/openapi.json and call the REST API with
95
+ the `x-api-key` header, or receive fills as signed webhooks (set one up on https://pmwallets.com/feed).
96
+
97
+ Docs: https://pmwallets.com/docs · Python: `pip install pmwallets pmwallets-copytrade` gives the same commands.
@@ -1,13 +1,21 @@
1
1
  """Official PMWallets SDK — https://pmwallets.com/docs"""
2
2
 
3
3
  from .client import DEFAULT_BASE_URL, AsyncClient, Client, PmwError
4
+ from .market import MarketInfo, MarketLookup, micro_to_decimal
5
+ from .mcp import MCP_PROTOCOL_VERSIONS, McpTool, serve_mcp
4
6
  from .stream import CLOSE_API_SEAT_TAKEN, CLOSE_SERVICE_RESTART, FileStateStore, FillMeta, FillStream, MemoryStateStore, StreamState, UpgradeRefused, websockets_connector
7
+ from .tools import MCP_INSTRUCTIONS, CursorFile, describe_fill, new_fills, pmwallets_tools
5
8
  from .types import Fill, FillCursor, FillsPage
9
+ from .version import VERSION
10
+ from .watch import Watcher
6
11
  from .webhook import verify_webhook
7
12
 
8
13
  __all__ = [
9
14
  "DEFAULT_BASE_URL", "AsyncClient", "Client", "PmwError",
10
15
  "CLOSE_API_SEAT_TAKEN", "CLOSE_SERVICE_RESTART", "FileStateStore", "FillMeta", "FillStream", "MemoryStateStore", "StreamState", "UpgradeRefused", "websockets_connector",
11
16
  "Fill", "FillCursor", "FillsPage", "verify_webhook",
17
+ "MarketInfo", "MarketLookup", "micro_to_decimal", "Watcher",
18
+ "MCP_PROTOCOL_VERSIONS", "McpTool", "serve_mcp", "MCP_INSTRUCTIONS", "CursorFile", "describe_fill", "new_fills", "pmwallets_tools",
19
+ "VERSION",
12
20
  ]
13
- __version__ = "0.5.1"
21
+ __version__ = VERSION