# 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-nbbo-quote name: AlgoSeek US Options Trade and NBBO Quote version: 0.1.0 status: draft domain: market-data tags: - algoseek - licensed-data - options - opra - us - tick description: purpose: Tick-level OPRA option trades plus NBBO-flagged quote updates (other quote updates removed) for US equity, ETF, ETN and ADR options, each row carrying the underlying's bid and ask. 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-contract (or per-expiration TAR) file; the root/underlying is NOT in the row (no Ticker, no OSI/OCC symbol) and must be taken from the file name/path. StrikePrice and Price are plain decimals in dollars per underlying share (strike 200, price 3.8), not scaled by 1000; the contract multiplier is not in the file. EventType decoding verified on the sample: 100 = 64 NBBO + 32 call + 4 FirmQuote (ask); 228 adds buy side 128 (bid); 38 = 32 call + 6 Rotation; 166 = 128 + 38; 33 = 32 call + 1 Trade. Bit 4 (16) marks a cancelled prior trade/quote; no cancel rows appear in the sample. Action ''FQ NB'' = FirmQuote with NBBO flag; quotes are one row per side (228 bid, 100 ask). The Exchange on an NBBO row is the venue posting that best price; many exchanges can post at the same millisecond.' authoritativeDefinitions: - type: businessDefinition url: https://algoseek.com/dataset/us-options-trade-and-nbbo-quote/ - type: implementation url: https://algoseek.com/data-docs/options-market-data/algoseek.US.Options.TANQ.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_TANQ}/ format: csv encoding: UTF-8 customProperties: - property: layout value: 'Plain-text CSV with a fixed header, events ordered by time. Guide: one file per option contract per trading day (example: AAPL call at the 325 strike expiring 2020-03-03, trading date 2020-02-27, in one file); each CSV gzip-compressed (about 7x expansion), and contracts of the same expiration are bundled into one TAR file. No bucket/path/file-name pattern is given. Sample rows are a single contract.' - 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/tanq/: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_and_nbbo_quote physicalName: opt_tanq physicalType: file logicalType: object businessName: US Options Trade and NBBO Quote description: Tick-level OPRA option trades plus NBBO-flagged quote updates (other quote updates removed) for US equity, ETF, ETN and ADR options, each row carrying the underlying's bid and ask. dataGranularityDescription: one trade, NBBO quote update or other OPRA event (rotation in sample) for one option contract, with underlying bid/ask properties: - name: Date logicalType: date logicalTypeOptions: format: yyyymmdd physicalType: string (yyyymmdd) (csv text) description: Trading date of the event in yyyymmdd. 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). 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', 'R' 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. Rotation rows in the sample also carry a side.' 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: 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: Trade condition (Table 4) on trade rows; quote condition (Table 5) on quote/rotation rows. Sample also shows '*' on 19 NBBO quote rows, which no table defines. 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: UnderBidPrice logicalType: number physicalType: decimal (csv text) description: Bid price of the underlying security at the event. 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 event. customProperties: - property: unit value: USD - 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 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: 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_tanq - property: vendorSampleUrl value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/opt_tanq.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: Options on equities, ETFs, ETNs and ADRs from the 16 SEC-approved options exchanges via OPRA; guide also mentions a curb session for a list of index options. Page says supplementary open-interest and end-of-day summary events are included. Start date not stated. - 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: 09:30:00-16:15:00 ET, plus a curb session 16:15:00-17:00:00 ET for a list of index options - 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 documents EventType as ''string''; sample values are decimal integers rendered as text.' - 'Doc discrepancy: Guide says quotes other than NBBO are filtered out, but the sample contains Rotation rows (EventType 38 and 166, Action ''R'') that carry no NBBO flag.' - 'Doc discrepancy: Guide intro calls the output ''bars'' ordered by time although rows are individual events.' - 'Doc discrepancy: Page says open-interest and end-of-day summary events are included; no such rows appear in the 100-row sample (Action values seen: FQ NB, R, T).' - 'Doc discrepancy: Sample Conditions contains ''*'' on 19 NBBO quote rows; no guide table defines ''*'' (Table 5 defines space, F, I, R, T, A, B, O, C, X, Y).' - 'Doc discrepancy: Guide says one file per option contract per trading day, then says contracts of an expiration are bundled in one TAR file; the sample is one contract (CallPut C, strike 200, expiry 20230908).' - 'Doc discrepancy: Intro describes a curb session 16:15:00-17:00:00 for a list of index options but gives no list of the symbols.' - 'Doc discrepancy: Underlying bid exceeds underlying ask in 4 of 100 sample rows (e.g. 195.08 vs 195.07), so the Under* pair is not guaranteed uncrossed.' - 'Doc discrepancy: Guide intro says 16 options exchanges, but Table 2 lists 31 codes including FINRA, OPRA, SIAC, THOMSON and UNKNOWN.' - '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'