openapi: 3.2.0
info:
  title: SiftingIO Market Data Live 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: Live
  description: Live market data read from the engine's latest snapshot.
paths:
  /v1/last/trade/{venue}/{symbol}:
    get:
      tags:
      - Live
      operationId: getLastTrade
      summary: Latest trade
      parameters:
      - $ref: '#/components/parameters/Venue'
      - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Latest trade snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastTrade'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/last/quote/{venue}/{symbol}:
    get:
      tags:
      - Live
      operationId: getLastQuote
      summary: Top-of-book quote
      parameters:
      - $ref: '#/components/parameters/Venue'
      - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Top-of-book quote.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastQuote'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/last/close/{venue}/{symbol}:
    get:
      tags:
      - Live
      operationId: getLastClose
      summary: Previous close
      description: 'The most recent previous close for one instrument. For crypto/forex/ commodities this is the engine''s fair price frozen at the last 00:00 UTC boundary; for stocks it is the official exchange session close. The response is immutable until the next close, so it is edge-cacheable (Cache-Control max-age expires at the next boundary) unlike the live trade/quote reads.

        '
      parameters:
      - $ref: '#/components/parameters/VenuePrevClose'
      - $ref: '#/components/parameters/Symbol'
      responses:
        '200':
          description: Latest previous close.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastClose'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/last/tvl/{chain}/{pair}:
    get:
      tags:
      - Live
      operationId: getLastTVL
      summary: Aggregated DEX pool TVL
      parameters:
      - $ref: '#/components/parameters/Chain'
      - $ref: '#/components/parameters/Pair'
      responses:
        '200':
          description: Aggregated TVL for the chain/pair.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LastTVL'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v1/snapshot/{venue}:
    get:
      tags:
      - Live
      operationId: getSnapshot
      summary: Full market snapshot (gzip required)
      description: 'Requires `Accept-Encoding: gzip`. Returns one entry per symbol the

        venue currently publishes, or scope it to a watchlist with `symbols`.

        Not paginated: a snapshot is the complete picture at `meta.as_of`.

        '
      parameters:
      - $ref: '#/components/parameters/AcceptEncodingGzip'
      - $ref: '#/components/parameters/Venue'
      - name: symbols
        in: query
        description: 'Comma-separated symbols (up to 250, case-insensitive). Omit to receive the full market. Any malformed symbol rejects the whole request with 400.

          '
        schema:
          type: string
        example: BTCUSD,ETHUSD,SOLUSD
      responses:
        '200':
          description: Market snapshot.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SnapshotResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/GzipRequired'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  parameters:
    Symbol:
      name: symbol
      in: path
      required: true
      description: Symbol, normalized to the venue's canonical form.
      schema:
        type: string
    Chain:
      name: chain
      in: path
      required: true
      description: EVM chain.
      schema:
        type: string
        enum:
        - eth
        - base
        - arbitrum
        - bsc
        - polygon
    AcceptEncodingGzip:
      name: Accept-Encoding
      in: header
      required: true
      description: Must include `gzip`; this endpoint returns 406 otherwise.
      schema:
        type: string
        enum:
        - gzip
    Pair:
      name: pair
      in: path
      required: true
      description: DEX pair (TOKEN0-TOKEN1) or FX pair (e.g. EURUSD).
      schema:
        type: string
    Venue:
      name: venue
      in: path
      required: true
      description: Market venue.
      schema:
        type: string
        enum:
        - stocks
        - crypto
        - forex
        - dex
    VenuePrevClose:
      name: venue
      in: path
      required: true
      description: 'Market venue for previous close. DEX has no previous-close product; commodities does (unlike the live trade/quote venues).

        '
      schema:
        type: string
        enum:
        - stocks
        - crypto
        - forex
        - commodities
  schemas:
    LastClose:
      type: object
      properties:
        s:
          type: string
          description: Symbol.
        c:
          type: string
          description: Close price.
        d:
          type: string
          description: UTC close date, YYYY-MM-DD.
        t:
          type: integer
          format: int64
          description: Close-boundary Unix epoch milliseconds.
    LastTVL:
      type: object
      properties:
        chain:
          type: string
        pair:
          type: string
        usd:
          type: string
        r0:
          type: string
          description: Reserve of token0.
        r1:
          type: string
          description: Reserve of token1.
        n:
          type: integer
          description: Pools aggregated.
        v:
          type: integer
        t:
          type: integer
          format: int64
    LastQuote:
      type: object
      properties:
        b:
          type: string
          description: Bid price.
        B:
          type: string
          description: Bid size.
        a:
          type: string
          description: Ask price.
        A:
          type: string
          description: Ask size.
        t:
          type: integer
          format: int64
    SnapshotEntry:
      type: object
      properties:
        s:
          type: string
          description: Symbol.
        p:
          type: string
          description: Last trade price.
        P:
          type: string
          description: Last trade size (0 for forex/stocks).
        b:
          type: string
          description: Best bid price.
        B:
          type: string
          description: Best bid size (0 for forex/stocks).
        a:
          type: string
          description: Best ask price.
        A:
          type: string
          description: Best ask size (0 for forex/stocks).
        t:
          type: integer
          format: int64
          description: Unix epoch milliseconds.
    SnapshotResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/SnapshotEntry'
        meta:
          type: object
          properties:
            as_of:
              type: string
              format: date-time
            venue:
              type: string
            count:
              type: integer
    LastTrade:
      type: object
      properties:
        s:
          type: string
          description: Symbol.
        p:
          type: string
          description: Last trade price.
        P:
          type: string
          description: Last trade size.
        t:
          type: integer
          format: int64
          description: Unix epoch milliseconds.
    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
  responses:
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Valid key, but the plan or tier does not include this market/venue.
      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'
    ServiceUnavailable:
      description: Upstream or snapshot temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: Invalid request parameters.
      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