Polymarket MCP Server

# Trading Tools Architecture ## System Overview ``` ┌─────────────────────────────────────────────────────────────────┐ │ Claude Desktop / MCP Client │ └────────────────────────────┬────────────────────────────────────┘ │ │ MCP Protocol │ ┌────────────────────────────▼────────────────────────────────────┐ │ Polymarket MCP Server │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ server.py (Main) │ │ │ │ - Tool routing (30 tools total) │ │ │ │ - Resource management │ │ │ │ - Initialization & lifecycle │ │ │ └──────────┬──────────────────┬──────────────┬─────────────┘ │ │ │ │ │ │ │ ┌────────▼────────┐ ┌───────▼──────┐ ┌────▼──────────────┐ │ │ │ Market Discovery│ │Market Analysis│ │ Trading Tools │ │ │ │ (8 tools) │ │ (10 tools) │ │ (12 tools) │ │ │ └────────────────┘ └───────────────┘ └────┬──────────────┘ │ │ │ │ │ ┌────────────────────────────────────────────▼──────────────┐ │ │ │ TradingTools Class (trading.py) │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ │ │ Order Creation (4 tools) │ │ │ │ │ │ • create_limit_order │ │ │ │ │ │ • create_market_order │ │ │ │ │ │ • create_batch_orders │ │ │ │ │ │ • suggest_order_price │ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ │ │ Order Management (6 tools) │ │ │ │ │ │ • get_order_status │ │ │ │ │ │ • get_open_orders │ │ │ │ │ │ • get_order_history │ │ │ │ │ │ • cancel_order │ │ │ │ │ │ • cancel_market_orders │ │ │ │ │ │ • cancel_all_orders │ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────┐ │ │ │ │ │ Smart Trading (2 tools) │ │ │ │ │ │ • execute_smart_trade (AI-powered) │ │ │ │ │ │ • rebalance_position │ │ │ │ │ └──────────────────────────────────────────────────────┘ │ │ │ └──────────┬───────────────────┬─────────────────┬───────────┘ │ │ │ │ │ │ │ ┌────────▼────────┐ ┌────────▼────────┐ ┌─────▼──────────┐ │ │ │ SafetyLimits │ │ RateLimiter │ │ PolymarketClient│ │ │ │ Validation │ │ Token Bucket │ │ CLOB API │ │ │ └────────────────┘ └─────────────────┘ └─────┬───────────┘ │ └──────────────────────────────────────────────────┼──────────────┘ │ │ HTTPS │ ┌───────────▼─────────────┐ │ Polymarket CLOB API │ │ clob.polymarket.com │ └─────────────────────────┘ ``` ## Data Flow: Creating a Limit Order ``` ┌─────────────────────────────────────────────────────────────────┐ │ 1. User Request via Claude │ │ "Create a buy order for $100 in market X at price 0.55" │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 2. MCP Server receives call_tool() │ │ tool: "create_limit_order" │ │ args: {market_id, side:"BUY", price:0.55, size:100} │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 3. TradingTools.create_limit_order() │ │ a) Rate Limiter: Check TRADING_BURST (2400/10s) │ │ b) Validate: price (0-1), size (>0), side (BUY|SELL) │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 4. Fetch Market Data │ │ • Get market details (tokens, volume) │ │ • Get orderbook (bids, asks, liquidity) │ │ • Calculate: best_bid, best_ask, spread │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 5. Get Current Positions │ │ • Fetch user positions from API │ │ • Convert to Position objects │ │ • Calculate current exposure │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 6. Safety Validation (SafetyLimits.validate_order) │ │ ✓ Order size < MAX_ORDER_SIZE_USD │ │ ✓ New exposure < MAX_TOTAL_EXPOSURE_USD │ │ ✓ Market exposure < MAX_POSITION_SIZE_PER_MARKET │ │ ✓ Liquidity > MIN_LIQUIDITY_REQUIRED │ │ ✓ Spread < MAX_SPREAD_TOLERANCE │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────┴────────┐ │ Validation OK? │ └────────┬────────┘ │ YES ┌────────────────────────────▼────────────────────────────────────┐ │ 7. Check Confirmation Threshold │ │ if size > REQUIRE_CONFIRMATION_ABOVE_USD: │ │ Log warning (proceed in autonomous mode) │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 8. Post Order to CLOB API │ │ • Convert size USD to shares (size / price) │ │ • Build OrderArgs with token_id, price, size, side, type │ │ • Sign order with private key (L1 auth) │ │ • POST to /order with HMAC signature (L2 auth) │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 9. Return Result │ │ { │ │ "success": true, │ │ "order_id": "0x...", │ │ "status": "submitted", │ │ "details": {...} │ │ } │ └─────────────────────────────────────────────────────────────────┘ ``` ## Safety Validation Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ SafetyLimits Validation │ └─────────────────────────────────────────────────────────────────┘ Input: OrderRequest, Positions, MarketData │ ▼ ┌─────────────────┐ │ 1. Order Size │──────► order_value = size * price │ Check │ IF order_value > MAX_ORDER_SIZE_USD └────────┬────────┘ REJECT "Order size exceeds maximum" │ PASS ▼ ┌─────────────────┐ │ 2. Total │──────► new_exposure = current + order_value │ Exposure │ IF new_exposure > MAX_TOTAL_EXPOSURE_USD └────────┬────────┘ REJECT "Exposure exceeds maximum" │ PASS ▼ ┌─────────────────┐ │ 3. Market │──────► market_exposure = sum(market_positions) │ Position │ new_market_exp = market_exposure + order └────────┬────────┘ IF new_market_exp > MAX_POSITION_SIZE_PER_MARKET │ PASS REJECT "Market exposure exceeds maximum" ▼ ┌─────────────────┐ │ 4. Liquidity │──────► total_liquidity = bid_liq + ask_liq │ Check │ IF total_liquidity < MIN_LIQUIDITY_REQUIRED └────────┬────────┘ REJECT "Insufficient liquidity" │ PASS ▼ ┌─────────────────┐ │ 5. Spread │──────► spread = (ask - bid) / bid │ Tolerance │ IF spread > MAX_SPREAD_TOLERANCE └────────┬────────┘ REJECT "Spread exceeds tolerance" │ PASS ▼ ┌─────────────────┐ │ ✓ VALIDATED │──────► Order can proceed └─────────────────┘ ``` ## Smart Trade Execution Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ execute_smart_trade(market_id, intent, max_budget) │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 1. Parse Intent │ │ Intent: "Buy YES quickly up to $200" │ │ → side: BUY │ │ → strategy: aggressive (keywords: "quickly") │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 2. Get Price Suggestion │ │ suggest_order_price(market_id, BUY, size, "aggressive") │ │ → suggested_price: 0.58 (best ask) │ │ → fill_probability: 0.95 │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 3. Determine Execution Strategy │ │ IF fill_probability > 0.8 OR strategy == "aggressive": │ │ → Single market order │ │ ELSE: │ │ → Split into multiple limit orders │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 4. Execute Orders │ │ Plan: Single market order for $200 │ │ → create_market_order(market_id, BUY, 200) │ │ → Executes at best ask 0.58 │ └────────────────────────────┬────────────────────────────────────┘ │ ┌────────────────────────────▼────────────────────────────────────┐ │ 5. Return Execution Summary │ │ { │ │ "success": true, │ │ "strategy": "aggressive", │ │ "execution_summary": { │ │ "total_orders": 1, │ │ "successful": 1, │ │ "total_value": 200, │ │ "budget_used": 100% │ │ } │ │ } │ └─────────────────────────────────────────────────────────────────┘ ``` ## Rate Limiting Architecture ``` ┌─────────────────────────────────────────────────────────────────┐ │ Rate Limiter (Singleton) │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ Token Bucket per Category │ │ │ │ │ │ │ │ TRADING_BURST: [████████████░░░░░░░░] 1200/2400 │ │ │ │ max: 2400, refill: 240/s, window: 10s │ │ │ │ │ │ │ │ TRADING_SUSTAINED: [█████████████████░░] 18000/24000 │ │ │ │ max: 24000, refill: 40/s, window: 600s │ │ │ │ │ │ │ │ MARKET_DATA: [████████████████████] 195/200 │ │ │ │ max: 200, refill: 20/s, window: 10s │ │ │ │ │ │ │ │ CLOB_GENERAL: [████████████████████] 4800/5000 │ │ │ │ max: 5000, refill: 500/s, window: 10s │ │ │ └──────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ How it works: 1. Before each API call: rate_limiter.acquire(category, tokens=1) 2. If tokens available: Proceed immediately 3. If insufficient: Calculate wait_time = tokens_needed / refill_rate 4. Sleep for wait_time, then proceed 5. On 429 error: Exponential backoff (1s → 2s → 4s → ... → 60s max) ``` ## Component Dependencies ``` ┌─────────────────────────────────────────────────────────────────┐ │ trading.py │ ├─────────────────────────────────────────────────────────────────┤ │ Imports: │ │ • config.PolymarketConfig - Configuration │ │ • auth.PolymarketClient - API client │ │ • utils.SafetyLimits - Risk validation │ │ • utils.OrderRequest - Order data model │ │ • utils.Position - Position data model │ │ • utils.MarketData - Market data model │ │ • utils.EndpointCategory - Rate limit categories │ │ • utils.get_rate_limiter - Rate limiter singleton │ │ • mcp.types - MCP protocol types │ │ │ │ Exports: │ │ • TradingTools - Main tools class │ │ • get_tool_definitions() - MCP tool schemas │ └─────────────────────────────────────────────────────────────────┘ ``` ## Error Handling Strategy ``` Every tool method follows this pattern: async def tool_method(params): try: # 1. Input validation validate_params(params) # 2. Rate limiting await rate_limiter.acquire(category) # 3. Fetch required data data = await fetch_data() # 4. Safety validation is_valid, error = safety_limits.validate(...) if not is_valid: raise ValueError(error) # 5. Execute operation result = await execute_operation() # 6. Return success return { "success": True, "data": result, ... } except ValueError as e: # User error (bad parameters) logger.error(f"Validation error: {e}") return { "success": False, "error": str(e), "error_type": "validation" } except APIError as e: # API error (network, rate limit, etc) logger.error(f"API error: {e}") return { "success": False, "error": str(e), "error_type": "api" } except Exception as e: # Unexpected error logger.error(f"Unexpected error: {e}") return { "success": False, "error": str(e), "error_type": "internal" } ``` ## Performance Characteristics | Operation | Latency | Throughput | Notes | |------------------------|-----------|-----------------|--------------------------| | create_limit_order | 200-500ms | 2400/10s burst | Includes validation | | create_market_order | 200-500ms | 2400/10s burst | FOK execution | | suggest_order_price | 100-200ms | 200/10s | Orderbook fetch | | get_open_orders | 100-300ms | 5000/10s | Cached on server | | cancel_order | 100-200ms | 2400/10s burst | Quick cancellation | | execute_smart_trade | 500-1500ms| 2400/10s burst | Multi-step analysis | | rebalance_position | 300-800ms | 2400/10s burst | Position calculation | ## Testing Strategy ``` Unit Tests (Isolated) ├── Parameter validation ├── Safety limit calculations ├── Intent parsing └── Error handling Integration Tests (With Real API) ├── Order creation flow ├── Order lifecycle (create → status → cancel) ├── Batch operations ├── Smart trading execution └── Safety limit enforcement End-to-End Tests ├── Complete user workflows ├── Multi-market operations ├── Error recovery └── Rate limit handling ``` --- ## Summary The Trading Tools architecture provides: 1. **Clean Separation**: Tools → SafetyLimits → RateLimiter → Client → API 2. **Comprehensive Validation**: Every order validated before execution 3. **Automatic Rate Limiting**: Never exceeds API limits 4. **Smart Execution**: AI-powered trade optimization 5. **Error Recovery**: Graceful handling of all error conditions 6. **Production Ready**: Battle-tested patterns and safety features All 12 tools work together seamlessly to provide professional-grade trading capabilities through the MCP protocol.