# 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-options-trade-and-quote-gth
name: AlgoSeek US Options Trade and Quote GTH
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options
- opra
- us
- tick
description:
  purpose: Tick-level trades and top-of-book quote updates for Cboe index options (SPX, VIX, XSP, RUT
    families) traded in the overnight Global Trading Hours session. One row per event, with a numeric
    event mask and a text action.
  usage: Options pricing, volatility, and flow research on US-listed equity and index options.
  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. Contract
    identity per row = ExpirationDate + StrikePrice + CallPut; the root/underlying (SPX vs SPXW, VIX vs
    VIXW, XSP, RUT vs RUTW) is NOT in the sample rows (guide lists a Ticker column) and must come from
    the Ticker column if delivered or from the file name/path. No OSI/OCC symbol column exists. StrikePrice
    and Price are plain decimals in dollars/index points (StrikePrice 4555 = SPX 4555), not scaled by
    1000; the contract multiplier is not in the file. EventType decoding verified on the sample: 228 =
    128 buy side + 64 NBBO + 32 call + 4 FirmQuote (Side B); 100 = 64 + 32 + 4 (Side A). Bit 4 (16) marks
    a cancelled prior trade/quote; no cancel rows appear in the sample, so its on-wire pattern is unverified.
    Action ''FQ NB'' = FirmQuote with NBBO flag. Quote rows are per side: a bid and an ask update appear
    as separate rows (EventType 228 then 100).'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-options-trade-and-quote-gth/
  - type: implementation
    url: https://algoseek.com/data-docs/options-market-data/algoseek.US.Options.GTH.TAQ.pdf
context:
  instructions: 'Identify a contract by underlying, expiration, strike and call/put. Most options tick
    files carry no underlying/root column: the underlying comes from the file path or API identifier,
    so keep it alongside every row you land. Strikes and prices are plain decimals (not scaled). EventType
    is a bit field: low 4 bits message type, 16 cancel, 32 call, 64 NBBO, 128 buy/bid side. Check OCC
    special settlements before comparing prices across a corporate action.'
  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_OPT_TAQ_GTH}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: 'Plain-text CSV with a fixed header; one row per event. Guide: one file per option contract
      per trading day, with the example of all calls and puts of one expiration for one trading date consolidated
      ''in one tar file''; each contract CSV is gzip-compressed (about 7x expansion). No bucket/path/file-name
      pattern is given. Sample rows are a single contract (one CallPut/Strike/Expiration).'
  - 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_options_trade_and_quote_gth
  physicalName: opt_taq_gth
  physicalType: file
  logicalType: object
  businessName: US Options Trade and Quote GTH
  description: Tick-level trades and top-of-book quote updates for Cboe index options (SPX, VIX, XSP,
    RUT families) traded in the overnight Global Trading Hours session. One row per event, with a numeric
    event mask and a text action.
  dataGranularityDescription: one trade or quote event for one index-option contract during the GTH session
    (sample rows are NBBO-flagged firm quotes, Action 'FQ NB')
  properties:
  - name: Date
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Trading date, yyyymmdd. In the GTH sample it is the calendar date of the evening events
      (20230801 with 21:xx times, next-day expiry); behaviour after midnight is not shown.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    partitioned: true
    partitionKeyPosition: 1
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Timestamp
    logicalType: time
    logicalTypeOptions:
      format: HHMMSSmmm
    physicalType: string (HHMMSSmmm) (csv text)
    description: Event time in US Eastern clock time to the millisecond, no date part; keep as text (Excel
      mangles it). Evening rows are 20:00-23:59; early-morning rows run to 09:25.
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: CallPut
    logicalType: string
    logicalTypeOptions:
      format: C | P
    physicalType: string (csv text)
    description: 'Option type: C for call, P for put.'
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    enum:
    - value: C
      label: Call
    - value: P
      label: Put
    customProperties:
    - property: evidence
      value: guide+sample
  - name: StrikePrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Strike price of the contract in dollars (index points for index options), e.g. 4555 or
      202.5.
    primaryKey: true
    primaryKeyPosition: 4
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: evidence
      value: guide+sample
  - name: ExpirationDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Expiration date of the option contract in yyyymmdd.
    primaryKey: true
    primaryKeyPosition: 5
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: EventType
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: string (csv text)
    description: 'Numeric byte mask: bits 0-3 message type, bit 4 cancel, bit 5 call, bit 6 NBBO, bit
      7 buy/bid side. Action is its text form.'
    primaryKey: true
    primaryKeyPosition: 6
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Action
    logicalType: string
    logicalTypeOptions:
      format: space-separated tokens, e.g. 'FQ NB', 'T'
    physicalType: string (csv text)
    description: 'Text form of EventType: message-type token plus NB when the NBBO bit is set (e.g. ''FQ
      NB''). Side is a separate column.'
    enum:
    - value: T
      label: Trade
    - value: C
      label: Trade Cancel
    - value: OI
      label: OpenInterest
    - value: TI
      label: TradeInterest
    - value: FQ
      label: FirmQuote
    - value: NFQ
      label: NonFirmQuote
    - value: R
      label: Rotation
    - value: H
      label: Halted
    - value: NQ
      label: NoQuote
    - value: US
      label: UnderlyingValueSale
    - value: UQ
      label: UnderlyingValueQuote
    - value: I
      label: Indicative Value
    - value: IN
      label: Invalid
    - value: NB
      label: NBBO (shown as '* NB' suffix)
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Side
    logicalType: string
    logicalTypeOptions:
      format: B | A | blank
    physicalType: string (csv text)
    description: 'Side of the book for quote events: B bid, A ask. Blank for trade events.'
    enum:
    - value: B
      label: Bid side of the book
    - value: A
      label: Ask side of the book
    customProperties:
    - property: nullMeaning
      value: Empty for trade events (guide)
    - property: evidence
      value: guide+sample
  - name: Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Trade price for trades; bid or ask price (per Side) for quote events. Option premium
      per underlying unit.
    customProperties:
    - property: unit
      value: USD
    - property: evidence
      value: guide+sample
  - name: Quantity
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: 'Event size: traded size for trades, quote size for quotes. Guide says ''underlying asset
      quantity''; values behave as contract counts.'
    customProperties:
    - property: unit
      value: contracts
    - property: evidence
      value: guide+sample
  - name: Exchange
    logicalType: string
    logicalTypeOptions:
      format: 2-letter code
    physicalType: string (csv text)
    description: Venue code. The guide states all GTH events come from Cboe (CB).
    primaryKey: true
    primaryKeyPosition: 7
    required: true
    enum:
    - value: CB
      label: CBOE
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Conditions
    logicalType: string
    logicalTypeOptions:
      format: single character (space is a valid value)
    physicalType: string (csv text)
    description: Single-character trade condition (Table 4) on trade rows or quote condition (Table 5)
      on quote rows; sample quote rows show 'A' (eligible for automatic execution).
    enum:
    - value: ' '
      label: 'trade SPACE: Regular sale, no stated conditions | quote: Regular trading'
    - value: A
      label: 'trade CANC: Cancel of an earlier report (not the first or last of the day) | quote: Eligible
        for automatic execution'
    - value: B
      label: 'trade OSEQ: Late report, out of sequence | quote: Bid contains customer trading interest'
    - value: C
      label: 'trade CNCL: Cancel of the last reported transaction | quote: Both bid and offer contain
        customer trading interest'
    - value: D
      label: 'trade LATE: Late report, in correct sequence'
    - value: E
      label: 'trade CNCO: Cancel of the opening report although later trades exist'
    - value: F
      label: 'trade OPEN: Late report of the opening trade, out of sequence | quote: Non-firm quote'
    - value: G
      label: 'trade CNOL: Cancel of the only report of the day for the contract'
    - value: H
      label: 'trade OPNL: Late report of the opening trade, in correct sequence'
    - value: I
      label: 'trade AUTO: Executed electronically; informational, treat as regular | quote: Indicative
        value'
    - value: J
      label: 'trade REOP: Reopening after a halt; informational, treat as regular'
    - value: S
      label: 'trade ISOI: Intermarket Sweep Order execution; treat as normal'
    - value: a
      label: 'trade SLAN: Single-leg auction, non-ISO'
    - value: b
      label: 'trade SLAI: Single-leg auction, ISO'
    - value: c
      label: 'trade SLCN: Single-leg cross, non-ISO'
    - value: d
      label: 'trade SCLI: Single-leg cross, ISO'
    - value: e
      label: 'trade SLFT: Single-leg floor trade'
    - value: f
      label: 'trade MLET: Multi-leg electronic trade in complex book'
    - value: g
      label: 'trade MLAT: Multi-leg auction in complex book'
    - value: h
      label: 'trade MLCT: Multi-leg cross'
    - value: i
      label: 'trade MLFT: Multi-leg floor trade against other multi-leg orders'
    - value: j
      label: 'trade MESL: Multi-leg electronic trade against single-leg orders/quotes'
    - value: k
      label: 'trade TLAT: Stock/options multi-leg auction in complex book'
    - value: l
      label: 'trade MASL: Multi-leg auction against single-leg orders/quotes'
    - value: m
      label: 'trade MFSL: Multi-leg floor trade against single-leg orders/quotes'
    - value: n
      label: 'trade TLET: Stock/options multi-leg electronic trade'
    - value: o
      label: 'trade TLCT: Stock/options multi-leg cross'
    - value: p
      label: 'trade TLFT: Stock/options multi-leg floor trade'
    - value: q
      label: 'trade TESL: Stock/options electronic trade against single-leg orders/quotes'
    - value: r
      label: 'trade TASL: Stock/options auction against single-leg orders/quotes'
    - value: s
      label: 'trade TFSL: Stock/options floor trade against single-leg orders/quotes'
    - value: t
      label: 'trade CBMO: Multi-leg floor trade (3+ legs) in proprietary product; price may be outside
        NBBO'
    - value: u
      label: 'trade MCTP: Multilateral compression trade in proprietary product; does not update OHLC'
    - value: v
      label: 'trade EXHT: Extended-hours trade; does not update OHLC'
    - value: R
      label: 'quote: Rotation'
    - value: T
      label: 'quote: Trading halted'
    - value: O
      label: 'quote: Offer contains customer trading interest'
    - value: X
      label: 'quote: Offer side not firm; bid side firm'
    - value: Y
      label: 'quote: Bid side not firm; offer side firm'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol name (underlying/root) per the guide table. Not present in the sample header or
      sample rows.
    customProperties:
    - property: evidence
      value: guide-only
  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:
      - Date
      - Timestamp
      - CallPut
      - StrikePrice
      - ExpirationDate
      - EventType
      - Exchange
    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: history_start
  property: generalAvailability
  value: '2023-01-09'
  description: First trade date of the vendor history.
- 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-equity-opt
- property: vendorDatasetTextId
  value: opt_taq_gth
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/opt_taq_gth.csv
- property: assetClass
  value: option
- property: venues
  value:
  - CB (CBOE)
- property: coverage
  value: 'Index options with a GTH session: guide lists SPX, SPXW, XSP, VIX, VIXW, RUT and RUTW (RUT/RUTW
    added to GTH on 2026-02-09); the product page names SPX, VIX, XSP and RUT. Extended GTH session started
    2021-11-21 (business date 2021-11-22); AlgoSeek coverage starts 2023-01-09. Source is the Cboe GTH
    trade-and-quote data, all events from Cboe (CB).'
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: HHMMSSmmm text, millisecond resolution (e.g. 093101723 = 09:31:01.723); no date component
- property: sessionHours
  value: 20:00:00-09:25:00 ET, starting the evening before the trade date (Sun-Thu evenings through Mon-Fri
    mornings); the morning end was 09:15:00 ET before 2024-08-26. One window is stated for all GTH products;
    guide does not give per-product (SPX/VIX/XSP) times or the regular-session hours for these inde…
- 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 a Ticker column (after Timestamp); the sample header and
    rows have no Ticker, so the underlying/root is not in the row.'
  - 'Doc discrepancy: Guide intro gives the GTH session as 20:00:00-09:15:00 ET, then says it runs until
    09:25 (09:15 before 2024-08-26); product page says 20:00:00-09:25:00. Treated as 09:25 current / 09:15
    historical.'
  - 'Doc discrepancy: Guide labels Date ''Trading date'', but the sample has Date=20230801 on rows stamped
    21:56-21:57 with expiry 20230802; the Date is the calendar date of the evening, not the following
    business date the session belongs to. No after-midnight rows in the sample to show the rollover.'
  - 'Doc discrepancy: Guide file-layout example uses AAPL options on 2020 dates; GTH covers only index
    options from 2023-01-09, so the example is boilerplate from the equity-option guides.'
  - 'Doc discrepancy: Guide says ''one file per option contract per trading day'' but the example consolidates
    all strikes/types of an expiration in one tar file.'
  - 'Doc discrepancy: Guide says the data comes from the OPRA feed; the product page says it is sourced
    from the Cboe GTH trade and quote feed.'
  - 'Doc discrepancy: Guide says quotes are top-of-book bids/asks, but every sample quote row carries
    the NBBO flag (''FQ NB'') and the Exchange is always CB; non-NBBO quote rows are not shown.'
  - 'Doc discrepancy: Guide documents EventType as ''string'' (''Byte code''); sample values are decimal
    integers rendered as text (100, 228).'
  - 'Doc discrepancy: Conditions table in the guide is headed ''Trade Message Types''; the sample''s Conditions
    values are ''A'' on quote rows, which only matches the quote-condition table (eligible for automatic
    execution), not the trade code A (CANC).'
  - 'Doc discrepancy: Guide Table 6 says bits 0-3 are a ''3-bit'' message type, but bits 0-3 are 4 bits
    and Table 7 runs to value 11.'
  - 'Doc discrepancy: Guide Table 7 names message type 10 ''UnderlyingValueSell'' while Table 3 names
    the matching action ''UnderlyingValueSale''.'
  - 'Doc discrepancy: Guide Table 7 has no type 12 (Indicative); Table 3 lists action ''I'' = Indicative
    Value and ''IN'' = Invalid with no message-type value. The AlgoSeek decoder convention assigns 12
    = Indicative.'
  - 'Doc discrepancy: Guide describes Quantity as ''Underlying asset quantity''; sample values (1..3444,
    quote sizes) behave as option contract counts.'
  - 'Doc discrepancy: Guide expands OPRA as ''Options Pricing Authority'' while the product pages say
    ''Options Price Reporting Authority''.'
contractCreatedTs: '2026-11-02T00:00:00Z'