# Generated by tools/build_contracts.py from tools/algoseek_catalog.py -- do not edit by hand.
# Open Data Contract Standard v3.2.0 (https://bitol-io.github.io/open-data-contract-standard/).
apiVersion: v3.2.0
kind: DataContract
id: urn:alphaswarm:datacontract:algoseek:us-future-options-trade-only
name: AlgoSeek US Future Options Trade Only
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options-on-futures
- cme-group
- tick
description:
  purpose: Tick-level trades for CME-listed options on futures, built by filtering the quote events out
    of the TAQ feed; each row has price, quantity, aggressor side and flags for trade and trade-adjacent
    statistic events.
  usage: Options-on-futures pricing and flow research on CME Group venues.
  limitations: 'Delivered as recorded from the source feed: AlgoSeek does not remove crossed or locked
    quotes, bad prints, or out-of-sequence packets unless contracted to. Consumers own cleaning. Row grain
    is one exchange event for one contract; there is no sequence-number column, so ties within the same
    millisecond are only ordered by file position. In the 100-row sample (UTCDate, UTCTime, Ticker, TypeMask)
    repeats; adding Price, Quantity, Orders and Flags makes the sample rows unique, but uniqueness is
    not guaranteed in full files. UTCDate/UTCTime are the event time in UTC and the daily file is cut
    at UTC midnight, so a CME overnight session spans two files. LocalDate is a Chicago calendar date:
    the TAQ and minute-bar samples keep the same LocalDate from 17:00 CT onward (no roll to the next CME
    trade date). Evening activity that crosses 00:00 UTC (e.g. Sunday 18:00 CST = Monday 00:00 UTC) appears
    under the next UTCDate with the earlier LocalDate. Aggressor side comes from TypeMask bits 7 (buyer-initiated)
    and 6 (seller-initiated) and the matching Type label; plain TRADE (mask 34 in samples) means the initiator
    is unknown. For quotes the same bits denote bid (bit 7) or offer (bit 6). Flags 2 (SHFlag) and 4 (SLFlag)
    mark session high/low prices; guide Table 6 shows such a row with Quantity 0 and Orders 0, and this
    dataset''s sample has them as TRADE (mask 34) rows with Quantity 0 and Orders 0. Filter on Quantity
    > 0 when counting trades or summing volume. Flag 8 (calculated price, no contracts) must be excluded
    when building bars.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-future-options-trade-only/
  - type: implementation
    url: https://algoseek.com/data-docs/futures-market-data/algoseek.US.Futures.Trades.Only.pdf
context:
  instructions: UTCDate/UTCTime are the event time in UTC and files cover UTC calendar days; LocalDate/LocalTime
    are Chicago clock time. The ticker is '<futures contract> <C|P><strike>' (e.g. 'ESU3 P4450'); the
    underlying is that futures contract month, not the spot index.
  verifiedStatements:
  - id: vs1
    question: What time zone are the timestamps in?
    answer: UTC, with LocalDate/LocalTime fields in US Central (Chicago) time.
  constraints:
  - id: c1
    constraint: 'Licensed vendor data: never export raw rows to a tenant-local destination or include
      them verbatim in a public artifact; serve only through entitlement-checked platform reads.'
  - id: c3
    constraint: Do not treat the vendor's `Ticker` as a stable identity across time; join on an AlgoSeek
      security key (SecId or ASID, which are distinct) or the platform symbol mapping.
servers:
- server: algoseek-s3
  type: s3
  environment: vendor
  description: AlgoSeek flat-file delivery (the layout the schema below describes).
  location: s3://${ALGOSEEK_S3_BUCKET_FUT_OPT_TRADES}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Plain-text CSV with a fixed header row, one row per event. By default one file per symbol
      (contract) per trading day, gzip-compressed (.csv.gz, about 8:1 ratio). Guide example: all events
      for ESH0 on 2020-01-28 are in one file. A trading day is UTC 00:00-24:00. The guide gives no bucket,
      path or file-name pattern.'
  - property: compression
    value: gzip
  - property: header
    value: true
  - property: entitlement
    value: Bucket access is granted per subscription; bucket names arrive with license provisioning.
schema:
- name: us_future_options_trade_only
  physicalName: fut_opt_trades
  physicalType: file
  logicalType: object
  businessName: US Future Options Trade Only
  description: Tick-level trades for CME-listed options on futures, built by filtering the quote events
    out of the TAQ feed; each row has price, quantity, aggressor side and flags for trade and trade-adjacent
    statistic events.
  dataGranularityDescription: 'One trade event (or trade-adjacent statistic: opening price, settlement,
    trade volume, open interest, empty book, session high/low marker) for one contract.'
  properties:
  - name: UTCDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: 'UTC calendar date of the event; the daily file is one UTC day (00:00-24:00). Guide wording:
      trading date (UTC).'
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    partitioned: true
    partitionKeyPosition: 1
    customProperties:
    - property: evidence
      value: guide+sample
  - name: UTCTime
    logicalType: time
    logicalTypeOptions:
      format: HHMMSSmmm
    physicalType: string (HH:MM:SS.mmm or HH:MM:SS.mmmiiinnn) (csv text)
    description: Event time in UTC as HHMMSSmmm (ms). In this sample leading zeros are dropped (100461
      = 00:01:00.461); left-pad to 9 digits.
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - property: unit
      value: ms
    - property: evidence
      value: guide+sample
  - name: LocalDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Chicago (CT) calendar date of the event; can differ from UTCDate and does not roll at
      the 17:00 CT session start.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: LocalTime
    logicalType: time
    logicalTypeOptions:
      format: HHMMSSmmm
    physicalType: string (HH:MM:SS.mmm or HH:MM:SS.mmmiiinnn) (csv text)
    description: Event time in Chicago local time (UTC-6 winter, UTC-5 during DST), same 9-digit HHMMSSmmm
      layout.
    customProperties:
    - property: unit
      value: ms
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: 'Option ticker: futures-style code (base symbol + month code + year digit), a space,
      then C/P and strike, e.g. ''ESU3 P4450''. Max 20 chars.'
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    partitioned: true
    partitionKeyPosition: 2
    customProperties:
    - property: evidence
      value: guide+sample
  - name: CallPut
    logicalType: string
    physicalType: string (csv text)
    description: 'Option type, C (call) or P (put). Guide: available only in the Future Options dataset.'
    enum:
    - value: C
      label: Call
    - value: P
      label: Put
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Strike
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: 'Option strike: fixed price for buying or selling the underlying outright future, in
      the future''s price units (e.g. 4450).'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Month
    logicalType: string
    logicalTypeOptions:
      format: single-letter CME month code
    physicalType: string (csv text)
    description: Option expiration month as a single-letter code (CME month codes, per the cmegroup.com
      table the guide links).
    enum:
    - value: F
      label: January
    - value: G
      label: February
    - value: H
      label: March
    - value: J
      label: April
    - value: K
      label: May
    - value: M
      label: June
    - value: N
      label: July
    - value: Q
      label: August
    - value: U
      label: September
    - value: V
      label: October
    - value: X
      label: November
    - value: Z
      label: December
    customProperties:
    - property: evidence
      value: guide+sample
  - name: ExpirationYear
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Option expiration year as a four-digit number (e.g. 2023).
    customProperties:
    - property: evidence
      value: guide+sample
  - name: SecurityID
    logicalType: string
    logicalTypeOptions:
      format: numeric string
    physicalType: string (csv text)
    description: 'Instrument identifier. Guide calls it an internal algoseek security ID (the Multiple
      Depth guide calls it a CME ID). Sample values: 3445, 314863, 634394.'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: TypeMask
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: 'Event type as an 8-bit mask: bits 0-4 message type, bit 5 final, bit 6 sell/offer side,
      bit 7 buy/bid side. Guide''s field table says ''Not in use'' but Appendix A defines it.'
    primaryKey: true
    primaryKeyPosition: 4
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Type
    logicalType: string
    physicalType: string (csv text)
    description: 'Event type label: quote side, trade with aggressor side, or statistic (opening/settlement/volume/open
      interest/empty book). Any label may carry an IMPLIED prefix.'
    enum:
    - value: TRADE AGRESSOR ON BUY
      label: Trade whose initiator was on the buy side
    - value: TRADE AGRESSOR ON SELL
      label: Trade whose initiator was on the sell side
    - value: TRADE
      label: Trade with unknown initiator (side cannot be determined)
    - value: OPENING PRICE
      label: First trade for the opening or re-opening of the instrument
    - value: FIXING PRICE
      label: Volume-weighted average price for the nearby (front month) contract
    - value: TRADE VOLUME
      label: Contracts traded in the instrument for the trading session
    - value: SETTLEMENT PRICE
      label: Official price set at a point in the trading day; Quantity carries the referenced trade date
        (yyyymmdd)
    - value: OPEN INTEREST
      label: Contracts not yet offset/fulfilled as of the previous trading day; sent before session start
    - value: EMPTY BOOK
      label: No current bid or ask (feed reset, maintenance or halt)
    - value: EMPTY BOOK BID
      label: Empty-book variant named in the guide
    - value: EMPTY BOOK FINAL
      label: Empty-book variant named in the guide; the label seen in samples
    - value: EMPTY BOOK BID FINAL
      label: Empty-book variant named in the guide
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Opening, trade or settlement price by event type, 6-decimal string; 0.000000 on trade-volume
      and empty-book rows (sample).
    primaryKey: true
    primaryKeyPosition: 5
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Quantity
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts traded at this price. 0 on SH/SL marker rows; SETTLEMENT PRICE carries the
      referenced trade date (yyyymmdd); TRADE VOLUME/OPEN INTEREST carry the count.
    primaryKey: true
    primaryKeyPosition: 6
    required: true
    customProperties:
    - property: unit
      value: contracts
    - property: evidence
      value: guide+sample
  - name: Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Customer orders at the price level. Guide says to ignore it for trades (zero before 2015-11-22,
      when the feed moved from FAST/FIX to MDP).
    primaryKey: true
    primaryKeyPosition: 7
    required: true
    customProperties:
    - property: unit
      value: count
    - property: evidence
      value: guide+sample
  - name: Flags
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Condition flag for the event. 2 and 4 mark session high/low rows (Quantity 0 in samples);
      8 = calculated price with no contracts; 1 = implied; 16 = opening.
    primaryKey: true
    primaryKeyPosition: 8
    required: true
    enum:
    - value: '0'
      label: Regular
    - value: '1'
      label: Implied (derived from spread/other relationships, not an outright event)
    - value: '2'
      label: SHFlag - marks the session high price
    - value: '4'
      label: SLFlag - marks the session low price
    - value: '8'
      label: CalculatedPrice - calculated price with no contracts actually traded; exclude from bars/backtests
    - value: '16'
      label: Opening
    customProperties:
    - property: evidence
      value: guide+sample
  quality:
  - id: row_count_positive
    metric: rowCount
    mustBeGreaterThan: 0
    dimension: completeness
    severity: error
    description: Every delivered partition (trade date, or snapshot) carries at least one row.
  - id: primary_key_unique
    metric: duplicateValues
    mustBe: 0
    arguments:
      properties:
      - UTCDate
      - UTCTime
      - Ticker
      - TypeMask
      - Price
      - Quantity
      - Orders
      - Flags
    dimension: uniqueness
    severity: warning
    description: 'Best-effort key for an event stream: same-timestamp events from one venue can repeat,
      so duplicates are reported, not rejected.'
  - id: Quantity_non_negative
    type: sql
    description: Quantity is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE Quantity < 0
    mustBe: 0
    dimension: accuracy
    severity: error
support:
- channel: algoseek-support
  tool: email
  url: mailto:support@algoseek.com
  scope: issues
  description: Vendor support for data defects, missing days, and entitlement problems.
team:
  name: AlphaSwarm data engineering
slaProperties:
- id: update_frequency
  property: frequency
  value: 1
  unit: d
  driver: analytics
- id: retention
  property: retention
  value: license-term
  description: Retention of landed copies is bounded by the AlgoSeek license; purge on termination.
  driver: regulatory
customProperties:
- property: vendor
  value: AlgoSeek
- property: vendorDataGroup
  value: us-futures
- property: vendorDatasetTextId
  value: fut_opt_trades
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/fut_opt_trades.csv
- property: assetClass
  value: future_option
- property: venues
  value:
  - CME
- property: coverage
  value: 'Page: all CME-traded future options contracts; tick-level history plus daily automated updates.
    Guide: Futures, Spreads and Future Options datasets cover securities listed on US exchanges; products
    are on cmegroup.com. Start of history not stated.'
- property: timezone
  value: Etc/UTC
- property: timestampFormat
  value: 9-digit HHMMSSmmm string with no separators (e.g. 220000003 = 22:00:00.003), millisecond precision
    in the 2023 samples. Guide field table also lists HH:MM:SS.mmm[iiinnn] and says nanoseconds (ms before
    2016).
- property: sessionHours
  value: 'Product-specific CME hours and maintenance breaks, not a fixed window (guide example: Gold maintenance
    16:00-17:00 CT; guide points to cmegroup.com/trading-hours). Files are cut at UTC midnight, mid-session.'
- property: priceAdjustment
  value: n/a
- property: licensedData
  value: true
- property: evidenceGrade
  value: vendor-doc
- property: knownIssues
  value:
  - Primary key is inferred; AlgoSeek's guide does not name one.
  - 'Doc discrepancy: Guide field table lists TypeMask as ''Not in use'' (integer), yet every sample row
    populates it and Appendix A defines its 8-bit encoding; treat TypeMask as live.'
  - 'Doc discrepancy: Guide field table describes UTCTime/LocalTime as nanosecond timestamps (milliseconds
    before 2016) in HH:MM:SS.mmm[iiinnn] form; the Timestamps section says HHMMSSZZZ (3-digit ms) and
    every sample value is a 9-digit HHMMSSmmm string with ms precision.'
  - 'Doc discrepancy: Guide calls UTCDate and LocalDate the ''trading date''; its Daily File rule is UTC
    00:00-24:00 and LocalDate is the Chicago calendar date of the event (guide Table 1 shows LocalDate
    20200127 at 18:00 local, i.e. 00:00 UTC on 2020-01-28; the family''s future-options trade-only sample
    has UTCDate 20230802 with LocalDate 20230801 at 00:01 UTC).'
  - 'Doc discrepancy: Guide describes the ticker scheme as ZZZMY/ZZZMY.SXXXX, but its own example (ESZ5
    P3600) and the options samples (ESU3 P4450, ESH4 P4600) separate the futures code and option code/strike
    with a space, not a dot; the year is a single digit.'
  - 'Doc discrepancy: SecurityID: this guide says ''internal security ID used by algoseek''; the Multiple
    Depth guide calls the same-named column a ''CME security identifier''. This sample has SecurityID
    372785 for ESH4 P4600; other family samples show a 4-digit value (ESU3 = 3445) and 6-digit values,
    so the scheme is not confirmed as the exchange''s.'
  - 'Doc discrepancy: Guide Table 6 (GCQ7 maintenance example) shows TypeMask 2, 12, 7 and 5 (aggressor
    trades carry mask 2), which do not follow the Appendix A encoding (final bit 32, side bits 64/128);
    Table 1 and the 2023 samples use 161/97/162/98.'
  - 'Doc discrepancy: Guide example ZSX3-ZSF3 is described as a Nov 2023 vs Jan 2023 soybean spread, an
    implausible pairing, which shows the single year digit is ambiguous in tickers.'
  - 'Doc discrepancy: Guide Table 3 spells ''TRADE AGGRESSOR ON BUY/SELL'' with two Gs; the samples (and
    the TAQ guide) use ''TRADE AGRESSOR ON BUY/SELL'' with one G.'
  - 'Doc discrepancy: Product page says each record is an executed trade, but guide Table 4 and the samples
    also contain statistics events (opening price, trade volume, open interest, empty book) and zero-quantity
    session high/low marker rows.'
  - 'Doc discrepancy: UTCTime loses leading zeros in this sample (e.g. 100461 for 00:01:00.461, 24540335
    for 02:45:40.335) while LocalTime keeps 9 digits; the future-options TAQ sample keeps zero padding
    (060103206). Parse UTCTime as text and left-pad to 9 digits.'
  - 'Doc discrepancy: 94 of the 100 sample rows are EMPTY BOOK FINAL events (TypeMask 108 and 172), so
    the preview contains few trades; guide Appendix A example 4 says bit 6 is ignored for EmptyBook, yet
    mask 172 sets bit 7 instead of bit 6.'
contractCreatedTs: '2026-11-02T00:00:00Z'