📦

io.github.whitmorelabs/polymarket-mcp

Trading intelligence tools for Polymarket: slippage, liquidity, arbitrage, price feeds

0 installs

Trust: 37 — Low

Rag

Ask AI about io.github.whitmorelabs/polymarket-mcp

I know everything about io.github.whitmorelabs/polymarket-mcp. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

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

Claude Desktop

Add to your claude_desktop_config.json:

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

Cursor / Windsurf / other MCP clients

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.

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

estimate_slippage — Estimate fill cost at different order sizes

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).

scan_market_liquidity — Liquidity depth, spread, and grade

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).

find_arbitrage_gaps — Scan all markets for YES+NO mispricing

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).

get_crypto_price — Real-time prices from Binance and CoinGecko

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.

get_contract_status — Time remaining and resolution status

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.

estimate_probability — Structured probability reasoning for any question

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.

calculate_portfolio_risk — Pure-math risk metrics across positions

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.

get_scoring_performance — Metadata and dataset stats (free)

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

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

get_shadow_wallets — Find wallets that co-trade with a whale

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.

get_top_wallets — Top-ranked wallets by score and PnL

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)

get_wallet_score — Full scoring breakdown for any wallet

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.

get_wallet_pnl — Realized PnL with per-category breakdown

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

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

get_wallet_clusters — Wallets independently co-trading with multiple top wallets

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)

get_btc_short_markets — Active BTC 5-min and 15-min contracts

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")

analyze_market_sentiment — Structured probabilistic analysis

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")

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

Admin CLI

# 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

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