CFTC Provider Extension

This package provides full access to the CFTC Commitment of Traders database. Reports are fetched by CFTC Code (e.g. 13874+) and returns the full history of the contract.

It also exposes the swap transaction and pricing data published by DTCC's Public Price Dissemination service — the swap data repository for CFTC-jurisdiction trades — including the CDS index tape, central bank overnight index swap curves, and FX forward points constructed from executed transactions.

Installation

Install into a Python environment (3.10 - 3.14) from PyPI with:

pip install openbb-cftc

Then build the Python static assets:

openbb-build

Credentials

Credentials are not required, but your IP address may be subject to throttling limits on the Commitment of Traders endpoints. The DTCC Public Price Dissemination endpoints are public and require no credentials.

API requests made using an application token are not throttled.

Create a free account here: https://evergreen.data.socrata.com/signup

Then, generate the app_token by signing in with the credentials here: https://publicreporting.cftc.gov/profile/edit/developer_settings.

Credentials Key

If adding a token, use cftc_app_token as the key in the user_settings.json file. The value expected value is the app_token and not the secret or api_key.

The token can be set as an environment variable:

CFTC_APP_TOKEN

Coverage

This extension provides a dedicated router module with eight endpoints, and one OpenBB Workspace application.

The DTCC endpoints draw on two different sources, deliberately:

• The cumulative slice is one zip per calendar day holding every transaction disseminated that day, in a 110-column CSV. It has no record cap.
• The search endpoint queries a date range server-side and returns JSON. It filters by UPI, currency and notional, but truncates at 10,000 records without saying so.

swap_trades stays on the slice. It is a raw feed of the published columns, its model is CSV-shaped, and the search's schema is a different shape (116 camelCase fields that split some of the CSV's merged columns) that would need a mapping layer for no gain — the slice already returns a full day uncapped, which is what a raw feed should do. With no date, it walks back from the newest published file to the most recent one holding transactions that match the query, because a Saturday's file is published but nearly empty.

ois_curve_history also stays on the slice: it is explicitly a per-report-date series, so per-node as-of dating would defeat its purpose.

cds_index_trades stays on the slice for the same reason swap_trades does, plus one of its own: it is a tape, so it must not silently drop prints, and the search's 10,000-record cap would do exactly that on a busy day. The slice returns a full day, uncapped.

Methodology

A compact reference for the formulas and assumptions behind the calculated endpoints. The discount factors DF(t) bootstrapped in the first block feed every block below.

Rate curve bootstrap — ois_curve, ois_curve_history

• Par rate at a tenor: the median of the day's executed fixed rates (aggregation selects median / mean / vwap).
• Discount factors, bootstrapped from par rate c, with annual fixed payments and accrual τ_i = days_i / b on the currency's money-market basis b (360 or 365):
  • tenor ≤ 1Y (one payment): DF = 1 / (1 + c·τ);
  • longer: DF_n = (1 − c·Σ_{i<n} τ_i·DF_i) / (1 + c·τ_n), the DF_i read off the curve built so far.
• Zero rate z, annually compounded ACT/365F over t years: DF = (1 + z)^(−t).
• Intermediate DFs interpolate on log DF (log_linear, or monotone Hermite log_cubic).
• Assumptions: fixed leg pays annually; negative rates admitted, so DF > 1 is allowed and the curve is not required to be monotone; a node is dropped only if its bootstrapped |z| exceeds a sanity bound.

Forward par swap rate — ois_forward_curve

A Nelson-Siegel-Svensson curve is fit to the bootstrapped log DF (trade-count weighted). The rate of a T-year swap starting t0 forward is the par rate of that forward schedule:

f(t0, T) = (DF(t0) − DF(t0 + T)) / Σ_i τ_i·DF(t0 + t_i)

over the swap's annual points t_i. A tail past the last pillar uses the extended fit and is flagged extrapolated.

Policy path — ois_policy_path

The forward par curve implies forwards off the spot curve; this reads them directly from the forward-starting OIS the spot curve excludes. A forward-starting OIS over [E, E+τ] fixes at the expected average compounded overnight rate over that window, so its fixed rate is a market observation of the forward policy rate. Trades are anchored to the curve date (a start that has rolled to spot drops out), bucketed to whole-month (forward start, tenor), medianed on the most recent day each bucket traded in depth, and sorted by start — the priced central-bank path. Its short, meeting-dated tenors are the policy segments; max_tenor bounds how far up the term a forward-starting swap is still treated as a policy point rather than a forward par rate.

FX forward points — fx_forward_points

• Rate of a trade is quote-per-base from the leg-notional ratio (not the reported basis field, which flips orientation).
• Spot S is the median of the shortest-dated trades: deliverable pairs use trades settling ≤ 2 days; a non-deliverable pair has no spot leg, so its two shortest tenor buckets are linearly extrapolated back to T+2.
• Executed points = (F − S)·pip, with F the tenor's median forward rate and pip the quote's smallest increment (10^4, or 10^2 for a JPY / two-decimal EM quote).
• Covered-interest-parity (theoretical) points: F_cip = S·(1 + r_q·T/b_q)/(1 + r_b·T/b_b). Each leg's simple rate is r = (1/DF − 1)·b/days, so (1 + r·T/b) = 1/DF and F_cip collapses to the factor ratio S·DF_base/DF_quote — basis-independent. basis_points = executed − theoretical is the cross-currency / NDF basis to onshore rates.
• An EM leg with no OIS builds DF_quote from its fixed-float IRS, then its non-deliverable cross swap — deepest source first.

FX implied volatility — fx_implied_vol

• Each option is inverted with Garman-Kohlhagen (two-rate Black-Scholes), forward F = S·DF_for/DF_dom, implied vol solved by bisection on the price (out-of-the-money options only, since an ITM one is redundant by put-call parity).
• A non-deliverable pair has no domestic (EM) OIS, so its domestic DF is implied from the observed NDF forward: DF_dom(t) = DF_for(t)·S / F_ndf(t), which makes F equal the traded NDF forward rather than a covered-parity one.
• Empirical surface: median vol per (grid strike, expiry). Theoretical: a lognormal-SABR smile per expiry (β = 1, α pinned to the ATM vol, ρ/ν by grid-and-refine least squares), evaluated on the grid.
• Strike grid: pip offsets from spot for the majors; basis-point moneyness, K = S·(1 + offset/10^4), for the wider-trading NDF pairs.

Swap valuation — swap_valuation

Off the bootstrapped DF and an annual fixed schedule to maturity T with annuity A = Σ_i τ_i·DF(t_i):

• Par rate c* = (1 − DF(T)) / A.
• Fixed leg PV = N·c·A; floating leg PV = N·(1 − DF(T)) — the sum of the period forwards f_i = (DF_{i−1}/DF_i − 1)/τ_i, discounted, telescopes to it.
• NPV (pay-fixed) = PV_float − PV_fixed; receive-fixed is its negative. A contract at c = c* prices to zero.
• DV01 = N·A·10^−4, the present value of one basis point on the fixed leg.

Swap payoff — swap_payoff

The valuation is one point; the payoff is the whole curve. Holding the contract rate c, the discount curve is shifted in parallel by δ (basis points), DF_δ(t) = DF(t)·e^{−δ·t}, and the swap re-valued at each shift. The result is the mark-to-market P&L profile against rates: zero at the entry par rate, rising for the side long rates (pay-fixed gains as rates rise), and concave for pay-fixed — it is short duration, so a symmetric shift loses more than it gains. Re-pricing off the shifted curve, rather than a straight DV01·δ line, is what shows that curvature.

Usage

The package can be used as a Python module, or a REST API.

REST API

Start the server over localhost with:

openbb-api

Python

from openbb import obb

search_results = obb.cftc.cot_search(query="gold")

print(search_results.to_df())

report = obb.cftc.cot(code="CFTC_088695", measure="percent_of_oi", limit=4)
print(report.to_df().T)

Overnight Index Swap Curves

obb.cftc.ois_curve builds a curve from the overnight index swaps reported to the CFTC. Par rates are the median of the executed fixed rates at each tenor; discount factors are bootstrapped from the par rates, and the zero rate is derived from the bootstrapped discount curve. The forward rate curve is a separate endpoint, ois_forward_curve (see below).

Each currency references its own central bank's overnight benchmark. Currencies whose OIS is too thinly reported to bootstrap a curve (AUD, NZD, KRW, PHP, TRY) are not offered — their liquidity sits in fixed-float swaps against a term benchmark instead.

Depth against staleness, and how this endpoint resolves it

Not every tenor trades every day, and a file is published every calendar day including the ones where nothing trades. A curve built from a single day is therefore full of holes: CHF OIS yields three nodes from one day, and a Saturday yields none at all.

Searching a window of dissemination days fixes the holes but introduces a worse problem if it is done naively. A 30-day median is not today's curve — it is a 30-day-average curve, and rates move inside the window. Buying depth with silent staleness is its own kind of lie.

So each tenor is priced from the most recent day it actually traded in depth, and reports that day as as_of_date along with staleness_days. Deep tenors stay fresh; thin ones show their age instead of hiding it in an average.

Because the search filters on the product's FISN (NA/Swap OIS {ccy}), not just its currency, it returns only that currency's OIS — so even a full year of prints stays well under the source's 10,000-record response cap. A thinly traded currency can therefore raise lookback_days to reach the whole one-year search horizon and still price each tenor from its freshest print; the search chains 180-day sub-windows to cover a span longer than one query allows. Widen the window for a currency that never fills its curve from a short one — a THB, ILS or BRL — and leave it short for USD or EUR, whose curve is dense from a week. A wide window resurrects tenors that last traded months ago, so pair it with max_staleness_days to keep the curve current — covered next.

curve = obb.cftc.ois_curve(currency="CHF", lookback_days=30)

The 10Y is today's; the 9M is a fortnight old and says so.

Capping staleness on a wide window

Reaching back a year fills a thin currency's curve, but not for free: a tenor that last traded eight months ago is priced against a market that has since moved, and splicing it beside a fresh node is a curve of two different dates pretending to be one. NZD is the clearest case — a full-year search finds a 1M node 250 days stale sitting under a 3M node priced yesterday, and the short end zig-zags because the two are from different regimes.

max_staleness_days drops any node whose freshest print is older than the cutoff, before the bootstrap, so a stale off-market rate never becomes a pillar the rest of the curve discounts through. It defaults to None — every node is kept and its age reported in staleness_days, the same judge-for-yourself default as min_trades — but on a wide window it is how you keep the result a curve rather than a mosaic:

curve = obb.cftc.ois_curve(currency="NZD", lookback_days=365, max_staleness_days=30)

Widen lookback_days for reach, then tighten max_staleness_days for freshness; the two knobs trade the curve's completeness against its currency, and the balance differs by how often the currency trades.

min_trades counts one day, not the window

This is the subtlety worth understanding before raising it.

min_trades is the number of trades a tenor must have on a single dissemination day to be dated to that day. It is not a count across the window. Widening lookback_days gives a tenor more chances to clear the bar; it does not pool trades to help it clear.

It defaults to 1: one executed trade is still a price, and dropping it would discard real transactional data in favour of no data at all. num_trades, min_rate and max_rate report how thin a node is, so the caller can judge rather than have the choice made for them.

Raising it costs whole tenors on a thin currency, because the bar is per-day:

CHF short-dated OIS trades at most once on any given day. No day will ever carry three 1M prints, so at min_trades=3 the CHF short end does not exist at any lookback_days — the curve simply starts at 1Y. There is no setting that gives you both a dated short end and three prints behind it, because those trades were never reported.

Negative rates

Negative rates are real — SARON, TONA and ESTR have all printed below zero — so the bootstrap admits them. A negative par rate discounts to more than 1.0, because the lender pays; CHF's short end carries discount_factor above 1 and a negative zero_rate.

Discount factors are therefore not guaranteed to decrease across the curve. A monotonically decreasing discount curve is not a no-arbitrage condition: it is equivalent to assuming every forward rate is positive, which is untrue of CHF and JPY. The condition the bootstrap enforces is a positive discount factor, plus a bound on the implied zero rate that rejects a node whose par rate is so far off-market that the bootstrap degenerates.

Sources

source="search" (default) queries a window of dissemination days, as above. source="slice" uses a single day's cumulative file: no per-node dating, sparse tenors missing. A file is published every calendar day, but a weekend or holiday file carries no swaps, so slice walks date back to the most recent day that actually priced the currency rather than returning an empty curve. It is kept as a fallback and for reproducing a specific published file exactly.

AONIA and NZIONA trade only a handful of times a day, so their curves need a long lookback_days and, to stay current, a max_staleness_days cap (see below).

BRL's DI maturities fall on fixed calendar dates rather than rolling tenors, so they do not snap to benchmark nodes; use granularity="observed" for a full BRL curve. CDI accrues on BUS/252, recovered to the same year fraction on calendar days.

from openbb import obb

curve = obb.cftc.ois_curve(currency="USD", date="2026-07-15")
print(curve.to_df())

The rate column carries the selected curve_type (par or zero) in percent — 4.32 is 4.32%, not a decimal — so the chart axis reads as a rate (the grid's percent formatter is not applied to the chart). The par and zero values below are shown together for illustration; the endpoint returns whichever one curve_type selects.

Granularity

granularity="benchmark" (default) snaps trades to standard nodes. granularity="observed" emits a node for every distinct tenor traded, including broken dates — roughly 180 nodes on a typical day, against 24 benchmark nodes.

Interpolation

interpolation sets how discount factors are read between pillars, on the log of the discount factor. It applies to ois_curve, ois_forward_curve and ois_curve_history.

• interpolation governs how the bootstrap interpolates intermediate discount factors, which shapes the par and zero curves (the forward curve is fitted separately, see below). log_linear (default) is piecewise linear on the log discount factors — the standard, most transparent choice, and the one a par-swap bootstrap is self-consistent with. log_cubic fits a monotone Hermite cubic (Fritsch–Butland slopes) to the log discount factors, smoother through the pillars without overshooting into a spurious negative forward.

The par rates are the curve's input and never move with interpolation; only the derived zero rates and discount factors do. Tenors of one year or less are a single payment with no interpolation, so they are identical under both schemes; longer nodes differ marginally.

Conventions and caveats

• Par rates are aggregated with the median by default. Notionals above the reporting cap are disseminated at the cap (and flagged by is_capped), which biases notional-weighted averages.
• The fixed leg accrues on the day count the trades report - ACT/360 for USD/EUR/CHF/MXN/COP/CLP, ACT/365F for GBP/JPY/CAD/SGD/INR/ZAR/THB/ILS, and BRL's BUS/252 recovered to the same year fraction on calendar days - with annual payments and a single payment for tenors of one year or less. Zero rates are annually compounded ACT/365F, so on an upward-sloping curve the zero rate sits above the par rate.
• min_trades (default 1) keeps every node, because one executed trade is still a price. It counts one dissemination day's trades, not the window's — see above before raising it.
• Each node's maturity_date rolls off its own as_of_date, not the curve's date.
• spot_only (default True) restricts the curve to spot-starting trades, judged against the day each trade was disseminated rather than the end of the window.
• Discount factors are positive but not necessarily decreasing: a negative par rate discounts above 1.0. Derived values are withheld only where the bootstrap degenerates; the observed par rate is still reported.
• The search endpoint truncates at 10,000 records without signalling it. A window that comes back at exactly that count is treated as truncated and bisected until every sub-window clears it; a single day that still hits the cap raises rather than building a curve from an arbitrary subset.
• Closed dissemination days are immutable, so each is cached on disk as its own partition and only the current day is re-queried. Daily slice files are revalidated against the source ETag. Slice files are retained for 366 days; the search endpoint serves a rolling one year, which a lookback_days beyond 180 reaches by chaining 180-day sub-windows.

Forward Rate Curve

obb.cftc.ois_forward_curve prices the forward par swap rate curve off the OIS curve - the object Bloomberg's Forward Curve (FWCV) shows. Each point is the rate of a forward_tenor swap starting that far forward, read off a Nelson-Siegel-Svensson (Svensson) fit to the bootstrapped discount factors and weighted by trade count, so a thin long-end node cannot kink it and a specific point like 5Y1Y or 1Y5Y is smooth and stable.

The swap length and the spacing between start dates are independent: forward_tenor is how long each forward swap runs, forward_step is how far apart the start dates sit. So forward_tenor="5Y", forward_step="1Y" plots the 5Y forward at yearly starts, matching how Bluegamma spaces its forward curve at the tenor. forward_count caps how many start dates are drawn (the next N steps); left unset the curve runs out to its last pillar. A swap whose tail runs past the last pillar is priced off the extended fit and flagged extrapolated rather than withheld, so the final start is still a real point.

from openbb import obb

# the 5Y forward at yearly start dates
fwd = obb.cftc.ois_forward_curve(currency="USD", forward_tenor="5Y", forward_step="1Y")
print(fwd.to_df())

The row index is the forward start date, so the chart reads across the dates each forward begins; tenor labels the swap and its start (5Y @ 5.00Y is the 5Y swap five years out).

FX Forward Points

obb.cftc.fx_forward_points builds forward points from the deliverable FX forwards and FX swaps reported to the CFTC. Deliverable FX forwards and swaps are excluded from the swap definition but remain reportable to swap data repositories, so they appear in the same data.

Spot FX is not reportable, so there is no spot fix in the data. Spot is proxied by the median of trades settling within two days — overnight FX swap legs, in practice.

Tenors are dated per-tenor exactly as the OIS curve's nodes are, with one addition: each tenor is priced against the spot of its own as-of day, not the curve's freshest spot. A tenor that last traded six days ago is differenced against that day's spot, so its points stay internally consistent instead of absorbing an unrelated spot move. spot_rate therefore varies row to row whenever staleness_days does.

from openbb import obb

points = obb.cftc.fx_forward_points(pair="USDJPY", date="2026-07-15")
print(points.to_df())

FX forward conventions and caveats

• Rates are derived from each trade's leg notionals, not the reported Exchange rate basis, which flips between USD/EUR and EUR/USD on the same instrument.
• min_notional (default 1,000,000 base units) is load-bearing. Sub-institutional prints — trades of order 10² base units — execute percent away from the interbank market. Left in, they dominate a tenor's median: the EURUSD 3M point moves from ~46 pips to ~292 pips, a level that is economically impossible for a 3M forward.
• Points are quoted in pips: 1/10,000 of the quote currency, or 1/100 against JPY.
• Depth varies sharply by pair. USDJPY is the best supported and is reliably monotonic; USDCAD and EURUSD are deep but not always monotonic — an individual bucket can print away from its neighbours on a given day, which is a property of the reported trades rather than of the construction. In the extreme, a single day's bucket dominated by off-market prints (or a funding squeeze, e.g. offshore CNH) can cross to the wrong side of spot and flip that tenor's sign; the median faithfully reports what traded. num_trades and the min_rate / max_rate spread — surfaced on the widget — flag such a bucket. GBPUSD and NZDUSD are thin and noisy. Check them before relying on a tenor.
• A tenor's spot_rate is its own as-of day's spot, so rows with different staleness_days are differenced against different spots. Points across such rows are each internally consistent but are not a single instant's curve.

Theoretical (covered interest parity) fair value

For a pair whose two legs both have an OIS curve — USD, EUR, GBP, JPY, CHF and CAD, i.e. all the USD majors — each tenor also carries the covered-interest-parity forward points alongside the executed ones. This is the forward that neutralizes the interest-rate differential (Lehman Brothers, FX Training Manual): F = S·(1 + r_quote·T/b) / (1 + r_base·T/b), where each leg's money-market rate r is the simple rate implied by its OIS discount factor — so the forward is the factor ratio S·DF_base/DF_quote, independent of how the curve compounds its zero — accruing on its own basis (365 days for GBP, JPY and CAD, 360 for USD, EUR and CHF). The base is at a forward premium (points added to spot) when the quote out-yields it, a discount otherwise.

• theoretical_points — the CIP fair value, in pips.
• basis_points — executed less theoretical: positive where the market pays over CIP fair value, negative under. This is the cross-currency basis the executed forwards are pricing.
• quotation — premium or discount, from the sign of the executed points.
• carry — whether a long base-currency forward earns or pays the points to the forward date: it earns at a discount (the base out-yields the quote, so it is bought forward below spot) and pays at a premium; the short-base side is the opposite (Lehman Brothers, FX Training Manual: pay or earn the points). quotation and carry are set for every pair.

AUDUSD and NZDUSD have no OIS curve for the foreign leg, so they carry the executed points (and quotation/carry) but no theoretical_points.

FX Implied Volatility

obb.cftc.fx_implied_vol inverts the vanilla FX options (NA/O Van Call|Put) reported to the CFTC to an implied volatility, using Garman-Kohlhagen — the two-rate FX form of Black-Scholes (Lehman Brothers, FX Training Manual: implied volatility is extracted from the Black-Scholes formula). Each option contributes its spot, strike, tenor, and premium; the two legs' OIS discount factors supply the forward and the discounting — so the pricing is consistent with the curve rather than a re-compounded zero — and spot is the same concurrent-forward proxy the forward points use.

from openbb import obb

vol = obb.cftc.fx_implied_vol(pair="EURUSD")
print(vol.to_df())

The output is the volatility surface: one row per strike, one column per expiry. A strike is an actual price of the pair — the strikes lie on a grid of point (pip) offsets from spot, so spot (offset zero) is the at-the-money reference and every column shares the same strike axis. Reading down a column traces that expiry's whole smile; reading across the spot strike is the near-the-money term structure (values in percent, e.g. 6.15 = 6.15%). Rendered as a table, each cell is colour-coded by its vol (green low → amber → red high), so the smile and the term structure read at a glance — a proper heatmap rather than overlapping lines.

(USD/JPY, theoretical basis — the downside strikes carry the higher vol, the market's standing bid for USD/JPY downside; a negative SABR correlation captures the skew.)

• basis picks how the surface is built:
  • empirical (default) medians the traded options at each grid strike — what actually traded, with gaps where nothing did. The vol is solved by bisection on the option price, which recovers the out-of-the-money wings a Newton step abandons where its vega vanishes.
  • theoretical fits each expiry's out-of-the-money prints to a lognormal-SABR smile (β = 1, α pinned to the observed at-the-money vol, ρ/ν found by a grid-and-refine least-squares) and evaluates it on the same strike grid — a smooth, gap-free smile, the per-expiry (α, ρ, ν) returned in the metadata. A fit needs strikes on both sides of the forward, else that expiry is skipped.
• Only out-of-the-money options are priced — an in-the-money one is redundant by put-call parity and its thin extrinsic value inverts to an unstable vol; the surviving puts and calls span the smile below and above the forward.
• Each option is only used if it executed on the dissemination day — an option struck days earlier priced against a different spot, so inverting it with today's spot would give a wrong vol.
• Each cell is trimmed to a plausibility band around that expiry's own median vol, so a lone off-market print cannot corrupt a strike.

The spot the whole surface hangs off is the median of the pair's shortest-dated deliverable forwards (NA/Fwd / NA/Swaps). Non-deliverable forwards (NA/Fwd NDF …, a scatter of off-spot strikes reported even for deliverable pairs) and vol/variance swaps are excluded — left in, they bias spot by tens of pips and manufacture a false skew. A cross with no deliverable forward of its own (e.g. GBP/JPY) is triangulated through the dollar from each leg's USD pair; the result reprices the cross's own options to within a few pips of their put-call-parity forward. Each option's strike is taken in whichever orientation sits closer to spot, so a record that mislabels its strike currency pair cannot invert a near-the-money strike into a bogus wing.

Offered for EURUSD, GBPUSD, USDJPY, USDCHF, USDCAD and EURGBP — the pairs whose options are reported to the CFTC in enough depth to build a surface each day; the thinner crosses are left off rather than returned empty. The two-rate pricing needs an OIS curve for each leg, priced off the rates slice contemporaneous with the options (EURGBP triangulates its spot through the dollar). Direction is read from the Call and Put currency and amount - the currency bought and sold - not the FISN, whose Call/Put label contradicts the economic legs on a fraction of trades. Depth is a single day's options, so on the empirical basis short expiries fill only near the money and longer ones reach the wings — the num_options column shows the depth behind each strike row.

CDS Index Trades

obb.cftc.cds_index_trades is the credit default swap index tape: one row per disseminated print, curated and fully typed from the credits file's 110 raw columns.

It is deliberately not a curve. There is no term structure to build — on 2026-07-15, 1,266 of the day's 1,338 index prints were the 5Y, against 7 at the 10Y and 7 at the 3Y. The 5Y is the market, and a bootstrap over the rest would be inventing a curve out of a handful of prints.

from openbb import obb

tape = obb.cftc.cds_index_trades(index="CDX.NA.HY", tenor="5Y", date="2026-07-15")
print(tape.to_df())

A 500bp coupon, 1.24mm paid upfront on 15mm of protection, and an index factor of 0.99 — 1% of the notional already written off by a default. That is the trade, priced without a spread.

A CDS index is priced by coupon plus upfront

This is the whole point of the endpoint, and it comes straight from the technical specification rather than from convention or inference.

For the credit asset class, Other payment type (#81) carries the validation rule:

C, at least one is required: ([Fixed rate] or [Spread] or [Other payment type] = 'UFRO').

and UFRO is defined as:

Upfront Payment, i.e., the initial payment made by one of the counterparties either to bring a transaction to fair value or for any other reason that may be the cause of an off-market transaction

The two price-carrying fields are conditional on each other. For credit, Fixed rate (#91) is required only:

if [Spread] is not populated and [Other payment type] ≠ 'UFRO' … else {blank}

and Spread (#100), symmetrically:

if [Fixed rate] is not populated and [Other payment type] ≠ 'UFRO' … else {blank}

The specification is explicit that the generic Price element does not apply here. Price (#93) states it is not applicable to:

Credit default swaps and credit total return swaps, as it is understood that the information included in the data elements Fixed rate, Spread and Upfront payment (Other payment type: Upfront payment) may be interpreted as the price of the transaction.

The data agrees: Price is populated on 0 of 1,338 index prints. The three fields the spec names are what price the trade, and they combine as the rule above dictates:

Every print carries at least one of the three, exactly as the rule requires — and 1,269 of 1,338 carry the standardised coupon. The coupons are the index conventions and nothing else: CDX.NA.HY and ITRAXX EUROPE CROSSOVER at 0.05, CDX.NA.IG and ITRAXX EUROPE at 0.01, CMBX.NA.BBB- at 0.03, CMBX.NA.AAA at 0.005. So coupon alone never distinguishes two trades in the same index; upfront_amount is what carries the price.

Why spread is not the traded level

spread is disseminated, so it is surfaced — raw, as reported. But reading it as "the CDS spread" is wrong twice over.

First, the spec makes it a conditional alternative, not a price: it is required only when there is no fixed rate and no upfront. It is populated on 77% of index prints, against 95% for the coupon.

Second, the field does not always contain a spread at all. Per the spec, notation 3 means "value expressed as decimal (e.g., 0.0257 instead of 2.57%)" and notation 1 means a monetary amount. On the price-quoted indices the reported number is the price in points of par, and the notation merely rescales it:

The two notations hold the same number, scaled by 10,000. This is where "CDX.NA.HY trades at 108bp" comes from, and it is a misreading: 108 is the price. High yield trades on upfront against a 500bp coupon, and a 108bp spread against a 500bp coupon is not a thing the market could produce.

So: read spread together with spread_notation, per index, or use coupon and upfront_amount, which mean the same thing on every row.

The index name has no series — maturity pins it

index comes from UPI Underlier Name, which names the family only: CDX.NA.IG, never CDX.NA.IG.45. The elements that might have carried a series are not disseminated here — Underlying Asset Name and Underlier ID-Leg 1 are populated on 0 of 1,338 index prints.

maturity_date (the spec's Expiration date, #142) is therefore load-bearing: it is the only field separating one series from another, and it is surfaced for exactly that reason.

obb.cftc.cds_index_trades(index="CDX.NA.IG", tenor="5Y", date="2026-07-15")

returns both the on-the-run 5Y maturing 2031-06-20 and the previous series maturing 2030-12-20. Both are "the 5Y"; only the maturity tells them apart.

tenor is derived, not disseminated: it is the years from execution_timestamp to maturity_date, snapped to the nearest standard CDS index tenor within one year. Two consequences worth knowing:

• An off-the-run series keeps the tenor it is quoted at. The 2030-12-20 print above is 4.43 years from execution and is labelled 5Y, because that is what it is.
• Execution timestamp "remains unchanged throughout the life of the UTI", so on a correction or termination the tenor describes the original trade, not time remaining today.
• CMBX and other long-dated underliers fall outside the standard grid and keep a rounded year count instead (31Y, 39Y), rather than being forced onto a CDS tenor they do not trade.

Scope and caveats

• Included: the index FISNs NA/CDS Corp Idx, NA/CDS Corp Idx Tra (tranches) and NA/CDS Sov Idx. Excluded: single names (NA/CDS Corp SN), baskets, and index swaptions (NA/CDS Idx Swt) — a swaption prices off a strike and premium rather than a coupon, and its UPI Underlier Name carries the FISN string instead of an index name, so it cannot be filtered by index at all. Check upi_fisn to separate tranche prints; the CDS index attachment point and detachment point elements are not publicly disseminated (P43 Reported = N), so a tranche cannot be identified by its attachment level.
• There is no per-message dissemination timestamp in this data. The spec defines one (Dissemination timestamp, #D3, "to the nearest second"), but the cumulative slice does not carry the column — the file's report date is the dissemination day. The endpoint therefore reports dissemination_date, alongside the spec's event_timestamp and execution_timestamp, which are per-print and exact.
• cleared is I or N, never Y (1,184 / 153 on the sample day). Part 43 disseminates the original swap, and I is "Intent to clear, for alpha transactions that are planned to be submitted to clearing". This is why venue is well populated: Platform identifier is "C if [Cleared] = 'N' or 'I'; NR if [Cleared] = 'Y'".
• Notionals above the reporting cap are disseminated at the cap and flagged by is_capped (178 of 1,338 prints on the sample day). When the notional is capped the SDR must proportionally scale the other disseminated amounts, so a capped print's upfront_amount is scaled too — do not read it as dollars against the true notional.
• min_notional therefore has a trap. It compares against the disseminated notional, and a capped notional is only a floor on the real one. The caps vary by index, tenor and currency — on the sample day USD prints capped at 50mm, 76mm, 250mm and 400mm — so a threshold above a cap silently drops capped prints that may be far larger than it. Filter on is_capped to see them.
• index matching is exact and case-insensitive, not a substring match: ITRAXX EUROPE is a prefix of ITRAXX EUROPE CROSSOVER and ITRAXX EUROPE SENIOR FINANCIALS, and a substring filter would silently conflate three different indices.
• The index dropdown lists the families observed in a sampled day's file and is a convenience, not a whitelist — the parameter is free text, so an index absent from the list still filters.
• The tape includes every action type (NEWT, MODI, CORR, EROR, TERM), because all of them are disseminated prints — a tape that silently dropped corrections would not be the tape. There is no action_type parameter; action_type and original_dissemination_identifier are columns, so filtering to new trades is df[df.action_type == "NEWT"].
• index_factor is below 1 once a constituent has defaulted; multiplied by notional_amount it yields the notional actually covered by the seller of protection.

Report Types

Reports can be filtered by measure, or include all reported fields. Report types come as 'Futures Only', or 'Combined' (futures and options combined positions), selectable by setting the futures_only boolean parameter.

Legacy

The Legacy report is broken down by exchange with reported open interest further broken down into three trader classifications: commercial, non-commercial and non-reportable.

Disaggregated

The Disaggregated reports are broken down by Agriculture and Natural Resource contracts. The Disaggregated reports break down reportable open interest positions into four classifications: Producer/Merchant, Swap Dealers, Managed Money and Other Reportables.

Financial

The Traders in Financial Futures (TFF) report includes financial contracts. The TFF report breaks down the reported open interest into five classifications: Dealer, Asset Manager, Leveraged Money, Other Reportables and Non-Reportables.

Supplemental

The Supplemental report includes 13 select agricultural commodity contracts for combined futures and options positions. Supplemental reports break down the reportable open interest positions into three trader classifications: non-commercial, commercial, and index traders.

Visit the CFTC website for detailed descriptions of reports and classification methodology.