market.search

Search for prediction markets matching natural language criteria across Polymarket and Kalshi.

---

Overview

The market.search tool enables agents to discover prediction markets using conversational queries. MoltMarket translates natural language into platform-specific API calls, normalizes responses, and returns unified market data.

Typical use cases:

• Finding markets by topic (e.g., "presidential election")

• Filtering by liquidity thresholds

• Searching by close date

• Category-based discovery

---

Parameters

Parameter	Type	Required	Description
query	string	Yes	Natural language search query
platforms	array	No	Platforms to search: ["polymarket", "kalshi"] or ["all"] (default: all)
min_liquidity	number	No	Minimum market liquidity in USD (default: 0)
max_close_days	number	No	Markets closing within N days (default: unlimited)
categories	array	No	Filter by category: ["politics", "economics", "technology", "sports"]
limit	number	No	Maximum results to return (default: 50, max: 100)

---

Request Examples

Basic Search

from openclaw import Agent
from moltmarket import PredictionMarketProvider

agent = Agent(providers=[PredictionMarketProvider()])

# Simple natural language search
result = agent.run("Find presidential election markets")

Filtered Search

result = agent.run("""
  Find election markets with > $1M liquidity
  closing in the next 30 days
""")

MCP Tool Call (JSON)

{
  "tool": "market.search",
  "parameters": {
    "query": "presidential election",
    "platforms": ["polymarket", "kalshi"],
    "min_liquidity": 1000000,
    "max_close_days": 30,
    "categories": ["politics"],
    "limit": 10
  }
}

---

Response Format

{
  "markets": [
    {
      "id": "0x1a2b3c4d5e6f...",
      "platform": "polymarket",
      "title": "Will Donald Trump win the 2024 presidential election?",
      "description": "This market resolves YES if Donald Trump wins...",
      "category": "politics",
      "probability": 0.47,
      "liquidity": 5200000,
      "volume_24h": 850000,
      "volume_total": 12500000,
      "close_date": "2024-11-05T23:59:59Z",
      "created_at": "2023-06-15T14:30:00Z",
      "outcomes": ["YES", "NO"],
      "url": "https://polymarket.com/market/...",
      "orderbook": {
        "best_bid": 0.46,
        "best_ask": 0.48,
        "spread": 0.02,
        "depth": {
          "bids": 125000,
          "asks": 118000
        }
      }
    },
    {
      "id": "PRES-2024",
      "platform": "kalshi",
      "title": "Presidential Election Winner 2024",
      "description": "This event resolves to YES if...",
      "category": "politics",
      "probability": 0.52,
      "liquidity": 2100000,
      "volume_24h": 320000,
      "volume_total": 4800000,
      "close_date": "2024-11-05T23:59:59Z",
      "created_at": "2023-05-01T10:00:00Z",
      "outcomes": ["YES", "NO"],
      "url": "https://kalshi.com/markets/...",
      "orderbook": {
        "best_bid": 0.51,
        "best_ask": 0.53,
        "spread": 0.02,
        "depth": {
          "bids": 85000,
          "asks": 92000
        }
      }
    }
  ],
  "count": 2,
  "platforms": ["polymarket", "kalshi"],
  "search_time_ms": 342
}

---

Response Fields

Market Object

Field	Type	Description
id	string	Platform-specific market identifier
platform	string	"polymarket" or "kalshi"
title	string	Market question or title
description	string	Full market description and resolution criteria
category	string	Market category (politics, economics, etc.)
probability	number	Implied probability (0-1) based on current prices
liquidity	number	Total market liquidity in USD
volume_24h	number	24-hour trading volume in USD
volume_total	number	All-time trading volume in USD
close_date	string	ISO 8601 datetime when market closes
created_at	string	ISO 8601 datetime when market was created
outcomes	array	Possible outcomes (usually ["YES", "NO"])
url	string	Direct link to market on platform
orderbook	object	Current orderbook snapshot

Orderbook Object

Field	Type	Description
best_bid	number	Highest buy price (0-1)
best_ask	number	Lowest sell price (0-1)
spread	number	Difference between best_ask and best_bid
depth.bids	number	Total USD value of buy orders
depth.asks	number	Total USD value of sell orders

---

Natural Language Patterns

MoltMarket understands various natural language patterns:

By Topic

"Find presidential election markets"
"Search for Fed rate decision markets"
"Show me AI regulation markets"

By Liquidity

"Markets with > $1M liquidity"
"High-volume election markets"
"Find liquid Fed markets"

By Time

"Markets closing this week"
"Find markets closing in 30 days"
"Show me long-term (> 6 months) markets"

By Category

"Find politics markets"
"Search economics category"
"Show technology prediction markets"

Combined Filters

"Find presidential markets with > $1M liquidity closing in 60 days"
"High-volume Fed rate markets on Polymarket"
"Politics markets closing this month on Kalshi"

---

Platform Differences

Polymarket

• Market ID Format: Ethereum address (0x...)

• Liquidity: Typically higher ($1M-$20M for major markets)

• Categories: Politics, Economics, Crypto, Sports, Pop Culture

• Settlement: On-chain via UMA oracle

• API Rate Limit: Public data unlimited

Kalshi

• Market ID Format: Alphanumeric string (e.g., PRES-2024)

• Liquidity: Lower than Polymarket ($100K-$5M)

• Categories: Regulated events only (politics, economics, climate)

• Settlement: CFTC-regulated, centralized

• API Rate Limit: 100 requests/minute

---

Error Handling

Common Errors

No Markets Found

{
  "error": "no_markets_found",
  "message": "No markets matching query 'obscure topic'",
  "suggestions": [
    "Try broader search terms",
    "Remove liquidity filters",
    "Expand close date range"
  ]
}

Platform Unavailable

{
  "error": "platform_unavailable",
  "message": "Polymarket API temporarily unavailable",
  "retry_after": 60,
  "fallback_platforms": ["kalshi"]
}

Rate Limit Exceeded

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests to Kalshi API",
  "retry_after": 30,
  "limit": "100 requests per minute"
}

---

Performance

Metric	Value
Average Response Time	342ms (p50)
95th Percentile	485ms (p95)
Timeout	5 seconds
Cache Duration	30 seconds (market data)
Parallel Search	Yes (queries Polymarket + Kalshi simultaneously)

---

Best Practices

1. Start Broad, Then Filter

   # Good: Start with broad search
   markets = agent.run("Find election markets")
   
   # Then filter programmatically
   high_liquidity = [m for m in markets if m['liquidity'] > 1000000]

2. Use Liquidity Filters for Trading

   # Ensure sufficient liquidity for execution
   agent.run("Find markets with > $500K liquidity")

3. Cache Results When Possible

   # Search once, reuse results
   markets = agent.run("Find Fed rate markets")
   
   # Use market IDs for subsequent operations
   for market in markets['markets']:
       analyze_market(market['id'])

4. Handle Platform Failures Gracefully

   try:
       result = agent.run("Search Polymarket for election markets")
   except PlatformUnavailable:
       # Fallback to Kalshi
       result = agent.run("Search Kalshi for election markets")

---

Related Tools

• market.get_data - Retrieve detailed market data

• market.get_probabilities - Calculate implied probabilities

• position.open - Open positions in discovered markets

---

Examples

See Arbitrage Detection for cross-platform search examples.