COTClient

COTClient

The COTClient is the main entry point for the SDK.

from cftc_cot import COTClient

# Initialize (unauthenticated, rate-limited)
client = COTClient()

# Initialize with API token (recommended for higher limits)
client = COTClient(app_token="YOUR_TOKEN")

# With caching (see the Caching guide)
client = COTClient(cache="memory")
client = COTClient(cache="disk", cache_dir="./cot_cache", cache_ttl=86400)

Constructor Parameters

Parameter	Default	Description
app_token	None	Socrata API app token for higher rate limits.
cache	None	"memory", "disk", a COTCache instance, or None. See Caching.
cache_dir	"./cot_cache"	Directory for the disk cache backend.
cache_ttl	86400	Cache time-to-live in seconds (24h).

The configured token and cache are automatically applied to every query the client creates.

Factory Methods (returns COTQuery instances)

• client.legacy(): Legacy Combined
• client.legacy_futures(): Legacy Futures Only
• client.disaggregated(): Disaggregated Combined
• client.disaggregated_futures(): Disaggregated Futures Only
• client.tff(): TFF Combined
• client.tff_futures(): TFF Futures Only

Convenience Methods

• client.latest(dataset, market, exact=False): Fetch latest row.
• client.history(dataset, market, weeks=52, exact=False): Fetch historical data.

By default market is matched as a prefix (e.g. "GOLD" matches "GOLD - COMMODITY EXCHANGE INC."). Pass exact=True to require an exact market-name match.

Discovery Methods

• client.list_markets(dataset, weeks=None, exchange=None): Sorted unique market names. Pass weeks to keep only markets that reported in the last N weeks (retired contracts drop out); pass exchange to keep only one exchange.
• client.list_exchanges(dataset, weeks=None): Sorted unique exchange names, optionally scoped to the last N weeks.
• client.split_market_exchange(name): Static helper splitting "GOLD - COMMODITY EXCHANGE INC." into ("GOLD", "COMMODITY EXCHANGE INC.").

# Markets that actually reported in the last 8 weeks, on one exchange
client.list_markets("legacy", weeks=8, exchange="CHICAGO MERCANTILE EXCHANGE")

# Exchanges active in the last 8 weeks
client.list_exchanges("legacy", weeks=8)