# 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-equities-trade-and-quote
name: AlgoSeek US Equities Trade and Quote
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- us
- tick
description:
  purpose: 'One row is one consolidated-feed (SIP) event for a US-listed equity: a venue or NBBO bid/ask
    quote update, a trade, or a trade cancellation, stamped to the nanosecond with venue and condition
    flags. Used to replay the order-of-arrival market state for microstructure research and backtests.'
  usage: Backtesting, execution and microstructure research, feature engineering for US equities.
  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. Sample
    channel: S3 CSV (sample_channel s3/cloud_storage, eq_taq.csv, 100 rows, AAPL on 2023-08-02); this
    dataset has no ArdaDB table sample. The JSON preview is identical to the CSV. Closed EventType set
    per guide Table 3: QUOTE BID, QUOTE BID NB, QUOTE ASK, QUOTE ASK NB, TRADE, TRADE NB, TRADE CANCELLED,
    TRADE NB CANCELLED; the 100-row sample contains only the first six. Do not sum quote sizes across
    NB and non-NB rows: an NB row repeats a quote already published by the originating exchange. TRADE
    NB is a trade at or within the NBBO; the guide recommends TRADE NB for backtesting. Trades away from
    the NBBO include some FINRA TRF reports, late reports, extended-hours trades (no NBBO pre/post), ISO
    orders and other trade-through exemptions.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-trade-and-quote/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-market-data/algoseek.US.Equity.TAQ.pdf
  - type: implementation
    url: https://algoseek.com/docs/rest-api/reference
context:
  instructions: Times are local US Eastern clock times (DST-aware), not UTC. Treat TRADE NB / NBBO-flagged
    rows as the backtest-grade subset. Cancellations reference earlier trades and can arrive hours later,
    so aggregate only after the session closes. Prices are unadjusted unless the dataset name says Adjusted;
    join us-equities-*-adjustment-factors on SecId for adjustment.
  verifiedStatements:
  - id: vs1
    question: What time zone are the timestamps in?
    answer: US Eastern local time with daylight saving (the guides label it EST/ET).
  - id: vs2
    question: Are prices adjusted for splits and dividends?
    answer: Only in datasets whose name contains Adjusted; all others are as traded.
  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_EQ_TAQ}/
  format: csv
  encoding: UTF-8
  customProperties:
  - property: layout
    value: Plain-text CSV with a fixed header row; by default one file per symbol per trading day (all
      events for e.g. AAPL on one date in one file); gzip-compressed (.csv.gz, ~8:1). The guide gives
      no bucket/key path for the data files; only the calendar files s3://us-equity-market-holidays/holidays.csv
      and earlycloses.csv are named.
  - 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/taq/:trade_date/: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_equities_trade_and_quote
  physicalName: eq_taq
  physicalType: file
  logicalType: object
  businessName: US Equities Trade and Quote
  description: 'One row is one consolidated-feed (SIP) event for a US-listed equity: a venue or NBBO bid/ask
    quote update, a trade, or a trade cancellation, stamped to the nanosecond with venue and condition
    flags. Used to replay the order-of-arrival market state for microstructure research and backtests.'
  dataGranularityDescription: one trade, trade cancellation, or top-of-book quote (bid or ask, venue-level
    or NBBO-creating) event for one ticker, in receive-time order
  properties:
  - name: Date
    logicalType: date
    logicalTypeOptions:
      format: yyyymmdd
    physicalType: string (yyyymmdd) (csv text)
    description: Trading date of the event, written yyyymmdd.
    primaryKey: true
    primaryKeyPosition: 1
    required: true
    partitioned: true
    partitionKeyPosition: 1
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Timestamp
    logicalType: time
    logicalTypeOptions:
      format: HH:MM:SS.mmmuuunnn (ns) from 2016; HH:MM:SS.mmm (ms) before 2016
    physicalType: string (HH:MM:SS.mmm or HH:MM:SS.mmmuuunnn) (csv text)
    description: 'Event time of day in US Eastern: nanosecond precision from 2016, millisecond before.
      Import as text, not an Excel time.'
    primaryKey: true
    primaryKeyPosition: 3
    required: true
    customProperties:
    - property: evidence
      value: guide+sample
  - name: EventType
    logicalType: string
    physicalType: string (csv text)
    description: 'Kind of event: venue or NBBO-creating bid/ask quote, trade, or a trade cancellation.'
    primaryKey: true
    primaryKeyPosition: 4
    required: true
    enum:
    - value: QUOTE BID
      label: an exchange's best bid changed (change in a market center's best bid)
    - value: QUOTE BID NB
      label: bid from an exchange that creates a new best bid in the NBBO; repeats a row already published
        for that exchange
    - value: QUOTE ASK
      label: an exchange's best ask changed (change in a market center's best ask)
    - value: QUOTE ASK NB
      label: ask from an exchange that creates a new best ask in the NBBO; repeats a row already published
        for that exchange
    - value: TRADE
      label: trade at an exchange or reported to a market center
    - value: TRADE NB
      label: trade at or within the NBBO
    - value: TRADE CANCELLED
      label: cancellation of an earlier trade (reduces traded volume by its quantity); a correction is
        a cancellation followed by the corrected trade
    - value: TRADE NB CANCELLED
      label: cancellation of an earlier NBBO trade
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Ticker
    logicalType: string
    physicalType: string (csv text)
    description: Symbol name of the security.
    primaryKey: true
    primaryKeyPosition: 2
    required: true
    partitioned: true
    partitionKeyPosition: 2
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Price
    logicalType: number
    physicalType: decimal (csv text)
    description: Price of the bid, ask or trade; up to 4 decimals for sub-penny prices; 0.00 on zero-quote
      closing events.
    customProperties:
    - property: unit
      value: USD
    - property: evidence
      value: guide+sample
  - name: Quantity
    logicalType: integer
    logicalTypeOptions:
      format: i64
    physicalType: integer (csv text)
    description: Number of shares in the quote or trade; can be 0 for some event types (e.g. zero closing
      quotes).
    customProperties:
    - property: unit
      value: shares
    - property: evidence
      value: guide+sample
  - name: Exchange
    logicalType: string
    physicalType: string (csv text)
    description: Exchange or reporting venue that produced the event, as an algoseek venue code.
    primaryKey: true
    primaryKeyPosition: 5
    required: true
    enum:
    - value: NYSE
      label: New York Stock Exchange LLC (SIP id N)
    - value: ARCA
      label: NYSE Arca, Inc. (P)
    - value: AMEX
      label: NYSE American, LLC (A)
    - value: NSE
      label: NYSE National, Inc. (C)
    - value: CSE
      label: NYSE Chicago, Inc. (M)
    - value: Nasdaq
      label: Nasdaq, Inc. (T via CTS / Q via UTP); sample files spell it NASDAQ
    - value: Nasdaq BX
      label: Nasdaq BX, Inc. (B); sample files spell it NASDAQ BX
    - value: NASDAQ PSX
      label: Nasdaq PHLX LLC (X)
    - value: ISE
      label: Nasdaq ISE, LLC (I)
    - value: CBOE
      label: Cboe Exchange, Inc. (W)
    - value: BATS Y
      label: Cboe BYX Exchange, Inc. (Y)
    - value: BATS
      label: Cboe BZX Exchange, Inc. (Z)
    - value: EDGA
      label: Cboe EDGA Exchange, Inc. (J)
    - value: EDGX
      label: Cboe EDGX Exchange, Inc. (K)
    - value: IEX
      label: Investors' Exchange LLC (V)
    - value: LTSE
      label: Long-Term Stock Exchange (L)
    - value: MIAX
      label: MIAX Pearl, LLC (H); sample files spell it MIAX PEARL
    - value: MEMX
      label: MEMX LLC, Members Exchange (U)
    - value: FINRA
      label: Financial Industry Regulatory Authority trade reporting facilities, i.e. off-exchange trades
        (D)
    - value: NE24X
      label: 24X National Exchange (G)
    - value: TXSE
      label: Texas Stock Exchange (F)
    - value: UNKNOWN
      label: Unknown venue
    - value: INVALID
      label: Invalid venue
    customProperties:
    - property: evidence
      value: guide+sample
  - name: Conditions
    logicalType: string
    logicalTypeOptions:
      format: hex uint32 bitmask, lower-case, no 0x prefix; guide examples zero-padded to 8 chars, sample
        drops leading zeros
    physicalType: hexadecimal (base 16) (csv text)
    description: Bitmask of sale-condition flags (trades) or quote-condition flags (quotes), as base-16
      text.
    customProperties:
    - 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
      - Ticker
      - Timestamp
      - 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
  - id: conditions_hex_uint32
    metric: invalidValues
    arguments:
      pattern: ^[0-9A-Fa-f]{1,8}$
    mustBe: 0
    dimension: conformity
    severity: error
    description: Conditions is a hex uint32 bit mask without a 0x prefix. The guide shows 8 zero-padded
      characters; delivered files use lower case and drop leading zeros (e.g. 401, a0000021).
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
- property: vendorDatasetTextId
  value: eq_taq
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_taq.csv
- property: assetClass
  value: equity
- property: venues
  value:
  - NYSE
  - ARCA
  - AMEX
  - NSE
  - CSE
  - Nasdaq
  - Nasdaq BX
  - NASDAQ PSX
  - ISE
  - CBOE
  - BATS Y
  - BATS
  - EDGA
  - EDGX
  - IEX
  - LTSE
  - MIAX
  - MEMX
  - FINRA
  - NE24X
  - TXSE
  - UNKNOWN
  - INVALID
- property: coverage
  value: All trades and level-1 bid/ask quotes from the SIP consolidated feed (CTA Tape A/B and UTP Tape
    C) for listed stocks, ETNs, ETFs, ADRs and funds, from 15+ US exchanges and marketplaces (Table 6
    lists 21 venues incl. FINRA, plus UNKNOWN/INVALID). History start is not stated; nanosecond timestamps
    start in 2016, millisecond before.
- property: timezone
  value: America/New_York
- property: timestampFormat
  value: HH:MM:SS.mmmuuunnn (9-digit fractional seconds, ns) from 2016; HH:MM:SS.mmm (ms) before 2016
- property: sessionHours
  value: '04:00-20:00 ET: pre-market 04:00:00-09:29:59, regular 09:30:00-16:00:00, post-market 16:00:01-20:00:00;
    events are occasionally recorded several minutes after 20:00; early close at 13:00 ET on some pre-holiday
    days'
- 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.
  - 'Doc discrepancy: Conditions width/case: guide Appendix A says flags are eight-character hex and Tables
    1/4/5 print them zero-padded (00000001, 80000401); the CSV sample prints lower-case hex with leading
    zeros dropped (value lengths 1, 3, 7, 8 such as ''1'', ''401'', ''4000001'', ''a0000021'').'
  - 'Doc discrepancy: Exchange spelling: guide Table 6 values ''Nasdaq'', ''Nasdaq BX'', ''MIAX'' appear
    in the sample as ''NASDAQ'', ''NASDAQ BX'', ''MIAX PEARL''; the guide itself mixes case (''Nasdaq''
    vs ''NASDAQ PSX'').'
  - 'Doc discrepancy: Guide text before Table 6 says ''19 SIP Market Center IDs (including FINRA)'' but
    the table lists 21 venues plus UNKNOWN and INVALID; the intro says ''15+ exchanges''.'
  - 'Doc discrepancy: Time zone is labelled ''EST'' in the guide although the 04:00-20:00 session and
    09:30/16:00 market hours are local Eastern clock times; DST handling is not stated.'
  - 'Doc discrepancy: Guide Table 2 has no ''Missing'' column (other algoseek guides do), so null/empty
    behaviour per field is undocumented; the 100-row sample has no empty cells.'
  - 'Doc discrepancy: NBBO paragraph describes a ''crossed NBBO (e.g. the Bid = Offer)''; Bid = Offer
    is a locked market, crossed means bid > offer (the Daily TAQ guide defines both correctly).'
  - 'Doc discrepancy: Trade Only guide Table 3 defines TRADE NB as a trade ''at national best price''
    and omits TRADE NB CANCELLED; this guide defines TRADE NB as at or within the NBBO and lists TRADE
    NB CANCELLED.'
  - 'Doc discrepancy: No history start date is given in the guide or on the product page; the sample covers
    one session slice (AAPL, 2023-08-02, from 09:30:00.000815872).'
contractCreatedTs: '2026-11-02T00:00:00Z'