PMWallets

pmwallets — PMWallets 的 Node.js SDK

PMWallets 的官方 Node.js / TypeScript 客户端：PMWallets 提供根据 Polygon 链计算的 Polymarket 智能资金排行榜，以及你关注的 Polymarket 钱包的实时成交记录——按顺序传递，恰好一次，所有遗漏都会重放。

中文说明 · Python SDK：pmwallets-python · 基于此 SDK 构建、开箱即用的跟单机器人：polymarket-copy-trading-bot

安装

npm install pmwallets     # Node.js ≥ 20

在 pmwallets.com/keys 创建 API 密钥。

用法

import { PmwClient, FillStream, FileStateStore, verifyWebhook } from 'pmwallets';

const pmw = new PmwClient({ apiKey: process.env.PMW_API_KEY! });

// who is making money on Polymarket, and how
const board = await pmw.leaderboard({ minWinLo: 0.55, minEligible: 30, style: 'taker', status: 'active', limit: 50 });
// only wallets whose address unlocks for free or for the $1 band (0 = free … 5; the ladder is board.pricing.bands)
const cheap = await pmw.leaderboard({ bands: [0, 1], minWinLo: 0.55 });

// follow one (billed per entity per hour; 402 = balance too low, 409 = dormant)
await pmw.subscribe({ entityId: board.rows[0].entityId, channels: ['ws'] });

// every fill of every entity you follow
const stream = new FillStream({
  client: pmw,
  store: new FileStateStore('./stream.json'),    // a restart resumes exactly where it stopped
  onFill: async (fill, { source }) => console.log(source, fill.side, fill.price, fill.tokenId),
  onEvent: (e) => e.type === 'fatal' && console.error(e.error.message),   // 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.start();

提供的功能

PmwClient	排行榜、实体、地址解锁（余额或套餐）、你解锁的地址（myAddresses）、套餐和余额、订阅、Webhook 状态和投递记录、成交记录重放（fills、fillsSince）、交易历史导出
FillStream	支持重新连接和保活的 WebSocket；通过 session/seq 检测遗漏的帧，并从最后一次投递的成交记录处重放；通过 eventId 去重；首次启动时定位在链头之后；游标持久化
verifyWebhook(rawBody, signature, secret)	验证 x-pmw-signature（原始请求体的 HMAC-SHA256）

每个账户仅有一个数据流：

• API 密钥连接的优先级高于 pmwallets.com 信息流页面（该页面不会抢占数据流）。
• 两个 API 连接之间，先连接的会保留数据流。第二个连接——无论是同一账户的另一个密钥，还是同一个机器人启动了两次——都会被拒绝：先收到 blocked，再收到 fatal，随后数据流停止。传入 takeover: true 可替换当前持有者；当前持有者会收到 replaced，再收到 fatal，随后停止（不会反过来争抢）。
• FillStream 使用随机 clientId 标识自身，因此网络中断后的重新连接会替换它自身已失效的连接，无需使用 takeover。
• 服务器重启时会以 1012 关闭 WebSocket；数据流会立即重新连接（事件 restarting），并重放所有遗漏内容。 HTTPS_PROXY：为 WebSocket 传入 wsOptions: { agent }，并设置全局 fetch dispatcher。

PMWallets 的服务器位于英国。同时也在 Polymarket 交易的使用者应从爱尔兰（AWS eu-west-1）运行：Polymarket 不接受来自英国、美国和若干欧盟国家的 API 订单。

AI Agent：命令行和 MCP

该软件包会安装一个 pmwallets 命令，用于输出 JSON——可供脚本使用，也适用于处理你所关注交易者成交记录的 AI Agent（Claude Code、Codex、Gemini CLI、Cursor、WorkBuddy，……）。

export PMW_API_KEY=pmw_…
npx pmwallets leaderboard --minWinLo 0.55 --category politics --limit 20
npx pmwallets subscribe <handle>          # billed per hour
npx pmwallets new-fills                   # fills since the previous call, each once (poll it)
npx pmwallets watch                       # live: one JSON line per fill, with its market and decimal amounts
npx pmwallets watch --batch-sec 30 --exec 'claude -p "Fills from traders I follow are on stdin. …"'
npx pmwallets mcp                         # the same as MCP tools
npx pmwallets skill                       # the guide to give your agent (SKILL.md)

• watch --exec 会在每个批次运行一次命令，并将成交记录作为 JSON 行传入其标准输入（也写入 $PMW_BATCH_FILE）；运行期间到达的成交记录会组成下一个批次。每个批次最多移交一次：若命令失败、超时或被中断，该批次会保存在 pmw-watch/failed/ 中，且不会重新运行——Agent 可能已经下单。重启后会从数据流停止的位置继续。
• 如需交易，请为 Agent 提供 pmwallets-copytrade：order buy <tokenId> --usdc 5 --key <eventId>（相同的密钥不会重复下单）、market、balance、positions。
• 不带 shell 的平台（Dify、Coze、n8n、GPT Actions）：导入 openapi.json。
• 命令行支持 HTTPS_PROXY / NO_PROXY。

MCP 配置（Claude Desktop、Cursor、Windsurf、WorkBuddy，……）：

{
  "mcpServers": {
    "pmwallets": {
      "command": "npx",
      "args": ["-y", "pmwallets", "mcp"],
      "env": { "PMW_API_KEY": "pmw_..." }
    }
  }
}

交易历史导出

购买后即可访问文件：每个钱包每天（UTC）对应一个 zstd 压缩的 CSV 文件，可立即下载，也可稍后再次下载。

const order = await client.createExport({ entityIds: ['0x…'], from: '2026-09-01', to: '2026-09-30' });
const { files } = await client.exportFiles(String(order.id));
for (const f of files) {
  const bytes = await client.downloadExportFile(f.wallet, f.day); // .csv.zst
}

exportFileUrl(wallet, day) 会返回短时有效的链接；API 密钥绝不会发送到存储主机。

资源

• Polymarket 聪明资金排行榜 — 根据 Polygon 链上数据为盈利的 Polymarket 交易者评分，并提供胜率置信区间
• Polymarket 跟单指南 — 哪些钱包值得关注，以及如何及时获取它们的成交记录
• 如何向 Polymarket 聪明资金学习 — 解读交易者的记录：置信区间、Maker 与 Taker、市场专长
• PMWallets API 文档 — WebSocket 和 webhook 成交推送、成交记录回放、交易历史导出
• 实测成交推送延迟 — 区块到推送的 p50 / p95 延迟，实时发布
• Polymarket 钱包关注方式对比 — 官方排行榜、免费跟踪工具、SQL 仪表板
• 常见问题 · 中文站

指南

• PMWallets SDK — Node.js 和 Python 客户端并列对比
• 如何实时获取 Polymarket 钱包的交易 — 轮询 Data API、读取 Polygon 上的 OrderFilled 事件，或使用支持回放的成交推送流
• Polymarket WebSocket API — 市场频道和用户频道能提供什么，不能提供什么
• 通过 webhook 发送 Polymarket 交易提醒 — 验证 HMAC-SHA256 签名、快速响应、根据 eventId 去重
• 如何导出 Polymarket 钱包的完整交易历史 — 超出 Data API 的 10,000 笔交易上限：从链上获取每笔成交，每个钱包每天一个 CSV 文件
• Polymarket 代币 ID、条件 ID 和 slug — 了解它们之间的关联
• 如何计算 Polymarket 钱包的 PnL — 以及不同网站为何得出不同结果
• 按类别划分的 Polymarket 排行榜 — 体育、加密货币、政治、电竞等，按链上 PnL 排名
• 最繁忙的 Polymarket 市场 — 过去 30 天交易量最大的 1,000 个市场，以及这些市场中交易者的表现
• 所有指南 · llms.txt

许可证

MIT