# 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-only-minute-bar
name: AlgoSeek US Options Trade Only Minute Bar
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- options
- opra
- us
- bar
description:
  purpose: One row per option contract per one-minute interval that had at least one trade, with trade
    open/high/low/close, VWAP, volume, trade count and the underlying's NBBO bid/ask at the first and
    last trade. Built from OPRA consolidated trades; no option quotes are included.
  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 = Ticker + CallPut + Strike + ExpirationDate (no OSI/OCC symbol, no contract id).
    Strike is USD per share, 4 decimals in sample; ExpirationDate yyyymmdd. Trade-driven bars: a bar is
    created only when at least one trade occurred; no bar means no trade. With a single trade, open =
    high = low = close. Trades with condition codes A, B, C, F, G, N, O, T are excluded (previously reported,
    late/out of sequence, canceled, late opening, single-report-to-cancel, floor-agreed price, canceled
    stopped, benchmark). Bar window: minute 11:04 covers times greater than 11:04:00 and less than 11:05:00.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-options-trade-only-minute-bar/
  - type: implementation
    url: https://algoseek.com/data-docs/options-market-data/algoseek.US.Options.Trades.Only.Minute.Bars.pdf
  - type: implementation
    url: https://algoseek.com/docs/rest-api/reference
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_1MIN}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Plain-text CSV with fixed header, gzip-compressed (uncompressed about 7x larger). One file
      per underlying ticker per trading day per option chain (ticker + expiration date). Bars ordered
      by time. Bucket/path naming not stated.
  - 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-equity-opt/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_options_trade_only_minute_bar
  physicalName: opt_trades_1min
  physicalType: file
  logicalType: object
  businessName: US Options Trade Only Minute Bar
  description: One row per option contract per one-minute interval that had at least one trade, with trade
    open/high/low/close, VWAP, volume, trade count and the underlying's NBBO bid/ask at the first and
    last trade. Built from OPRA consolidated trades; no option quotes are included.
  dataGranularityDescription: one option contract (Ticker x CallPut x Strike x ExpirationDate) x one 1-minute
    bar (TimeBarStart) on one trading Date; a row exists only if there was at least one trade in that
    minute
  properties:
  - name: Date
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Trading date of the bar
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    partitioned: true
    partitionKeyPosition: 1
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: TimeBarStart
    logicalType: time
    logicalTypeOptions:
      format: HH:MM:SS
    physicalType: string (time) (csv text)
    description: Start of the one-minute bar; guide says HHMM, sample delivers HH:MM:SS (09:30:00)
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol name; sample shows the underlying/root (AAPL). Root vs underlying for index or
      adjusted roots is not stated
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    partitioned: true
    partitionKeyPosition: 2
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: CallPut
    logicalType: string
    physicalType: string (csv text)
    description: Option type, C = Call or P = Put
    primaryKey: true
    primaryKeyPosition: 4
    required: true
    enum:
    - value: C
      label: Call
    - value: P
      label: Put
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Strike
    logicalType: number
    physicalType: decimal (csv text)
    description: Fixed price at which the option can be exercised, quoted per share of underlying
    primaryKey: true
    primaryKeyPosition: 5
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: ExpirationDate
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Expiration date of the option contract
    primaryKey: true
    primaryKeyPosition: 6
    required: true
    customProperties:
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: OpenTradePrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the first trade in the bar
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: HighTradePrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the highest trade in the bar
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: LowTradePrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the lowest trade in the bar
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: CloseTradePrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the last trade in the bar
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Blank
    - property: evidence
      value: guide+sample
  - name: UnderOpenBidPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Underlying NBBO bid at the time of the opening trade (Table 3); Table 2 says first option
      event
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderOpenAskPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Underlying NBBO ask at the time of the opening trade (Table 3); Table 2 says first option
      event
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderCloseBidPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Underlying NBBO bid at the time of the closing trade (Table 3); Table 2 says last option
      event
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: UnderCloseAskPrice
    logicalType: number
    physicalType: decimal (csv text)
    description: Underlying NBBO ask at the time of the closing trade (Table 3); Table 2 says last option
      event
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: VWAP
    logicalType: number
    physicalType: decimal (csv text)
    description: Volume-weighted average trade price in the bar
    required: true
    customProperties:
    - property: unit
      value: USD
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: Volume
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Total contracts traded in the bar
    required: true
    customProperties:
    - property: unit
      value: contracts
    - property: nullMeaning
      value: Never
    - property: evidence
      value: guide+sample
  - name: TotalTrades
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Total number of trades in the bar
    required: true
    customProperties:
    - property: unit
      value: count
    - property: nullMeaning
      value: Never
    - 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:
      - Date
      - TimeBarStart
      - Ticker
      - CallPut
      - Strike
      - ExpirationDate
    dimension: uniqueness
    severity: error
    description: The declared primary key is unique within each delivered partition (one file or table
      snapshot).
  - id: trade_high_ge_low
    type: sql
    description: HighTradePrice is never below LowTradePrice in the same row.
    query: SELECT COUNT(*) FROM {object} WHERE HighTradePrice IS NOT NULL AND LowTradePrice IS NOT NULL
      AND HighTradePrice < LowTradePrice
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: TotalTrades_non_negative
    type: sql
    description: TotalTrades is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE TotalTrades < 0
    mustBe: 0
    dimension: accuracy
    severity: error
  - id: Volume_non_negative
    type: sql
    description: Volume is never negative.
    query: SELECT COUNT(*) FROM {object} WHERE Volume < 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: 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_1min
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/opt_trades_1min.csv
- property: assetClass
  value: option
- property: venues
  value:
  - OPRA consolidated feed (16 options exchanges; individual venues not named)
- property: coverage
  value: US listed options from the OPRA consolidated feed (16 options exchanges); guide intro names options
    on equities, ETFs, ETNs and ADRs; page says all US equity options exchanges reporting via OPRA. History
    start date is not stated.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: TimeBarStart HH:MM:SS in sample (guide says HHMM for minute bars, HHMMSS for second bars); no
    sub-minute event times are delivered
- property: sessionHours
  value: 09:30:00-16:15:00 ET per guide (most options stop at 16:00, some index options trade to 16:15).
    No Curb-session statement.
- property: priceAdjustment
  value: unadjusted
- property: licensedData
  value: true
- property: evidenceGrade
  value: vendor-doc
- property: knownIssues
  value:
  - Primary key is inferred; AlgoSeek's guide does not name one.
  - Update cadence and publication latency are not stated in the guide; confirm with AlgoSeek (or GET
    /v1/meta/datasets/{id}/status).
  - 'Doc discrepancy: TimeBarStart: guide says HHMM for minute bars (HHMMSS for second bars); the sample
    delivers HH:MM:SS (''09:30:00'') in all rows.'
  - 'Doc discrepancy: Under* fields are described twice: Table 2 says underlying NBBO at the first/last
    option bid, ask or trade event, while Table 3 says at the time of OpenTradePrice / CloseTradePrice.
    Sample comparison with the TAQ minute bar for the same contract and minute (195 put, 09:30) gives
    different underlying quotes (195.11/195.14 here vs 194.98/195.10), supporting the Table 3 reading
    (tak…'
  - 'Doc discrepancy: Guide Table 3 shows Missing = Blank for the four trade-price fields, yet a bar exists
    only when a trade occurred, so in practice they are always present; the sample has no blanks.'
  - 'Doc discrepancy: Guide intro describes the feed as built from quotes and trades, but the dataset
    contains trade-derived fields only.'
  - 'Doc discrepancy: Guide says ''EST'' for the session while the other options guides say ''ET''.'
  - 'Doc discrepancy: Guide Bar Notes mention second-bar examples (130302) although this dataset is minute
    bars only.'
  - 'Doc discrepancy: Guide columns match the 17-column sample header exactly, in the same order.'
contractCreatedTs: '2026-11-02T00:00:00Z'