MCP Tools

Complete reference for all Clawmarket MCP tools with JSON schemas, parameters, and response formats.

Overview

Clawmarket provides 6 core MCP tools for AI agent prediction market workflows:

1. market.search - Discover prediction markets by search criteria

2. market.get_data - Retrieve orderbook, trades, and market metadata

3. position.open - Open new positions in prediction markets

4. position.close - Close existing positions

5. portfolio.get_positions - Retrieve all active positions and P&L

6. market.get_probabilities - Extract market-implied probability distributions

market.search

Discover prediction markets matching search criteria.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query for market title/description
platform	string	No	Filter by platform (polymarket, kalshi)
category	string	No	Filter by category (politics, economics, technology)
min_liquidity	number	No	Minimum liquidity in USD
status	string	No	Market status (open, closed, resolved)

Request Example:

{
  "tool": "market.search",
  "parameters": {
    "query": "2024 presidential election",
    "platform": "polymarket",
    "category": "politics",
    "min_liquidity": 10000,
    "status": "open"
  }
}

Response:

{
  "markets": [
    {
      "id": "0x1a2b3c4d5e",
      "platform": "polymarket",
      "title": "Will Donald Trump win the 2024 U.S. presidential election?",
      "description": "Resolves YES if Donald Trump wins the electoral college...",
      "category": "politics",
      "close_date": "2024-11-05T23:59:59Z",
      "resolution_date": "2024-11-06T12:00:00Z",
      "total_volume": 15234567.89,
      "liquidity": 234567.89,
      "outcomes": [
        {
          "name": "YES",
          "probability": 0.47,
          "best_bid": 0.465,
          "best_ask": 0.475,
          "volume_24h": 125000
        },
        {
          "name": "NO",
          "probability": 0.53,
          "best_bid": 0.525,
          "best_ask": 0.535,
          "volume_24h": 132000
        }
      ]
    }
  ],
  "total_results": 1,
  "query_time_ms": 45
}

market.get_data

Retrieve detailed market data including orderbook depth, trade history, and metadata.

Parameters:

Parameter	Type	Required	Description
market_id	string	Yes	Unique market identifier
platform	string	Yes	Platform name (polymarket, kalshi)
data_types	array	Yes	Data to retrieve (orderbook, trades, metadata)
depth	number	No	Orderbook depth levels (default: 10)
trades_limit	number	No	Number of recent trades (default: 50)

Request Example:

{
  "tool": "market.get_data",
  "parameters": {
    "market_id": "0x1a2b3c4d5e",
    "platform": "polymarket",
    "data_types": ["orderbook", "trades", "metadata"],
    "depth": 10,
    "trades_limit": 20
  }
}

Response:

{
  "market_id": "0x1a2b3c4d5e",
  "orderbook": {
    "YES": {
      "bids": [
        {"price": 0.465, "size": 1000, "orders": 3},
        {"price": 0.460, "size": 2500, "orders": 7}
      ],
      "asks": [
        {"price": 0.475, "size": 1500, "orders": 4},
        {"price": 0.480, "size": 3000, "orders": 6}
      ]
    },
    "NO": {
      "bids": [
        {"price": 0.525, "size": 1200, "orders": 5},
        {"price": 0.520, "size": 2800, "orders": 8}
      ],
      "asks": [
        {"price": 0.535, "size": 1600, "orders": 3},
        {"price": 0.540, "size": 2900, "orders": 5}
      ]
    }
  },
  "recent_trades": [
    {
      "timestamp": "2026-03-10T14:32:15Z",
      "outcome": "YES",
      "price": 0.47,
      "size": 500,
      "side": "buy"
    }
  ],
  "metadata": {
    "total_volume": 15234567.89,
    "volume_24h": 257000.00,
    "open_interest": 32456.78,
    "implied_probability": 0.47,
    "spread": 0.01
  }
}

position.open

Open a new position in a prediction market.

Parameters:

Parameter	Type	Required	Description
market_id	string	Yes	Market identifier
platform	string	Yes	Platform name
outcome	string	Yes	Outcome to buy (YES, NO, or category name)
order_type	string	Yes	Order type (market, limit)
amount	number	Yes	USD amount to invest
limit_price	number	No	Limit price (required for limit orders)
slippage_tolerance	number	No	Max acceptable slippage (default: 0.02)

Request Example:

{
  "tool": "position.open",
  "parameters": {
    "market_id": "0x1a2b3c4d5e",
    "platform": "polymarket",
    "outcome": "YES",
    "order_type": "market",
    "amount": 500,
    "slippage_tolerance": 0.02
  }
}

Response:

{
  "position_id": "pos_9x8y7z6w5v",
  "status": "filled",
  "market_id": "0x1a2b3c4d5e",
  "market_title": "Will Donald Trump win the 2024 U.S. presidential election?",
  "outcome": "YES",
  "shares": 1063.83,
  "avg_price": 0.47,
  "total_cost": 500.00,
  "fees": 2.50,
  "slippage": 0.01,
  "timestamp": "2026-03-10T14:35:22Z",
  "tx_hash": "0xabc123def456..."
}

position.close

Close an existing position.

Parameters:

Parameter	Type	Required	Description
position_id	string	Yes	Position identifier
platform	string	Yes	Platform name
close_type	string	Yes	Close type (market, limit)
limit_price	number	No	Limit price (for limit orders)
partial_shares	number	No	Close partial position (default: close all)

Request Example:

{
  "tool": "position.close",
  "parameters": {
    "position_id": "pos_9x8y7z6w5v",
    "platform": "polymarket",
    "close_type": "market"
  }
}

Response:

{
  "position_id": "pos_9x8y7z6w5v",
  "status": "closed",
  "market_title": "Will Donald Trump win the 2024 U.S. presidential election?",
  "outcome": "YES",
  "shares_sold": 1063.83,
  "avg_sell_price": 0.52,
  "proceeds": 553.19,
  "cost_basis": 500.00,
  "fees": 2.81,
  "pnl": 50.38,
  "pnl_percent": 10.08,
  "timestamp": "2026-03-10T15:12:08Z",
  "tx_hash": "0xdef456ghi789..."
}

portfolio.get_positions

Retrieve all active positions across platforms with portfolio summary.

Parameters:

Parameter	Type	Required	Description
platforms	array	No	Filter by platforms (default: all connected)
status	string	No	Filter by status (open, closed, all)

Request Example:

{
  "tool": "portfolio.get_positions",
  "parameters": {
    "platforms": ["polymarket", "kalshi"],
    "status": "open"
  }
}

Response:

{
  "positions": [
    {
      "position_id": "pos_9x8y7z6w5v",
      "platform": "polymarket",
      "market_id": "0x1a2b3c4d5e",
      "market_title": "Will Donald Trump win the 2024 U.S. presidential election?",
      "outcome": "YES",
      "shares": 1063.83,
      "entry_price": 0.47,
      "current_price": 0.52,
      "market_value": 553.19,
      "cost_basis": 500.00,
      "unrealized_pnl": 53.19,
      "unrealized_pnl_percent": 10.64,
      "opened_at": "2026-03-10T14:35:22Z"
    }
  ],
  "summary": {
    "total_positions": 1,
    "total_market_value": 553.19,
    "total_cost_basis": 500.00,
    "total_unrealized_pnl": 53.19,
    "total_realized_pnl": 127.45,
    "by_platform": {
      "polymarket": {"positions": 1, "value": 553.19},
      "kalshi": {"positions": 0, "value": 0.00}
    }
  }
}

market.get_probabilities

Extract market-implied probability distributions for analysis.

Parameters:

Parameter	Type	Required	Description
market_id	string	Yes	Market identifier
platform	string	Yes	Platform name

Request Example:

{
  "tool": "market.get_probabilities",
  "parameters": {
    "market_id": "0x1a2b3c4d5e",
    "platform": "polymarket"
  }
}

Response:

{
  "market_id": "0x1a2b3c4d5e",
  "market_title": "Will Donald Trump win the 2024 U.S. presidential election?",
  "probabilities": [
    {
      "outcome": "YES",
      "probability": 0.52,
      "bid": 0.515,
      "ask": 0.525,
      "confidence_interval": {
        "lower": 0.50,
        "upper": 0.54
      }
    },
    {
      "outcome": "NO",
      "probability": 0.48,
      "bid": 0.475,
      "ask": 0.485,
      "confidence_interval": {
        "lower": 0.46,
        "upper": 0.50
      }
    }
  ],
  "last_updated": "2026-03-10T15:20:00Z",
  "data_quality": "high"
}

Error Responses

All tools return structured error responses:

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient USDC balance. Required: 500 USDC, Available: 247 USDC",
    "details": {
      "required": 500,
      "available": 247,
      "platform": "polymarket"
    }
  }
}

Common error codes:

• MARKET_NOT_FOUND - Market ID does not exist

• MARKET_CLOSED - Market has closed to new orders

• INSUFFICIENT_BALANCE - Insufficient funds for trade

• SLIPPAGE_EXCEEDED - Price moved beyond slippage tolerance

• RATE_LIMIT_EXCEEDED - Too many requests

• AUTHENTICATION_FAILED - Invalid API credentials

• POSITION_NOT_FOUND - Position ID does not exist

Rate Limits

Per Platform:

• Polymarket: 100 requests/minute, 5 orders/second

• Kalshi: 200 requests/minute, 10 orders/second

Per Tool:

• market.search: 30/minute

• market.get_data: 60/minute

• position.open: 20/minute

• position.close: 20/minute

• portfolio.get_positions: 60/minute

• market.get_probabilities: 60/minute