futures_search_markets

Resolve a futures-market topic to ranked markets in our curated catalog.

Covers 20 CFTC COT markets across two report families: 13 Traders in Financial Futures (TFF) markets (Treasury, SOFR, E-mini equity index, and major FX futures) and 7 Disaggregated markets across energy (WTI crude oil, Henry Hub natural gas), metals (gold, copper), and grains (corn, soybeans, wheat SRW).

The result is the shared envelope: data.query echoes the search and data.matches is the ranked list (best first); meta holds source ("futures_catalog") and the freshest match as_of; pagination is null — this is a bounded relevance list, not a paged one, so refine the query rather than expecting to page.

Each match carries market (the stable key — pass it to futures_get_positioning), the CFTC cftc_contract_market_code, name, report_name (as CFTC publishes it), exchange, group, report_type (tff or disaggregated), trader_categories (the five categories valid for that family, in canonical order), report_variants (the ingested universes: futures_only and/or futures_and_options), coverage (first/last report week we hold, or null if none ingested yet), a score in [0, 1], and a match_reason (market_key/cftc_code/name/keyword). An empty/whitespace query returns no matches (a normal, empty success — not an error).

Example: futures_search_markets(query="WTI crude oil futures").