# 📈 CFTC COT Enhanced — Position Velocity & Percentile Tracker (`nexgendata/cftc-cot-position-velocity-tracker`) Actor Weekly CFTC Commitment of Traders with the percentile + velocity overlay every commodity desk builds in Excel: net position, 3-yr percentile, week-over-week velocity for managed money, swap dealers, commercials, non-reportables. Legacy, disaggregated, TFF families. From publicreporting.cftc.gov. - **URL**: https://apify.com/nexgendata/cftc-cot-position-velocity-tracker.md - **Developed by:** [NexGenData](https://apify.com/nexgendata) (community) - **Categories:** Business - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $150.00 / 1,000 cot records This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 📈 CFTC COT Enhanced — Position Velocity & Percentile Tracker **The percentile-and-velocity overlay every commodity desk builds in Excel — sold as a clean weekly API feed.** Pulls the CFTC Commitment of Traders (COT) report straight from `publicreporting.cftc.gov`, then computes net position, 3-year percentile rank, and week-over-week position velocity for every category your desk cares about: managed money, swap dealers, commercials, and non-reportables. Raw COT JSON is free. The work that turns it into a tradable signal — net-position normalization across long/short/spread fields, 3-year rolling percentile rank vs the trailing 156 weeks, week-over-week velocity calc, and consistent schema across the legacy / disaggregated / financial (TFF) report families — is the value this actor packages. One run, one dataset, one consistent shape. --- ### What you get - **One row per (contract × category × week)** with `commodity_name`, `contract_market_name`, `contract_code`, `report_date`, `category`, `long_positions`, `short_positions`, `spread_positions`, `net_position`, `open_interest_all`, `percentile_3yr`, `velocity_week_over_week_pct`. - **All three CFTC report families.** `legacy` (Commercial / Non-Commercial / Non-Reportable for every futures contract), `disaggregated` (Managed Money / Swap Dealers / Producer-Merchant / Other Reportables for energy, metals, ag), and `financial` / TFF (Asset Manager / Leveraged Funds / Dealer / Other for rates, FX, equity indices). - **3-year percentile rank.** For each emitted week, the actor computes the percentile of the current net position vs the trailing 156 weeks for the same contract + category. `managed_money` long-position percentile of 87 on WTI = positioning is heavier than 87% of the trailing 3-year history. - **Week-over-week velocity.** Signed percentage change in net position vs the prior week, with absolute-value denominator so the metric stays comparable across long-heavy and short-heavy regimes. - **Flexible commodity matching.** Pass an exact `contract_market_name` (e.g. `CRUDE OIL, LIGHT SWEET-WTI`) for a tight single-contract pull, or a fuzzier commodity term like `GOLD`, `NATURAL GAS`, `CORN`, `SOYBEANS` for a multi-contract sweep. - **No anti-bot risk.** The CFTC Socrata API is an explicit public-data endpoint with no auth, no rate-limit auth, and stable JSON. `User-Agent: NexGenData CFTC COT Actor hello@thenextgennexus.com` per the CFTC fair-access convention. --- ### Use cases - **Commodity trader / energy desk.** Daily check for "are managed money WTI longs at a >90th percentile vs trailing 3 years?" — historically the cleanest mean-reversion signal in crude oil. Pair the velocity column with the percentile to catch the moment the smart money starts unwinding extreme positioning. - **Macro hedge fund analyst.** Cross-commodity positioning regime tracker — pull `report_type=financial` for rates and FX TFF, `disaggregated` for energy and ag, and pipe them into your factor model. The percentile + velocity overlay replaces the manual Excel pivot every analyst rebuilds quarterly. - **Ag merchant / corn-soy hedger.** Weekly snapshot of where commercial hedgers and managed money sit on CBOT corn, wheat, soybeans + the basis for futures-vs-cash decisions. The 3-year percentile is the canonical anchor used by every grain elevator risk desk. --- ### Sample input ```json { "commodity": "WTI CRUDE OIL", "report_type": "disaggregated", "weeks_back": 52, "category": "all", "max_records": 100 } ```` Tight single-category single-commodity run: ```json { "commodity": "CRUDE OIL, LIGHT SWEET-WTI", "report_type": "disaggregated", "weeks_back": 4, "category": "managed_money", "max_records": 4 } ``` Financial (TFF) report for the S\&P 500 E-Mini: ```json { "commodity": "E-MINI S&P 500", "report_type": "financial", "weeks_back": 26, "category": "managed_money", "max_records": 50 } ``` *** ### Sample output ```json { "commodity_name": "CRUDE OIL", "contract_market_name": "CRUDE OIL, LIGHT SWEET-WTI", "contract_code": "067411", "market_and_exchange_names": "CRUDE OIL, LIGHT SWEET-WTI - ICE FUTURES EUROPE", "report_date": "2026-05-26", "report_week": "2026 Report Week 22", "report_type": "disaggregated", "category": "managed_money", "long_positions": 158420, "short_positions": 41880, "spread_positions": 52310, "net_position": 116540, "open_interest_all": 1782430, "percentile_3yr": 87.18, "velocity_week_over_week_pct": 4.21, "source_url": "https://publicreporting.cftc.gov/resource/disaggregated", "data_source": "live" } ``` Each emitted record is one dataset row. The percentile is in 0–100 and is `null` when there are fewer than 4 trailing reference weeks for that contract × category (typical only for very recently listed contracts). The velocity is `null` when the prior week's net position is unavailable or zero. *** ### How the data flows | Stage | What happens | |---|---| | **1. Fetch** | One Socrata `GET /resource/{dataset_id}.json?$where=…&$order=report_date DESC&$limit={weeks_back + 156}` against the chosen report family (`6dca-aqww` legacy, `72hh-3qpy` disaggregated, `gpe5-46if` financial / TFF). | | **2. Group** | Rows are bucketed by `contract_market_name` so multi-contract commodity queries (e.g. `CRUDE OIL` matches WTI + Brent + heating-oil cross-spreads) get independent percentile / velocity lineages per contract. | | **3. Normalize** | Per category, long / short / spread fields are pulled from the correct columns for that report family (e.g. `m_money_positions_long_all` for disaggregated managed money, `lev_money_positions_long` for financial TFF leveraged money). | | **4. Compute** | `net_position = long - short`. `percentile_3yr` = classical rank of current net vs the trailing 156 weeks. `velocity_week_over_week_pct` = signed `% change in net` with absolute-value denominator. | | **5. Emit** | Most-recent `weeks_back` rows per (contract × category), capped at `max_records`. Each emitted record is also charged via `cot-record` PPE so cost scales linearly with dataset rows. | *** ### 🔗 Related Actors NexGenData publishes a deep finance + regulatory cluster — pair this COT tracker with any of these for end-to-end positioning + filings + enforcement intelligence: | Actor | What it does | |---|---| | [SEC EDGAR Search](https://apify.com/nexgendata/sec-edgar-search) | Full-text EDGAR filing search across every form type — pair with COT positioning to cross-check insider activity vs futures-desk positioning. | | [SEC Form 4 Insider Trading](https://apify.com/nexgendata/sec-form-4-insider-trading-scraper) | Daily insider buy/sell filings — the equity-market counterpart to COT futures positioning. | | [SEC Form 13F Holdings Tracker](https://apify.com/nexgendata/sec-form-13f-holdings-tracker) | Quarterly institutional 13F holdings — pair with COT financial (TFF) for a complete view of managed-money positioning across equities and rates. | | [SEC Form 8-K Material Events](https://apify.com/nexgendata/sec-form-8k-material-events-scraper) | Material-event filings — overlay on commodity-name-mentioning issuers to catch supply / earnings shocks before they move COT positioning. | | [SEC Form D Scraper](https://apify.com/nexgendata/sec-form-d-scraper) | Reg D private offerings — useful for tracking commodity-fund and CTA capital formation that feeds managed-money positioning. | | [SEC Litigation Releases](https://apify.com/nexgendata/sec-litigation-releases) | Daily SEC enforcement press releases — the regulatory companion to commodity-market positioning intelligence. | | [SEC Schedule 13D/G Activist Tracker](https://apify.com/nexgendata/sec-schedule-13dg-activist-tracker) | Activist-investor 13D/G filings for cross-referencing with COT positioning in commodity-linked equities. | *** ### About NexGenData NexGenData publishes a deep catalogue of Apify actors covering financial regulators, IP offices, government registries, sanctions lists, and corporate filings across the US, EU, UK, APAC, and beyond. Engineered for daily compliance pipelines, M\&A diligence, and quant research. Every actor links back to an authoritative public source. Contact: hello@thenextgennexus.com # Actor input Schema ## `commodity` (type: `string`): Which CFTC futures market to pull positioning history for. Matching is case-insensitive and runs in this order: (1) exact match on `contract_market_name` (e.g. `CRUDE OIL, LIGHT SWEET-WTI`), (2) LIKE %query% on `contract_market_name`, (3) LIKE %query% on `commodity_name` (e.g. `CRUDE OIL`, `GOLD`, `NATURAL GAS`, `SILVER`, `WHEAT`, `CORN`, `SOYBEANS`, `COTTON`, `SUGAR`, `COFFEE`, `LIVE CATTLE`). Default = `WTI CRUDE OIL` (resolves to the NYMEX / ICE Europe WTI futures contract). For a precise single-contract pull, use the exact `contract_market_name` from publicreporting.cftc.gov. ## `report_type` (type: `string`): Which CFTC COT report family to query. `legacy` = the classic Commercial / Non-Commercial / Non-Reportable breakdown (every futures contract, all commodity groups). `disaggregated` = the post-2009 breakdown that splits Non-Commercial into Managed Money + Other Reportables and Commercial into Producer/Merchant + Swap Dealers — the standard view for energy, metals, ag commodities. `financial` = the Traders in Financial Futures (TFF) breakdown for financial contracts (rates, equity indices, FX) splitting Asset Manager / Leveraged Funds / Dealer / Other Reportables. Default = `disaggregated`. ## `weeks_back` (type: `integer`): Number of weekly COT reports (most recent first) to emit per (contract × category). Minimum 1, maximum 260 (= 5 years of weekly history). Default = 52 (one year). The actor ALWAYS pulls at least 156 prior weeks BEFORE the emit window for the 3-year percentile rank calculation, regardless of this setting. ## `category` (type: `string`): Which trader bucket to emit positions for. `all` = emit one row per category that the chosen report\_type exposes (5 categories for disaggregated/financial, 3 for legacy). `managed_money` = the hedge-fund / CTA / commodity-pool bucket (disaggregated + financial only). `swap_dealers` = bank swap-dealer hedge bucket (disaggregated + financial). `commercials` = producer/merchant/processor (disaggregated), commercial hedger (legacy), or asset manager/institutional (financial TFF). `non_reportable` = small speculator residual under the CFTC reporting threshold (all three report families). When the chosen category does not exist for the chosen report\_type, the actor falls back to the first valid category and logs a warning. ## `max_records` (type: `integer`): Hard ceiling on dataset rows emitted across all (contract × category × week) combinations. Default = 100 (good for one commodity × one category × 52 weeks, or one commodity × 5 categories × 20 weeks). Raise this for multi-commodity sweeps or full-history backfills. Maximum 2000. ## Actor input object example ```json { "commodity": "WTI CRUDE OIL", "report_type": "disaggregated", "weeks_back": 52, "category": "all", "max_records": 100 } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "commodity": "WTI CRUDE OIL", "report_type": "disaggregated", "weeks_back": 52, "category": "all", "max_records": 100 }; // Run the Actor and wait for it to finish const run = await client.actor("nexgendata/cftc-cot-position-velocity-tracker").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "commodity": "WTI CRUDE OIL", "report_type": "disaggregated", "weeks_back": 52, "category": "all", "max_records": 100, } # Run the Actor and wait for it to finish run = client.actor("nexgendata/cftc-cot-position-velocity-tracker").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "commodity": "WTI CRUDE OIL", "report_type": "disaggregated", "weeks_back": 52, "category": "all", "max_records": 100 }' | apify call nexgendata/cftc-cot-position-velocity-tracker --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=nexgendata/cftc-cot-position-velocity-tracker", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "📈 CFTC COT Enhanced — Position Velocity & Percentile Tracker", "description": "Weekly CFTC Commitment of Traders with the percentile + velocity overlay every commodity desk builds in Excel: net position, 3-yr percentile, week-over-week velocity for managed money, swap dealers, commercials, non-reportables. Legacy, disaggregated, TFF families. From publicreporting.cftc.gov.", "version": "0.0", "x-build-id": "BzGaGbmafxc6IyJXC" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/nexgendata~cftc-cot-position-velocity-tracker/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-nexgendata-cftc-cot-position-velocity-tracker", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/nexgendata~cftc-cot-position-velocity-tracker/runs": { "post": { "operationId": "runs-sync-nexgendata-cftc-cot-position-velocity-tracker", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/nexgendata~cftc-cot-position-velocity-tracker/run-sync": { "post": { "operationId": "run-sync-nexgendata-cftc-cot-position-velocity-tracker", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "commodity": { "title": "Commodity (contract market name or commodity name)", "type": "string", "description": "Which CFTC futures market to pull positioning history for. Matching is case-insensitive and runs in this order: (1) exact match on `contract_market_name` (e.g. `CRUDE OIL, LIGHT SWEET-WTI`), (2) LIKE %query% on `contract_market_name`, (3) LIKE %query% on `commodity_name` (e.g. `CRUDE OIL`, `GOLD`, `NATURAL GAS`, `SILVER`, `WHEAT`, `CORN`, `SOYBEANS`, `COTTON`, `SUGAR`, `COFFEE`, `LIVE CATTLE`). Default = `WTI CRUDE OIL` (resolves to the NYMEX / ICE Europe WTI futures contract). For a precise single-contract pull, use the exact `contract_market_name` from publicreporting.cftc.gov.", "default": "WTI CRUDE OIL" }, "report_type": { "title": "COT report family", "enum": [ "legacy", "disaggregated", "financial" ], "type": "string", "description": "Which CFTC COT report family to query. `legacy` = the classic Commercial / Non-Commercial / Non-Reportable breakdown (every futures contract, all commodity groups). `disaggregated` = the post-2009 breakdown that splits Non-Commercial into Managed Money + Other Reportables and Commercial into Producer/Merchant + Swap Dealers — the standard view for energy, metals, ag commodities. `financial` = the Traders in Financial Futures (TFF) breakdown for financial contracts (rates, equity indices, FX) splitting Asset Manager / Leveraged Funds / Dealer / Other Reportables. Default = `disaggregated`.", "default": "disaggregated" }, "weeks_back": { "title": "Weeks of history to emit", "minimum": 1, "maximum": 260, "type": "integer", "description": "Number of weekly COT reports (most recent first) to emit per (contract × category). Minimum 1, maximum 260 (= 5 years of weekly history). Default = 52 (one year). The actor ALWAYS pulls at least 156 prior weeks BEFORE the emit window for the 3-year percentile rank calculation, regardless of this setting.", "default": 52 }, "category": { "title": "Trader category to emit", "enum": [ "managed_money", "swap_dealers", "commercials", "non_reportable", "all" ], "type": "string", "description": "Which trader bucket to emit positions for. `all` = emit one row per category that the chosen report_type exposes (5 categories for disaggregated/financial, 3 for legacy). `managed_money` = the hedge-fund / CTA / commodity-pool bucket (disaggregated + financial only). `swap_dealers` = bank swap-dealer hedge bucket (disaggregated + financial). `commercials` = producer/merchant/processor (disaggregated), commercial hedger (legacy), or asset manager/institutional (financial TFF). `non_reportable` = small speculator residual under the CFTC reporting threshold (all three report families). When the chosen category does not exist for the chosen report_type, the actor falls back to the first valid category and logs a warning.", "default": "all" }, "max_records": { "title": "Max records emitted", "minimum": 1, "maximum": 2000, "type": "integer", "description": "Hard ceiling on dataset rows emitted across all (contract × category × week) combinations. Default = 100 (good for one commodity × one category × 52 weeks, or one commodity × 5 categories × 20 weeks). Raise this for multi-commodity sweeps or full-history backfills. Maximum 2000.", "default": 100 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```