pmwallets

Dados de smart-money da Polymarket para agentes de IA: rankings de traders, registros e preenchimentos ao vivo.

GitHub

Documentação

pmwallets — SDK Node.js para PMWallets

npm License: MIT Discord

Cliente oficial Node.js / TypeScript para PMWallets: o ranking de smart money da Polymarket calculado a partir da rede Polygon, e os fills em tempo real das carteiras da Polymarket que você segue — entregues em ordem, exatamente uma vez, com cada lacuna reproduzida.

中文说明 · SDK Python: pmwallets-python · Bot de copy-trading pronto para uso construído sobre ele: polymarket-copy-trading-bot

Instalação

npm install pmwallets     # Node.js ≥ 20

Crie uma chave de API em 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();

O que está incluído

PmwClientranking, entidades, desbloqueios de endereços (saldo ou plano), seus endereços desbloqueados (myAddresses), plano e saldo, assinaturas, status de webhook e entregas, reprodução de fills (fills, fillsSince), exportações de histórico de negociações
FillStreamWebSocket com reconexão e keep-alive; detecta quadros perdidos por session/seq e os reproduz a partir do último fill entregue; remove duplicatas por eventId; ancora atrás da cabeça da cadeia no primeiro início; cursor persistido
verifyWebhook(rawBody, signature, secret)verifica x-pmw-signature (HMAC-SHA256 do corpo bruto)

Um stream por conta:

  • Uma conexão com chave de API tem prioridade sobre a página de feed do pmwallets.com (a página nunca toma o stream dela).
  • Entre duas conexões de API, a primeira mantém o stream. Uma segunda — outra chave da mesma conta, ou o mesmo bot iniciado duas vezes — é recusada: blocked, depois fatal, e o stream para. Passe takeover: true para substituir o titular; o titular recebe replaced, depois fatal, e para (não revida).
  • Um FillStream se identifica com um clientId aleatório, então suas próprias reconexões após uma queda de rede substituem sua própria conexão morta sem precisar de takeover.
  • Quando o servidor reinicia, ele fecha o socket com 1012; o stream reconecta imediatamente (evento restarting) e reproduz qualquer coisa que perdeu. HTTPS_PROXY: passe wsOptions: { agent } para o WebSocket e defina um dispatcher de fetch global.

Os servidores da PMWallets estão no Reino Unido. Um consumidor que também negocia na Polymarket deve rodar da Irlanda (AWS eu-west-1): a Polymarket não aceita ordens de API do Reino Unido, dos EUA e de vários países da UE.

Agentes de IA: linha de comando e MCP

O pacote instala um comando pmwallets que imprime JSON — para scripts e para agentes de IA (Claude Code, Codex, Gemini CLI, Cursor, WorkBuddy, …) que agem sobre os fills dos traders que você segue.

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 executa o comando uma vez por lote, com os fills no stdin como linhas JSON (e em $PMW_BATCH_FILE); fills que chegam enquanto ele roda formam o próximo lote. Um lote é entregue no máximo uma vez: um lote cujo comando falha, expira ou é interrompido é mantido em pmw-watch/failed/ e nunca é reexecutado — o agente pode já ter colocado uma ordem. Reinícios retomam de onde o stream parou.
  • Para negociar, dê ao agente pmwallets-copytrade: order buy <tokenId> --usdc 5 --key <eventId> (a mesma chave nunca ordena duas vezes), market, balance, positions.
  • Plataformas sem shell (Dify, Coze, n8n, GPT Actions): importe openapi.json.
  • HTTPS_PROXY / NO_PROXY são respeitados pela linha de comando.

Configuração MCP (Claude Desktop, Cursor, Windsurf, WorkBuddy, …):

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

Exportações de histórico de negociações

Uma compra é acesso a arquivos: um CSV comprimido com zstd por carteira por dia UTC, baixável imediatamente e novamente depois.

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) retorna o link de curta duração; a chave de API nunca é enviada ao host de armazenamento.

Recursos

Guias

Licença

MIT