pmwallets

Polymarket smart-money data for AI agents: trader rankings, records and live fills.

GitHub

Documentation

pmwallets — Node.js SDK for PMWallets

npm License: MIT Discord

Official Node.js / TypeScript client for PMWallets: the Polymarket smart-money leaderboard computed from the Polygon chain, and the real-time fills of the Polymarket wallets you follow — delivered in order, exactly once, with every gap replayed.

中文说明 · Python SDK: pmwallets-python · Ready-to-run copy-trading bot built on it: polymarket-copy-trading-bot

Install

npm install pmwallets     # Node.js ≥ 20

Create an API key on pmwallets.com/keys.

Usage

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();

What is in it

PmwClientleaderboard, entities, address unlocks (balance or plan), your unlocked addresses (myAddresses), plan and balance, subscriptions, webhook status and deliveries, fills replay (fills, fillsSince), trade-history exports
FillStreamWebSocket 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
verifyWebhook(rawBody, 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 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 clientId, 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: pass wsOptions: { agent } for the WebSocket and set a global fetch dispatcher.

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.

AI agents: command line and MCP

The package installs a pmwallets command that prints JSON — for scripts, and for AI agents (Claude Code, Codex, Gemini CLI, Cursor, WorkBuddy, …) that act on the fills of the traders you follow.

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 runs the command once per batch, the fills on its stdin as JSON lines (and in $PMW_BATCH_FILE); fills that arrive while it runs make the next batch. A batch is handed over at most once: one whose command fails, times out or is interrupted is kept in pmw-watch/failed/ and never re-run — the agent may already have placed an order. Restarts resume from where the stream stopped.
  • To trade, give the agent pmwallets-copytrade: order buy <tokenId> --usdc 5 --key <eventId> (the same key never orders twice), market, balance, positions.
  • Platforms without a shell (Dify, Coze, n8n, GPT Actions): import openapi.json.
  • HTTPS_PROXY / NO_PROXY are honoured by the command line.

MCP config (Claude Desktop, Cursor, Windsurf, WorkBuddy, …):

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

Trade-history exports

A purchase is access to files: one zstd-compressed CSV per wallet per UTC day, downloadable at once and again later.

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) returns the short-lived link instead; the API key is never sent to the storage host.

Resources

Guides

License

MIT