Metadata-Version: 2.4
Name: polymarket-trading-mcp
Version: 0.1.1
Summary: MCP server and Python toolkit for Polymarket prediction markets: slippage estimation, liquidity scanning, arbitrage detection, price feeds, and sentiment analysis.
Project-URL: Homepage, https://github.com/whitmorelabs/polymarket-mcp
Project-URL: Repository, https://github.com/whitmorelabs/polymarket-mcp
Author-email: Whitmore Labs <whitmorelabsai@gmail.com>
License: MIT
License-File: LICENSE
Keywords: ai-agent,arbitrage,clob,cryptocurrency,defi,liquidity,llm-tools,mcp,mcp-server,model-context-protocol,polygon,polymarket,prediction-market,prediction-markets,price-feed,sentiment-analysis,slippage,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: uvicorn>=0.20.0
Provides-Extra: dev
Requires-Dist: hatch>=1.7.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# polymarket-mcp

```bash
pip install polymarket-mcp
```

MCP server and Python toolkit for Polymarket prediction markets. Gives AI agents real-time slippage estimation, liquidity scanning, arbitrage detection, crypto price feeds, contract timers, sentiment analysis, probability estimation, and portfolio risk calculation — all through the Model Context Protocol.

Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.

---

## Quick Start

### Claude Desktop

Add to your `claude_desktop_config.json`:

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

### Run as SSE server

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

### Run as streamable HTTP

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

---

## Tools

All free tools require no API key. Paid tools require an API key from [whitmorelabs.io](https://github.com/whitmorelabs/polymarket-mcp).

### Free Tools

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

```python
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`
Scan a market's liquidity depth with spread and depth at 1%/2%/5% from mid.

```python
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 active Polymarket markets for YES + NO price sums that don't equal 1.00.

```python
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 crypto price from Binance and/or CoinGecko in parallel, with latency metadata.

```python
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 for active Polymarket contracts. BTC 5-min/15-min contracts use slug timestamp parsing for exact expiry.

```python
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`
Estimate the probability of any event using structured reasoning. Base rates, key factors, timeframe analysis — all in one structured JSON response.

```python
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 for a portfolio of prediction market positions. No external API calls.

```python
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`
Free. No API key. Returns scoring methodology, current dataset stats, and pricing. Call this first to evaluate whether the paid data is worth it.

### Paid Tools (API key required)

7-day free trial on signup. After trial: pay-per-request in USDC on Polygon.

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

Volume discount: 50% off above 1000 requests/day.

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

```python
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 Polymarket wallets from MoonMirror's scoring engine (PnL + consistency + specialization - drawdown penalty).

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

#### `get_wallet_score`
Full scoring breakdown for a specific wallet address.

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

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

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

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

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

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

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

```python
get_btc_short_markets(api_key="your-key")
```

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

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

---

## Wallet Intelligence: How It Works

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.

---

## Alternatives Comparison

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

---

## Configuration

All settings via environment variables:

```env
# 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

```bash
# 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

[github.com/whitmorelabs/polymarket-mcp](https://github.com/whitmorelabs/polymarket-mcp)

Issues, PRs, and stars welcome.
