openapi: 3.2.0
info:
  title: SiftingIO Market Data DEX 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: DEX
  description: On-chain wallet portfolios and historical DEX bars.
paths:
  /v1/hist/dex/{symbol}/bars:
    get:
      tags:
      - DEX
      operationId: getDexBars
      summary: Historical DEX OHLCV bars (gzip required)
      description: 'Requires `Accept-Encoding: gzip`. OHLCV bars for USD-quoted DEX

        tokens, aggregated from executed on-chain swaps. Buckets with zero

        trades are omitted (the series is sparse). Requires the `dex_defi`

        market on paid keys. When `start` predates the earliest indexed bar

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

        field. `v` is base-asset volume (e.g. ETH for ETHUSD), not USD value.

        '
      parameters:
      - $ref: '#/components/parameters/AcceptEncodingGzip'
      - name: symbol
        in: path
        required: true
        description: Base token plus the `USD` suffix, e.g. `ETHUSD`. Case-insensitive.
        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'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '406':
          $ref: '#/components/responses/GzipRequired'
        '422':
          $ref: '#/components/responses/DataUnavailable'
        '429':
          $ref: '#/components/responses/TooManyRequests'
  /v1/fnd/dex/wallet/{chain}/{address}:
    get:
      tags:
      - DEX
      operationId: getWalletPortfolio
      summary: Wallet token portfolio
      parameters:
      - $ref: '#/components/parameters/Chain'
      - name: address
        in: path
        required: true
        description: 0x-prefixed 40-hex-char wallet address.
        schema:
          type: string
      responses:
        '200':
          description: Token holdings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WalletPortfolio'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
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
    WalletToken:
      type: object
      properties:
        contract_address:
          type: string
        symbol:
          type: string
        name:
          type: string
        decimals:
          type: integer
        logo:
          type: string
        raw_balance:
          type: string
          description: Integer balance in base units.
        balance:
          type: string
          description: Human-readable balance.
        native:
          type: boolean
    WalletPortfolio:
      type: object
      properties:
        chain:
          type: string
        address:
          type: string
        tokens:
          type: array
          items:
            $ref: '#/components/schemas/WalletToken'
        count:
          type: integer
        updated_at:
          type: integer
          format: int64
          description: Unix epoch seconds.
    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:
    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
    BarEnd:
      name: end
      in: query
      description: Inclusive upper bound. Default now.
      schema:
        type: string
    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
    BarStartRequired:
      name: start
      in: query
      required: true
      description: Inclusive lower bound (YYYY-MM-DD or RFC3339). Required.
      schema:
        type: string
  responses:
    DataUnavailable:
      description: No upstream has data for the requested window.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    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