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

# Prediction Markets Market Details

> Read Prediction Markets market cards and outcome ids before loading probability history.

<Note icon="sparkles">
  **Available as MCP tools**: `polymarket_market_read` + `polymarket_price_history` - call directly from Claude / Cursor / any MCP client. See [MCP Server](/en/integration/mcp-server) for the 60-second setup.
</Note>

<Badge color="green" icon="circle-check">Live</Badge>
 
<Badge color="gray" size="sm">free · market read</Badge>
 
<Badge color="gray" size="sm">free · price history</Badge>

## What it does for your agent

`polymarket_market_read` loads one market selected from a Prediction Markets event card. It returns the market question, status, outcomes, outcome token ids, tags, liquidity, volume, and event context so an agent can decide which side of the market to inspect.

`polymarket_price_history` takes one `outcome_token_id` from that market and returns implied-probability points at `1h` or `1d` resolution. Use it to show how market-implied odds moved over time; do not treat it as OHLCV candles, order book depth, or executable quotes.

## 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 is present
    Agent->>MCP: polymarket_price_history(outcome_token_id, interval, range)
    MCP-->>Agent: points[] · probability · coverage status
  else outcome token is missing
    Agent->>Agent: answer from market card only
  end
```

## Response

### Market read response

<ResponseField name="data" type="PolymarketMarket" required>
  One market card.

  <Expandable title="PolymarketMarket fields">
    <ResponseField name="market_card_id" type="string" required>
      Stable LLMQuant market id. Use this after reading an event card.
    </ResponseField>

    <ResponseField name="event_card_id" type="string" required>
      Parent event id.
    </ResponseField>

    <ResponseField name="market_question" type="string" required>
      The market question agents should quote or summarize.
    </ResponseField>

    <ResponseField name="outcomes" type="PolymarketOutcome[]" required>
      Outcome sides. Each outcome can include `label`, `outcome_token_id`, `current_probability`, and latest price metadata.
    </ResponseField>

    <ResponseField name="status" type="string" required>
      Market status: `active`, `inactive`, or `closed`.
    </ResponseField>

    <ResponseField name="volume" type="number" nullable>Reported market volume when available.</ResponseField>
    <ResponseField name="liquidity" type="number" nullable>Reported market liquidity when available.</ResponseField>
    <ResponseField name="coverage_status" type="string" required>Coverage state for this market card.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for market read.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</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 response

<ResponseField name="data" type="PolymarketPriceHistory" required>
  Probability history for one outcome token.

  <Expandable title="PolymarketPriceHistory fields">
    <ResponseField name="outcome_token_id" type="string" required>Outcome token requested.</ResponseField>
    <ResponseField name="interval" type="string" required>`1h` or `1d`.</ResponseField>

    <ResponseField name="points" type="PolymarketPricePoint[]" required>
      Ordered probability points.
    </ResponseField>

    <ResponseField name="coverage_status" type="string" required>
      Data availability state for the requested token and range.
    </ResponseField>

    <ResponseField name="coverage_notice" type="string" required>
      Plain-English explanation of availability.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">Number of returned points.</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for price history.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</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 }
}
```

## Notes

<Tip>
  Start from [`Prediction Markets Events`](/en/api/prediction-markets/events). Market ids and outcome token ids are selected from event cards, not guessed.
</Tip>

<Tip>
  Use `1d` for narrative timelines and `1h` when the agent needs intraday movement around a dated event.
</Tip>

<Warning>
  `interval` only accepts `1h` and `1d`. Requests such as `interval=15m` return `400` before any credit is charged.
</Warning>

<Warning>
  Price history returns implied-probability points for one outcome token. It is not OHLCV, order book data, trade history, or investment advice.
</Warning>

## Direct invocation

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

    // 2) Load daily probability history for the 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>

## Full parameter reference

<AccordionGroup>
  <Accordion title="polymarket_market_read — request parameters" icon="file-lines">
    <ParamField path="market_card_id" type="string" required>
      Market id returned by an event card; the alias `pmm_253254` is also accepted.
    </ParamField>
  </Accordion>

  <Accordion title="polymarket_price_history — request parameters" icon="chart-line">
    <ParamField query="outcome_token_id" type="string" required>
      Outcome token id returned by `polymarket_market_read`.
    </ParamField>

    <ParamField query="interval" type="string" required>
      `1h` or `1d`.
    </ParamField>

    <ParamField query="start_time" type="string">ISO 8601 UTC start. Must be used with `end_time`.</ParamField>
    <ParamField query="end_time" type="string">ISO 8601 UTC end. Must be used with `start_time`.</ParamField>
    <ParamField query="limit" type="number">Optional maximum points returned. Range `1-20000`.</ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Prediction Markets Events" icon="gauge-high" href="/en/api/prediction-markets/events">
    Browse, search, and read event cards before selecting a market.
  </Card>

  <Card title="Prediction Markets Price History" icon="chart-line" href="/en/api/prediction-markets/price-history">
    Query probability history after selecting an outcome token.
  </Card>
</Columns>