polymarket-mcp

name	polymarket-mcp
description	Polymarket MCP server tools — query markets, events, and trades via 3 API tools
category	research

Polymarket MCP Server — Agent Skill

MCP tools for querying Polymarket prediction market data. No auth required for read-only access.

Tools

getmarkets — Query prediction markets

Find markets by topic, status, volume. Returns market data with outcome probabilities.

Key params: active (true/false), closed (true/false), slug, order (volume/liquidity), limit

Example queries:

# Top active markets by volume
getmarkets(limit=10, active="true", closed="false")

# Find a specific market
getmarkets(slug="bitcoin-above-100k-on-june-30")

# Resolved markets (for P&L analysis)
getmarkets(limit=50, closed="true")

Response fields:

• question — market question text
• slug — URL-friendly identifier (use for trade queries)
• outcomes — JSON array like ["Yes", "No"]
• outcomePrices — JSON array like ["0.65", "0.35"] — price = probability
• volume — total USDC traded
• active / closed — market state

getevents — Query event groups

Events group related markets (e.g., "NBA Finals" event contains multiple game markets).

gettrades — Get live trade feed

Returns recent trades. Use slug for market-specific, proxywallet for wallet-specific.

Key params: limit, slug, proxywallet (wallet address), side (BUY/SELL)

⚠️ Important: Does NOT return historical trades for resolved markets. Only live data.

Agent Workflows

"What are the odds of X?"

1. getmarkets(limit=20, active="true") — search active markets
2. Filter by keyword in question field
3. Parse outcomePrices — each price is a probability (0.65 = 65%)
4. Report: "Polymarket shows X at Y% based on $Z volume"

"Show me the hottest markets right now"

1. getmarkets(limit=10, active="true", closed="false", order="volume")
2. Present top markets with their odds

"Who's trading on market X?"

1. getmarkets(slug="market-slug") — get market details
2. gettrades(slug="market-slug", limit=50) — see recent trades
3. Count BUY vs SELL, identify active wallets

"What resolved recently?"

1. getmarkets(limit=20, closed="true", order="volume")
2. Show winners from outcomePrices (outcome at 1.0 = winner)

Interpreting Market Prices

Market price = crowd's probability estimate.

• Price $0.65 on "Yes" = 65% chance of Yes
• Prices always sum to ~1.0

Quality signals:

• Volume > $100K = liquid, reliable
• Many recent trades = active price discovery
• Tight outcome spread = efficient market

Caveats:

• Low volume markets (< $10K) may be poorly priced
• Prices include risk premium, not pure probabilities
• Resolution depends on market rules (check question text)

Pitfalls

• gettrades uses a different API (data-api.polymarket.com) than getmarkets/getevents (gamma-api.polymarket.com). Don't assume same data.
• Slug matching is approximate for resolved markets — querying a resolved slug returns the active market with a similar slug
• outcomePrices is a JSON string, not an array — parse it: json.loads(prices)
• Rate limits — no hard limits documented, but use 1-2s delays between bulk queries
• Ephemeral markets (5m/15m crypto) get purged from the API after resolution
• Market makers are common — they provide liquidity, not alpha

Connection to Polymarket Intel

For deeper analysis (wallet scoring, consensus signals, paper trading), use the polymarket-intel CLI:

cd ~/polymarket-intel && python3 main.py signals   # smart money consensus
cd ~/polymarket-intel && python3 main.py leaderboard # top wallets
cd ~/polymarket-intel && python3 main.py run         # full pipeline

The MCP tools provide raw data; polymarket-intel provides the intelligence layer on top.