# Futures REST endpoints Weekly CFTC Commitments of Traders positioning for curated financial-futures markets — Treasuries, SOFR, E-mini equity indices, and major FX — by trader category. 2 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md documents the same operations for MCP clients. ## GET /v1/futures/markets Markets Ranked curated-market matches for a topic/key/code query, best first. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | query | query | `string` | yes | — | — | Futures-market topic, market-key fragment, or CFTC contract-market code across 20 curated TFF and Disaggregated COT markets (financial futures plus energy, metals, and grains) | | limit | query | `integer` | no | 10 | min 1, max 50 | Max ranked matches to return | ### Example request Required parameters only, with values taken from the schema. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/futures/markets?query=QUERY" ``` ### Response `200` Successful Response — `FuturesMarketsSearchResult`. - `data` `FuturesSearchData` (required) — The envelope ``data`` for discovery: the echoed ``query`` plus the ranked ``matches`` (best first). - `query` `string` (required) - `matches` `array` (required) - `market` `string` (required) - `cftc_contract_market_code` `string` (required) - `name` `string` (required) - `report_name` `string` (required) - `exchange` `string` (required) - `group` `string` (required) - `report_type` `"tff" | "disaggregated"` (required) — CFTC Commitments of Traders report family. - `trader_categories` `array<"dealer_intermediary" | "asset_manager_institutional" | "leveraged_funds" | "other_reportables" | "nonreportable" | "producer_merchant_processor_user" | "swap_dealer" | "managed_money">` (required) - `report_variants` `array<"futures_only" | "futures_and_options">` (required) - `coverage` `MarketCoverage | null` (required) - `first_report_date` `string (date)` (required) - `last_report_date` `string (date)` (required) - `score` `number` (required) - `match_reason` `"market_key" | "cftc_code" | "name" | "keyword"` (required) — Where a search query matched, so an agent can see why a market ranked. ``market_key`` — the stable id matched (exact/prefix/substring); ``cftc_code`` — the CFTC contract-market code matched exactly; ``name`` — the human name or the report name as published matched; ``keyword`` — every query token appears somewhere in the market's searchable text (name, key, report name, exchange, group, aliases). - `as_of` `string (date-time)` (required) - `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json ## GET /v1/futures/positioning Positioning Weekly COT positioning for one market, newest first, bounded and paged. Carries the derived ``net_position`` and ``net_position_pctile_52w`` per trader category so callers never compute them. ### Parameters | Parameter | In | Type | Required | Default | Constraints | Description | | --- | --- | --- | --- | --- | --- | --- | | market | query | `string` | yes | — | — | Exact market key, e.g. ust_10y_note, emini_sp500, or wti_crude | | category | query | `"dealer_intermediary" \| "asset_manager_institutional" \| "leveraged_funds" \| "other_reportables" \| "nonreportable" \| "producer_merchant_processor_user" \| "swap_dealer" \| "managed_money" \| null` | no | — | — | Optional trader-category filter. TFF: dealer_intermediary, asset_manager_institutional, leveraged_funds, other_reportables, nonreportable. Disaggregated: producer_merchant_processor_user, swap_dealer, managed_money, other_reportables, nonreportable. The category must be valid for the market's report family; omit for all five per week | | report_variant | query | `"futures_only" \| "futures_and_options"` | no | "futures_only" | — | COT universe: futures_only (default) or futures_and_options; keep constant while paging | | limit | query | `integer` | no | 100 | min 1, max 500 | Report weeks to return, newest first | | cursor | query | `string \| null` | no | — | — | Opaque pagination cursor from a previous response's pagination.next_cursor; keep category/report_variant constant while paging; omit to start from the newest report week. | ### Example request Required parameters only, with values taken from the schema. ```bash curl --fail --silent --show-error \ --header "X-API-KEY: adk_..." \ "https://api.agentdatasets.com/v1/futures/positioning?market=MARKET" ``` ### Response `200` Successful Response — `FuturesPositioningResult`. - `data` `FuturesPositioningData` (required) — The envelope ``data`` for one market's positioning history. Carries the market identity inline (key, name, exchange, the echoed ``report_variant`` and optional ``category`` filter) so an agent can read the ``weeks`` without a second lookup; ``weeks`` is the bounded, newest-first page. - `market` `string` (required) - `cftc_contract_market_code` `string` (required) - `name` `string` (required) - `exchange` `string` (required) - `report_variant` `"futures_only" | "futures_and_options"` (required) — The two position-report variants published by CFTC. - `category` `"dealer_intermediary" | "asset_manager_institutional" | "leveraged_funds" | "other_reportables" | "nonreportable" | "producer_merchant_processor_user" | "swap_dealer" | "managed_money" | null` (required) - `weeks` `array` (required) - `report_date` `string (date)` (required) - `open_interest` `string` (required) - `change_open_interest` `string | null` (required) - `categories` `array` (required) - `category` `"dealer_intermediary" | "asset_manager_institutional" | "leveraged_funds" | "other_reportables" | "nonreportable" | "producer_merchant_processor_user" | "swap_dealer" | "managed_money"` (required) — Trader categories across supported COT report families. - `positions_long` `string` (required) - `positions_short` `string` (required) - `positions_spread` `string | null` (required) - `change_long` `string | null` (required) - `change_short` `string | null` (required) - `change_spread` `string | null` (required) - `net_position` `string` (required) - `net_position_pctile_52w` `number | null` (required) - `meta` `FuturesPositioningMeta` (required) — Positioning provenance: everything is contract counts, so ``units`` is constant for the whole result. ``as_of`` is the freshest ingestion timestamp on the returned page. - `source` `string` (required) - `as_of` `string (date-time) | string (date) | null` - `units` `string` - `pagination` `Pagination | null` - `limit` `integer` (required) - `has_more` `boolean` (required) - `next_cursor` `string | null` Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json