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.
- pmwallets-0.5.1/README.md → pmwallets-0.7.0/PKG-INFO +72 -1
- pmwallets-0.5.1/PKG-INFO → pmwallets-0.7.0/README.md +54 -19
- {pmwallets-0.5.1 → pmwallets-0.7.0}/README.zh.md +37 -1
- pmwallets-0.7.0/SKILL.md +97 -0
- pmwallets-0.7.0/glama.json +4 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/pyproject.toml +6 -3
- pmwallets-0.7.0/src/pmwallets/SKILL.md +97 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/__init__.py +9 -1
- pmwallets-0.7.0/src/pmwallets/cli.py +222 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/client.py +67 -0
- pmwallets-0.7.0/src/pmwallets/market.py +101 -0
- pmwallets-0.7.0/src/pmwallets/mcp.py +126 -0
- pmwallets-0.7.0/src/pmwallets/tools.py +277 -0
- pmwallets-0.7.0/src/pmwallets/version.py +1 -0
- pmwallets-0.7.0/src/pmwallets/watch.py +803 -0
- pmwallets-0.7.0/tests/test_agent.py +335 -0
- pmwallets-0.7.0/tests/test_watch.py +857 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/uv.lock +1 -1
- {pmwallets-0.5.1 → pmwallets-0.7.0}/.github/workflows/ci.yml +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/.github/workflows/publish.yml +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/.gitignore +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/LICENSE +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/stream.py +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/types.py +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/src/pmwallets/webhook.py +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/tests/test_client.py +0 -0
- {pmwallets-0.5.1 → pmwallets-0.7.0}/tests/test_real_socket.py +0 -0
- {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
|
-
|
|
21
|
+
<!-- mcp-name: io.github.polymarketwallets/pmwallets -->
|
|
22
|
+
|
|
23
|
+
[](https://pypi.org/project/pmwallets/) [](LICENSE) [](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
|
-
|
|
3
|
+
<!-- mcp-name: io.github.polymarketwallets/pmwallets -->
|
|
4
|
+
|
|
5
|
+
[](https://pypi.org/project/pmwallets/) [](LICENSE) [](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
|
-
[](https://pypi.org/project/pmwallets/) [](LICENSE)
|
|
3
|
+
[](https://pypi.org/project/pmwallets/) [](LICENSE) [](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,付款后立即可下载,之后也能再下。
|
pmwallets-0.7.0/SKILL.md
ADDED
|
@@ -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.
|
|
@@ -4,14 +4,17 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "pmwallets"
|
|
7
|
-
version = "0.
|
|
8
|
-
description = "Official PMWallets SDK: Polymarket smart-money leaderboard, real-time wallet fills over WebSocket with gap replay, webhooks and
|
|
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__ =
|
|
21
|
+
__version__ = VERSION
|