> ## Documentation Index
> Fetch the complete documentation index at: https://docs.llmquantdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 预测市场事件

> 为 Agent 浏览、语义搜索并读取金融范围内的预测市场事件卡片。

<Note icon="sparkles">
  **可作为 MCP 工具调用**：`polymarket_event_browse` + `polymarket_event_search` + `polymarket_event_read` —— 可在 Claude / Cursor / 任意 MCP 客户端中直接使用。详见 [MCP Server](/zh-CN/integration/mcp-server) 60 秒配置。
</Note>

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="blue" size="sm">1 credit · browse</Badge>
 
<Badge color="blue" size="sm">2 credits · search</Badge>
 
<Badge color="gray" size="sm">免费 · read</Badge>

## 它为 Agent 做什么

预测市场 event 会把相关 market question 归到一张 agent 可读的卡片里。自然语言问题优先用 `polymarket_event_search`，例如“Bitcoin ETF approval”或“Fed rate cut odds”；只有用户要 list 或给了精确过滤条件时才用 `polymarket_event_browse`，例如 `q=ETF`、`tag=policy` 或 `min_volume=10000`。

Event card 是入口，不是终点。Browse 或 search 返回 `event_card_id` 后，继续调用 `polymarket_event_read`，让 agent 先看到事件说明、生命周期状态、标签和子 market 预览，再决定读哪个 market。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  alt 用户给出过滤条件
    Agent->>MCP: polymarket_event_browse(status, q, tag, asset, limit)
    MCP-->>Agent: events[] · eventCardId · title · markets[]
  else 用户用自然语言提问
    Agent->>MCP: polymarket_event_search(query, status, limit)
    MCP-->>Agent: events[] · semanticScore · eventCardId
  end
  Note over Agent: 选择 markets 最贴近任务的 event
  Agent->>MCP: polymarket_event_read(event_card_id)
  MCP-->>Agent: event card · market previews · coverage status
```

## 返回值

### Browse 和 search 返回

<ResponseField name="data.events" type="PolymarketEvent[]" required>
  Browse 按生命周期和流动性排序。Search 按语义相关性排序。

  <Expandable title="PolymarketEvent 字段">
    <ResponseField name="event_card_id" type="string" required>
      稳定的 LLMQuant event id。传给 `polymarket_event_read` 继续读取。
    </ResponseField>

    <ResponseField name="title" type="string" required>
      可读的事件标题。
    </ResponseField>

    <ResponseField name="description" type="string" nullable>
      有数据时返回事件层面的说明。
    </ResponseField>

    <ResponseField name="market_count" type="number" required>
      这张 event card 下的子 markets 数量。
    </ResponseField>

    <ResponseField name="markets" type="PolymarketMarketPreview[]" required>
      Market 预览，包含 `market_card_id`、`market_question`、outcomes、状态、流动性和成交量。
    </ResponseField>

    <ResponseField name="tags" type="string[]" required>
      金融标签，例如 `crypto`、`policy` 或 `macro`。
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Event 状态：`active`、`inactive` 或 `closed`。
    </ResponseField>

    <ResponseField name="coverage_status" type="string" required>
      这张规范化 event card 的覆盖状态。
    </ResponseField>

    <ResponseField name="semantic_score" type="number" nullable>
      语义搜索结果中会返回。分数越高，越贴近 query。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">本次返回的 events 数量。</ResponseField>
<ResponseField name="data.nextCursor" type="string">Browse 有更多结果时返回的分页 cursor。</ResponseField>
<ResponseField name="data.scope" type="string">本产品固定为 `finance`。</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Browse 为 `1`，search 为 `2`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

```json title="200 OK · event search" expandable theme={null}
{
  "data": {
    "events": [
      {
        "event_card_id": "4b8f35c6-4781-4f3c-9237-142fc16467cd",
        "title": "Bitcoin ETF approved by Jan 15?",
        "description": "Markets related to whether a spot Bitcoin ETF is approved.",
        "market_count": 1,
        "markets": [
          {
            "market_card_id": "e370488a-33b5-4abd-8c5c-37c7ad8a60fc",
            "market_question": "Bitcoin ETF approved by Jan 15?",
            "outcomes": [
              { "label": "Yes", "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658", "current_probability": 0.51 }
            ],
            "status": "closed",
            "volume": 1250000,
            "liquidity": 48000
          }
        ],
        "tags": ["crypto", "etf"],
        "status": "closed",
        "coverage_status": "partial",
        "semantic_score": 0.91
      }
    ],
    "count": 1,
    "scope": "finance"
  },
  "meta": { "creditsUsed": 2, "remainingCredits": 98 }
}
```

### Event read 返回

<ResponseField name="data" type="PolymarketEvent" required>
  单张 event card，包含 browse/search 返回的字段，以及更完整的事件信息。
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Event read 固定为 `0`。</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">账户剩余 credit。</ResponseField>

## 说明

<Tip>
  用户自然语言问题优先用 search。只有明确 list 或 exact lexical filters 时才用 browse（`status=active`、`q=ETF`、`min_volume=10000`）。选择 event 后先 read，让 agent 一次看到所有子问题。
</Tip>

<Tip>
  如果需要 market 层面的 outcomes 和概率历史，带着 event card 里的 `market_card_id` 继续看 [`预测市场 Market 详情`](/zh-CN/api/prediction-markets/markets)。
</Tip>

<Warning>
  这个产品面向金融范围。它不覆盖体育、娱乐、钱包状态、订单簿或交易动作。
</Warning>

<Warning>
  `start_time` 和 `end_time` 必须成对使用，并且 `start_time` 不能晚于 `end_time`。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 搜索 event
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_event_search",
        "arguments": { "query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5 }
      }
    }

    // 2) 读取选中的 event
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_event_read",
        "arguments": { "event_card_id": "pme_902959" }
      }
    }
    ```

    ```python Python (HTTP) theme={null}
    import os, requests

    base = "https://api.llmquantdata.com"
    headers = {"Authorization": f"Bearer {os.environ['LLMQUANT_API_KEY']}"}

    events = requests.post(
        f"{base}/api/polymarket/events/search",
        headers=headers,
        json={"query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5},
    ).json()["data"]["events"]

    event = requests.get(
        f"{base}/api/polymarket/events/{events[0]['event_card_id']}",
        headers=headers,
    ).json()["data"]
    print(event["title"], event["market_count"])
    ```

    ```bash cURL theme={null}
    curl -X POST "https://api.llmquantdata.com/api/polymarket/events/search" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query": "Bitcoin ETF approval", "status": "active_or_recently_closed", "limit": 5}'

    curl "https://api.llmquantdata.com/api/polymarket/events/pme_902959" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="polymarket_event_browse — 请求参数" icon="sliders">
    <ParamField query="status" type="string" default="active">
      `active`、`inactive`、`closed` 或 `active_or_recently_closed` 之一。
    </ParamField>

    <ParamField query="q" type="string">可选 exact lexical filter，匹配 event title、slug、tags、child market questions 和 outcome labels。最多 200 字符。</ParamField>
    <ParamField query="tag" type="string">可选金融标签，例如 `crypto` 或 `policy`。</ParamField>
    <ParamField query="asset" type="string">可选资产或实体过滤，例如 `BTC`。</ParamField>
    <ParamField query="start_time" type="string">ISO 8601 UTC 起始时间。必须和 `end_time` 一起使用。</ParamField>
    <ParamField query="end_time" type="string">ISO 8601 UTC 结束时间。必须和 `start_time` 一起使用。</ParamField>
    <ParamField query="min_volume" type="number">可选的 event 级别市场成交量下限。</ParamField>
    <ParamField query="min_liquidity" type="number">可选的 event 级别市场流动性下限。</ParamField>
    <ParamField query="limit" type="number" default={20}>返回 events 上限。范围 `1-100`。</ParamField>
    <ParamField query="cursor" type="string">来自 `data.nextCursor` 的分页 cursor。</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_search — 请求参数" icon="magnifying-glass">
    <ParamField body="query" type="string" required>自然语言 query。最多 2,000 字符。</ParamField>

    <ParamField body="status" type="string" default="active_or_recently_closed">
      `active`、`inactive`、`closed` 或 `active_or_recently_closed` 之一。
    </ParamField>

    <ParamField body="tag" type="string">可选金融标签。</ParamField>
    <ParamField body="start_time" type="string">ISO 8601 UTC 起始时间。必须和 `end_time` 一起使用。</ParamField>
    <ParamField body="end_time" type="string">ISO 8601 UTC 结束时间。必须和 `start_time` 一起使用。</ParamField>
    <ParamField body="limit" type="number" default={5}>返回 events 上限。范围 `1-20`。</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_read — 请求参数" icon="file-lines">
    <ParamField path="event_card_id" type="string" required>
      Browse 或 search 返回的 event id；也接受 alias `pme_902959`。
    </ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns cols={2}>
  <Card title="预测市场 Market 详情" icon="gauge-high" href="/zh-CN/api/prediction-markets/markets">
    读取 market outcomes 和隐含概率历史。
  </Card>

  <Card title="MCP Server 接入" icon="plug" href="/zh-CN/integration/mcp-server">
    60 秒接入 Claude / Cursor / 任意 agent harness。
  </Card>
</Columns>