cotbias¶

Official Python SDK and Model Context Protocol (MCP) Server for the COT Bias Terminal Quant API.

cotbias provides institutional traders, quantitative researchers, and AI agents with direct access to curated CFTC Commitments of Traders (COT) positioning datasets, 156-week historical metrics across four CFTC report families, multi-asset screeners, and AI-synthesized positioning regimes.

⚡ Quick Start¶

Installation¶

# Standard Python SDK (batteries-included with pandas)
pip install cotbias

# Or with Model Context Protocol (MCP) server support
pip install "cotbias[mcp]"

15-Line SDK Example¶

import os
from cotbias import CotClient

# Authenticate with your Quant Tier API key
client = CotClient(api_key=os.environ["COT_API_KEY"])

# 1. Fetch AI positioning regime & sentiment attribution
inference = client.inference.get("ES")
print(f"ES Bias: {inference.ai_bias_score} | Regime: {inference.cot_positioning_regime}")
print(f"Attribution: {inference.macro_rationale}")

# 2. Fetch 52-week historical COT positioning timeseries
history = client.timeseries.get("ES", lookback_weeks=52, as_dataframe=True)
print(history[["report_date", "non_comm_net", "cot_index_52w"]].tail())

🚀 Key Features¶

🤖 MCP Server for AI Agents📈 Multi-Report Timeseries🔍 Cross-Asset Screener🛡 Enterprise Reliability

Run cotbias-mcp or uvx "cotbias[mcp]" cotbias-mcp to connect institutional COT positioning directly into Claude Desktop, Cursor IDE, or Cline. Tools include automatic 5-minute / 1-hour in-memory response caching to conserve API quota and reduce latency.

Query Legacy, Disaggregated, Financial Traders (TFF), and Commodity Index (CIT) reports up to 156 weeks back. Access normalized positioning indices, 3-year rolling Z-scores, concentration ratios, and hedging pressure.

Screen over 60+ futures contracts across Equities, FX, Commodities, and Rates by AI bias scores, crowdedness risk, dealer flows, and positioning percentiles.

Built-in exponential backoff with jitter on transient 5xx errors and network timeouts, standard HTTP/2 support, full async client parity (AsyncCotClient), and robust Pydantic data models.

🧭 Documentation Map¶

Getting Started: API keys, installation options, and client initialization.
SDK User Guide: Deep dives into Timeseries, Inference, Screeners, and Async usage.
MCP Server Guide: Setting up Claude Desktop, Cursor, and custom agent integrations.
API Reference: Complete autogenerated signatures for classes, methods, models, and exceptions.
Changelog: Release history and migration notes.