pmwallets

Datos de smart-money de Polymarket para agentes de IA: rankings de traders, registros y operaciones en vivo.

GitHub

Documentación

pmwallets — SDK de Node.js para PMWallets

npm License: MIT Discord

Cliente oficial de Node.js / TypeScript para PMWallets: el ranking de dinero inteligente de Polymarket calculado a partir de la cadena Polygon, y los fills en tiempo real de las carteras de Polymarket que sigues — entregados en orden, exactamente una vez, con cada hueco reproducido.

中文说明 · SDK de Python: pmwallets-python · Bot de copy-trading listo para usar construido sobre él: polymarket-copy-trading-bot

Instalación

npm install pmwallets     # Node.js ≥ 20

Crea una clave de API en pmwallets.com/keys.

Uso

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

Qué incluye

PmwClientranking, entidades, desbloqueos de direcciones (saldo o plan), tus direcciones desbloqueadas (myAddresses), plan y saldo, suscripciones, estado de webhooks y entregas, reproducción de fills (fills, fillsSince), exportaciones de historial de operaciones
FillStreamWebSocket con reconexión y keep-alive; detecta frames perdidos mediante session/seq y los reproduce desde el último fill entregado; deduplica mediante eventId; se ancla detrás de la cabeza de la cadena en el primer inicio; cursor persistido
verifyWebhook(rawBody, signature, secret)verifica x-pmw-signature (HMAC-SHA256 del cuerpo crudo)

Un stream por cuenta:

  • Una conexión con clave de API tiene prioridad sobre la página de feed de pmwallets.com (la página nunca le quita el stream).
  • Entre dos conexiones de API, la primera mantiene el stream. Una segunda — otra clave de la misma cuenta, o el mismo bot iniciado dos veces — es rechazada: blocked, luego fatal, y el stream se detiene. Pasa takeover: true para reemplazar al titular; el titular recibe replaced, luego fatal, y se detiene (no contraataca).
  • Un FillStream se identifica con un clientId aleatorio, por lo que sus propias reconexiones tras una caída de red reemplazan su propia conexión muerta sin necesidad de takeover.
  • Cuando el servidor se reinicia, cierra el socket con 1012; el stream se reconecta de inmediato (evento restarting) y reproduce cualquier cosa que haya perdido. HTTPS_PROXY: pasa wsOptions: { agent } para el WebSocket y configura un dispatcher de fetch global.

Los servidores de PMWallets están en el Reino Unido. Un consumidor que también opera en Polymarket debería ejecutarse desde Irlanda (AWS eu-west-1): Polymarket no acepta órdenes de API desde el Reino Unido, EE. UU. y varios países de la UE.

Agentes de IA: línea de comandos y MCP

El paquete instala un comando pmwallets que imprime JSON — para scripts y para agentes de IA (Claude Code, Codex, Gemini CLI, Cursor, WorkBuddy, …) que actúan sobre los fills de los traders que sigues.

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 ejecuta el comando una vez por lote, con los fills en su stdin como líneas JSON (y en $PMW_BATCH_FILE); los fills que llegan mientras se ejecuta forman el siguiente lote. Un lote se entrega como máximo una vez: uno cuyo comando falla, expira o se interrumpe se mantiene en pmw-watch/failed/ y nunca se vuelve a ejecutar — el agente ya puede haber colocado una orden. Los reinicios se reanudan desde donde se detuvo el stream.
  • Para operar, dale al agente pmwallets-copytrade: order buy <tokenId> --usdc 5 --key <eventId> (la misma clave nunca ordena dos veces), market, balance, positions.
  • Plataformas sin shell (Dify, Coze, n8n, GPT Actions): importa openapi.json.
  • HTTPS_PROXY / NO_PROXY son respetados por la línea de comandos.

Configuración de MCP (Claude Desktop, Cursor, Windsurf, WorkBuddy, …):

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

Exportaciones de historial de operaciones

Una compra es acceso a archivos: un CSV comprimido con zstd por cartera y por día UTC, descargable de inmediato y más tarde.

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) devuelve el enlace de corta duración en su lugar; la clave de API nunca se envía al host de almacenamiento.

Recursos

Guías

Licencia

MIT