# 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-only
name: AlgoSeek US Equities Trade Only
version: 0.1.0
status: draft
domain: market-data
tags:
- algoseek
- licensed-data
- equity
- us
- tick
description:
  purpose: One row is one trade (or trade cancellation) printed on the SIP consolidated tape for a US-listed
    equity, with price, size, venue and sale-condition flags but no quotes. Used for execution, volume
    and trade-signal studies.
  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_trades.csv, 100 rows, AAPL on 2023-08-02); no
    ArdaDB table sample for this dataset. The JSON preview is identical to the CSV. Documented EventType
    set: TRADE, TRADE NB, TRADE CANCELLED. Treat TRADE NB CANCELLED as an open question (documented only
    in the TAQ guide) before making the set strictly closed. TRADE NB is the trade type the guide recommends
    for backtesting; TRADE rows not at the NBBO include some FINRA TRF reports, late reports, extended-hours
    trades (no NBBO pre/post), ISO orders and trade-through exemptions. Cancellations reduce traded volume
    by their Quantity, may arrive hours after the original trade and are not adjacent to it; a correction
    is a cancellation followed by the corrected trade. Consumers computing volume must net them out.'
  authoritativeDefinitions:
  - type: businessDefinition
    url: https://algoseek.com/dataset/us-equities-trade-only/
  - type: implementation
    url: https://algoseek.com/data-docs/equity-market-data/algoseek.US.Equity.Trades.Only.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_TRADES}/
  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; 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/trades/: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_only
  physicalName: eq_trades
  physicalType: file
  logicalType: object
  businessName: US Equities Trade Only
  description: One row is one trade (or trade cancellation) printed on the SIP consolidated tape for a
    US-listed equity, with price, size, venue and sale-condition flags but no quotes. Used for execution,
    volume and trade-signal studies.
  dataGranularityDescription: one trade or trade-cancellation 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 trade, 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: 'Trade 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: a trade, a trade at the NBBO, or a trade cancellation.'
    primaryKey: true
    primaryKeyPosition: 4
    required: true
    enum:
    - value: TRADE
      label: trade at the exchange or reported to the market center
    - value: TRADE NB
      label: trade at national best price (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
    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: Trade price; up to 4 decimals for sub-penny prices.
    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 traded; the guide notes it can be 0 for some event types.
    customProperties:
    - property: unit
      value: shares
    - property: evidence
      value: guide+sample
  - name: Exchange
    logicalType: string
    physicalType: string (csv text)
    description: Exchange or reporting venue (algoseek venue code); FINRA marks off-exchange TRF reports.
    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 that apply to the trade, 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_trades
- property: vendorSampleUrl
  value: https://as-metadata-services-assets.s3.amazonaws.com/sample_data/cloud_storage/eq_trades.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 on all US public equity exchanges plus off-exchange trades reported to FINRA TRFs,
    for listed stocks, ETNs, ETFs, ADRs and funds from 15+ exchanges and marketplaces, across the full
    04:00-20:00 ET session; no quotes. History start is not stated; nanosecond timestamps from 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 Table
    1 prints them as 8 characters (80000401, a0000421); the CSV sample prints lower-case hex with leading
    zeros dropped (value lengths 1, 3, 7, 8 such as ''1'', ''401'', ''4000001'').'
  - 'Doc discrepancy: Exchange spelling: guide Table 4 values ''Nasdaq'', ''Nasdaq BX'', ''MIAX'' appear
    in the sample as ''NASDAQ'', ''NASDAQ BX'', ''MIAX PEARL''.'
  - 'Doc discrepancy: Guide text before Table 4 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: EventType: guide Table 3 documents three values (TRADE, TRADE NB, TRADE CANCELLED);
    the TAQ guide also documents TRADE NB CANCELLED. Whether this dataset can emit it is unstated; the
    sample has only TRADE and TRADE NB.'
  - 'Doc discrepancy: TRADE NB is ''trade at national best price'' in Table 3 and ''a trade at the National
    Best Bid Offer'' in the NBBO paragraph; the TAQ guide says ''at or within the NBBO''.'
  - 'Doc discrepancy: Time zone is labelled ''EST'' while session times are local Eastern clock times;
    DST handling is not stated.'
  - 'Doc discrepancy: Guide Table 2 has no ''Missing'' column, so null/empty behaviour is undocumented;
    the 100-row sample has no empty cells.'
  - 'Doc discrepancy: No history start date is given in the guide or on the product page; the sample is
    one slice (AAPL, 2023-08-02, 09:30:00.014-09:30:00.657).'
contractCreatedTs: '2026-11-02T00:00:00Z'