0xArchive Data Quality API

openapi: 3.2.0
info:
  title: 0xArchive Data Quality API
  description: REST API for current and historical market data from Hyperliquid and Lighter. Hyperliquid coverage includes core perpetuals, Spot, HIP-3 builder perpetuals, and HIP-4 outcome markets. Coverage and access requirements vary by route. See https://docs.0xarchive.io/ for authentication, limits, and examples.
  version: 1.6.1
  termsOfService: https://0xarchive.io/terms
  contact:
    name: 0xArchive Support
    url: https://0xarchive.io
    email: support@0xarchive.io
  license:
    name: Proprietary
    url: https://0xarchive.io/terms
servers:
- url: https://api.0xarchive.io
  description: Production API
security:
- ApiKeyAuth: []
tags:
- name: Data Quality
  description: 'Data quality monitoring: system status, coverage, incidents, latency, and SLA metrics.'
paths:
  /v1/data-quality/status:
    get:
      tags:
      - Data Quality
      summary: Get system status
      description: Get overall system health status including per-exchange and per-data-type status.
      operationId: getDataQualityStatus
      responses:
        '200':
          description: System status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-quality/coverage:
    get:
      tags:
      - Data Quality
      summary: Get coverage summary
      description: 'Get data coverage summary for supported venue families, including earliest/latest data, record counts, and completeness. Note: May take 30-60 seconds on first request (results are cached server-side for 5 minutes).'
      operationId: getDataQualityCoverage
      responses:
        '200':
          description: Coverage summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CoverageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-quality/coverage/{exchange}:
    get:
      tags:
      - Data Quality
      summary: Get exchange coverage
      description: 'Get data coverage for a specific exchange. Note: May take 30-60 seconds on first request (results are cached server-side for 5 minutes).'
      operationId: getExchangeCoverage
      parameters:
      - name: exchange
        in: path
        required: true
        description: Exchange name
        schema:
          type: string
          enum:
          - hyperliquid
          - lighter
          - hip3
          - spot
          - hip4
          example: hyperliquid
      responses:
        '200':
          description: Exchange coverage
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeCoverageResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/data-quality/coverage/{exchange}/{symbol}:
    get:
      tags:
      - Data Quality
      summary: Get symbol coverage with gaps
      description: 'Get data coverage for a specific symbol on an exchange, including gap detection showing periods where data may be missing. Supports optional `from`/`to` query params (Unix ms) to bound the gap detection window (default: last 30 days). Returns empirical data cadence when sufficient data is available. Historical coverage uses hour-level granularity. Note: May take 30-60 seconds on first request (gap detection results are cached server-side for 1 hour).'
      operationId: getSymbolCoverage
      parameters:
      - name: exchange
        in: path
        required: true
        description: Exchange name
        schema:
          type: string
          enum:
          - hyperliquid
          - lighter
          - hip3
          - spot
          - hip4
          example: hyperliquid
      - name: symbol
        in: path
        required: true
        description: Symbol name (e.g., BTC, ETH)
        schema:
          type: string
          example: BTC
        example: BTC
      - name: from
        in: query
        required: false
        description: 'Start of gap detection window (Unix milliseconds). Default: now - 30 days.'
        schema:
          type: integer
          format: int64
          example: 1704067200000
      - name: to
        in: query
        required: false
        description: 'End of gap detection window (Unix milliseconds). Default: now.'
        schema:
          type: integer
          format: int64
          example: 1706745600000
      responses:
        '200':
          description: Symbol coverage with gaps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SymbolCoverageResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/data-quality/incidents:
    get:
      tags:
      - Data Quality
      summary: List incidents
      description: List data quality incidents with filtering and pagination.
      operationId: listIncidents
      parameters:
      - name: status
        in: query
        description: Filter by incident status
        schema:
          type: string
          enum:
          - open
          - investigating
          - identified
          - monitoring
          - resolved
      - name: exchange
        in: query
        description: Filter by exchange
        schema:
          type: string
      - name: since
        in: query
        description: Only show incidents starting after this timestamp (Unix ms)
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        description: 'Maximum results per page (default: 20, max: 100)'
        schema:
          type: integer
          default: 20
          maximum: 100
      - name: offset
        in: query
        description: Pagination offset
        schema:
          type: integer
          default: 0
      responses:
        '200':
          description: List of incidents
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IncidentsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-quality/incidents/{id}:
    get:
      tags:
      - Data Quality
      summary: Get incident
      description: Get a specific incident by ID.
      operationId: getIncident
      parameters:
      - name: id
        in: path
        required: true
        description: Incident ID
        schema:
          type: string
      responses:
        '200':
          description: Incident details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Incident'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /v1/data-quality/latency:
    get:
      tags:
      - Data Quality
      summary: Get latency metrics
      description: Get current latency metrics for supported venue families including WebSocket, REST API, and data freshness.
      operationId: getLatencyMetrics
      responses:
        '200':
          description: Latency metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LatencyResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /v1/data-quality/sla:
    get:
      tags:
      - Data Quality
      summary: Get SLA metrics
      description: Get SLA compliance metrics for a specific month including uptime, completeness, and latency targets vs actuals.
      operationId: getSlaMetrics
      parameters:
      - name: year
        in: query
        description: Year (defaults to current year)
        schema:
          type: integer
          example: 2026
      - name: month
        in: query
        description: Month 1-12 (defaults to current month)
        schema:
          type: integer
          minimum: 1
          maximum: 12
          example: 1
      responses:
        '200':
          description: SLA metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SlaResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    CompletenessMetrics:
      type: object
      properties:
        orderbook:
          type: number
        fills:
          type: number
        funding:
          type: number
        overall:
          type: number
    LatencyResponse:
      type: object
      description: Latency metrics response
      properties:
        measured_at:
          type: string
          format: date-time
        exchanges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExchangeLatency'
    DataFreshness:
      type: object
      description: Data freshness metrics
      properties:
        orderbook_lag_ms:
          type:
          - integer
          - 'null'
        fills_lag_ms:
          type:
          - integer
          - 'null'
        funding_lag_ms:
          type:
          - integer
          - 'null'
        oi_lag_ms:
          type:
          - integer
          - 'null'
    ExchangeStatus:
      type: object
      description: Status of a single exchange
      properties:
        status:
          type: string
          enum:
          - operational
          - degraded
          - outage
          - maintenance
        last_data_at:
          type:
          - string
          - 'null'
          format: date-time
          description: Timestamp of last received data
        latency_ms:
          type:
          - integer
          - 'null'
          description: Current latency in milliseconds
    CoverageGap:
      type: object
      description: A gap in data coverage
      required:
      - start
      - end
      - duration_minutes
      properties:
        start:
          type: string
          format: date-time
          description: Start of gap (last data before gap)
        end:
          type: string
          format: date-time
          description: End of gap (first data after gap)
        duration_minutes:
          type: integer
          description: Gap duration in minutes
    Incident:
      type: object
      description: Data quality incident
      properties:
        id:
          type: string
          description: Unique incident ID
        status:
          type: string
          enum:
          - open
          - investigating
          - identified
          - monitoring
          - resolved
        severity:
          type: string
          enum:
          - minor
          - major
          - critical
        exchange:
          type:
          - string
          - 'null'
          description: Affected exchange
        data_types:
          type: array
          items:
            type: string
          description: Affected data types
        symbols_affected:
          type: array
          items:
            type: string
          description: Affected symbols
        started_at:
          type: string
          format: date-time
        resolved_at:
          type:
          - string
          - 'null'
          format: date-time
        duration_minutes:
          type:
          - integer
          - 'null'
        title:
          type: string
        description:
          type:
          - string
          - 'null'
        root_cause:
          type:
          - string
          - 'null'
        resolution:
          type:
          - string
          - 'null'
        records_affected:
          type:
          - integer
          - 'null'
          format: int64
        records_recovered:
          type:
          - integer
          - 'null'
          format: int64
    SlaResponse:
      type: object
      description: SLA compliance response
      properties:
        period:
          type: string
          description: Period covered (e.g., '2026-01')
        sla_targets:
          $ref: '#/components/schemas/SlaTargets'
        actual:
          $ref: '#/components/schemas/SlaActual'
        incidents_this_period:
          type: integer
        total_downtime_minutes:
          type: integer
    ApiLatency:
      type: object
      properties:
        current_ms:
          type: integer
        avg_1h_ms:
          type: integer
        avg_24h_ms:
          type: integer
    IncidentsResponse:
      type: object
      description: Incidents list response
      properties:
        incidents:
          type: array
          items:
            $ref: '#/components/schemas/Incident'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Error:
      type: object
      description: Error response
      properties:
        code:
          type: integer
          description: HTTP status code
        error:
          type: string
          description: Error message
        error_code:
          type: string
          description: 'Machine-readable error code. Common values: `invalid_query_params` (a query parameter failed to parse or validate) and `invalid_path_params` (a path parameter failed to parse). Other endpoint-specific codes exist; treat unknown codes as generic errors of the given HTTP status.'
        request_id:
          type: string
          format: uuid
          description: Unique request ID for support
    DataTypeStatus:
      type: object
      description: Status of a data type
      properties:
        status:
          type: string
          enum:
          - operational
          - degraded
          - outage
          - maintenance
        completeness_24h:
          type: number
          description: Data completeness over last 24 hours (0-100)
    Pagination:
      type: object
      description: Pagination info
      properties:
        total:
          type: integer
          description: Total number of items
        limit:
          type: integer
          description: Page size limit
        offset:
          type: integer
          description: Current offset
    DataCadence:
      type: object
      description: Empirical data cadence measurement based on last 7 days of data
      required:
      - median_interval_seconds
      - p95_interval_seconds
      - sample_count
      properties:
        median_interval_seconds:
          type: number
          description: Median interval between consecutive records in seconds
        p95_interval_seconds:
          type: number
          description: 95th percentile interval between consecutive records in seconds
        sample_count:
          type: integer
          format: int64
          description: Number of intervals sampled for this measurement
    SlaTargets:
      type: object
      properties:
        uptime:
          type: number
          description: Uptime target percentage
        data_completeness:
          type: number
          description: Data completeness target percentage
        api_latency_p99_ms:
          type: integer
          description: API P99 latency target in ms
    SlaActual:
      type: object
      properties:
        uptime:
          type: number
        uptime_status:
          type: string
          enum:
          - met
          - missed
        data_completeness:
          $ref: '#/components/schemas/CompletenessMetrics'
        completeness_status:
          type: string
          enum:
          - met
          - missed
        api_latency_p99_ms:
          type: integer
        latency_status:
          type: string
          enum:
          - met
          - missed
    ExchangeLatency:
      type: object
      description: Latency metrics for an exchange
      properties:
        websocket:
          allOf:
          - $ref: '#/components/schemas/WebSocketLatency'
        rest_api:
          allOf:
          - $ref: '#/components/schemas/ApiLatency'
        data_freshness:
          $ref: '#/components/schemas/DataFreshness'
    WebSocketLatency:
      type: object
      properties:
        current_ms:
          type: integer
        avg_1h_ms:
          type: integer
        avg_24h_ms:
          type: integer
        p99_24h_ms:
          type:
          - integer
          - 'null'
    DataTypeCoverage:
      type: object
      description: Coverage for a data type
      properties:
        earliest:
          type: string
          format: date-time
          description: Earliest available data timestamp
        latest:
          type: string
          format: date-time
          description: Latest available data timestamp
        total_records:
          type: integer
          format: int64
          description: Total number of records
        symbols:
          type: integer
          description: Number of symbols with data
        resolution:
          type:
          - string
          - 'null'
          description: Data resolution (e.g., '1.2s', '1m')
        lag:
          type:
          - string
          - 'null'
          description: Current data lag
        completeness:
          type: number
          description: Completeness percentage (0-100)
    ExchangeCoverageResponse:
      type: object
      description: Coverage for a single exchange
      properties:
        exchange:
          type: string
          description: Exchange name
        data_types:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DataTypeCoverage'
    SymbolCoverageResponse:
      type: object
      description: Per-symbol coverage response with gap detection
      required:
      - exchange
      - symbol
      - data_types
      properties:
        exchange:
          type: string
          description: Exchange name
        symbol:
          type: string
          description: Symbol name
        data_types:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/SymbolDataTypeCoverage'
    StatusResponse:
      type: object
      description: Overall system status
      properties:
        status:
          type: string
          enum:
          - operational
          - degraded
          - outage
          - maintenance
          description: Overall system status
        updated_at:
          type: string
          format: date-time
          description: When this status was computed
        exchanges:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/ExchangeStatus'
          description: Per-exchange status
        data_types:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/DataTypeStatus'
          description: Per-data-type status
        active_incidents:
          type: integer
          description: Number of active incidents
    SymbolDataTypeCoverage:
      type: object
      description: Coverage for a symbol and data type
      required:
      - earliest
      - latest
      - total_records
      - completeness
      - gaps
      properties:
        earliest:
          type: string
          format: date-time
        latest:
          type: string
          format: date-time
        total_records:
          type: integer
          format: int64
        completeness:
          type: number
          description: 24-hour completeness percentage (0-100)
        historical_coverage:
          type:
          - number
          - 'null'
          description: Historical coverage percentage (0-100) based on hours with data / total hours in range
        gaps:
          type: array
          items:
            $ref: '#/components/schemas/CoverageGap'
          description: Detected data gaps within the requested time window
        cadence:
          allOf:
          - $ref: '#/components/schemas/DataCadence'
          description: Empirical data cadence measurement (present when sufficient data exists)
    CoverageResponse:
      type: object
      description: Overall coverage response
      properties:
        exchanges:
          type: array
          items:
            $ref: '#/components/schemas/ExchangeCoverageResponse'
  responses:
    BadRequest:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 400
            error: 'Failed to deserialize query string: limit: invalid digit found in string'
            error_code: invalid_query_params
            request_id: 3f2a9c71-5b0e-4d68-9a4c-7e1d2b6f8a05
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 404
            error: Resource not found
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 401
            error: Missing or invalid API key. Provide X-API-Key header.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key for authentication. Get yours at https://0xarchive.io/dashboard
externalDocs:
  description: 0xArchive Developer Docs
  url: https://docs.0xarchive.io/
x-0xarchive-docs-language-overlay:
  name: data-quality-supported-venue-language
  reason: Public OpenAPI language must describe supported venue-family coverage instead of broad exchange coverage.
  updated_at: '2026-05-24'
  remove_when: Public source OpenAPI uses supported venue-family wording for data-quality coverage and latency descriptions.
x-0xarchive-docs-overlay:
  name: hyperliquid-spot
  reason: Hyperliquid Spot routes are included in the local REST contract.
  source: live endpoint behavior and public CLI/MCP/Skill surface truth
  updated_at: '2026-05-08'
  remove_when: Public source contract includes the same Spot route family.