PMWallets
中文

Polymarket for AI agents: an MCP server and a command line

Claude, Cursor, Codex, Gemini CLI, WorkBuddy and other agents can compare Polymarket traders on the leaderboard, choose whom to follow and process their fills as they happen. Both tools are open source and print JSON.

What an agent can do

  • leaderboard: rank traders over 30 or 7 days, filtered by category, win rate (the low end of its interval), style and size.
  • entity: one trader's full record — profit, markets won and lost, maker or taker, categories. A free account opens a fixed sample of 20 traders plus those it has paid to unlock; an active monthly plan opens the others on the board.
  • subscribe / cancel_subscription / subscriptions: follow the fills of a trader whose address you have unlocked, stop, list who you follow.
  • new_fills: every fill since the previous call, each exactly once — for an agent that checks in on a schedule.
  • fills and market: replay from a ledger position; turn a token ID into its question and outcome.
  • account: your plan and balance.

Connect it as an MCP server

Add this to the MCP settings of Claude Desktop, Claude Code, Cursor or any other client that runs local MCP servers. The API key comes from your account page. The second server is optional: it is the copy-trading bot, and only needed if the agent should place orders.

json
{
  "mcpServers": {
    "pmwallets": {
      "command": "npx",
      "args": ["-y", "pmwallets", "mcp"],
      "env": { "PMW_API_KEY": "pmw_..." }
    },
    "copytrade": {
      "command": "npx",
      "args": ["-y", "pmwallets-copytrade", "mcp", "--config", "/abs/path/config.yaml"]
    }
  }
}

Or call the command line

The Node.js and Python packages expose the same tools through the `pmwallets` command; run the Python version with `uvx pmwallets`. Each command prints JSON for the agent to read from a shell; `npx pmwallets skill` prints instructions for using the tools.

bash
export PMW_API_KEY=pmw_...
npx pmwallets leaderboard --category politics --minWinLo 0.55 --limit 20
npx pmwallets entity <handle>
npx pmwallets subscribe <handle>      # billed per hour while it runs
npx pmwallets new-fills               # fills since the previous call, each once
npx pmwallets watch                   # live: one JSON line per fill

React to fills as they happen

`watch --exec` runs your command once per batch of fills, with the fills on its standard input. A batch is handed over at most once: if the command fails or times out, the batch is kept in pmw-watch/failed/ and not run again, because the agent may already have placed an order. Restarts carry on from where the stream stopped.

bash
npx pmwallets watch --batch-sec 30 --exec 'claude -p "Fills from traders I follow are on stdin. For each BUY above $1000, check the market with pmwallets-copytrade market, and buy $5 with --key <eventId> if the price is below 0.6." --allowedTools "Bash(pmwallets-copytrade:*)"'

Placing orders

PMWallets never places orders and never sees a private key. pmwallets-copytrade, the open-source bot, does it from your machine with your Polymarket account, and gives the agent market, balance, positions, trades, order_buy and order_sell.

  • A buy is fill-or-kill and its USDC amount is a ceiling the order never exceeds.
  • Pass the fill's eventId as the key: the same key never places a second order, so a retried agent cannot double a trade.
  • Dry-run mode simulates every order against the live order book; switch to live only when the agent's decisions look right.
  • The private key stays on your machine, supplied through the config or an environment variable, and the bot redacts secrets from its output.

Platforms without a shell

Dify, Coze, n8n and GPT Actions can import the OpenAPI description at https://pmwallets.com/openapi.json and call the same endpoints over HTTPS. Signed webhooks push each fill to a URL you choose instead of waiting to be asked.

What an API key can spend

An API key can spend your balance. Following a trader needs that trader's address unlocked first (a one-off price shown on the board, free for some, or from a monthly plan's allowance), then costs $0.01 per hour while the feed runs, or uses a slot of your plan; exports are paid too. There is no separate cap for keys, so give an agent a key on an account with only what you are willing to let it spend. A key cannot create other keys or change your plan — that needs a signed-in browser.

Questions

Is there a Polymarket MCP server?

Yes. Run `npx -y pmwallets mcp` to give an agent the Polymarket trader leaderboard, trader records and live fills from the traders you follow. `pmwallets-copytrade mcp` adds market data and orders on your own account.

Can ChatGPT use it?

Through GPT Actions: import https://pmwallets.com/openapi.json and authenticate with your API key. Agents that run commands or MCP servers locally (Claude, Cursor, Codex, Gemini CLI, WorkBuddy) can use the MCP server or the command line directly.

Does PMWallets trade for me?

No. PMWallets sells data. Orders are placed by the open-source copy-trading bot running on your own machine, under limits you set: a USDC ceiling per buy, no second order for the same key when you pass the fill's eventId, and dry-run mode until you switch to live.

What does it cost?

Ranking traders is free with an account. To follow a trader, unlock its address once (some are free), then pay $0.01 per hour for its fills, or use a monthly plan. The MCP server, the command line and the bot are free and MIT-licensed.

Related