openapi: 3.2.0
info:
  title: 0xArchive Lighter - Liquidations 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: Lighter - Liquidations
paths:
  /v1/lighter/liquidations/{symbol}:
    get:
      tags:
      - Lighter - Liquidations
      summary: Get Lighter liquidation events
      description: Get Lighter liquidation events in a bounded time range using cursor pagination. Lighter liquidations are available only from the start of live capture; no public historical backfill is available before that window. Explicit endpoint cost is 3 credits per request.
      operationId: getLighterLiquidations
      parameters:
      - name: symbol
        in: path
        required: true
        description: Lighter market symbol.
        schema:
          type: string
          example: BTC
        example: BTC
      - name: start
        in: query
        description: Start timestamp in Unix milliseconds. Defaults depend on the route family.
        schema:
          type: integer
          format: int64
      - name: end
        in: query
        description: End timestamp in Unix milliseconds. Defaults to now.
        schema:
          type: integer
          format: int64
      - name: cursor
        in: query
        description: Cursor for pagination. Use the value from the previous response metadata.
        schema:
          type: string
      - name: limit
        in: query
        description: 'Maximum number of results (default: 100, max: 1000)'
        schema:
          type: integer
          default: 100
          maximum: 1000
      responses:
        '200':
          description: Lighter liquidation events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseLighterLiquidationArray'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /v1/lighter/liquidations/{symbol}/volume:
    get:
      tags:
      - Lighter - Liquidations
      summary: Get Lighter liquidation volume
      description: Get aggregated Lighter liquidation volume in time-bucketed intervals. Long/short classification follows Lighter liquidation trade semantics. Explicit endpoint cost is 3 credits per request.
      operationId: getLighterLiquidationVolume
      parameters:
      - name: symbol
        in: path
        required: true
        description: Lighter market symbol.
        schema:
          type: string
          example: BTC
        example: BTC
      - name: start
        in: query
        description: Start timestamp in Unix milliseconds. Defaults depend on the route family.
        schema:
          type: integer
          format: int64
      - name: end
        in: query
        description: End timestamp in Unix milliseconds. Defaults to now.
        schema:
          type: integer
          format: int64
      - name: cursor
        in: query
        description: Cursor for pagination. Use the value from the previous response metadata.
        schema:
          type: string
      - name: limit
        in: query
        description: 'Maximum number of results (default: 100, max: 1000)'
        schema:
          type: integer
          default: 100
          maximum: 1000
      - name: interval
        in: query
        description: Aggregation interval. Defaults to 1h.
        schema:
          type: string
          enum:
          - 5m
          - 15m
          - 30m
          - 1h
          - 4h
          - 1d
          default: 1h
      responses:
        '200':
          description: Lighter liquidation volume buckets
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseLiquidationVolumeArray'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  responses:
    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.
    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
    RateLimited:
      description: Rate limit exceeded
      headers:
        X-RateLimit-Limit:
          schema:
            type: integer
          description: Requests per second limit
        X-RateLimit-Remaining:
          schema:
            type: integer
          description: Remaining requests this second
        X-RateLimit-Reset:
          schema:
            type: integer
          description: Unix timestamp when limit resets
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: 429
            error: Rate limit exceeded
  schemas:
    ApiResponseLighterLiquidationArray:
      type: object
      description: API response containing an array of native Lighter liquidation events
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/LighterLiquidation'
        meta:
          type: object
          properties:
            count:
              type: integer
              description: Number of records returned
            next_cursor:
              type:
              - string
              - 'null'
              description: 'Cursor for pagination (format: timestamp_tradeId)'
            request_id:
              type: string
              format: uuid
              description: Unique request ID for support
    LiquidationVolume:
      type: object
      description: Aggregated liquidation volume for a time bucket
      required:
      - symbol
      - coin
      - timestamp
      - total_usd
      - long_usd
      - short_usd
      - count
      - long_count
      - short_count
      properties:
        symbol:
          type: string
          description: Trading pair symbol
          example: BTC
        coin:
          type: string
          description: Trading pair symbol (deprecated, use symbol instead)
          example: BTC
          deprecated: true
        timestamp:
          type: string
          format: date-time
          description: Bucket start timestamp (UTC)
          example: '2025-05-21T10:00:00.000Z'
        total_usd:
          type: number
          description: Total liquidation volume in USD
          example: 1250000.5
        long_usd:
          type: number
          description: Long liquidation volume in USD
          example: 750000.25
        short_usd:
          type: number
          description: Short liquidation volume in USD
          example: 500000.25
        count:
          type: integer
          description: Total number of liquidations
          example: 42
        long_count:
          type: integer
          description: Number of long liquidations
          example: 25
        short_count:
          type: integer
          description: Number of short liquidations
          example: 17
    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
    ApiResponseLiquidationVolumeArray:
      type: object
      description: API response containing an array of aggregated liquidation volumes
      properties:
        success:
          type: boolean
          example: true
        data:
          type: array
          items:
            $ref: '#/components/schemas/LiquidationVolume'
        meta:
          type: object
          properties:
            count:
              type: integer
              description: Number of records returned
            next_cursor:
              type:
              - string
              - 'null'
              description: Cursor for pagination
    LighterLiquidation:
      type: object
      description: 'Native Lighter liquidation event. Raw ask/bid account fields are preserved instead of a derived `liquidated_user`: the upstream payload does not reliably flag which side was liquidated, so the liquidated side is derived at read time from position signs. Margin and fee integer fields are raw upstream units.'
      required:
      - symbol
      - timestamp
      - transaction_time_us
      - trade_id
      - liquidation_type
      - price
      - size
      - usd_amount
      - ask_account
      - bid_account
      - ask_order_id
      - bid_order_id
      - is_maker_ask
      - taker_position_size_before
      - maker_position_size_before
      - taker_entry_quote_before
      - maker_entry_quote_before
      - taker_initial_margin_fraction_before
      - maker_initial_margin_fraction_before
      - taker_allocated_margin_usdc_before
      - taker_allocated_margin_usdc_after
      - maker_allocated_margin_usdc_before
      - maker_allocated_margin_usdc_after
      - taker_fee
      - maker_fee
      - taker_position_sign_changed
      - maker_position_sign_changed
      - block_height
      - tx_hash
      - raw_json
      - source
      properties:
        symbol:
          type: string
          description: Trading pair symbol
          example: BTC
        timestamp:
          type: integer
          format: int64
          description: Liquidation timestamp in Unix epoch milliseconds
          example: 1785116108743
        transaction_time_us:
          type: integer
          format: int64
          description: Intra-block transaction time in microseconds
          example: 1785116108751813
        trade_id:
          type: integer
          format: int64
          description: Unique Lighter trade ID of the liquidation fill
          example: 26144238102
        liquidation_type:
          type: string
          description: Upstream liquidation type
          example: liquidation
        price:
          type: number
          description: Execution price
          example: 64921.9
        size:
          type: number
          description: Liquidated size in base units
          example: 0.18476
        usd_amount:
          type: number
          description: Notional value of the liquidation in USD
          example: 11994.970244
        ask_account:
          type: string
          description: Lighter account index on the ask side (serialized as a string)
          example: '728637'
        bid_account:
          type: string
          description: Lighter account index on the bid side (serialized as a string)
          example: '726722'
        ask_order_id:
          type: integer
          format: int64
          description: Order ID on the ask side
          example: 562952982931319
        bid_order_id:
          type: integer
          format: int64
          description: Order ID on the bid side
          example: 844421854021817
        is_maker_ask:
          type: boolean
          description: True if the maker was on the ask side
          example: false
        taker_position_size_before:
          type: number
          description: Taker's signed position size before the fill (long positive, short negative)
          example: 0.19771
        maker_position_size_before:
          type: number
          description: Maker's signed position size before the fill
          example: -1.85452
        taker_entry_quote_before:
          type: number
          description: Taker's position entry quote value before the fill
          example: 12945.451185
        maker_entry_quote_before:
          type: number
          description: Maker's position entry quote value before the fill
          example: 120665.315247
        taker_initial_margin_fraction_before:
          type: integer
          description: Taker's initial margin fraction before the fill (raw upstream units)
          example: 200
        maker_initial_margin_fraction_before:
          type: integer
          description: Maker's initial margin fraction before the fill (raw upstream units)
          example: 500
        taker_allocated_margin_usdc_before:
          type: integer
          format: int64
          description: Taker's isolated-margin USDC allocation before the fill (raw upstream units)
          example: 259232053
        taker_allocated_margin_usdc_after:
          type: integer
          format: int64
          description: Taker's isolated-margin USDC allocation after the fill (raw upstream units)
          example: 23859483
        maker_allocated_margin_usdc_before:
          type: integer
          format: int64
          description: Maker's isolated-margin USDC allocation before the fill (raw upstream units)
          example: 0
        maker_allocated_margin_usdc_after:
          type: integer
          format: int64
          description: Maker's isolated-margin USDC allocation after the fill (raw upstream units)
          example: 0
        taker_fee:
          type: integer
          description: Taker fee (raw upstream units)
          example: 10000
        maker_fee:
          type: integer
          description: Maker fee (raw upstream units)
          example: 28
        taker_position_sign_changed:
          type: boolean
          description: True if the fill flipped the taker's position between long and short
          example: false
        maker_position_sign_changed:
          type: boolean
          description: True if the fill flipped the maker's position between long and short
          example: false
        block_height:
          type: integer
          format: int64
          description: Lighter L2 block height containing the liquidation
          example: 300340672
        tx_hash:
          type: string
          description: Lighter settlement transaction hash (fixed-width hex)
          example: 000000198190c10e0000019fa13627c7000000000000000000000000000000000000000000000000
        raw_json:
          type: string
          description: Raw upstream payload as received from Lighter.
        source:
          type: string
          description: Row provenance
          example: ws
  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.