# 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-futures-trade-and-quote
name: AlgoSeek US Futures Trade and Quote
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- futures
- cme-group
- tick
description:
  purpose: Tick-level trades and best bid/ask quote updates for CME-listed futures, with UTC and Chicago
    timestamps, an aggressor-side event type and flags; used for microstructure, execution research and
    backtesting.
  usage: Futures backtesting, roll research, and intraday microstructure 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 (this dataset''s
    100-row sample contains none). 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-futures-trade-and-quote/
  - type: implementation
    url: https://algoseek.com/data-docs/futures-market-data/algoseek.US.Futures.TAQ.pdf
  - type: implementation
    url: https://algoseek.com/docs/rest-api/reference
context:
  instructions: UTCDate/UTCTime are the event time in UTC and files cover UTC calendar days, so one CME
    overnight session spans two files and Sunday-evening trading lands under Monday's UTCDate. LocalDate/LocalTime
    are Chicago clock time and do not roll at the 17:00 CT session open; derive the exchange trade date
    yourself. The ticker is one contract month (e.g. ESZ3), not a continuous series; roll explicitly.
    Aggressor side comes from TypeMask bits 7 (buy) and 6 (sell); a plain TRADE means the initiator is
    unknown. Rows flagged as calculated (Flags 8) are not trades.
  verifiedStatements:
  - id: vs1
    question: What time zone are the timestamps in?
    answer: UTC, with LocalDate/LocalTime fields in US Central (Chicago) time.
  - id: vs2
    question: Which file holds a Sunday-evening CME session?
    answer: The Monday UTCDate file; files are UTC calendar days.
  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_TAQ}/
  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.
- server: algoseek-rest-api
  type: api
  environment: vendor
  description: AlgoSeek Datasets REST API (X-API-KEY header; JSON, CSV or gzipped CSV). Returns AlgoSeek's
    normalized API layout, which differs from the flat-file columns in this contract's schema.
  location: https://api.algoseek.com/v1/data/us-futures/taq/:trade_date/:identifier
  customProperties:
  - property: auth
    value: X-API-KEY header issued by AlgoSeek
  - property: columnsEndpoint
    value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/columns
  - property: statusEndpoint
    value: https://api.algoseek.com/v1/meta/datasets/{dataset_id}/status
  - property: responseFormats
    value:
    - json
    - csv
    - csv_gzip
  - property: pagination
    value: offset + limit; tick endpoints take trade_date and identifier (Ticker or ASID) in the path
schema:
- name: us_futures_trade_and_quote
  physicalName: fut_taq
  physicalType: file
  logicalType: object
  businessName: US Futures Trade and Quote
  description: Tick-level trades and best bid/ask quote updates for CME-listed futures, with UTC and Chicago
    timestamps, an aggressor-side event type and flags; used for microstructure, execution research and
    backtesting.
  dataGranularityDescription: One exchange event (quote update, trade, or statistic such as opening/settlement
    price, trade volume, open interest, empty book) 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, 9 digits HHMMSSmmm with no separators (ms precision in samples), e.g.
      220000003 = 22:00:00.003.
    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: 'Contract ticker, max 20 chars: base symbol + month code + last digit of expiry year
      (e.g. ESZ3); spreads use a LEG-LEG form.'
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    partitioned: true
    partitionKeyPosition: 2
    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: QUOTE BID
      label: Exchange's best bid quote
    - value: QUOTE SELL
      label: Exchange's best sell (ask) quote
    - 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, bid/ask or settlement price by event type, 6-decimal string; 0.000000
      on empty-book, trade-volume and open-interest 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 or quoted at this price. SETTLEMENT PRICE rows carry the referenced
      trade date (yyyymmdd); TRADE VOLUME and OPEN INTEREST rows carry the count (sample).
    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_taq
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/fut_taq.csv
- property: assetClass
  value: future
- property: venues
  value:
  - CME
  - CBOT
  - COMEX
  - NYMEX
- property: coverage
  value: 'Page: futures traded on US exchanges including CME, CBOT, COMEX and NYMEX, full historical archive
    plus daily automated updates. Guide: Futures, Spreads and Future Options datasets cover securities
    listed on US exchanges. 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
    314863 for ESZ3; 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 2 lists CallPut, Strike, Month and ExpirationYear but marks them options-only;
    they are absent from this futures sample header and are not included in columns.'
  - 'Doc discrepancy: Product page says Flags carry ''exchange condition codes''; the guide''s Flags are
    implied, session-high/low, calculated-price and opening markers (0/1/2/4/8/16).'
  - 'Doc discrepancy: Product page speaks of bid/ask quotes; the Type label for the ask side is QUOTE
    SELL (no ''QUOTE ASK'' value exists in the guide or samples).'
contractCreatedTs: '2026-11-02T00:00:00Z'