CFTC COT SDK

A robust, verified Python SDK for accessing, querying, and analyzing CFTC Commitments of Traders (COT) data.

Overview

The cftc-cot SDK provides a fluent, production-ready interface for the CFTC's SODA2 API. It simplifies the complexity of querying 6 different CFTC datasets, handles API-specific naming quirks, and provides powerful post-fetch analysis tools.

Key Features

• Fluent API: Chainable query building for intuitive data retrieval.
• Market & Exchange Discovery: List markets and exchanges, filter queries by exchange, and scope list_markets(weeks=...) to a recent window so retired contracts drop out.
• Cross-domain analysis: COT Index across multiple windows (cot_index_multi), a masking() metric exposing positioning the coarse report hides, and compare() — a tidy long frame for cross-market and cross-classification comparison.
• Production-Tested: Verified field mappings and API interactions against live CFTC data.
• Advanced Analysis: Net Positions, Z-Scores, the classic 0–100 COT Index, extreme positioning detection, long/short ratios, percentile ranks, and week-over-week change.
• Caching: Optional in-memory or persistent disk caching of API responses (COT data updates weekly, so a 24h TTL eliminates redundant requests).
• Resilient Networking: Automatic retry with exponential backoff on transient API failures (429/5xx).
• Command-Line Interface: A cftc-cot CLI for quick lookups without writing Python.
• Robust Field Handling: Preserves official API quirks (typos, naming inconsistencies) using structured field constants.
• Production Ready: Full type hinting, comprehensive exception hierarchy, and rate-limiting support via app tokens.

Installation

pip install cftc-cot-soda

# With disk caching support:
pip install cftc-cot-soda[cache]

Install from GitHub

# Latest tagged release, straight from the source repo
pip install git+https://github.com/victorKariuki/cftc-cot.git@v0.5.0

# Or the wheel attached to a GitHub Release
pip install https://github.com/victorKariuki/cftc-cot/releases/download/v0.5.0/cftc_cot_soda-0.5.0-py3-none-any.whl

Quick Start

from cftc_cot import COTClient, COTAnalysis

# Initialize client
client = COTClient()

# Query: the 52 most recent weekly reports of Crude Oil positioning.
# last_n_weeks anchors to the data's actual latest report dates (not wall-clock
# now), so it accounts for CFTC's publishing lag and never comes back empty.
df = client.legacy().market("Crude Oil").last_n_weeks(52).execute()

# Analyze: Compute net positions and the COT Index
analysis = COTAnalysis(df, classification="legacy")
df_analyzed = analysis.cot_index(window=52)

print(df_analyzed[['report_date_as_yyyy_mm_dd', 'noncomm_net', 'noncomm_net_cot_index']].tail())

Caching

# In-memory cache (per-process) or persistent disk cache.
client = COTClient(cache="memory")
client = COTClient(cache="disk", cache_dir="./cot_cache", cache_ttl=86400)

Command-Line Interface

cftc-cot latest  --dataset legacy --market "Crude Oil"
cftc-cot history --dataset legacy --market "Crude Oil" --weeks 52
cftc-cot markets --dataset legacy
cftc-cot index   --dataset legacy --market "Crude Oil" --window 156

# Choose output format and enable caching:
cftc-cot --format json --cache memory latest --dataset legacy --market "Gold"

MCP Server

Expose COT data to MCP-compatible LLM clients (Claude Desktop, IDE assistants) over stdio. Install the extra and run the cftc-cot-mcp command:

pip install cftc-cot-soda[mcp]   # requires Python >= 3.10
cftc-cot-mcp

• Tools: list_markets, latest_report, history, net_positions, cot_index, z_scores, long_short_ratios, wow_change, percentile_rank, extremes (all support an exact flag and return clear errors when a market doesn't match).
• Resources: cot://datasets, cot://fields/{classification}.
• Prompts: analyze_market, positioning_summary.

Example Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "cftc-cot": {
      "command": "cftc-cot-mcp"
    }
  }
}

Documentation

For a complete API reference, guides, and dataset specifications, please visit our GitHub Wiki.

License

This project is licensed under the MIT License. See the LICENSE file for details.