PMWallets MCP server

pmwallets — Node.js SDK for PMWallets

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

One stream per account:

HTTPS_PROXY: pass wsOptions: { agent } for the WebSocket and set a global fetch dispatcher.

• 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.

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

Shortened. The full README is on GitHub.