Skip to main content

​
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

ToolUse whenDefault?
SEARCH_RELEVANT_MARKETSYou have a plain-language scenarioYes — start here
SEARCH_EVENTSYou want grouped event pages with nested contractsWhen you know the event family
SEARCH_MARKETSYou know a ticker or event familyAfter you’ve narrowed
GET_MARKETYou have a specific tickerFor 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 scenarioDirect contract?Available proxy
”Will China invade Taiwan?”No”Will Taiwan be issued a Level 4 travel warning?"
"Will Iran retaliate against the US?”RareTravel warnings, sanctions designations, military-action contracts
”Will country X default?”Rarely directBond yield contracts, IMF agreement contracts
”Will company X get acquired?”Sometimes directM&A announcement contracts, regulatory approval contracts
”Will Russia and Ukraine reach a ceasefire?”NoUkraine-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

FieldMeaning
probability_yesDecimal probability the contract resolves YES.
volumeCumulative dollar volume traded.
open_interestLive notional held.
volume_24h_fp (in raw)Last-day volume — better activity signal than liquidity.
close_timeResolution deadline.
rules_primaryExact resolution criteria — read this before citing a probability.
settlement_sourcesWho 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.