API Reference: Settlements and COT Positioning
Details
Docs navigation
- Getting started: Quickstart, Authentication, Rate limits, Errors and retries
- Guides: Symbol formats, Timestamps and time zones, Pagination, Split and dividend adjustments, WebSocket streaming, Dataset downloads, Excel and Google Sheets, Changelog
- API reference: Stock bars, Stock trades and quotes, Snapshots and movers, Tickers, exchanges, calendar, Splits and dividends, Fundamentals and SEC filings, Options chain and Greeks, Options EOD, bars, OI, Forex, Crypto, Crypto derivatives, Futures bars and continuous, Settlements and COT (you are here), Indices, Economic data, Technical indicators
- SDKs: Python, JavaScript
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
finalfor 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.