# 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 name: AlgoSeek US Options Trade Only version: 0.1.0 status: draft domain: market-data tags: - algoseek - licensed-data - options - opra - us - tick description: purpose: Tick-level OPRA trades in US equity, ETF, ETN and ADR options, each row carrying the option NBBO in force and the underlying's bid, ask and last trade at execution; used for execution-quality and trade-aggressiveness analysis. 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 within a per-chain file; the root/underlying is NOT in the row (no Ticker, no UnderSymbol, no OSI/OCC symbol) and must be taken from the file name/path. StrikePrice (e.g. 202.5) and Price are plain decimals in dollars per underlying share, 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; 7 = put Halted; 135 = 128 + 7. Bit 4 (16) would mark a cancelled prior trade; no cancel rows appear in the sample, but cancel conditions A, C, E and G exist in Conditions. Halted rows come in pairs at one Timestamp (EventType 7 and 135) with Side blank, Price 0 and Quantity 0; filter on Action = T to get trades only.' authoritativeDefinitions: - type: businessDefinition url: https://algoseek.com/dataset/us-options-trade-only/ - type: implementation url: https://algoseek.com/data-docs/options-market-data/algoseek.US.Options.Trades.Only.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}/ format: csv encoding: UTF-8 customProperties: - property: layout value: 'Plain-text CSV with a fixed header, trade events ordered by time. Guide: one file per options chain (a specific expiration) per trading day; example of all AAPL calls and puts for one expiration on one trading date consolidated in one file; each CSV 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.' - 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/:trade_date/:identifier/:expiration_date 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 physicalName: opt_trades physicalType: file logicalType: object businessName: US Options Trade Only description: Tick-level OPRA trades in US equity, ETF, ETN and ADR options, each row carrying the option NBBO in force and the underlying's bid, ask and last trade at execution; used for execution-quality and trade-aggressiveness analysis. dataGranularityDescription: one executed option trade (plus halt events in the sample) with the last NBBO and underlying snapshot properties: - name: Date logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: Trading date of the event in yyyymmdd; the guide marks the column as optional. 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). Sample rows omit the leading zero before 10:00 (8 digits, e.g. 93000008). 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: integer (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', 'H' 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. Also blank on the Halted rows in the sample.' 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 trade events (0 on halt rows). Some sample cells appear as dd.mm.yy dates (spreadsheet corruption), e.g. 02.03.23 for 2.3. 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: Two-letter code of the options venue that reported the trade or posted the quote (guide Table 2). primaryKey: true primaryKeyPosition: 7 required: true enum: - value: AM label: AMEX - value: AR label: ARCA - value: BA label: BATS - value: BY label: BATS_Y - value: BO label: BOSTON - value: C2 label: C2 - value: CB label: CBOE - value: CS label: CSE - value: EA label: EDGA - value: EX label: EDGX - value: FI label: FINRA - value: IE label: IEX OPTIONS - value: IS label: ISE - value: IG label: ISE_GEMINI - value: IM label: ISE_MERCURY - value: LT label: LTSE - value: MI label: MIAX - value: MP label: MIAX_PEARL - value: ME label: MIAX_EMERALD - value: MS label: MIAX_SAPPHIRE - value: MX label: MEMX - value: M2 label: MX2 OPTIONS - value: NA label: NASDAQ - value: NB label: NASDAQ_BX - value: NP label: NASDAQ_PSX - value: NS label: NSE - value: NY label: NYSE - value: OP label: OPRA - value: SI label: SIAC - value: TH label: THOMSON - value: UN label: UNKNOWN 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); on halt rows the sample shows T, a quote-condition code (trading halted). 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). Sample drops the leading zero before 10:00. customProperties: - property: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - property: evidence value: guide+sample - name: LastBidPrice logicalType: number physicalType: decimal (csv text) description: Price of the last option NBBO bid. Some sample cells are date-mangled (dd.mm.yy). customProperties: - property: unit value: USD - property: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - 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: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - property: evidence value: guide+sample - name: LastBidCondition logicalType: string logicalTypeOptions: format: single character (space and '*' occur) physicalType: string (csv text) description: Condition of the last option NBBO bid. No guide table; sample shows space, *, A, B. customProperties: - property: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - 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). Sample drops the leading zero before 10:00. customProperties: - property: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - property: evidence value: guide+sample - name: LastAskPrice logicalType: number physicalType: decimal (csv text) description: Price of the last option NBBO ask. Some sample cells are date-mangled (dd.mm.yy). customProperties: - property: unit value: USD - property: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - 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: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - property: evidence value: guide+sample - name: LastAskCondition logicalType: string logicalTypeOptions: format: single character (space and '*' occur) physicalType: string (csv text) description: Condition of the last option NBBO ask. No guide table; sample shows space, *, A, B, O, Y. customProperties: - property: nullMeaning value: 'unstated (sample: blank when no prior NBBO)' - property: evidence value: guide+sample - name: UnderBidPrice logicalType: number physicalType: decimal (csv text) description: Bid price of the underlying security at the trade. Can exceed UnderAskPrice (crossed) in the sample. customProperties: - property: unit value: USD - property: evidence value: guide+sample - name: UnderAskPrice logicalType: number physicalType: decimal (csv text) description: Ask price of the underlying security at the trade. customProperties: - property: unit value: USD - property: evidence value: guide+sample - name: UnderLastTradeTime logicalType: time logicalTypeOptions: format: HHMMSSmmmuuunnn (15 digits, ns); sample drops the leading zero before 10:00 physicalType: string (HHMMSSmmmuuunnn) (csv text) description: Time of the underlying's last trade at nanosecond resolution (ET). customProperties: - property: evidence value: guide+sample - name: UnderLastTradePrice logicalType: number physicalType: decimal (csv text) description: Price of the underlying's last trade. customProperties: - property: unit value: USD - property: evidence value: guide+sample - name: UnderLastTradeSize logicalType: integer logicalTypeOptions: format: i64 physicalType: integer (csv text) description: Size of the underlying's last trade (shares inferred from values such as 100, 42). customProperties: - property: unit value: shares - 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 - 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 - id: UnderLastTradeSize_non_negative type: sql description: UnderLastTradeSize is never negative. query: SELECT COUNT(*) FROM {object} WHERE UnderLastTradeSize < 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-equity-opt - property: vendorDatasetTextId value: opt_trades - property: vendorSampleUrl value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/opt_trades.csv - property: assetClass value: option - property: venues value: - AM (AMEX) - AR (ARCA) - BA (BATS) - BY (BATS_Y) - BO (BOSTON) - C2 (C2) - CB (CBOE) - CS (CSE) - EA (EDGA) - EX (EDGX) - FI (FINRA) - IE (IEX OPTIONS) - IS (ISE) - IG (ISE_GEMINI) - IM (ISE_MERCURY) - LT (LTSE) - MI (MIAX) - MP (MIAX_PEARL) - ME (MIAX_EMERALD) - MS (MIAX_SAPPHIRE) - MX (MEMX) - M2 (MX2 OPTIONS) - NA (NASDAQ) - NB (NASDAQ_BX) - NP (NASDAQ_PSX) - NS (NSE) - NY (NYSE) - OP (OPRA) - SI (SIAC) - TH (THOMSON) - UN (UNKNOWN) - property: coverage value: All trades from the consolidated OPRA feed for options on equities, ETFs, ETNs and ADRs across the 16 SEC-approved options exchanges; the product page says all US equity options exchanges reporting via OPRA. Start date not stated. - property: timezone value: America/New_York - property: timestampFormat value: Option times HHMMSSmmm (ms, text); underlying last-trade time HHMMSSmmmuuunnn (ns, 15 digits). The sample strips leading zeros before 10:00. - property: sessionHours value: 09:30:00-16:15:00 ET - 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: Neither the guide nor the sample has a Ticker/root column: the underlying of each row is only implied by the file, so rows are not self-describing.' - 'Doc discrepancy: Guide field table orders EventType, Side, Action; the sample header orders EventType, Action, Side.' - 'Doc discrepancy: Guide types EventType as ''integer'' (other options guides say ''string''); sample values are plain decimal integers.' - 'Doc discrepancy: Guide Timestamp is HHMMSSmmm (9 characters); sample Timestamp and LastBid/AskTime values lack the leading zero before 10:00 (e.g. 93000008), and UnderLastTradeTime has 14 digits instead of 15 (e.g. 92959996516310), so they were evidently stored as numbers.' - 'Doc discrepancy: 54 cells in the published sample CSV and JSON preview are date-mangled prices in dd.mm.yy form (Price 15, LastBidPrice 20, LastAskPrice 19), e.g. 02.03.23 for 2.3 and 06.06.23 for 6.6; the true format is plain decimal.' - 'Doc discrepancy: Sample includes Halted rows (EventType 7 and 135, Action ''H'', Price 0, Quantity 0, Conditions ''T''); the guide and page describe the dataset as trades only.' - 'Doc discrepancy: Guide has no quote-condition table for LastBidCondition/LastAskCondition; sample shows space, *, A, B, O, Y (A/B/O/Y match the quote conditions defined in sibling guides) and ''*'' is undocumented anywhere.' - 'Doc discrepancy: Guide intro says 16 options exchanges, but Table 2 lists 31 codes including FINRA, OPRA, SIAC, THOMSON and UNKNOWN.' - 'Doc discrepancy: The catalog page title reads ''US Options Trade Only Minute Bar Data'' although the dataset is tick-level.' - 'Doc discrepancy: First sample row has blank LastBid*/LastAsk* fields (no NBBO yet); the guide does not describe missing-value behaviour.' - 'Doc discrepancy: Underlying bid can exceed the underlying ask in the sample (9 of 100 rows), so UnderBidPrice/UnderAskPrice are not guaranteed to be an uncrossed quote.' - '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'