---
title: "CFTC Commitments of Traders positioning for a reference"
method: GET
path: "/api/market/references/{ticker}/positioning"
tags: ["public-market-data"]
---

# CFTC Commitments of Traders positioning for a reference

`GET /api/market/references/{ticker}/positioning`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/market/references/{ticker}/positioning`
- Auth: none required

Keyless weekly CFTC Commitments of Traders positioning (legacy
report, futures only) for a catalog ticker with a listed US futures
equivalent: gold, silver, platinum, palladium, WTI and Brent crude,
EUR/USD, GBP/USD, and the S&P 500 and Nasdaq-100 e-mini futures for
`SPY` and `QQQ`. Up to 12 reports, newest first.

Positions are as of each Tuesday (`reportDate`) and published the
following Friday. Values are in contracts; net is long minus short.
Non-commercial traders are mostly speculators, commercial traders
hedge a business exposure. Week-over-week changes are CFTC's own
and null when not published. Other catalog tickers answer 200 with
`coverage: not_applicable`. `status` is `fresh` within 12 hours of
CoinRithm's last read, `stale` up to 8 days, then `unavailable`
with no reports; an upstream failure still answers 200. A ticker
outside the catalog returns 404.

## Path parameters

- `ticker` string, required

## Response `200`

Contract, weekly reports, freshness and attribution

- PublicCftcPositioningResponse
  - `ticker` string, required
  - `coverage` 'available' | 'not_applicable', required
  - `status` 'fresh' | 'stale' | 'unavailable', required: Freshness of an upstream dataset CoinRithm re-reads on a schedule. `stale` data is still served inside its documented maximum age; `unavailable` means no usable copy, never zero or empty truth.
  - `contract` PublicCftcContract, required
    - `code` string, required: CFTC contract market code.
    - `market` string, required: Market and exchange name as CFTC publishes it.
    - `exchange` string, required
    - `units` string, nullable, required: Contract units as CFTC publishes them.
  - `reports` PublicCftcReport[], required: Up to 12 weekly reports, newest first.
    - `reportDate` string, required: Tuesday the positions are as of, `YYYY-MM-DD`.
    - `openInterest` number, required
    - `nonCommercial` PublicCftcNonCommercialSide, required
      - `long` number, required
      - `short` number, required
      - `net` number, required
      - `spreading` number, nullable, required
    - `commercial` PublicCftcSide, required
      - `long` number, required
      - `short` number, required
      - `net` number, required: Long minus short, in contracts.
    - `nonReportable` PublicCftcSide, required
      - `long` number, required
      - `short` number, required
      - `net` number, required: Long minus short, in contracts.
    - `change` PublicCftcChange, required: Week-over-week changes as computed by CFTC; null when not published.
      - `openInterest` number, nullable, required
      - `nonCommercialNet` number, nullable, required
      - `commercialNet` number, nullable, required
  - `asOf` string, date-time, nullable, required: When CoinRithm last read the report from CFTC.
  - `source` PublicCftcSource, required
    - `name` string, required
    - `url` string, uri, required
    - `publisher` string, required
    - `dataset` string, required
    - `datasetUrl` string, uri, required
    - `note` string, required
  - `meta` PublicFreshUntilMeta, required
    - `freshUntil` string, date-time, required: Instant until which shared caches may reuse this response.

## Other responses

- `400`: Invalid ticker or query parameter
- `404`: Reference instrument not found
- `429`: Public request rate limit exceeded; honor `Retry-After`.

---

[API](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api.md) · [All operations](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/revisions/28fb59f285fe?raw)