Futures
Weekly CFTC Commitments of Traders positioning for curated financial-futures markets — Treasuries, SOFR, E-mini equity indices, and major FX — by trader category.
Paths are relative to https://api.agentdatasets.com. Every endpoint mirrors an MCP tool over the same service layer — the tool catalog 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
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| 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 | integer | No | 10 | min 1, max 50 | Max ranked matches to return |
Example request
Required parameters only, with values taken from the schema. Optional parameters are in the table above.
[ BASH ]
curl --fail --silent --show-error \
--header "X-API-KEY: adk_..." \
"https://api.agentdatasets.com/v1/futures/markets?query=QUERY"Response
200 Successful Response · expand a branch to see its fields.
dataFuturesSearchDatarequiredThe envelope ``data`` for discovery: the echoed ``query`` plus the ranked ``matches`` (best first).
- querystringrequired
matchesarray<FuturesMarketMatch>required
- marketstringrequired
- cftc_contract_market_codestringrequired
- namestringrequired
- report_namestringrequired
- exchangestringrequired
- groupstringrequired
- report_type"tff" | "disaggregated"requiredCFTC Commitments of Traders report family.
- trader_categoriesarray<"dealer_intermediary" | "asset_manager_institutional" | "leveraged_funds" | "other_reportables" | "nonreportable" | "producer_merchant_processor_user" | "swap_dealer" | "managed_money">required
- report_variantsarray<"futures_only" | "futures_and_options">required
coverageMarketCoveragerequirednullable
- first_report_datestring (date)required
- last_report_datestring (date)required
- scorenumberrequired
- match_reason"market_key" | "cftc_code" | "name" | "keyword"requiredWhere 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_ofstring (date-time)required
metaMetarequiredResult-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.
- sourcestringrequired
- as_ofstring (date-time) | string (date)nullable
paginationPaginationnullable
- limitintegerrequired
- has_morebooleanrequired
- next_cursorstringnullable
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
| Name | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| market | string | Yes | — | — | Exact market key, e.g. ust_10y_note, emini_sp500, or wti_crude |
| category | "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 | "futures_only" | "futures_and_options" | No | "futures_only" | — | COT universe: futures_only (default) or futures_and_options; keep constant while paging |
| limit | integer | No | 100 | min 1, max 500 | Report weeks to return, newest first |
| cursor | 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. Optional parameters are in the table above.
[ BASH ]
curl --fail --silent --show-error \
--header "X-API-KEY: adk_..." \
"https://api.agentdatasets.com/v1/futures/positioning?market=MARKET"Response
200 Successful Response · expand a branch to see its fields.
dataFuturesPositioningDatarequiredThe 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.
- marketstringrequired
- cftc_contract_market_codestringrequired
- namestringrequired
- exchangestringrequired
- report_variant"futures_only" | "futures_and_options"requiredThe 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"requirednullable
weeksarray<WeeklyPositioning>required
- report_datestring (date)required
- open_intereststringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- change_open_intereststringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
categoriesarray<CategoryPositioning>required
- category"dealer_intermediary" | "asset_manager_institutional" | "leveraged_funds" | "other_reportables" | "nonreportable" | "producer_merchant_processor_user" | "swap_dealer" | "managed_money"requiredTrader categories across supported COT report families.
- positions_longstringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- positions_shortstringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- positions_spreadstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- change_longstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- change_shortstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- change_spreadstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- net_positionstringrequiredpattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
- net_position_pctile_52wnumberrequirednullable
metaFuturesPositioningMetarequiredPositioning provenance: everything is contract counts, so ``units`` is constant for the whole result. ``as_of`` is the freshest ingestion timestamp on the returned page.
- sourcestringrequired
- as_ofstring (date-time) | string (date)nullable
- unitsstringdefault "contracts"
paginationPaginationnullable
- limitintegerrequired
- has_morebooleanrequired
- next_cursorstringnullable