openapi: 3.2.0
info:
  title: SiftingIO Market Data Crypto API
  version: 1.0.0
  description: 'REST data-plane for the SiftingIO market data API: live prices,

    SEC fundamentals (filings, XBRL financials, ratios, insiders, ownership),

    historical OHLCV bars, market calendars, DEX wallet portfolios, and the

    US economic calendar.


    Authentication is by API key, sent as the `X-API-Key` header (preferred)

    or the `api_key` query parameter.


    Several endpoints return large payloads and **require** `Accept-Encoding: gzip`

    (they respond `406` otherwise): the screener, both financials endpoints,

    all historical-bars endpoints, and the market snapshot.


    This document describes the data plane only. Account, billing, and auth

    (the `/ops/v1` control plane) are out of scope.

    '
  license:
    name: MIT
    identifier: MIT
  contact:
    name: SiftingIO
    url: https://sifting.io/docs
servers:
- url: https://api.sifting.io
  description: Production
security:
- ApiKeyHeader: []
- ApiKeyQuery: []
tags:
- name: Crypto
  description: Historical OHLCV bars for crypto symbols.
paths:
  /v1/hist/crypto/{symbol}/bars:
    get:
      tags:
      - Crypto
      operationId: getCryptoBars
      summary: Historical crypto OHLCV bars (gzip required)
      description: 'Requires `Accept-Encoding: gzip`. When `start` predates all upstreams''

        coverage the API returns `422` with code `data_unavailable` and an

        `earliest` field.

        '
      parameters:
      - $ref: '#/components/parameters/AcceptEncodingGzip'
      - name: symbol
        in: path
        required: true
        description: USD-quoted crypto symbol, e.g. `BTCUSD`.
        schema:
          type: string
      - $ref: '#/components/parameters/BarStartRequired'
      - $ref: '#/components/parameters/BarEnd'
      - $ref: '#/components/parameters/BarInterval'
      - $ref: '#/components/parameters/Cursor'
      - name: limit
        in: query
        schema:
          type: integer
          default: 1000
          maximum: 5000
      responses:
        '200':
          description: OHLCV bars.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BarsResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/GzipRequired'
        '422':
          $ref: '#/components/responses/DataUnavailable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    Bar:
      type: object
      properties:
        t:
          type: integer
          format: int64
          description: Bar open time, Unix epoch ms.
        o:
          type: number
        h:
          type: number
        l:
          type: number
        c:
          type: number
        v:
          type: number
    BarsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Bar'
        meta:
          $ref: '#/components/schemas/BarsMeta'
    BarsMeta:
      type: object
      properties:
        as_of:
          type: string
          format: date-time
        next_cursor:
          type: string
        symbol:
          type: string
        interval:
          type: string
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: Machine-readable error code, e.g. `unknown_ticker`.
        message:
          type: string
        retry_after:
          type: number
          description: Present on rate-limit errors.
      additionalProperties: true
  parameters:
    BarInterval:
      name: interval
      in: query
      description: 'Bar interval. Default 1m. All `/v1/hist/*` routes accept the same set: intraday (1m–1h), plus `1d` (UTC calendar day), `1w` (Monday-aligned), and `1mo` (calendar month). Coarser bars are aggregated from 1-minute history; a `1d`/`1w`/`1mo` bar opens at midnight UTC of the period start.

        '
      schema:
        type: string
        enum:
        - 1m
        - 5m
        - 15m
        - 30m
        - 1h
        - 1d
        - 1w
        - 1mo
        default: 1m
    Cursor:
      name: cursor
      in: query
      description: Opaque pagination cursor from a previous response's `meta.next_cursor`.
      schema:
        type: string
    BarEnd:
      name: end
      in: query
      description: Inclusive upper bound. Default now.
      schema:
        type: string
    BarStartRequired:
      name: start
      in: query
      required: true
      description: Inclusive lower bound (YYYY-MM-DD or RFC3339). Required.
      schema:
        type: string
    AcceptEncodingGzip:
      name: Accept-Encoding
      in: header
      required: true
      description: Must include `gzip`; this endpoint returns 406 otherwise.
      schema:
        type: string
        enum:
        - gzip
  responses:
    BadRequest:
      description: Invalid request parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    DataUnavailable:
      description: No upstream has data for the requested window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Rate limit exceeded.
      headers:
        Retry-After:
          description: Seconds to wait before retrying.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    GzipRequired:
      description: 'This endpoint requires `Accept-Encoding: gzip`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
    ApiKeyQuery:
      type: apiKey
      in: query
      name: api_key