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

# Prediction Markets Workflow

> Anchoring scenario probability questions on market-implied prices, including the proxy-contract pattern

## When to use

Any question that benefits from a market-implied probability anchor: "what's the chance X happens?", "is the market pricing in Y?", "scenario probability for Z."

## Default pattern: SEARCH\_RELEVANT\_MARKETS first

```python theme={null}
prediction_market_tool_call(
    tool_name="SEARCH_RELEVANT_MARKETS",
    tool_arguments={
        "query": "Will <plain-language scenario>?",
        "limit": 10,
        "status": "open",
        "include_history": True,
        "history_days": 14,
    }
)
```

Returns ranked candidate contracts with `probability_yes`, `volume`, `open_interest`, `close_time`, `public_url` (cite this), and a `raw` payload with `rules_primary`, `yes_bid` / `yes_ask`, and `volume_24h_fp`.

Plus a `series_matches` field — broader contract series that overlap your query.

## The proxy pattern

Direct contracts on legally sensitive scenarios often don't exist. Platforms list **proxies** that resolve on legible, verifiable events:

| User scenario                                | Direct contract? | Available proxy                                                                         |
| -------------------------------------------- | ---------------- | --------------------------------------------------------------------------------------- |
| "Will China invade Taiwan?"                  | No               | Taiwan Level-4 travel warning contracts                                                 |
| "Will Iran retaliate?"                       | Rare             | Travel warnings, sanctions designations                                                 |
| "Will country X default?"                    | Rarely           | Bond yield contracts, IMF agreement contracts                                           |
| "Will company X get acquired?"               | Sometimes        | M\&A announcement, regulatory approval contracts                                        |
| "Will Russia and Ukraine reach a ceasefire?" | No               | Ukraine-agreement, Bank of Russia rate, Russia crude export, sanctions-relief contracts |

When the user's question matches a politically/legally restricted scenario, expect proxy contracts and report them as such. Don't say "no relevant markets" until you've checked `series_matches` and broader search.

## Reading the response

| Field                      | Meaning                                                            |
| -------------------------- | ------------------------------------------------------------------ |
| `probability_yes`          | Decimal probability the contract resolves YES (0.46 = 46%).        |
| `volume`                   | Cumulative dollar volume traded.                                   |
| `open_interest`            | Live notional held.                                                |
| `volume_24h_fp` (in `raw`) | Last-day volume — better activity signal than `liquidity`.         |
| `rules_primary`            | Exact resolution criteria — read this before citing a probability. |

The contract's resolution criteria often differ from the user's literal question. The implied probability is on the *contract's* event, not necessarily the user's framing.

## Known quirks

* `include_history=True` is best-effort; the `history` array often comes back empty even when set.
* `status` defaults to `open`. Use `status='closed'` for resolved markets.
* `liquidity` is often `0.0000`; use `volume_24h_fp` from `raw` instead.

## Other tools

* `SEARCH_EVENTS(search=…, with_nested_markets=True)` — grouped event pages with nested contracts. Use when you know the event family and want term-structure-style comparisons.
* `SEARCH_MARKETS(...)` — when you already have a ticker or series ticker.
* `GET_MARKET(ticker)` — full record for a specific contract.

## Citation

When citing a contract:

* Lead with the resolution question (verbatim from `title`).
* Give probability as a percent and the close date.
* Note dollar volume so the reader can weight liquidity.
* Link the `public_url`.
* If it's a proxy, say so explicitly: "no direct contract exists; closest tradeable proxy is X."