LibraryCOT

17 sty 2022

█ OVERVIEW

This library is a Pine programmer's tool that provides functions to access Commitment of Traders (​COT) data for futures. Four of our scripts use it:
 • Commitment of Traders: Legacy Metrics
 • Commitment of Traders: Disaggregated Metrics
 • Commitment of Traders: Financial Metrics
 • Commitment of Traders: Total

If you do not program in Pine and want to use ​COT data, please see the indicators linked above.


█ CONCEPTS

Commitment of Traders ​(​COT) data is tallied by the Commodity ​Futures Trading Commission (CFTC), a US federal agency that oversees the trading of derivative markets such as futures in the US. It is weekly data that provides traders with information about open interest for an asset. The CFTC oversees derivative markets traded on different exchanges, so ​COT data is available for assets that can be traded on CBOT, ​CME, NYMEX, COMEX, and ICEUS.

Accessing ​COT data from a Pine script requires the generation of a ticker ID string for use with request.security(). The ticker string must be encoded in a special format that includes both CFTC and TradingView-specific content. The format of the ticker IDs is somewhat complex; this library's functions make their generation easier. Note that if you know the ​COT ticker ID string for specific data, you can enter it from the chart's "Symbol Search" dialog box.

A ticker for ​COT data in Pine has the following structure:

Pine Script®

where an underscore prefixing a component name inside <> is only included if the component is not a null string, and:
  <COTType>
    Is a digit representing the type of the COT report the data comes from: "" for legacy COT data, "2" for disaggregated data and "3" for financial data.
  <CFTCCode>
    Is a six digit code that represents a commodity. Example: wheat futures (root "ZW") have the code "001602".
  <includeOptions>
    Is either "F" if the report data should exclude Options data, or "FO" if such data is included.
  <metricCode>
    Is the TradingView code of the metric. This library's `metricNameAndDirectionToTicker()` function creates both
    the <metricCode> and <metricDirection> components of a ​COT ticker from the metric names and directions listed in the above chart.
    The different metrics are explained in the CFTC's Explanatory Notes.
  <metricDirection>
    Is the direction of the metric: "Long", "Short", "Spreading" or "No direction".
    Not all directions are applicable to all metrics. The valid ones are listed next to each metric in the above chart.
  <metricType>
    Is the type of the metric, possible values are "All", "Old" and "Other".
    The difference between the types is explained in the "Old and Other Futures" section of the CFTC's Explanatory Notes.

As an example, the Legacy report Open Interest data for ZW futures (options included) in the old standard has the ticker "COT:001602_FO_OI_OLD". The same data using the current standard without futures has the ticker "COT:001602_F_OI".


█ USING THE LIBRARY

The first functions in the library are helper functions that generate components of a ​COT ticker ID. The last function, `COTTickerid()`, is the one that generates the full ticker ID string by calling some of the helper functions. We use it like this in our example:

Pine Script®

This library's chart displays the valid values for the `metricName` and `metricDirection` arguments. They vary for each of the three types of ​COT data (the `COTType` argument). The chart also displays the ​COT ticker ID string in the `exampleTicker` variable.



Look first. Then leap.


The library's functions are:

rootToCFTCCode(root)
  Accepts a futures root and returns the relevant CFTC code.
  Parameters:
    root: Root prefix of the future's symbol, e.g. "ZC" for "ZC1!"" or "ZCU2021".
  Returns: The <CFTCCode> part of a COT ticker corresponding to `root`, or "" if no CFTC code exists for the `root`.

currencyToCFTCCode(curr)
  Converts a currency string to its corresponding CFTC code.
  Parameters:
    curr: Currency code, e.g., "USD" for US Dollar.
  Returns: The <CFTCCode> corresponding to the currency, if one exists.

optionsToTicker(includeOptions)
  Returns the <includeOptions> part of a COT ticker using the `includeOptions` value supplied, which determines whether options data is to be included.
  Parameters:
    includeOptions: A "bool" value: 'true' if the symbol should include options and 'false' otherwise.
  Returns: The <includeOptions> part of a COT ticker: "FO" for data that includes options and "F" for data that doesn't.

metricNameAndDirectionToTicker(metricName, metricDirection)
  Returns a string corresponding to a metric name and direction, which is one component required to build a valid COT ticker ID.
  Parameters:
    metricName: One of the metric names listed in this library's chart. Invalid values will cause a runtime error.
    metricDirection: Metric direction. Possible values are: "Long", "Short", "Spreading", and "No direction".
      Valid values vary with metrics. Invalid values will cause a runtime error.
  Returns: The <metricCode><metricDirection> part of a COT ticker ID string, e.g., "OI_OLD" for "Open Interest" and "No direction",
    or "TC_L" for "Traders Commercial" and "Long".

typeToTicker(metricType)
  Converts a metric type into one component required to build a valid COT ticker ID.
  See the "Old and Other Futures" section of the CFTC's Explanatory Notes for details on types.
  Parameters:
    metricType: Metric type. Accepted values are: "All", "Old", "Other".
  Returns: The <metricType> part of a COT ticker.

convertRootToCOTCode(mode, convertToCOT)
  Depending on the `mode`, returns a CFTC code using the chart's symbol or its currency information when `convertToCOT = true`.
  Otherwise, returns the symbol's root or currency information. If no COT data exists, a runtime error is generated.
  Parameters:
    mode: A string determining how the function will work. Valid values are:
      "Root": the function extracts the futures symbol root (e.g. "ES" in "ESH2020") and looks for its CFTC code.
      "Base currency": the function extracts the first currency in a pair (e.g. "EUR" in "EURUSD") and looks for its CFTC code.
      "Currency": the function extracts the quote currency ("JPY" for "TSE:9984" or "USDJPY") and looks for its CFTC code.
      "Auto": the function tries the first three modes (Root -> Base Currency -> Currency) until a match is found.
    convertToCOT: "bool" value that, when `true`, causes the function to return a CFTC code.
      Otherwise, the root or currency information is returned. Optional. The default is `true`.
  Returns: If `convertToCOT` is `true`, the <CFTCCode> part of a COT ticker ID string.
    If `convertToCOT` is `false`, the root or currency extracted from the current symbol.

COTTickerid(COTType, CTFCCode, includeOptions, metricName, metricDirection, metricType)
  Returns a valid TradingView ticker for the COT symbol with specified parameters.
  Parameters:
    COTType: A string with the type of the report requested with the ticker, one of the following: "Legacy", "Disaggregated", "Financial".
    CTFCCode: The <CFTCCode> for the asset, e.g., wheat futures (root "ZW") have the code "001602".
    includeOptions: A boolean value. 'true' if the symbol should include options and 'false' otherwise.
    metricName: One of the metric names listed in this library's chart.
    metricDirection: Direction of the metric, one of the following: "Long", "Short", "Spreading", "No direction".
    metricType: Type of the metric. Possible values: "All", "Old", and "Other".
  Returns: A ticker ID string usable with `request.security()` to fetch the specified Commitment of Traders data.


█ AVAILABLE METRICS

Different COT types provide different metrics. The table of all metrics available for each of the types can be found below.

Pine Script®

28 mar 2022

Informacje o Wersji

v2
Small update to compatibility with "ES" symbols.

16 wrz

Informacje o Wersji

v3

This version release comes with the following changes:

 • Direct COT requests: Now that Pine scripts can execute dynamic requests, users no longer need to call `COTTickerid()` to construct a valid ticker ID and pass it to request.security() separately to retrieve COT data. This library version exports a `requestCommitmentOfTraders()` function that uses request.security() internally to fetch COT data dynamically based on the specified arguments.

This example shows a valid call to this function that requests Open Interest data from a Legacy report for the chart symbol's root, base currency, or quote currency:

Pine Script®

 • Expanded root mapping: We've replaced the former switch-based logic for mapping and obtaining root codes. This version stores root identifiers and their corresponding CFTC codes within a pre-initialized map, avoiding the scope limitations that previously restricted the library's allowed number of codes. This structure is now possible because scripts with dynamic requests enabled can call `request.*()` functions with "series" arguments.

 • Enhanced errors: We've improved the library's error-handling behaviors and added clearer, more informative runtime error messages.



New functions:


requestCommitmentOfTraders(COTType, CFTCCode, includeOptions, metricName, metricDirection, metricType)
  Requests CFTC Commitment of Traders (COT) data with specified parameters. Calls to this function count toward a script's `request.*()` call limit.
  Parameters:
    COTType (string): The type of report to request. Possible values are: "Legacy", "Disaggregated", "Financial".
    CFTCCode (string): The CFTC code for the asset. For example, wheat futures (root "ZW") have the code "001602". Use the library's `convertRootToCOTCode()` function to get a valid code for the chart symbol's root, base currency, or main currency.
    includeOptions (bool): If `true`, the COT symbol includes options information. Otherwise, it does not.
    metricName (string): One of the valid metric names listed in the library's documentation and source code.
    metricDirection (string): Metric direction. Possible values are: "Long", "Short", "Spreading", and "No direction". Consult the library's documentation or code to see which direction values apply to the specified metric.
    metricType (string): The metric type. Possible values are: "All", "Old", "Other".
  Returns: (float) The specified Commitment of Traders data series. If no data is available, raises a runtime error.



Updated functions:


convertRootToCOTCode(mode, convertToCOT)
  Produces a "string" containing the chart symbol's root prefix or currency information, or the corresponding CFTC Commitment of Traders (COT) report code, depending on the specified `mode` and `convertToCOT` value.

COTTickerid(COTType, CFTCCode, includeOptions, metricName, metricDirection, metricType)
  Creates a valid TradingView ticker ID for a CFTC Commitment of Traders (COT) symbol with specified parameters.



Removed exports:


rootToCFTCCode(root)
  Accepts a futures root and returns the relevant CFTC code.

currencyToCFTCCode(currency)
  Converts a currency string to its corresponding CFTC code.

optionsToTicker(includeOptions)
  Returns the <includeOptions> part of a COT ticker using the `includeOptions` value supplied, which determines whether options data is to be included.

metricNameAndDirectionToTicker(metricName, metricDirection)
  Returns a string corresponding to a metric name and direction, which is one component required to build a valid COT ticker ID.

typeToTicker(metricType)
  Converts a metric type into one component required to build a valid COT ticker ID. See the "Old and Other Futures" section of the CFTC's Explanatory Notes for details on types.