# 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-multiple-depth
name: AlgoSeek US Futures Multiple Depth
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- futures
- cme-group
- depth
description:
  purpose: 'Level-2 order book updates for CME-listed futures: each row snapshots one side of the book
    with up to 10 price levels, each with price, aggregate size and order count.'
  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
    (from the sample and the guide''s prose about snapshots): one row is a full snapshot of one side (B
    or S) of an instrument''s book after an update, with up to 10 levels. At the same instant the sample
    shows a B row and an S row. There is no action/delta column and no sequence number; 57 of 100 sample
    rows share (UTCTime, Side) with another row, so rows within the same millisecond are ordered only
    by file position and the key is not unique. Guide says multiple snapshots can fall in the same millisecond
    for very active instruments because updates are published when an incremental book-update transaction
    (FIX batch) completes. Each row always has 10 Price/Size/Orders triples; only the first Depth levels
    carry data and the rest are zero (e.g. Depth 5 -> levels 6-10 are zero). Depth is 1, 2, 5 or 10 depending
    on instrument type; ES in the sample is 10. Treat level price 0 as ''no level'', not a price. Level
    1 is the best price: in the sample bid prices strictly fall and ask prices strictly rise from L1 to
    L10.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-futures-multiple-depth/
  - type: implementation
    url: https://algoseek.com/data-docs/futures-market-data/algoseek.US.Futures.Multiple.Depth.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_MULTIPLE_DEPTH}/
  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 per trading day (UTC 00:00-24:00); guide example: ticker GEH3 on 2019-09-09. 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/multiple-depth/: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_multiple_depth
  physicalName: fut_multiple_depth
  physicalType: file
  logicalType: object
  businessName: US Futures Multiple Depth
  description: 'Level-2 order book updates for CME-listed futures: each row snapshots one side of the
    book with up to 10 price levels, each with price, aggregate size and order count.'
  dataGranularityDescription: One snapshot of one book side (B or S) of one contract at one update time,
    up to 10 levels.
  properties:
  - name: UTCDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: UTC calendar date of the book update; the daily file is one UTC day (00:00-24:00).
    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 (HHMMSSmmm) (csv text)
    description: Update time in UTC, 9 digits HHMMSSmmm with no separators (ms precision), 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 (HHMMSSmmm) (csv text)
    description: Chicago calendar date of the update. The guide's table lists this field with the time
      format (swapped with LocalTime).
    customProperties:
    - property: evidence
      value: guide+sample
  - name: LocalTime
    logicalType: time
    logicalTypeOptions:
      format: HHMMSSmmm
    physicalType: string (yyyymmdd) (csv text)
    description: Update time in Chicago local time (UTC-6 winter, UTC-5 DST), HHMMSSmmm. The guide's table
      lists the date format here (swapped).
    customProperties:
    - property: unit
      value: ms
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Instrument name, max 20 characters (e.g. ESZ3).
    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 id; this guide calls it the CME security identifier (the TAQ guides call it
      an internal algoseek id). Sample ESZ3 = 314863, same as in the TAQ sample.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Side
    logicalType: string
    physicalType: string (csv text)
    description: 'Which side of the book the row''s levels describe: B for bids, S for sells.'
    primaryKey: true
    primaryKeyPosition: 4
    required: true
    enum:
    - value: B
      label: Buy (bid) side of the book
    - value: S
      label: Sell (ask/offer) side of the book
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Flags
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Marks a regular book event (0) or an implied one (1); implied levels come from spread
      relationships and may sit away from the regular bid/ask.
    primaryKey: true
    primaryKeyPosition: 5
    required: true
    enum:
    - value: '0'
      label: Regular book
    - value: '1'
      label: Implied
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Depth
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of book levels shown for this instrument (1, 2, 5 or 10, by instrument type);
      levels beyond Depth are zero-filled.
    enum:
    - value: '1'
      label: 1 level
    - value: '2'
      label: 2 levels
    - value: '5'
      label: 5 levels
    - value: '10'
      label: 10 levels (maximum)
    customProperties:
    - property: unit
      value: count
    - property: evidence
      value: guide+sample
  - name: L1Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 1 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L1Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 1.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L1Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 1.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L2Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 2 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L2Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 2.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L2Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 2.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L3Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 3 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L3Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 3.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L3Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 3.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L4Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 4 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L4Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 4.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L4Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 4.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L5Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 5 (level 1 is the best price; bids fall and asks rise with level).
      Missing from the guide's table (L4 is listed twice).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: sample-only
  - name: L5Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 5. Missing from the guide's table.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: sample-only
  - name: L5Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 5. Missing from the guide's table.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: sample-only
  - name: L6Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 6 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L6Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 6.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L6Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 6.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L7Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 7 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L7Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 7.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L7Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 7.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L8Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 8 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L8Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 8.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L8Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 8.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L9Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 9 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L9Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 9.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L9Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 9.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L10Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price at book level 10 (level 1 is the best price; bids fall and asks rise with level).
    customProperties:
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L10Size
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Contracts resting at book level 10.
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: 0 when the level is unused
    - property: evidence
      value: guide+sample
  - name: L10Orders
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of orders at book level 10.
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: 0 when the level is unused
    - 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
      - Side
      - 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: L10Size_non_negative
    type: sql
    description: L10Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L10Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L1Size_non_negative
    type: sql
    description: L1Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L1Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L2Size_non_negative
    type: sql
    description: L2Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L2Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L3Size_non_negative
    type: sql
    description: L3Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L3Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L4Size_non_negative
    type: sql
    description: L4Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L4Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L5Size_non_negative
    type: sql
    description: L5Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L5Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L6Size_non_negative
    type: sql
    description: L6Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L6Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L7Size_non_negative
    type: sql
    description: L7Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L7Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L8Size_non_negative
    type: sql
    description: L8Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L8Size < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: L9Size_non_negative
    type: sql
    description: L9Size is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE L9Size < 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_multiple_depth
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/fut_multiple_depth.csv
- property: assetClass
  value: future
- property: venues
  value:
  - CME
  - CBOT
  - COMEX
  - NYMEX
- property: coverage
  value: 'Page: multi-level order book for CME-listed futures (CME, CBOT, COMEX, NYMEX), up to 10 levels
    per side; guide: 10 levels for all bids and asks of US exchange futures. Full historical archive plus
    daily automated updates per the page; 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.
- property: sessionHours
  value: Product-specific CME hours; the guide says a session spans the week with dates cut at UTC midnight
    (e.g. all messages with UTC date 2014-03-12 are posted under 2014-03-12) and the book is carried over
    past midnight.
- property: priceAdjustment
  value: n/a
- property: licensedData
  value: true
- property: evidenceGrade
  value: vendor-doc+sample
- property: knownIssues
  value:
  - Primary key is inferred; AlgoSeek's guide does not name one.
  - 'Doc discrepancy: Guide Table 2 swaps the formats of the local fields: LocalTime is typed string (yyyymmdd)
    and LocalDate string (HHMMSSmmm); the sample (and the descriptions) show LocalDate = yyyymmdd and
    LocalTime = HHMMSSmmm.'
  - 'Doc discrepancy: Guide Table 2 lists L4Price/L4Size/L4Orders twice and omits L5Price/L5Size/L5Orders;
    the sample header has L1..L10 in order, so the second ''L4'' block is L5.'
  - 'Doc discrepancy: SecurityID is described here as a ''CME security identifier'', whereas the Futures
    TAQ and Trade Only guides call the same column an ''internal security ID used by algoseek''; ESZ3
    has SecurityID 314863 in both the TAQ and depth samples of 2023-08-02.'
  - 'Doc discrepancy: Guide describes UTCDate/UTCTime/LocalDate/LocalTime with ''transaction'' / ''trade''
    wording although these rows are book updates, not trades; no trade events exist in this dataset.'
  - 'Doc discrepancy: Guide says a trading session ''spans an entire week'' and dates are cut in UTC,
    while the Daily File section says one file per symbol per UTC day (00:00-24:00); the carry-over of
    the book across UTC midnight is described only in prose.'
  - 'Doc discrepancy: Guide Table 1 example (GEH3, 2019) shows prices with 3-4 decimals and zero order
    counts at every level, whereas the 2023 ES sample has 6-decimal price strings and non-zero order counts;
    Table 1 omits UTCDate, UTCTime, SecurityID and levels 3-10 (guide says so).'
  - 'Doc discrepancy: Guide names no exchanges or venues, whereas the product page lists CME, CBOT, COMEX
    and NYMEX.'
contractCreatedTs: '2026-11-02T00:00:00Z'