# 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-minute-bar
name: AlgoSeek US Futures Trade Only Minute Bar
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- futures
- cme-group
- bar
description:
  purpose: 'One-minute 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 1 of 100 bars (trades with no aggressor
    side); BuyQuantity/BuyTradeCount are blank in 0 bars and SellQuantity/SellTradeCount in 0 (guide Missing
    = Blank). Bars are event-based and trade-only: a row exists only for a minute 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-minute-bar/
  - type: implementation
    url: https://algoseek.com/data-docs/futures-market-data/algoseek.US.Futures.Trades.Only.Minute.Bars.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_TRADES_1MIN}/
  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.
- 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/trades-1min/: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_only_minute_bar
  physicalName: fut_trades_1min
  physicalType: file
  logicalType: object
  businessName: US Futures Trade Only Minute Bar
  description: 'One-minute 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 minute 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 (sample); guide says HH:MM for minute bars
    physicalType: string (time) (csv text)
    description: UTC start of the one-minute bar, HH:MM:SS in the sample (guide says HH:MM for minute
      bars). Sample events fall in [start, start+60 s).
    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 (sample); guide says HH:MM for minute bars
    physicalType: string (time) (csv text)
    description: Chicago local start time of the bar (DST-aware), same layout as UTCTimeBarStart.
    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: integer (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: decimal (csv text)
    description: Total contracts traded in the bar; can exceed BuyQuantity + SellQuantity when some trades
      have no aggressor side.
    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_1min
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/fut_trades_1min.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 (sample; guide says HH:MM for minute bars).
- property: sessionHours
  value: Product-specific CME hours and breaks, not a fixed window; bars are keyed to UTC clock minutes.
- 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 types TotalVolume as integer and TotalQuantity as decimal, but the sample
    has TotalVolume with 6 decimals (e.g. 1909236.250000) and TotalQuantity as whole numbers; the Second
    Bar guide lists them the other way round (decimal / integer).'
  - 'Doc discrepancy: Guide says UTCTimeBarStart/LocalTimeBarStart are HH:MM for minute bars; the sample
    shows HH:MM:SS (e.g. 22:00:00).'
  - 'Doc discrepancy: Guide''s note says a one-minute bar 11:04 covers times greater than 11:04 to less
    than 11:05, and a one-second bar 13:03:02 covers times greater than 13:03:01 up to 13:03:02, which
    reads as end-labelled and conflicts with the column name BarStart; no event times are in the trade-only
    sample to settle it (the TAQ minute-bar sample shows start-labelled windows).'
  - '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 22:07:00 UTC bar has 29 contracts all at 4538.25 and TotalVolume 131609.25 in the sample.'
  - 'Doc discrepancy: Trade-only minute-bar guide lists CallPut, Strike, Month and ExpirationYear as options-only
    fields; they are absent from this futures sample header and are not included in columns.'
contractCreatedTs: '2026-11-02T00:00:00Z'