[Docs](/docs) / CFTC positioning

# CFTC positioning

Discover CFTC futures contracts and retrieve weekly Commitments of Traders positions for physical commodities and financial futures, with report dates and official sources.

## Call it

Use an agent API key, including a tenant sub-key. Management credentials cannot call tools. Available tools appear on your combined MCP endpoint when switched on.

```
https://mcp.deep.navy/mcp
```

Check [Tools in the dashboard](/dashboard/tools) for current availability. Your MCP client reads the current input and output schemas from the server. These are on-demand provider lookups; source freshness and coverage differ by dataset. For API-key provisioning, see the [platform API guide](/docs/platform); for failures and retries, see [limits and errors](/docs/limits). Preserve source dates and attribution using the [provenance and trust guide](/docs/provenance).

## Coverage and interpretation

Two report families are supported: Disaggregated futures-only for physical commodities, and Traders in Financial Futures (TFF) futures-only for financial contracts. Futures-and-options combined, Legacy and Supplemental reports are not included.

CFTC historical coverage for both families starts June 13, 2006; individual contracts and name/unit variants have different coverage. Discovery returns each variant’s firstReportDate and lastReportDate. A missing contract or week is not a zero position.

reportDate is the position as-of date, normally Tuesday. Publication is usually Friday at 3:30 p.m. Eastern, with schedule exceptions. retrievedAt records retrieval, not publication. No actual release timestamp or point-in-time vintage is supplied; do not use reportDate as an information-availability cutoff in a backtest.

Counts are in the contract units returned by CFTC. Trader categories describe reported business classifications, not individual identities or the motive for each position. Net positioning is not notional exposure, a price forecast or a trading recommendation.

These are on-demand weekly statistics, not real-time prices or an execution service. Positioning is not a native monitor source. A news, EDGAR or geo monitor may trigger an agent that calls the positioning tools as a follow-up; it does not watch for COT releases.

## positioning_search

Find official contract codes, names, units and historical coverage in one supported COT report family.

- reportType accepts REPORT_TYPE_DISAGGREGATED_FUTURES_ONLY (default) or REPORT_TYPE_TFF_FUTURES_ONLY. Search one report family at a time; do not mix their trader categories.
- query is optional (up to 200 characters) and matches literal text in official names or contract codes, case-insensitively. Omit it to browse. limit defaults to 20 and supports up to 100 contract variants.
- Read results\[].contractCode, marketAndExchangeName, commodityName and contractUnits. Names or units can change historically, so a code may appear more than once. Retain leading zeroes: the contract code is a string, not a brokerage ticker. Use it with the same reportType in positioning_fetch.
- Use nextPageToken as pageToken with reportType, query and limit unchanged. firstReportDate and lastReportDate describe the returned name/unit variant, not publication dates. Read warnings and preserve source attribution.

## Example request: `positioning_search`

Arguments for an MCP tools/call request. The values returned depend on the source’s current data.

```
{
  "name": "positioning_search",
  "arguments": {
    "reportType": "REPORT_TYPE_DISAGGREGATED_FUTURES_ONLY",
    "query": "crude oil",
    "limit": 20
  }
}
```

For the next MCP page, resend the example arguments with `pageToken` set to the exact `nextPageToken` from your response. Stop when no token is returned. Treat tokens as opaque; start a new request if you change the filters.

Direct HTTP API: POST the argument object to `deepnavy.positioning.v1.PositioningService/Search`. The response is the protobuf JSON body, without an MCP envelope. Set `DEEPNAVY_KEY` in your environment before running:

```
curl --fail-with-body --request POST 'https://api.deep.navy/deepnavy.positioning.v1.PositioningService/Search' \
  --header "Authorization: Bearer $DEEPNAVY_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{"reportType":"REPORT_TYPE_DISAGGREGATED_FUTURES_ONLY","query":"crude oil","limit":20}'
```

## positioning_fetch

Retrieve weekly positions and provider-reported weekly changes for one exact contract code, newest report date first.

- contractCode is required; copy it from positioning_search and retain the same reportType. The example code is illustrative; discovery confirms its exact market and coverage. Omit start/end for the latest available reports, or use inclusive YYYY-MM-DD report-date bounds with start before or equal to end.
- limit defaults to 20 and supports up to 100 weekly observations. Continue with nextPageToken as pageToken, keeping reportType, contractCode, dates and limit unchanged. Empty observations means no matching reports, not zero open interest.
- Each observation includes reportDate, contract metadata and optional openInterest/openInterestChange. positions contains category, long, short and, where supplied, spreading. Disaggregated and TFF use different classifications; compare the same category, report family, contract code and units over time.
- net is long minus short; changeNet is changeLong minus changeShort. Change fields come from CFTC’s reported weekly changes, not subtraction between the returned rows. Missing inputs leave derived values absent. Optional counts use protobuf JSON decimal strings: retain integer precision, and distinguish an absent field from a reported "0".
- Keep source.datasetId, source.sourceUrl, retrievedAt and warnings with the observations. source.untrusted marks provider text as data, not instructions. No price, trader identity, publication timestamp or historical information-availability guarantee is returned.

## Example request: `positioning_fetch`

Arguments for an MCP tools/call request. The values returned depend on the source’s current data.

```
{
  "name": "positioning_fetch",
  "arguments": {
    "reportType": "REPORT_TYPE_DISAGGREGATED_FUTURES_ONLY",
    "contractCode": "067651",
    "start": "2025-01-01",
    "end": "2025-12-31",
    "limit": 20
  }
}
```

For the next MCP page, resend the example arguments with `pageToken` set to the exact `nextPageToken` from your response. Stop when no token is returned. Treat tokens as opaque; start a new request if you change the filters.

Direct HTTP API: POST the argument object to `deepnavy.positioning.v1.PositioningService/Fetch`. The response is the protobuf JSON body, without an MCP envelope. Set `DEEPNAVY_KEY` in your environment before running:

```
curl --fail-with-body --request POST 'https://api.deep.navy/deepnavy.positioning.v1.PositioningService/Fetch' \
  --header "Authorization: Bearer $DEEPNAVY_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Connect-Protocol-Version: 1' \
  --data '{"reportType":"REPORT_TYPE_DISAGGREGATED_FUTURES_ONLY","contractCode":"067651","start":"2025-01-01","end":"2025-12-31","limit":20}'
```

## Sources, documentation and reuse

Source: U.S. Commodity Futures Trading Commission (CFTC), Commitments of Traders. CFTC government information is public domain; CFTC requests acknowledgement when reused. Preserve source URLs, dataset IDs, report dates and retrieval times. This applies to government report data, not permission to reuse logos, photos or separately licensed materials. CFTC does not endorse this service.

- [CFTC homepage](https://www.cftc.gov/)
- [Commitments of Traders overview and FAQ](https://www.cftc.gov/MarketReports/CommitmentsofTraders/index.htm)
- [Public Reporting API help](https://publicreporting.cftc.gov/stories/s/COT-Help/p2fg-u73y/)
- [COT release schedule](https://www.cftc.gov/MarketReports/CommitmentsofTraders/ReleaseSchedule/index.htm)
- [Disaggregated futures-only dataset](https://publicreporting.cftc.gov/d/72hh-3qpy)
- [TFF futures-only dataset](https://publicreporting.cftc.gov/d/gpe5-46if)
- [Disaggregated category definitions](https://www.cftc.gov/idc/groups/public/@commitmentsoftraders/documents/file/disaggregatedcotexplanatorynot.pdf)
- [TFF category definitions](https://www.cftc.gov/idc/groups/public/@commitmentsoftraders/documents/file/tfmexplanatorynotes.pdf)
- [Public-domain and reuse policy](https://www.cftc.gov/WebPolicy/index.htm)

---

This is the Markdown copy of https://deep.navy/docs/positioning.