polymarket-mcp

<!-- mcp-name: io.github.whitmorelabs/polymarket-mcp -->

Prediction market intelligence for AI agents. Wallet scores, arbitrage detection, liquidity analysis, and real-time price feeds for Polymarket — backed by proprietary data from 195+ curated on-chain wallets.

---

What can it do?

Ask your AI agent:

• "Find all Polymarket markets where YES + NO prices don't add up to 100%"
• "What's the slippage if I buy $500 of YES on the Bitcoin $100k market?"
• "Show me the top 20 wallets on Polymarket by score and PnL"
• "Which wallets co-trade alongside this whale? Find the shadow network."
• "What's the liquidity grade for this market — is it safe to enter?"
• "Calculate my portfolio risk across these 5 positions"
• "What's the probability that Bitcoin hits $150k by June?"
• "Scan today's crypto news and match to open Polymarket markets"

---

Install

pip install polymarket-trading-mcp

Or run directly:

uvx --python 3.11 polymarket-trading-mcp

---

MCP Config

<details> <summary><strong>Claude Desktop</strong></summary>

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "polymarket": {
      "command": "polymarket-mcp",
      "args": ["--stdio"]
    }
  }
}

</details>

<details> <summary><strong>Cursor / Windsurf / other MCP clients</strong></summary>

Run as SSE server:

polymarket-mcp
# Starts on http://127.0.0.1:8000/sse

Run as streamable HTTP:

polymarket-mcp --http
# Starts on http://127.0.0.1:8000/mcp

Then point your client at http://127.0.0.1:8000/sse or http://127.0.0.1:8000/mcp.

</details>

---

How it compares

Feature	polymarket-mcp	Manual CLOB calls	py-clob-client
MCP integration	Yes	No	No
Slippage estimation	Yes	DIY	Partial
Arbitrage scanning	Yes	DIY	No
Wallet intelligence	Yes	No	No
Price feed (multi-source)	Yes	No	No
Probability engine	Yes	No	No
Portfolio risk math	Yes	No	No
AI agent ready	Yes	No	No

---

Tools

Free Tools

<details> <summary><strong>estimate_slippage</strong> — Estimate fill cost at different order sizes</summary>

Walk the CLOB order book and calculate average fill price for a given position size.

estimate_slippage(
    market_id="71321045679252212594626385532587807886473352341859285086426388424842616389328",
    side="BUY",
    position_size_usd=500.0
)

Returns: best_price, avg_fill_price, slippage_pct, liquidity_available, recommendation (go/caution/no-go).

</details>

<details> <summary><strong>scan_market_liquidity</strong> — Liquidity depth, spread, and grade</summary>

Scan a market's liquidity depth with spread and depth at 1%/2%/5% from mid.

scan_market_liquidity(market_id="71321045679252212594626385532587807886473352341859285086426388424842616389328")

Returns: best_bid, best_ask, spread_pct, depth buckets, liquidity_grade (A/B/C).

</details>

<details> <summary><strong>find_arbitrage_gaps</strong> — Scan all markets for YES+NO mispricing</summary>

Scan all active Polymarket markets for YES + NO price sums that don't equal 1.00.

find_arbitrage_gaps(min_gap_pct=2.0)

Returns: markets with gaps, gap size, and direction to exploit (BUY_BOTH or SELL_BOTH).

</details>

<details> <summary><strong>get_crypto_price</strong> — Real-time prices from Binance and CoinGecko</summary>

Real-time crypto price from Binance and/or CoinGecko in parallel, with latency metadata.

get_crypto_price(symbol="BTC", sources="binance,coingecko")

Returns: per-source prices, average, max deviation between sources.

</details>

<details> <summary><strong>get_contract_status</strong> — Time remaining and resolution status</summary>

Time remaining and resolution status for active Polymarket contracts. BTC 5-min/15-min contracts use slug timestamp parsing for exact expiry.

get_contract_status(market_id="btc-updown-5m-1711234567")
get_contract_status(category="crypto")  # scan all short-duration contracts

Returns: time_remaining_seconds, time_remaining_human, current_odds.

</details>

<details> <summary><strong>estimate_probability</strong> — Structured probability reasoning for any question</summary>

Estimate the probability of any event using structured reasoning. Base rates, key factors, timeframe analysis — all in one structured JSON response.

estimate_probability(question="Will Bitcoin reach $150k before end of 2025?")

Returns: estimated_probability (0-1), confidence_level, factors_for, factors_against, base_rate_note, reasoning.

</details>

<details> <summary><strong>calculate_portfolio_risk</strong> — Pure-math risk metrics across positions</summary>

Pure-math risk metrics for a portfolio of prediction market positions. No external API calls.

calculate_portfolio_risk(positions='[{"market_id": "abc123", "side": "YES", "size": 200, "entry_price": 0.65}]')

Returns: total_exposure, max_loss, max_gain, diversification_score, kelly_warnings, rebalancing_suggestions.

</details>

<details> <summary><strong>get_scoring_performance</strong> — Metadata and dataset stats (free)</summary>

Returns scoring methodology, current dataset stats, and pricing. Call this first to evaluate whether the paid data is worth it. No API key required.

</details>

Paid Tools (API key required)

7-day free trial on signup. After trial: pay-per-request in USDC on Polygon. Volume discount: 50% off above 1000 requests/day.

Tool	Cost
get_shadow_wallets	$0.05/request
get_top_wallets	$0.05/request
get_wallet_score	$0.05/request
get_wallet_pnl	$0.05/request
get_wallet_clusters	$0.05/request
get_btc_short_markets	$0.01/request
analyze_market_sentiment	$0.05/request

<details> <summary><strong>get_shadow_wallets</strong> — Find wallets that co-trade with a whale</summary>

Find wallets that co-trade with a seed wallet across the same Polymarket categories.

get_shadow_wallets(seed_wallet="0xabc...", api_key="your-key")

Returns: up to 20 shadow wallets ranked by co-trading intensity, shared categories, win rates.

</details>

<details> <summary><strong>get_top_wallets</strong> — Top-ranked wallets by score and PnL</summary>

Top-ranked Polymarket wallets from MoonMirror's scoring engine (PnL + consistency + specialization - drawdown penalty).

get_top_wallets(api_key="your-key", limit=50, min_score=0.5)

</details>

<details> <summary><strong>get_wallet_score</strong> — Full scoring breakdown for any wallet</summary>

Full scoring breakdown for a specific wallet address.

get_wallet_score(address="0xabc...", api_key="your-key")

Returns: score components, win rate, trade count, data freshness.

</details>

<details> <summary><strong>get_wallet_pnl</strong> — Realized PnL with per-category breakdown</summary>

Realized PnL for a wallet with per-category breakdown. Pre-computed from Goldsky subgraph.

get_wallet_pnl(address="0xabc...", api_key="your-key")

</details>

<details> <summary><strong>get_wallet_clusters</strong> — Wallets independently co-trading with multiple top wallets</summary>

Wallets that independently appear alongside 3+ different top-scoring wallets — stronger signal than a single shadow match.

get_wallet_clusters(api_key="your-key", min_co_trades=3)

</details>

<details> <summary><strong>get_btc_short_markets</strong> — Active BTC 5-min and 15-min contracts</summary>

Active BTC 5-min and 15-min Polymarket contracts with token IDs and current midpoint prices. Cached, refreshed every 60 seconds.

get_btc_short_markets(api_key="your-key")

</details>

<details> <summary><strong>analyze_market_sentiment</strong> — Structured probabilistic analysis</summary>

Structured probabilistic analysis for a prediction market question using Claude's reasoning.

analyze_market_sentiment(question="Will Ethereum ETF hit $10B AUM by Q3 2025?", api_key="your-key")

</details>

---

Pricing

Tier	Cost	Access
Free tools	$0	Slippage, liquidity, timer, price feeds, arbitrage, risk calculator
Paid tools	$0.05/request	Wallet intelligence, sentiment analysis
Bundle	pip install polymarket-trading-mcp	All 10 tools

Standalone packages also available: polymarket-slippage, polymarket-liquidity, polymarket-arb-detector, polymarket-price-feed, polymarket-sentiment, polymarket-timer, polymarket-news, polymarket-onchain

---

Why this server?

Every other Polymarket MCP server queries public APIs. We have proprietary wallet intelligence — curated scores, real PnL data from Goldsky, and shadow wallet networks discovered through counterparty mining. Data you can't get anywhere else.

The paid wallet tools are backed by MoonMirror, a Polymarket wallet intelligence engine. MoonMirror continuously monitors wallets on-chain, scores them on PnL, consistency, and market specialization, and pre-computes shadow wallet relationships.

All wallet queries return in < 100ms because everything is pre-computed. No blocking subgraph calls.

---

Configuration

All settings via environment variables:

# Server
HOST=127.0.0.1
PORT=8000

# DB paths (for self-hosted wallet intelligence)
MOONMIRROR_DB_PATH=/path/to/moonmirror.db
SERVICES_DB_PATH=/path/to/services.db

# Pricing
PRICE_WALLET_INTEL=0.05
PRICE_MARKET_DATA=0.01
TRIAL_DAYS=7

# Rate limiting
RATE_PER_KEY=5
RATE_GLOBAL=20

---

<details> <summary><strong>Admin CLI</strong></summary>

# Create an API key
polymarket-mcp --create-key "customer-name"

# Top up a key's USDC balance
polymarket-mcp --top-up YOUR_KEY 10.0

</details>

---

github.com/whitmorelabs/polymarket-mcp — issues, PRs, and stars welcome.