# futures_get_positioning Weekly COT positioning for one market, newest first, with derived values. | Field | Value | | --- | --- | | Category | Futures (`futures`) | | Exposure | public | | MCP tool | `futures_get_positioning` | | Documentation | https://www.agentdatasets.com/docs/tools/futures_get_positioning | ## Description Weekly COT positioning for one market, newest first, with derived values. The result is the shared envelope. `data` holds the market identity (`market`, `cftc_contract_market_code`, `name`, `exchange`) plus the echoed `report_variant`/`category` filters and the bounded `weeks` page. Each week has `report_date` (the Tuesday the CFTC observed), market-level `open_interest` and `change_open_interest`, and a `categories` list with per-category `positions_long`, `positions_short`, `positions_spread` (null where CFTC publishes no spreading category, including `nonreportable` and Disaggregated `producer_merchant_processor_user`), week-over-week `change_*` fields (null on the first report week), and two derived values you should read rather than compute: `net_position` (long − short; positive = net long) and `net_position_pctile_52w` (where this week's net position ranks among the trailing 52 weekly reports, 0 = most short, 100 = most long; null until a full 52-week window exists). All position values are contract counts (`meta.units` = "contracts"); values are exact decimals serialized as JSON strings. `meta` holds `source` ("cftc") and `as_of` (freshest ingestion on the page); `pagination` holds the cursor paging state. To page, pass `pagination.next_cursor` back as `cursor`; when `pagination.has_more` is false you have reached the oldest report week we hold. CFTC COT data is US government work in the public domain. Errors carry a machine `code`: `unknown_entity` for a market key we do not hold (with `Did you mean: …?` suggestions — or call futures_search_markets), and `bad_parameter` for a category invalid for the market's report family, a malformed cursor, or an out-of-range limit. Example: `futures_get_positioning(market="wti_crude", category="managed_money", limit=52)`. ## Parameters Input schema advertised to MCP clients and mirrored by the REST query string. | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | market | input | `string` | yes | — | — | The exact market key, e.g. 'ust_10y_note', 'emini_sp500', 'euro_fx', or 'wti_crude'. For a topic rather than an exact key, call futures_search_markets first — this tool does not fuzzy-match. | | category | input | `"dealer_intermediary" \| "asset_manager_institutional" \| "leveraged_funds" \| "other_reportables" \| "nonreportable" \| "producer_merchant_processor_user" \| "swap_dealer" \| "managed_money" \| null` | no | null | — | Optional trader-category filter. TFF categories: `dealer_intermediary`, `asset_manager_institutional`, `leveraged_funds`, `other_reportables`, `nonreportable`. Disaggregated categories: `producer_merchant_processor_user`, `swap_dealer`, `managed_money`, `other_reportables`, `nonreportable`. The category must be valid for the selected market's report family; a family-invalid category returns `bad_parameter` with that family's valid set. Omit for all five per week. | | report_variant | input | `"futures_only" \| "futures_and_options"` | no | "futures_only" | — | Which COT universe: `futures_only` (default) or `futures_and_options` (options positions folded in on a futures-equivalent basis). Keep it constant while paging. | | limit | input | `integer` | no | 100 | min 1, max 500 | Report weeks to return, newest first (1–500); default 100 ≈ two years. | | cursor | input | `string \| null` | no | null | — | Opaque pagination cursor from a previous response's `pagination.next_cursor`; keep `category` and `report_variant` constant while paging. Omit to start from the newest report week. | ## Provenance - `cftc` — U.S. Commodity Futures Trading Commission, Weekly Traders in Financial Futures and Disaggregated COT futures-only and futures-and-options-combined reports for 20 curated financial and commodity futures markets (U.S. Government work, public domain (us-gov-public-domain)). See https://www.agentdatasets.com/docs/attribution.md - `futures_catalog` — Curated internal catalog (CFTC COT markets), Discovery catalog for futures-market search: the curated CFTC contract-market whitelist (Treasury, SOFR, E-mini equity index, FX, energy, metals, and grain futures); each match identifies its TFF or Disaggregated report family and valid trader categories; positioning data carries the `cftc` source tag (Names only CFTC public-domain contract markets (see the `cftc` entry); the catalog identifier itself carries no separate license). See https://www.agentdatasets.com/docs/attribution.md Dataset registry: `futures_cot_positioning`.