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

> SEARCH_RELEVANT_MARKETS-first prediction-market patterns, the proxy-contract pattern for legally-sensitive scenarios, and contract-quirk caveats

## Overview

The `prediction-markets` skill teaches agents to anchor scenario probability questions on market-implied prices rather than narrative impression. Use it when the question benefits from a probability anchor: "what's the chance X happens?", "is the market pricing in Y?", "scenario probability for Z."

## The four tools, ranked

| Tool                      | Use when                                           | Default?                       |
| ------------------------- | -------------------------------------------------- | ------------------------------ |
| `SEARCH_RELEVANT_MARKETS` | You have a plain-language scenario                 | **Yes — start here**           |
| `SEARCH_EVENTS`           | You want grouped event pages with nested contracts | When you know the event family |
| `SEARCH_MARKETS`          | You know a ticker or event family                  | After you've narrowed          |
| `GET_MARKET`              | You have a specific ticker                         | For deep contract metadata     |

## Default pattern

```
prediction_market.SEARCH_RELEVANT_MARKETS(
    query="<plain-language scenario>",
    limit=10,
    status="open",
    include_history=True,
    history_days=14
)
```

Returns ranked candidate contracts with `title`, `subtitle`, `category`, `status`, `close_time`, `probability_yes`, `volume`, `open_interest`, `liquidity`, `score`, `public_url` (cite this), and a `raw` payload including bid/ask, `rules_primary`, and settlement source.

Plus `series_matches` — broader contract series the query overlaps.

## The proxy pattern (essential)

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               | "Will Taiwan be issued a Level 4 travel warning?"                                                              |
| "Will Iran retaliate against the US?"        | Rare             | Travel warnings, sanctions designations, military-action contracts                                             |
| "Will country X default?"                    | Rarely direct    | Bond yield contracts, IMF agreement contracts                                                                  |
| "Will company X get acquired?"               | Sometimes direct | M\&A announcement contracts, regulatory approval contracts                                                     |
| "Will Russia and Ukraine reach a ceasefire?" | No               | Ukraine-agreement contracts, Bank of Russia rate cuts, Russia crude export volumes, 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 for the proxy via `series_matches` and broader search.

## Reading the response

| Field                      | Meaning                                                            |
| -------------------------- | ------------------------------------------------------------------ |
| `probability_yes`          | Decimal probability the contract resolves YES.                     |
| `volume`                   | Cumulative dollar volume traded.                                   |
| `open_interest`            | Live notional held.                                                |
| `volume_24h_fp` (in `raw`) | Last-day volume — better activity signal than `liquidity`.         |
| `close_time`               | Resolution deadline.                                               |
| `rules_primary`            | Exact resolution criteria — read this before citing a probability. |
| `settlement_sources`       | Who calls the resolution (e.g. State Dept, BLS).                   |

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

## Known quirks

* `include_history=True` with `history_days=N` is best-effort; the `history` array often comes back empty. For history, fall back to `GET_MARKET(ticker)` or web research.
* Status filter defaults to `open`. Set `status='closed'` for resolved markets.
* `liquidity` is often `0.0000`; use `volume_24h_fp` from `raw` instead.

## Cross-skill arrival

* **From `gdelt-discover-and-drill`**: you have a topic and possibly a key date or actor. Phrase the prediction-market query in scenario form ("Will X happen by Y date?") rather than topic form.
* **From `macro-finance`**: you've seen a price move. Look for both the direct contract and any proxy contracts.
* **From `multi-surface-synthesis`**: you contribute the "what's expected" signal; if the contract is a proxy, label it as such.

## 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, and link `public_url`. If it's a proxy, say so explicitly.