# 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-only-second-bar
name: AlgoSeek US Futures Trade Only Second Bar
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- futures
- cme-group
- bar
description:
  purpose: 'One-second event-based bars built only from executed trades in CME-listed futures: OHLC, dollar-style
    volume, contract and trade counts, and buy/sell aggressor splits.'
  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. In the
    sample TotalQuantity differs from BuyQuantity + SellQuantity in 0 of 100 bars (trades with no aggressor
    side); BuyQuantity/BuyTradeCount are blank in 41 bars and SellQuantity/SellTradeCount in 33 (guide
    Missing = Blank). Bars are event-based and trade-only: a row exists only for a second with at least
    one actual trade, so the series is sparse (sample UTCTimeBarStart values skip empty intervals). A
    contract-day with no trades has no file; very illiquid contracts may have none for weeks. A file is
    created only if there is at least one trade in the whole 24-hour session. Calculated trade prices
    (not actual trades, Flags 8 in the tick data) are excluded from bars. If a bar has a single trade,
    OpenPrice = HighPrice = LowPrice = ClosePrice.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-futures-trade-only-second-bar/
  - type: implementation
    url: https://algoseek.com/data-docs/futures-market-data/algoseek.US.Futures.Trades.Only.Second.Bars.pdf
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_TRADES_1SEC}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Plain-text CSV with a fixed header row, gzip-compressed (.csv.gz, about 8:1). By default one
      file per symbol (contract) per trading day (guide example: ESH0 on 2020-01-28). A file exists only
      if the contract had enough activity that day; no bucket, path or file-name pattern is given.'
  - 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_futures_trade_only_second_bar
  physicalName: fut_trades_1sec
  physicalType: file
  logicalType: object
  businessName: US Futures Trade Only Second Bar
  description: 'One-second event-based bars built only from executed trades in CME-listed futures: OHLC,
    dollar-style volume, contract and trade counts, and buy/sell aggressor splits.'
  dataGranularityDescription: One contract x one UTC second that had at least one trade.
  properties:
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: 'Contract symbol: base symbol + month code + last digit of expiry year (e.g. ESZ3).'
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    partitioned: true
    partitionKeyPosition: 2
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UTCDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: UTC trade date of the bar (the UTC calendar day of the bar start).
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    partitioned: true
    partitionKeyPosition: 1
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UTCTimeBarStart
    logicalType: time
    logicalTypeOptions:
      format: HH:MM:SS
    physicalType: string (time) (csv text)
    description: UTC start of the one-second bar, HH:MM:SS.
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: LocalDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: 'Chicago calendar date of the bar start (guide: local trade date); differs from UTCDate
      when UTC is 5-6 h ahead of the date.'
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: LocalTimeBarStart
    logicalType: time
    logicalTypeOptions:
      format: HH:MM:SS
    physicalType: string (time) (csv text)
    description: Chicago local start time of the bar (DST-aware), HH:MM:SS.
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OpenPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the first trade in the bar.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: HighPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Highest trade price in the bar.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: LowPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Lowest trade price in the bar.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: ClosePrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the last trade in the bar.
    customProperties:
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: TotalVolume
    logicalType: number
    physicalType: decimal (csv text)
    description: 'Sum of trade price x contracts over the bar (guide: ''Total Dollar Volume''); in price
      units, no contract multiplier applied (sample-checked).'
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: TotalQuantity
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Total contracts traded in the bar; can exceed BuyQuantity + SellQuantity when some trades
      have no aggressor side.
    required: true
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: BuyQuantity
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts in trades with 'Trade Aggressor on Buy'; blank if none.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SellQuantity
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts in trades with 'Trade Aggressor on Sell'; blank if none.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: TotalTradeCount
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of separate trades in the bar; can exceed BuyTradeCount + SellTradeCount when
      some trades have no aggressor side.
    required: true
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: BuyTradeCount
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of 'Trade Aggressor on Buy' trades; blank if none.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: SellTradeCount
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of 'Trade Aggressor on Sell' trades; blank if none.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: Blank
    - 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:
      - Ticker
      - UTCDate
      - UTCTimeBarStart
    dimension: uniqueness
    severity: error
    description: The declared primary key is unique within each delivered partition (one file or table
      snapshot).
  - id: bar_high_ge_low
    type: sql
    description: HighPrice is never below LowPrice in the same row.
    query: SELECT COUNT(*) FROM {object} WHERE HighPrice IS NOT NULL AND LowPrice IS NOT NULL AND HighPrice
      < LowPrice
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: open_close_within_range
    type: sql
    description: 'Open and close usually sit inside the high-low range. Only a warning: some AlgoSeek
      aggregations take open/close from a different event set than high/low (seen in the Daily OHLC sample).'
    query: SELECT COUNT(*) FROM {object} WHERE OpenPrice > HighPrice OR OpenPrice < LowPrice OR ClosePrice
      > HighPrice OR ClosePrice < LowPrice
    mustBe: 0
    dimension: accuracy
    severity: warning
  - id: BuyTradeCount_non_negative
    type: sql
    description: BuyTradeCount is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE BuyTradeCount < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: SellTradeCount_non_negative
    type: sql
    description: SellTradeCount is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE SellTradeCount < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: TotalTradeCount_non_negative
    type: sql
    description: TotalTradeCount is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE TotalTradeCount < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: TotalVolume_non_negative
    type: sql
    description: TotalVolume is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE TotalVolume < 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_trades_1sec
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/fut_trades_1sec.csv
- property: assetClass
  value: future
- property: venues
  value:
  - CME
  - CBOT
  - COMEX
  - NYMEX
- property: coverage
  value: 'Page: futures on US exchanges incl. CME, CBOT, COMEX and NYMEX, trade-only, full historical
    archive plus daily automated updates. Guide: bars for securities listed on US exchanges. Start of
    history not stated.'
- property: timezone
  value: Etc/UTC
- property: timestampFormat
  value: Bar start HH:MM:SS.
- property: sessionHours
  value: Product-specific CME hours and breaks, not a fixed window; bars are keyed to UTC clock seconds.
- 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 note says a one-second bar 13:03:02 covers times greater than 13:03:01 up
    to 13:03:02, which reads as end-labelled, while the column is named UTCTimeBarStart; the sample''s
    first bar is 00:00:00 UTC (18:00:00 local, 20240129/20240128) with 6 trades, which is more consistent
    with a start-labelled [t, t+1 s) window, but the sample has no event times to prove it.'
  - 'Doc discrepancy: The guide''s worked timestamp example uses a minute-level time (UTCTimeBarStart
    01:30 -> LocalTimeBarStart 20:30) although this dataset has only one-second bars.'
  - 'Doc discrepancy: Guide names TotalVolume ''Total Dollar Volume'' (sum of price x contract size),
    but it equals price x number of contracts in price units, not USD notional (no contract multiplier).
    E.g. the 00:00:01 UTC bar has 11 contracts all at 4904.25 and TotalVolume 53946.75 in the sample.'
contractCreatedTs: '2026-11-02T00:00:00Z'