---
title: "CFTC COT speculative net positioning per market"
method: GET
path: "/api/macro/cot-positioning"
tags: ["Macro"]
---

# CFTC COT speculative net positioning per market

`GET /api/macro/cot-positioning`

## Request

- Base URL: `https://www.oxfordledge.com` (the document declares no server; this is the origin it was published from)
- URL: `https://www.oxfordledge.com/api/macro/cot-positioning`
- Auth: none declared

Weekly CFTC Commitments-of-Traders speculative positioning (K6).

Net positioning by speculative trader category (managed money for
physical commodities, leveraged funds for financial futures) per
curated market, latest `weeks` weekly reports. FREE public-domain
data — deliberately ungated, matching the /api/macro-events sibling
(sf_monetization_v3). Degrades to {markets: [], count: 0} when PG is
unavailable or the cftc_cot table is empty (pre-first-ingest).

## Query parameters

- `weeks` integer

## Response `200`

Successful Response

- CotPositioningResponse: `GET /api/macro/cot-positioning` — CFTC Commitments-of-Traders speculative positioning per market (K6 consumer, 2026-07-09). FREE public-domain data, deliberately NO tier-gate (sf_monetization_v3; matches the ungated /api/macro-events sibling). Both branches return {markets, count}; the error branch adds `error` and keeps markets=[] so the FE card iteration never NPEs.
  - `markets` CotMarketPositioning[], required
    - `market_key` string, required: Stable market id, e.g. "gold" / "crude_oil" / "sp500".
    - `market_label` string, required: Display label, e.g. "Gold (COMEX)".
    - `category` string, required: Speculative trader category the numbers describe: "Managed money" (disaggregated report) or "Leveraged funds" (TFF report).
    - `series` CotSeriesPoint[], required: Weekly net-positioning history, oldest first (sparkline order).
      - `date` string, required: COT report date (ISO YYYY-MM-DD, the Tuesday as-of date).
      - `net` integer, nullable: Speculative net position (long - short) in contracts; null when a leg was unreported.
    - `report_type` string, nullable: "disaggregated" or "tff".
    - `as_of` string, nullable: Latest report date (ISO).
    - `mm_long` integer, nullable: Latest speculative long contracts.
    - `mm_short` integer, nullable: Latest speculative short contracts.
    - `mm_net` integer, nullable: Latest net (long - short) contracts.
    - `net_change` integer, nullable: Week-over-week change in net contracts (latest minus prior report).
    - `open_interest` integer, nullable: Latest total open interest (contracts).
  - `count` integer, required
  - `error` string, nullable

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api.md) · [All operations](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/llms.txt) · [OpenAPI document](https://skmtc.dev/oxfordledge/apis/oxford-ledge-api/revisions/e832a1260f0b?raw)