# 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-gth-trade-only
name: AlgoSeek US Options GTH Trade Only
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options
- opra
- us
- tick
description:
  purpose: Tick-level trades in Cboe index options during the overnight Global Trading Hours session,
    each row carrying the NBBO bid and ask (time, price, size, condition) in force when the trade printed.
  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,
    Price and LastBid/AskPrice are plain decimals in dollars/index points (StrikePrice 4580 = SPX 4580),
    not scaled by 1000; the contract multiplier is not in the file. EventType decoding verified on the
    sample: 33 = 32 call + 1 Trade; 1 = put Trade; NBBO bit (64) is clear on trade rows and Side is blank.
    Bit 4 (16) would mark a cancelled prior trade; no cancel rows appear in the sample. LastBid*/LastAsk*
    are the option NBBO in force at the trade; LastBidTime/LastAskTime can equal the trade Timestamp or
    lag it by seconds or minutes (sample shows both). Exchange is CB on every sample row.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-options-gth-trade-only/
  - type: implementation
    url: https://algoseek.com/data-docs/options-market-data/algoseek.US.Options.GTH.Trades.Only.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_TRADES_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 in
      one file; each CSV is gzip-compressed (about 7x expansion). No bucket/path/file-name pattern is
      given. Sample rows span many strikes and both calls and puts of one expiration, i.e. chain-level.'
  - 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_gth_trade_only
  physicalName: opt_trades_gth
  physicalType: file
  logicalType: object
  businessName: US Options GTH Trade Only
  description: Tick-level trades in Cboe index options during the overnight Global Trading Hours session,
    each row carrying the NBBO bid and ask (time, price, size, condition) in force when the trade printed.
  dataGranularityDescription: one executed trade in one index-option contract during GTH, with the last
    NBBO bid/ask snapshot
  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: nullMeaning
      value: unstated (guide marks column optional)
    - 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. '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: H
      label: Halted
    - value: I
      label: Indicative Value
    - value: IN
      label: Invalid
    - value: OI
      label: OpenInterest
    - value: R
      label: Rotation
    - value: T
      label: Trade
    - value: TI
      label: TradeInterest
    - value: UQ
      label: UnderlyingValueQuote
    - value: US
      label: UnderlyingValueSale
    - 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.
    primaryKey: true
    primaryKeyPosition: 8
    required: true
    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.'
    primaryKey: true
    primaryKeyPosition: 9
    required: true
    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 (guide Table 4); sample shows I (AUTO) and f (MLET).
    enum:
    - value: ' '
      label: 'SPACE: Regular sale, no stated conditions'
    - value: A
      label: 'CANC: Cancel of an earlier report (not the first or last of the day)'
    - value: B
      label: 'OSEQ: Late report, out of sequence'
    - value: C
      label: 'CNCL: Cancel of the last reported transaction'
    - value: D
      label: 'LATE: Late report, in correct sequence'
    - value: E
      label: 'CNCO: Cancel of the opening report although later trades exist'
    - value: F
      label: 'OPEN: Late report of the opening trade, out of sequence'
    - value: G
      label: 'CNOL: Cancel of the only report of the day for the contract'
    - value: H
      label: 'OPNL: Late report of the opening trade, in correct sequence'
    - value: I
      label: 'AUTO: Executed electronically; informational, treat as regular'
    - value: J
      label: 'REOP: Reopening after a halt; informational, treat as regular'
    - value: S
      label: 'ISOI: Intermarket Sweep Order execution; treat as normal'
    - value: a
      label: 'SLAN: Single-leg auction, non-ISO'
    - value: b
      label: 'SLAI: Single-leg auction, ISO'
    - value: c
      label: 'SLCN: Single-leg cross, non-ISO'
    - value: d
      label: 'SCLI: Single-leg cross, ISO'
    - value: e
      label: 'SLFT: Single-leg floor trade'
    - value: f
      label: 'MLET: Multi-leg electronic trade in complex book'
    - value: g
      label: 'MLAT: Multi-leg auction in complex book'
    - value: h
      label: 'MLCT: Multi-leg cross'
    - value: i
      label: 'MLFT: Multi-leg floor trade against other multi-leg orders'
    - value: j
      label: 'MESL: Multi-leg electronic trade against single-leg orders/quotes'
    - value: k
      label: 'TLAT: Stock/options multi-leg auction in complex book'
    - value: l
      label: 'MASL: Multi-leg auction against single-leg orders/quotes'
    - value: m
      label: 'MFSL: Multi-leg floor trade against single-leg orders/quotes'
    - value: n
      label: 'TLET: Stock/options multi-leg electronic trade'
    - value: o
      label: 'TLCT: Stock/options multi-leg cross'
    - value: p
      label: 'TLFT: Stock/options multi-leg floor trade'
    - value: q
      label: 'TESL: Stock/options electronic trade against single-leg orders/quotes'
    - value: r
      label: 'TASL: Stock/options auction against single-leg orders/quotes'
    - value: s
      label: 'TFSL: Stock/options floor trade against single-leg orders/quotes'
    - value: t
      label: 'CBMO: Multi-leg floor trade (3+ legs) in proprietary product; price may be outside NBBO'
    - value: u
      label: 'MCTP: Multilateral compression trade in proprietary product; does not update OHLC'
    - value: v
      label: 'EXHT: Extended-hours trade; does not update OHLC'
    customProperties:
    - property: evidence
      value: guide+sample
  - name: LastBidTime
    logicalType: time
    logicalTypeOptions:
      format: HHMMSSmmm
    physicalType: string (HHMMSSmmm) (csv text)
    description: Time of the last option NBBO bid before the trade (ET, ms).
    customProperties:
    - property: evidence
      value: guide+sample
  - name: LastBidPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the last option NBBO bid.
    customProperties:
    - property: unit
      value: USD
    - property: evidence
      value: guide+sample
  - name: LastBidSize
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Size of the last option NBBO bid.
    customProperties:
    - property: unit
      value: contracts
    - property: evidence
      value: guide+sample
  - name: LastBidCondition
    logicalType: string
    logicalTypeOptions:
      format: single character
    physicalType: string (csv text)
    description: Condition code of the last option NBBO bid. Guide has no table for it; sample shows A,
      B, C, O.
    customProperties:
    - property: evidence
      value: guide+sample
  - name: LastAskTime
    logicalType: time
    logicalTypeOptions:
      format: HHMMSSmmm
    physicalType: string (HHMMSSmmm) (csv text)
    description: Time of the last option NBBO ask before the trade (ET, ms).
    customProperties:
    - property: evidence
      value: guide+sample
  - name: LastAskPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the last option NBBO ask.
    customProperties:
    - property: unit
      value: USD
    - property: evidence
      value: guide+sample
  - name: LastAskSize
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Size of the last option NBBO ask.
    customProperties:
    - property: unit
      value: contracts
    - property: evidence
      value: guide+sample
  - name: LastAskCondition
    logicalType: string
    logicalTypeOptions:
      format: single character
    physicalType: string (csv text)
    description: Condition code of the last option NBBO ask. Guide has no table for it; sample shows A,
      B, C, O.
    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
      - Price
      - Quantity
    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: LastAskSize_non_negative
    type: sql
    description: LastAskSize is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE LastAskSize < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: LastBidSize_non_negative
    type: sql
    description: LastBidSize is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE LastBidSize < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - 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_trades_gth
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/opt_trades_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 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.'
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: HHMMSSmmm text, millisecond resolution; no date component (Timestamp, LastBidTime, LastAskTime)
- 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.'
  - 'Doc discrepancy: Guide labels Date ''Trading date (optional)''; the sample has Date=20230801 on trades
    stamped 21:15-21:28 with expiry 20230802, i.e. the calendar date of the evening, not the following
    business date. No after-midnight rows exist in the sample.'
  - '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.'
  - 'Doc discrepancy: Guide says ''one file per option contract per trading day'' but the example (and
    the multi-strike sample) is chain-level.'
  - 'Doc discrepancy: Guide intro says the data is based on top-of-book quotes and trades; the dataset
    only carries trades plus an NBBO snapshot (LastBid*/LastAsk*).'
  - 'Doc discrepancy: Guide has no quote-condition table for LastBidCondition/LastAskCondition (no Table
    5); sample values A, B, C, O match the quote conditions defined in the sibling GTH TAQ guide (A eligible
    for auto execution, B bid customer interest, O offer customer interest, C both).'
  - 'Doc discrepancy: Guide Table 3 (Action) omits C (Trade Cancel), FQ, NFQ and NQ that the TAQ guide
    lists; only T appears in the sample.'
  - 'Doc discrepancy: Guide documents EventType as ''string''; sample values are decimal integers rendered
    as text (1, 33).'
  - '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'