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

> Browse, search, and read finance-scoped Prediction Markets event cards for agent workflows.

<Note icon="sparkles">
  **Available as MCP tools**: `polymarket_event_browse` + `polymarket_event_search` + `polymarket_event_read` - 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="blue" size="sm">1 credit · browse</Badge>
 
<Badge color="blue" size="sm">2 credits · search</Badge>
 
<Badge color="gray" size="sm">free · read</Badge>

## What it does for your agent

Prediction Markets events group related market questions into one agent-readable card. Use `polymarket_event_search` for natural-language questions such as "Bitcoin ETF approval" or "Fed rate cut odds"; use `polymarket_event_browse` only for list requests or exact filters such as `q=ETF`, `tag=policy`, or `min_volume=10000`.

The event card is the entry point, not the final stop. After browse or search returns an `event_card_id`, call `polymarket_event_read` to load the event description, lifecycle state, tags, and child market previews before choosing a market.

## Agent flow

```mermaid theme={null}
sequenceDiagram
  participant Agent
  participant MCP as data-mcp
  alt User gives filters
    Agent->>MCP: polymarket_event_browse(status, q, tag, asset, limit)
    MCP-->>Agent: events[] · eventCardId · title · markets[]
  else User asks in natural language
    Agent->>MCP: polymarket_event_search(query, status, limit)
    MCP-->>Agent: events[] · semanticScore · eventCardId
  end
  Note over Agent: choose the event whose markets match the task
  Agent->>MCP: polymarket_event_read(event_card_id)
  MCP-->>Agent: event card · market previews · coverage status
```

## Response

### Browse and search response

<ResponseField name="data.events" type="PolymarketEvent[]" required>
  Browse results use lifecycle and liquidity ordering. Search results use semantic relevance.

  <Expandable title="PolymarketEvent fields">
    <ResponseField name="event_card_id" type="string" required>
      Stable LLMQuant event id. Pass this to `polymarket_event_read`.
    </ResponseField>

    <ResponseField name="title" type="string" required>
      Human-readable event title.
    </ResponseField>

    <ResponseField name="description" type="string" nullable>
      Event-level description when available.
    </ResponseField>

    <ResponseField name="market_count" type="number" required>
      Number of child markets in the event card.
    </ResponseField>

    <ResponseField name="markets" type="PolymarketMarketPreview[]" required>
      Market previews with `market_card_id`, `market_question`, outcomes, status, liquidity, and volume.
    </ResponseField>

    <ResponseField name="tags" type="string[]" required>
      Finance tags such as `crypto`, `policy`, or `macro`.
    </ResponseField>

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

    <ResponseField name="coverage_status" type="string" required>
      Coverage state for this normalized event card.
    </ResponseField>

    <ResponseField name="semantic_score" type="number" nullable>
      Present on semantic search results. Higher means closer to the query.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.count" type="number">Number of returned events.</ResponseField>
<ResponseField name="data.nextCursor" type="string">Pagination cursor for browse, when more events are available.</ResponseField>
<ResponseField name="data.scope" type="string">Always `finance` for this product surface.</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">`1` for browse and `2` for search.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</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 response

<ResponseField name="data" type="PolymarketEvent" required>
  One event card with the same fields returned by browse/search, plus full event metadata.
</ResponseField>

<ResponseField name="meta.creditsUsed" type="number">Always `0` for event read.</ResponseField>
<ResponseField name="meta.remainingCredits" type="number">Account credits remaining.</ResponseField>

## Notes

<Tip>
  Use search for user language. Use browse only for explicit list or exact lexical filters (`status=active`, `q=ETF`, `min_volume=10000`). Read the selected event before choosing a market so the agent sees all child questions together.
</Tip>

<Tip>
  For market-level outcomes and probability history, continue to [`Prediction Markets Market Details`](/en/api/prediction-markets/markets) with the `market_card_id` returned in the event card.
</Tip>

<Warning>
  This surface is finance-scoped. It does not cover sports, entertainment, wallet state, order books, or trading actions.
</Warning>

<Warning>
  `start_time` and `end_time` must be used together, and `start_time` cannot be after `end_time`.
</Warning>

## Direct invocation

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

    // 2) Read the selected 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>

## Full parameter reference

<AccordionGroup>
  <Accordion title="polymarket_event_browse — request parameters" icon="sliders">
    <ParamField query="status" type="string" default="active">
      One of `active`, `inactive`, `closed`, or `active_or_recently_closed`.
    </ParamField>

    <ParamField query="q" type="string">Optional exact lexical filter across event title, slug, tags, child market questions, and outcome labels. Max 200 characters.</ParamField>
    <ParamField query="tag" type="string">Optional finance tag, such as `crypto` or `policy`.</ParamField>
    <ParamField query="asset" type="string">Optional asset or entity filter, such as `BTC`.</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="min_volume" type="number">Optional minimum event-level market volume.</ParamField>
    <ParamField query="min_liquidity" type="number">Optional minimum event-level market liquidity.</ParamField>
    <ParamField query="limit" type="number" default={20}>Maximum events returned. Range `1-100`.</ParamField>
    <ParamField query="cursor" type="string">Pagination cursor from `data.nextCursor`.</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_search — request parameters" icon="magnifying-glass">
    <ParamField body="query" type="string" required>Natural-language query. Max 2,000 characters.</ParamField>

    <ParamField body="status" type="string" default="active_or_recently_closed">
      One of `active`, `inactive`, `closed`, or `active_or_recently_closed`.
    </ParamField>

    <ParamField body="tag" type="string">Optional finance tag.</ParamField>
    <ParamField body="start_time" type="string">ISO 8601 UTC start. Must be used with `end_time`.</ParamField>
    <ParamField body="end_time" type="string">ISO 8601 UTC end. Must be used with `start_time`.</ParamField>
    <ParamField body="limit" type="number" default={5}>Maximum events returned. Range `1-20`.</ParamField>
  </Accordion>

  <Accordion title="polymarket_event_read — request parameters" icon="file-lines">
    <ParamField path="event_card_id" type="string" required>
      Event id returned by browse or search; the alias `pme_902959` is also accepted.
    </ParamField>
  </Accordion>
</AccordionGroup>

## Related

<Columns cols={2}>
  <Card title="Prediction Markets Market Details" icon="gauge-high" href="/en/api/prediction-markets/markets">
    Read market outcomes and implied-probability history.
  </Card>

  <Card title="MCP Server setup" icon="plug" href="/en/integration/mcp-server">
    Connect Claude / Cursor / any harness in 60 seconds.
  </Card>
</Columns>