> ## 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.

# 预测市场 Market 详情

> 读取预测市场 market 卡片，并查询 outcome token 的小时或日度概率历史。

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

<Badge color="green" icon="circle-check">已上线</Badge>
 
<Badge color="gray" size="sm">免费 · market read</Badge>
 
<Badge color="gray" size="sm">免费 · price history</Badge>

## 它为 Agent 做什么

`polymarket_market_read` 用来读取从预测市场 event card 里选中的单个 market。它返回 market 问题、状态、outcomes、outcome token ids、标签、流动性、成交量和所属 event 信息，帮助 agent 判断下一步应该看哪个 outcome。

`polymarket_price_history` 接收这个 market 里的一个 `outcome_token_id`，返回 `1h` 或 `1d` 粒度的隐含概率点。用它展示市场概率如何随时间变化；不要把它当成 OHLCV K 线、订单簿深度或可成交报价。

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  Agent->>MCP: polymarket_market_read(market_card_id)
  MCP-->>Agent: market card · outcomes[] · outcomeTokenId
  alt outcome token 存在
    Agent->>MCP: polymarket_price_history(outcome_token_id, interval, range)
    MCP-->>Agent: points[] · probability · coverage status
  else outcome token 缺失
    Agent->>Agent: 只根据 market card 回答
  end
```

## 返回值

### Market read 返回

<ResponseField name="data" type="PolymarketMarket" required>
  单张 market card。

  <Expandable title="PolymarketMarket 字段">
    <ResponseField name="market_card_id" type="string" required>
      稳定的 LLMQuant market id。先读取 event card，再用它选择 market。
    </ResponseField>

    <ResponseField name="event_card_id" type="string" required>
      父级 event id。
    </ResponseField>

    <ResponseField name="market_question" type="string" required>
      Agent 应该引用或总结的 market 问题。
    </ResponseField>

    <ResponseField name="outcomes" type="PolymarketOutcome[]" required>
      Market 的不同结果。每个 outcome 可包含 `label`、`outcome_token_id`、`current_probability` 和最近的概率信息。
    </ResponseField>

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

    <ResponseField name="volume" type="number" nullable>有数据时返回 market 成交量。</ResponseField>
    <ResponseField name="liquidity" type="number" nullable>有数据时返回 market 流动性。</ResponseField>
    <ResponseField name="coverage_status" type="string" required>这张 market card 的数据可用状态。</ResponseField>
  </Expandable>
</ResponseField>

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

```json title="200 OK · market read" expandable theme={null}
{
  "data": {
    "market_card_id": "e370488a-33b5-4abd-8c5c-37c7ad8a60fc",
    "event_card_id": "4b8f35c6-4781-4f3c-9237-142fc16467cd",
    "market_question": "Bitcoin ETF approved by Jan 15?",
    "outcomes": [
      {
        "label": "Yes",
        "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
        "current_probability": 0.51,
        "last_price_time": "2024-01-10T00:00:00Z",
        "coverage_status": "partial"
      },
      { "label": "No", "outcome_token_id": null, "current_probability": 0.49 }
    ],
    "status": "closed",
    "volume": 1250000,
    "liquidity": 48000,
    "coverage_status": "partial"
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

### Price history 返回

<ResponseField name="data" type="PolymarketPriceHistory" required>
  单个 outcome token 的概率历史。

  <Expandable title="PolymarketPriceHistory 字段">
    <ResponseField name="outcome_token_id" type="string" required>请求的 outcome token。</ResponseField>
    <ResponseField name="interval" type="string" required>`1h` 或 `1d`。</ResponseField>

    <ResponseField name="points" type="PolymarketPricePoint[]" required>
      按时间排列的概率点。
    </ResponseField>

    <ResponseField name="coverage_status" type="string" required>
      这个 token 和时间范围的数据可用状态。
    </ResponseField>

    <ResponseField name="coverage_notice" type="string" required>
      面向用户和 agent 的可用性说明。
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">返回的数据点数量。</ResponseField>

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

```json title="200 OK · price history" expandable theme={null}
{
  "data": {
    "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
    "interval": "1d",
    "points": [
      { "time": "2024-01-01T00:00:00Z", "probability": 0.39, "price": 0.39 },
      { "time": "2024-01-02T00:00:00Z", "probability": 0.42, "price": 0.42 }
    ],
    "coverage_status": "partial",
    "coverage_notice": "Partial probability history is available for the requested window.",
    "count": 2
  },
  "meta": { "creditsUsed": 0, "remainingCredits": 99 }
}
```

## 说明

<Tip>
  从 [`预测市场事件`](/zh-CN/api/prediction-markets/events) 开始。Market id 和 outcome token id 都应该从 event card 里选，不要靠猜。
</Tip>

<Tip>
  叙事时间线优先用 `1d`；如果 agent 需要看某个事件日前后的日内变化，再用 `1h`。
</Tip>

<Warning>
  `interval` 只接受 `1h` 和 `1d`。`interval=15m` 这类请求会在扣 credit 前返回 `400`。
</Warning>

<Warning>
  Price history 返回的是单个 outcome token 的隐含概率点。它不是 OHLCV、订单簿数据、成交历史或投资建议。
</Warning>

## 直接调用

<Accordion title="HTTP / SDK 示例" icon="terminal">
  <CodeGroup>
    ```typescript MCP (Claude / Cursor) theme={null}
    // 1) 读取 market
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_market_read",
        "arguments": { "market_card_id": "pmm_253254" }
      }
    }

    // 2) 读取 Yes outcome 的日度概率历史
    {
      "method": "tools/call",
      "params": {
        "name": "polymarket_price_history",
        "arguments": {
          "outcome_token_id": "98787006152320761811798607481686168525551752574583108841982899511109091268658",
          "interval": "1d",
          "start_time": "2024-01-01T00:00:00Z",
          "end_time": "2024-01-15T00:00:00Z"
        }
      }
    }
    ```

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

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

    market = requests.get(
        f"{base}/api/polymarket/markets/pmm_253254",
        headers=headers,
    ).json()["data"]
    token = market["outcomes"][0]["outcome_token_id"]

    history = requests.get(
        f"{base}/api/polymarket/price-history",
        headers=headers,
        params={
            "outcome_token_id": token,
            "interval": "1d",
            "start_time": "2024-01-01T00:00:00Z",
            "end_time": "2024-01-15T00:00:00Z",
        },
    ).json()["data"]
    print(history["points"][:2])
    ```

    ```bash cURL theme={null}
    curl "https://api.llmquantdata.com/api/polymarket/markets/pmm_253254" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"

    curl "https://api.llmquantdata.com/api/polymarket/price-history?outcome_token_id=98787006152320761811798607481686168525551752574583108841982899511109091268658&interval=1d&start_time=2024-01-01T00%3A00%3A00Z&end_time=2024-01-15T00%3A00%3A00Z" \
      -H "Authorization: Bearer $LLMQUANT_API_KEY"
    ```
  </CodeGroup>
</Accordion>

## 完整参数参考

<AccordionGroup>
  <Accordion title="polymarket_market_read — 请求参数" icon="file-lines">
    <ParamField path="market_card_id" type="string" required>
      Event card 返回的 market id；也接受 alias `pmm_253254`。
    </ParamField>
  </Accordion>

  <Accordion title="polymarket_price_history — 请求参数" icon="chart-line">
    <ParamField query="outcome_token_id" type="string" required>
      `polymarket_market_read` 返回的 outcome token id。
    </ParamField>

    <ParamField query="interval" type="string" required>
      `1h` 或 `1d`。
    </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="limit" type="number">可选的返回 points 上限。范围 `1-20000`。</ParamField>
  </Accordion>
</AccordionGroup>

## 相关接口

<Columns cols={2}>
  <Card title="预测市场事件" icon="gauge-high" href="/zh-CN/api/prediction-markets/events">
    先浏览、搜索并读取 event card，再选择 market。
  </Card>

  <Card title="预测市场概率历史" icon="chart-line" href="/zh-CN/api/prediction-markets/price-history">
    选好 outcome token 后，查询它的概率历史。
  </Card>
</Columns>