paean-polymarket-mcp

Polymarket prediction market MCP server — trade, monitor, and analyze prediction markets for AI agents.

Warning: AI-Generated Software — Use at Your Own Risk

This software was generated with AI assistance. It has not been independently audited for security vulnerabilities. Prediction market trading involves significant financial risk, including total loss of funds. Orders are executed on Polymarket's CLOB (Central Limit Order Book) on Polygon and are binding once filled. The authors and contributors accept no liability for any loss of funds, failed transactions, or any other damages resulting from use of this software. Before using with real wallets or mainnet assets, conduct your own security review, test thoroughly, and never trade more than you can afford to lose.

paean-polymarket-mcp is a Model Context Protocol server that exposes Polymarket prediction market operations as tools for AI agents. It enables agents to search markets, analyze prices, place orders, and manage positions — without embedding any credentials in prompts or tool outputs.

Key capabilities:

• Market discovery — Search events, get market details, order books, prices, and historical data
• Trading — Place limit/market orders (GTC, GTD, FOK, FAK), cancel orders, view trade history
• Portfolio — Check USDC balance, view open positions, track open orders
• Arbitrage-ready — Price history, order book depth, and spread data for quantitative analysis

Privacy-first design:

• Private keys are read exclusively from environment variables
• Secrets are never logged, returned in tool outputs, or exposed in any way
• Works in read-only mode (market data, prices, order books) without any wallet configured

Quick start

# Run with npx (no install needed)
npx paean-polymarket-mcp

# Or install globally
npm install -g paean-polymarket-mcp
paean-polymarket-mcp

With a private key (for trading):

POLYMARKET_PRIVATE_KEY=0xabc... npx paean-polymarket-mcp

Environment Variables

| Variable | Required | Default | Description | |---|---|---|---| | POLYMARKET_PRIVATE_KEY | For trading | — | Polygon wallet private key (hex, 0x-prefixed) | | POLYMARKET_HOST | No | https://clob.polymarket.com | CLOB API host | | POLYMARKET_RPC_URL | No | — | Custom Polygon RPC endpoint | | POLYMARKET_FUNDER | No | — | Polymarket profile/funder address (for proxy wallets) | | POLYMARKET_SIGNATURE_TYPE | No | 0 | 0 = EOA wallet, 1 = Magic/Email login, 2 = Proxy |

Without POLYMARKET_PRIVATE_KEY, the server runs in read-only mode — market search, prices, order books, and historical data are still fully available.

Tools

Market Discovery

search_markets

Search Polymarket prediction markets by keyword via the Gamma API. Returns events with their markets, outcomes, prices, and volumes.

{ "query": "bitcoin", "active": true, "limit": 10, "tag": "crypto" }

get_market

Get detailed information about a specific market by its condition ID.

{ "condition_id": "0x19ee98e..." }

Returns question, outcomes, token IDs, prices, volume, tick size, and neg risk flag.

get_orderbook

Get the order book (bids and asks) for a specific outcome token.

{ "token_id": "935929492..." }

Returns price levels, sizes, spread, tick size, and last trade price.

get_market_prices

Get the current midpoint price, spread, and last trade price for an outcome token.

{ "token_id": "935929492..." }

get_price_history

Get historical price data for trend analysis, backtesting, and arbitrage detection.

{ "market": "0x19ee98e...", "interval": "1d", "fidelity": 100 }

Intervals: 1h, 6h, 1d, 1w, max.

Trading

get_wallet_address

Get the configured Polygon wallet address. Safe to call — never reveals private keys.

{}

get_balance

Get USDC collateral balance and allowance on Polymarket.

{}

create_order

Place an order on Polymarket. Supports limit orders (GTC, GTD) and market orders (FOK, FAK).

{
  "token_id": "935929492...",
  "price": 0.65,
  "size": 100,
  "side": "BUY",
  "order_type": "GTC"
}

• price: Between 0.001 and 0.999 (e.g. 0.65 = 65% probability for YES tokens)
• size: Number of shares for limit orders; USDC amount for market BUY orders
• side: BUY or SELL
• order_type: GTC (Good-Til-Cancelled), GTD (Good-Til-Date), FOK (Fill-Or-Kill), FAK (Fill-And-Kill)

cancel_order

Cancel an open order by its order ID.

{ "order_id": "abc123..." }

get_open_orders

List all open (resting) orders. Optionally filter by market or token.

{ "market": "0x19ee98e..." }

get_trades

Get executed trade history with prices, sizes, fees, and timestamps.

{ "market": "0x19ee98e..." }

Account

get_positions

Get current open positions via the Polymarket Data API.

{}

derive_api_key

Derive or create CLOB API credentials from the configured wallet. Normally done automatically on the first trading call.

{}

Integration

PaeanClaw

Add to paeanclaw.config.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "paean-polymarket-mcp"],
      "env": {
        "POLYMARKET_PRIVATE_KEY": "${POLYGON_PRIVATE_KEY}"
      }
    }
  }
}

Tools are available as polymarket__search_markets, polymarket__create_order, etc.

OpenPaean / ai-paean-cli

Add to ~/.paean/mcp_config.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "paean-polymarket-mcp"],
      "env": {
        "POLYMARKET_PRIVATE_KEY": "${POLYGON_PRIVATE_KEY}"
      }
    }
  }
}

Claude Desktop / Cursor

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "paean-polymarket-mcp"],
      "env": {
        "POLYMARKET_PRIVATE_KEY": "0xYourHexKey"
      }
    }
  }
}

Read-only mode (no wallet)

For market research without trading:

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["-y", "paean-polymarket-mcp"]
    }
  }
}

Example Flows

Market research

1. search_markets — find events matching your interests
2. get_market — get detailed info (outcomes, token IDs, tick size)
3. get_orderbook — analyze liquidity depth
4. get_price_history — review price trends
5. get_market_prices — check current midpoint and spread

Place a trade

1. search_markets — find the market
2. get_market — get token IDs and tick size
3. get_orderbook — check current prices and liquidity
4. get_balance — verify sufficient USDC
5. create_order — place the order
6. get_open_orders — verify order is resting

Arbitrage analysis

1. search_markets — find related markets
2. get_market_prices — compare YES/NO prices across markets
3. get_orderbook — check depth and slippage at target size
4. get_price_history — identify price dislocations
5. create_order — execute trades when opportunities arise

Testing

Build first, then run the integration test:

npm run build

# Read-only tests (no key needed)
node scripts/test-mcp.mjs

# Full tests with trading (order construction + signing)
POLYMARKET_PRIVATE_KEY=0x... node scripts/test-mcp.mjs

The test script covers all 13 tools. Without a funded Polymarket wallet, trading tests will validate order construction and signing but may receive expected errors (insufficient balance, geo-restriction).

Security notes

• Never commit private keys to version control. Use environment variables or a secrets manager.
• The server uses stdio transport only — it never opens a network port.
• create_order requires explicit parameters (token, price, size, side) — it cannot be called without full specification.
• API credentials are derived from the wallet and stored only in memory for the session duration.
• In read-only mode (no key), no signing or authentication is performed.
• All Polymarket operations occur on Polygon mainnet (chain ID 137). Ensure you are using the correct network.

Development

git clone [email protected]:paean-ai/paean-polymarket-mcp.git
cd paean-polymarket-mcp
npm install
npm run build
npm start

Use MCP Inspector for debugging:

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT — Paean AI