Dr. Manhattan - Prediction Market Trading

Dr. Manhattan is a unified API for prediction markets, similar to how CCXT works for cryptocurrency exchanges. It supports Polymarket, Kalshi, Opinion, Limitless, and Predict.fun through a single interface.

Setup

Install dependencies with uv:

uv venv && uv pip install -e .

For MCP server (Claude integration):

uv sync --extra mcp

Supported Exchanges

Usage as a Python Library

Read-Only (No Credentials)

import dr_manhattan

polymarket = dr_manhattan.Polymarket({'timeout': 30})
markets = polymarket.fetch_markets()
for market in markets:
    print(f"{market.question}: {market.prices}")

With Authentication

import dr_manhattan

polymarket = dr_manhattan.Polymarket({
    'private_key': '0x...',
    'funder': '0x...',
})

order = polymarket.create_order(
    market_id="market_123",
    outcome="Yes",
    side=dr_manhattan.OrderSide.BUY,
    price=0.65,
    size=100,
    params={'token_id': 'token_id'}
)

Exchange Factory

from dr_manhattan import create_exchange, list_exchanges

print(list_exchanges())  # ['polymarket', 'opinion', 'limitless', 'predictfun', 'kalshi']
exchange = create_exchange('polymarket', {'timeout': 30})

Usage via MCP Server

Dr. Manhattan exposes all trading capabilities as MCP tools. Configure in Claude Code (~/.claude/settings.json or .mcp.json):

{
  "mcpServers": {
    "dr-manhattan": {
      "command": "/path/to/dr-manhattan/.venv/bin/python",
      "args": ["-m", "dr_manhattan.mcp.server"],
      "cwd": "/path/to/dr-manhattan"
    }
  }
}

MCP Tools Reference

Exchange Tools:

• list_exchanges - List all available prediction market exchanges.
• getexchangeinfo(exchange) - Get metadata and capabilities for an exchange.
• validate_credentials(exchange) - Check if credentials are valid without trading.

Market Discovery:

• search_markets(exchange, query) - Search markets by keyword. This is the fastest way to find markets about a topic.
• fetch_markets(exchange, limit?, offset?) - Fetch all markets with pagination.
• fetchmarket(exchange, marketid) - Fetch a specific market by ID.
• fetchmarketsby_slug(exchange, slug) - Fetch markets by slug or URL (Polymarket, Limitless).
• findtradeablemarket(exchange, binary?, limit?, min_liquidity?) - Find a suitable market for trading.
• findcryptohourlymarket(exchange, tokensymbol?) - Find crypto hourly price markets (Polymarket).
• fetchtokenids(exchange, market_id) - Get token IDs for a market.
• parsemarketidentifier(identifier) - Extract slug from a Polymarket URL.
• gettagby_slug(slug) - Get Polymarket tag information.

Orderbook:

• getorderbook(exchange, tokenid) - Get full orderbook (bids and asks).
• getbestbidask(exchange, tokenid) - Get best bid and ask prices.

Trading:

• createorder(exchange, marketid, outcome, side, price, size) - Place a buy or sell order. Price is 0-1 (probability). Side is "buy" or "sell".
• cancelorder(exchange, orderid, market_id?) - Cancel a specific order.
• cancelallorders(exchange, market_id?) - Cancel all open orders.
• fetchorder(exchange, orderid, market_id?) - Get order details and fill status.
• fetchopenorders(exchange, market_id?) - List all open orders.

Account:

• fetch_balance(exchange) - Get account balance (USDC).
• fetchpositions(exchange, marketid?) - Get current positions with PnL.
• fetchpositionsformarket(exchange, marketid) - Get positions for a specific market.
• calculatenav(exchange, marketid?) - Calculate net asset value (cash + positions).

Strategy Management:

• createstrategysession(strategytype, exchange, marketid, ...) - Start a market-making strategy in the background.
• getstrategystatus(session_id) - Get real-time strategy status (NAV, positions, delta).
• getstrategymetrics(session_id) - Get performance metrics (uptime, fills).
• pausestrategy(sessionid) - Pause a running strategy.
• resumestrategy(sessionid) - Resume a paused strategy.
• stopstrategy(sessionid, cleanup?) - Stop a strategy and optionally cancel orders.
• liststrategysessions - List all active strategy sessions.

Common Workflows

Find and Analyze a Market

1. Use search_markets with a keyword to find relevant markets.
2. Pick a market from the results and note its id and metadata.clobTokenIds.
3. Use get_orderbook with a token ID to see current bids and asks.
4. Use getbestbid_ask for a quick spread check.

Place a Trade

1. Find the market using searchmarkets or fetchmarketsbyslug.
2. Check fetch_balance to confirm available funds.
3. Get the orderbook with get_orderbook to see current prices.
4. Use create_order with the market ID, outcome ("Yes" or "No"), side ("buy" or "sell"), price (0-1), and size.
5. Monitor with fetchorder or fetchopen_orders.

Run a Market-Making Strategy

1. Find a market with searchmarkets or findtradeable_market.
2. Start with createstrategysession(strategytype="marketmaking", exchange, market_id).
3. Monitor with getstrategystatus and getstrategymetrics.
4. Control with pausestrategy, resumestrategy, or stop_strategy.

Check Portfolio

1. fetch_balance to see cash.
2. fetch_positions to see all open positions with unrealized PnL.
3. calculate_nav for total portfolio value (cash + positions).

Key Concepts

• Prices are probabilities ranging from 0 to 1 (exclusive). A price of 0.65 means the market implies a 65% chance.
• Outcomes are typically "Yes" and "No" for binary markets. Their prices sum to approximately 1.
• Token IDs are exchange-specific identifiers for each outcome of a market. Needed for orderbook queries.
• Slugs are human-readable URL identifiers (e.g., "trump-2024") used by Polymarket and Limitless.
• Order types supported: GTC (Good-Til-Cancel), FOK (Fill-Or-Kill), IOC (Immediate-Or-Cancel).

Running Examples

uv run python examples/list_all_markets.py polymarket
uv run python examples/spread_strategy.py --exchange polymarket --slug fed-decision
uv run python examples/spike_strategy.py -e opinion -m 813 --spike-threshold 0.02

Data Models

Market fields: id, question, outcomes, prices, volume, liquidity, closetime, ticksize, description, metadata (contains slug, clobTokenIds).

Order fields: id, marketid, outcome, side (BUY/SELL), price, size, filled, status (PENDING/OPEN/FILLED/CANCELLED), timein_force.

Position fields: marketid, outcome, size, averageprice, currentprice. Properties: costbasis, currentvalue, unrealizedpnl.

Orderbook fields: bids (price, size descending), asks (price, size ascending). Properties: bestbid, bestask, mid_price, spread.