Early access is open. Free sample datasets are live now. Download a sample

API Reference: Settlements and COT Positioning

Details

Docs navigation

Two kinds of official futures numbers live here. The settlements endpoint returns what the exchange publishes each day per contract: settlement price, open interest, cleared volume and price limits. Our COT API endpoint returns the weekly CFTC Commitments of Traders report, which shows how dealers, asset managers, hedge funds and other groups are positioned in each market.

Early access. Planned v1 endpoints, not live yet. Settlements: Free gets prior-day settlement and open interest for front months; Starter ($29/mo) full history for all contracts; Pro ($79/mo) adds same-day preliminary settlements and price limits. COT: every raw report with full history is free on every plan; Starter adds derived net positions, weekly changes and 3-year percentiles. A real CFTC sample is downloadable today.

Details

Settlements

GET https://api.marketdata.co/v1/futures/settlements

Name Type Required Default Description
symbol string one of symbol or root Contract, e.g. ESZ6
root string All contracts for a root on each date
start, end string no last session Dates
settlement_type string no final final or preliminary (Pro)

Response fields

Field Type Description
symbol string Contract
date string Session the numbers belong to
settlement_price number Official settlement
settlement_type string final or preliminary
previous_settlement_price number Prior session (optional)
open_interest number Open contracts
cleared_volume number Volume cleared for the session (optional)
high_limit_price, low_limit_price number Daily price limits (optional)
exchange_margin number Initial margin per contract, USD (optional)
timestamp string When the exchange published it, UTC (optional)

Example (curl):

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.marketdata.co/v1/futures/settlements?root=ES&start=2026-11-18&end=2026-11-19"

Details

Commitments of Traders

GET https://api.marketdata.co/v1/futures/cot

Parameters

Name Type Required Default Description
symbol string no all Our root (ES) or a CFTC code (13874A)
report_type string no financial legacy, disaggregated, financial (TFF)
scope string no futures_only futures_only or futures_and_options
start, end string no 1 year Filter on position date
derived boolean no false Add net positions and percentiles (Starter)
limit, cursor, format no Paging and output

Response fields (financial report)

Field Type Description
symbol string Our root where one exists, else the CFTC code
cftc_code string CFTC contract market code
market, exchange string Names as CFTC reports them
report_type, scope string As requested
date string Position date (a Tuesday)
release_date string Publication date (usually the Friday after)
open_interest, change_in_open_interest number Total and week-on-week change
dealer_long, dealer_short, dealer_spreading number Dealers and intermediaries
asset_manager_long, asset_manager_short, asset_manager_spreading number Asset managers
leveraged_funds_long, leveraged_funds_short, leveraged_funds_spreading number Hedge funds and CTAs
other_reportable_long, other_reportable_short number Other reportables
nonreportable_long, nonreportable_short number Small traders
leveraged_funds_net number Derived: long minus short
net_position_percentile_3y number Derived: 0 to 100 rank over 156 weeks

Legacy and disaggregated reports return their own groups (noncommercial_*, commercial_*, producer_*, swap_dealer_*, managed_money_*).

Example

Example (Python), leveraged fund net position in E-mini S&P 500:

import os
import requests
import pandas as pd

r = requests.get(
    "https://api.marketdata.co/v1/futures/cot",
    headers={"Authorization": f"Bearer {os.environ['MARKETDATA_API_KEY']}"},
    params={"symbol": "ES", "report_type": "financial", "start": "2023-01-01"},
)
cot = pd.DataFrame(r.json()["results"]).set_index("date")
cot["lev_net"] = cot["leveraged_funds_long"] - cot["leveraged_funds_short"]
print(cot["lev_net"].tail())

Rows from our free CFTC sample (a subset of columns from the same report):

symbol,date,market,exchange,cftc_code,open_interest,dealer_long,dealer_short,asset_manager_long,asset_manager_short,leveraged_funds_long,leveraged_funds_short,change_in_open_interest
ES,2026-10-27,E-MINI S&P 500,CHICAGO MERCANTILE EXCHANGE,13874A,1955711,193848,833441,1111055,187606,102079,502683,20241
ES,2026-11-03,E-MINI S&P 500,CHICAGO MERCANTILE EXCHANGE,13874A,1986532,182419,870993,1111721,183137,125269,497587,30821
ES,2026-11-10,E-MINI S&P 500,CHICAGO MERCANTILE EXCHANGE,13874A,2017687,175005,910294,1115756,201626,145755,448815,31155

Source: CFTC

In those three weeks, leveraged funds went from 400,604 contracts net short to 303,060 net short.

API

Errors for these endpoints

HTTP error.code When
400 invalid_parameter Unknown report_type or scope
403 plan_required derived=true on Free, preliminary settlements below Pro
404 symbol_not_found No CFTC market for that root

Watch out

Notes and gotchas

  • COT positions are as of Tuesday and released on Friday. For backtests, key on release_date, or you will trade on data three days before it was public.
  • Federal holidays can push a release to the following Monday.
  • Some markets appear in several CFTC rows (for example the E-mini and the Micro E-mini). They are separate contracts; add them yourself if you want the combined picture, scaled by contract size.
  • Spreading positions are counted on both sides in the CFTC totals.
  • Preliminary settlements can be revised the same evening. Use final for anything stored.

Keep reading

Next steps

Details

Was this page useful?

[Yes] [No]

Need a COT derived field we don't compute? Tell us on the custom data form.