Lighter order API

openapi: 3.2.0
info:
  title: Lighter account Order API
  version: '1.0'
servers:
- url: https://mainnet.zklighter.elliot.ai
tags:
- name: order
paths:
  /api/v1/accountActiveOrders:
    get:
      summary: accountActiveOrders
      operationId: accountActiveOrders
      tags:
      - order
      description: Get account active orders. `auth` can be generated using the SDK.
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: market_id
        in: query
        required: false
        description: If not specified, returns active orders for all markets.
        schema:
          type: integer
          format: int16
          default: '255'
      - name: market_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - spot
          - perp
          default: all
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/accountInactiveOrders:
    get:
      summary: accountInactiveOrders
      operationId: accountInactiveOrders
      tags:
      - order
      description: Get account inactive orders. `auth` can be generated using the SDK.
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: market_id
        in: query
        required: false
        schema:
          type: integer
          format: int16
          default: '255'
      - name: ask_filter
        in: query
        required: false
        schema:
          type: integer
          format: int8
          default: '-1'
      - name: between_timestamps
        in: query
        required: false
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 100
      - name: market_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - spot
          - perp
          default: all
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Orders'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/assetDetails:
    get:
      summary: assetDetails
      operationId: assetDetails
      tags:
      - order
      description: Get asset details for a specific asset or all assets
      parameters:
      - name: asset_id
        in: query
        required: false
        schema:
          type: integer
          format: int16
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetDetails'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/exchangeStats:
    get:
      summary: exchangeStats
      operationId: exchangeStats
      tags:
      - order
      description: Get exchange stats
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeStats'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/export:
    get:
      summary: export
      operationId: export
      tags:
      - order
      description: Export trades and funding payments, limited to 12 months or 1M trades. END_TS_IN_MS - START_TS_IN_MS should not be larger than 12 months in milliseconds, both timestamps should be greater than or equal to 17 January 2025 00:00:00 UTC (lighter's mainnet genesis)
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      - name: account_index
        in: query
        required: false
        schema:
          type: integer
          format: int64
          default: '-1'
      - name: market_id
        in: query
        required: false
        schema:
          type: integer
          format: int16
          default: '255'
      - name: type
        in: query
        required: true
        schema:
          type: string
          enum:
          - funding
          - trade
      - name: start_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
          minimum: 1735689600000
          maximum: 1830297600000
      - name: end_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
          minimum: 1735689600000
          maximum: 1830297600000
      - name: side
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - long
          - short
          default: all
      - name: role
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - maker
          - taker
          default: all
      - name: trade_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - trade
          - liquidation
          - deleverage
          - market-settlement
          default: all
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExportData'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/orderBookDetails:
    get:
      summary: orderBookDetails
      operationId: orderBookDetails
      tags:
      - order
      description: Get order books metadata
      parameters:
      - name: market_id
        in: query
        required: false
        schema:
          type: integer
          format: int16
          default: '255'
      - name: filter
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - spot
          - perp
          default: all
        description: Filter order books by type
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBookDetails'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/orderBookOrders:
    get:
      summary: orderBookOrders
      operationId: orderBookOrders
      tags:
      - order
      description: Get order book orders
      parameters:
      - name: market_id
        in: query
        required: true
        schema:
          type: integer
          format: int16
      - name: limit
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 250
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBookOrders'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/orderBooks:
    get:
      summary: orderBooks
      operationId: orderBooks
      tags:
      - order
      description: Get order books metadata.<hr>**Response Description:**<br><br>1) **Taker and maker fees** are in percentage.<br>2) **Min base amount:** The amount of base token that can be traded in a single order.<br>3) **Min quote amount:** The amount of quote token that can be traded in a single order.<br>4) **Supported size decimals:** The number of decimal places that can be used for the size of the order.<br>5) **Supported price decimals:** The number of decimal places that can be used for the price of the order.<br>6) **Supported quote decimals:** Size Decimals + Quote Decimals.
      parameters:
      - name: market_id
        in: query
        required: false
        schema:
          type: integer
          format: int16
          default: '255'
      - name: filter
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - spot
          - perp
          default: all
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderBooks'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/recentTrades:
    get:
      summary: recentTrades
      operationId: recentTrades
      tags:
      - order
      description: Get recent trades
      parameters:
      - name: market_id
        in: query
        required: true
        schema:
          type: integer
          format: int16
      - name: limit
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 100
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trades'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/trades:
    get:
      summary: trades
      operationId: trades
      tags:
      - order
      description: Get trades for lighter accounts, including sub-accounts and public pools. `auth` is required for master accounts and sub accounts.
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
      - name: market_id
        in: query
        required: false
        schema:
          type: integer
          format: int16
          default: '255'
      - name: market_type
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - spot
          - perp
          default: all
      - name: account_index
        in: query
        required: false
        schema:
          type: integer
          format: int64
          default: '-1'
      - name: order_index
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: sort_by
        in: query
        required: true
        schema:
          type: string
          enum:
          - block_height
          - timestamp
          - trade_id
      - name: sort_dir
        in: query
        required: false
        schema:
          type: string
          enum:
          - desc
          default: desc
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: from
        in: query
        required: false
        schema:
          type: integer
          format: int64
          default: '-1'
      - name: ask_filter
        in: query
        required: false
        schema:
          type: integer
          format: int8
          default: '-1'
      - name: role
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - maker
          - taker
          default: all
      - name: type
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - trade
          - liquidation
          - deleverage
          - market-settlement
          default: all
      - name: limit
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 100
      - name: aggregate
        in: query
        required: false
        schema:
          type: boolean
          format: boolean
          default: 'false'
      - name: skip_ask_order_id
        in: query
        required: false
        schema:
          type: string
      - name: skip_bid_order_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Trades'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/exchangeMetrics:
    get:
      summary: exchangeMetrics
      operationId: exchangeMetrics
      tags:
      - order
      description: Get exchange metrics. When filtering by market, use the market symbol as a value.
      parameters:
      - name: period
        in: query
        required: true
        schema:
          type: string
          enum:
          - h
          - d
          - w
          - m
          - q
          - y
          - all
      - name: kind
        in: query
        required: true
        schema:
          type: string
          enum:
          - volume
          - maker_fee
          - taker_fee
          - liquidation_fee
          - trade_count
          - liquidation_count
          - liquidation_volume
          - inflow
          - outflow
          - transfer_fee
          - withdraw_fee
          - open_interest
          - account_count
          - active_account_count
          - tps
          - buyback
          - buyback_usdc
      - name: filter
        in: query
        required: false
        schema:
          type: string
          enum:
          - byMarket
      - name: value
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGetExchangeMetrics'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/executeStats:
    get:
      summary: executeStats
      operationId: executeStats
      tags:
      - order
      description: Get execute stats
      parameters:
      - name: period
        in: query
        required: true
        schema:
          type: string
          enum:
          - d
          - w
          - m
          - q
          - y
          - all
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGetExecuteStats'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
components:
  schemas:
    ExportData:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        data_url:
          type: string
      title: ExportData
      required:
      - code
      - data_url
    ExchangeMetric:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          example: '1640995200'
        data:
          type: number
          format: double
          example: '93566.25'
      title: ExchangeMetric
      required:
      - timestamp
      - data
    Orders:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        next_cursor:
          type: string
        orders:
          type: array
          items:
            $ref: '#/components/schemas/Order'
      title: Orders
      required:
      - code
      - orders
    OrderBookDetails:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        order_book_details:
          type: array
          items:
            $ref: '#/components/schemas/PerpsOrderBookDetail'
        spot_order_book_details:
          type: array
          items:
            $ref: '#/components/schemas/SpotOrderBookDetail'
      title: OrderBookDetails
      required:
      - code
      - order_book_details
      - spot_order_book_details
    MarketConfig:
      type: object
      properties:
        market_margin_mode:
          type: integer
          format: int32
          example: 0
        insurance_fund_account_index:
          type: integer
          format: int64
          example: 281474976710655
        liquidation_mode:
          type: integer
          format: int32
          example: 0
        force_reduce_only:
          type: boolean
          format: boolean
          example: false
        funding_fee_discounts_enabled:
          type: boolean
          format: boolean
        trading_hours:
          type: string
          example: ''
        hidden:
          type: boolean
        rfq_enabled:
          type: boolean
          format: boolean
      title: MarketConfig
      required:
      - market_margin_mode
      - insurance_fund_account_index
      - liquidation_mode
      - force_reduce_only
      - trading_hours
      - hidden
      - rfq_enabled
    PerpsOrderBookDetail:
      type: object
      properties:
        symbol:
          type: string
          example: ETH
        market_id:
          type: integer
          format: int16
          example: 0
        market_type:
          type: string
          example: perp
          enum:
          - perp
          - spot
        base_asset_id:
          type: integer
          format: int16
          example: 0
        quote_asset_id:
          type: integer
          format: int16
          example: 0
        status:
          type: string
          example: active
          enum:
          - inactive
          - active
        taker_fee:
          type: string
          example: '0.0001'
        maker_fee:
          type: string
          example: '0.0000'
        liquidation_fee:
          type: string
          example: '0.01'
        min_base_amount:
          type: string
          example: '0.01'
        min_quote_amount:
          type: string
          example: '0.1'
        supported_size_decimals:
          type: integer
          format: uint8
          example: '4'
        supported_price_decimals:
          type: integer
          format: uint8
          example: '4'
        supported_quote_decimals:
          type: integer
          format: uint8
          example: '4'
        order_quote_limit:
          type: string
          example: '281474976.710655'
        size_decimals:
          type: integer
          format: uint8
          example: '4'
        price_decimals:
          type: integer
          format: uint8
          example: '4'
        quote_multiplier:
          type: integer
          format: int64
          example: '10000'
        default_initial_margin_fraction:
          type: integer
          format: uin16
          example: '100'
        min_initial_margin_fraction:
          type: integer
          format: uin16
          example: '100'
        maintenance_margin_fraction:
          type: integer
          format: uin16
          example: '50'
        closeout_margin_fraction:
          type: integer
          format: uin16
          example: '100'
        last_trade_price:
          type: number
          format: double
          example: '3024.66'
        daily_trades_count:
          type: integer
          format: int64
          example: '68'
        daily_base_token_volume:
          type: number
          format: double
          example: '235.25'
        daily_quote_token_volume:
          type: number
          format: double
          example: '93566.25'
        daily_price_low:
          type: number
          format: double
          example: '3014.66'
        daily_price_high:
          type: number
          format: double
          example: '3024.66'
        daily_price_change:
          type: number
          format: double
          example: '3.66'
        open_interest:
          type: number
          format: double
          example: '93.0'
        daily_chart:
          type: object
          example: '{1640995200:3024.66}'
          additionalProperties:
            type: number
            format: double
        market_config:
          $ref: '#/components/schemas/MarketConfig'
        strategy_index:
          type: integer
          format: uint8
        is_maker_fee_enabled:
          type: boolean
          example: true
        is_taker_fee_enabled:
          type: boolean
          example: true
        funding_clamp_small:
          type: string
          example: '0.005'
        funding_clamp_big:
          type: string
          example: '0.4'
        base_interest_rate:
          type: string
          example: '0.0001'
      title: PerpsOrderBookDetail
      required:
      - symbol
      - market_id
      - market_type
      - base_asset_id
      - quote_asset_id
      - status
      - taker_fee
      - is_taker_fee_enabled
      - maker_fee
      - is_maker_fee_enabled
      - liquidation_fee
      - min_base_amount
      - min_quote_amount
      - order_quote_limit
      - supported_size_decimals
      - supported_price_decimals
      - supported_quote_decimals
      - size_decimals
      - price_decimals
      - quote_multiplier
      - default_initial_margin_fraction
      - min_initial_margin_fraction
      - maintenance_margin_fraction
      - closeout_margin_fraction
      - last_trade_price
      - daily_trades_count
      - daily_base_token_volume
      - daily_quote_token_volume
      - daily_price_low
      - daily_price_high
      - daily_price_change
      - open_interest
      - daily_chart
      - market_config
      - strategy_index
      - funding_clamp_small
      - funding_clamp_big
      - base_interest_rate
    Order:
      type: object
      properties:
        order_index:
          type: integer
          format: int64
          example: '1'
        client_order_index:
          type: integer
          format: int64
          example: '234'
        order_id:
          type: string
          example: '1'
        client_order_id:
          type: string
          example: '234'
        market_index:
          type: integer
          format: int16
          example: '1'
        owner_account_index:
          type: integer
          format: int64
          example: '1'
        initial_base_amount:
          type: string
          example: '0.1'
        price:
          type: string
          example: '3024.66'
        nonce:
          type: integer
          format: int64
          example: '722'
        remaining_base_amount:
          type: string
          example: '0.1'
        is_ask:
          type: boolean
          format: boolean
          example: 'true'
        base_size:
          type: integer
          format: int64
          example: '12354'
        base_price:
          type: integer
          format: int32
          example: '3024'
        filled_base_amount:
          type: string
          example: '0.1'
        filled_quote_amount:
          type: string
          example: '0.1'
        side:
          type: string
          example: buy
          default: buy
          description: ' TODO: remove this'
        type:
          type: string
          example: limit
          enum:
          - limit
          - market
          - stop-loss
          - stop-loss-limit
          - take-profit
          - take-profit-limit
          - twap
          - twap-sub
          - liquidation
        time_in_force:
          type: string
          enum:
          - good-till-time
          - immediate-or-cancel
          - post-only
          - Unknown
          default: good-till-time
        reduce_only:
          type: boolean
          format: boolean
          example: 'true'
        trigger_price:
          type: string
          example: '3024.66'
        order_expiry:
          type: integer
          format: int64
          example: '1640995200'
        status:
          type: string
          example: open
          enum:
          - in-progress
          - pending
          - open
          - filled
          - canceled
          - canceled-post-only
          - canceled-reduce-only
          - canceled-position-not-allowed
          - canceled-margin-not-allowed
          - canceled-too-much-slippage
          - canceled-not-enough-liquidity
          - canceled-self-trade
          - canceled-expired
          - canceled-oco
          - canceled-child
          - canceled-liquidation
          - canceled-invalid-balance
        trigger_status:
          type: string
          example: twap
          enum:
          - na
          - ready
          - mark-price
          - twap
          - parent-order
        trigger_time:
          type: integer
          format: int64
          example: '1640995200'
        parent_order_index:
          type: integer
          format: int64
          example: '1'
        parent_order_id:
          type: string
          example: '1'
        to_trigger_order_id_0:
          type: string
          example: '1'
        to_trigger_order_id_1:
          type: string
          example: '1'
        to_cancel_order_id_0:
          type: string
          example: '1'
        block_height:
          type: integer
          format: int64
          example: '45434'
        timestamp:
          type: integer
          format: int64
          example: '1640995200'
        created_at:
          type: integer
          format: int64
          example: '1640995200'
        updated_at:
          type: integer
          format: int64
          example: '1640995200'
        transaction_time:
          type: integer
          format: int64
        integrator_fee_collector_index:
          type: string
        integrator_maker_fee:
          type: string
        integrator_taker_fee:
          type: string
      title: Order
      required:
      - order_index
      - client_order_index
      - order_id
      - client_order_id
      - market_index
      - owner_account_index
      - initial_base_amount
      - price
      - nonce
      - remaining_base_amount
      - is_ask
      - base_size
      - base_price
      - filled_base_amount
      - filled_quote_amount
      - side
      - type
      - time_in_force
      - reduce_only
      - trigger_price
      - order_expiry
      - status
      - trigger_status
      - trigger_time
      - parent_order_index
      - parent_order_id
      - to_trigger_order_id_0
      - to_trigger_order_id_1
      - to_cancel_order_id_0
      - block_height
      - timestamp
      - created_at
      - updated_at
      - integrator_fee_collector_index
      - integrator_maker_fee
      - integrator_taker_fee
      - transaction_time
    RespGetExchangeMetrics:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/ExchangeMetric'
      title: RespGetExchangeMetrics
      required:
      - code
      - metrics
    SpotOrderBookDetail:
      type: object
      properties:
        symbol:
          type: string
          example: ETH/USDC
        market_id:
          type: integer
          format: int16
          example: 2048
        market_type:
          type: string
          example: spot
          enum:
          - perp
          - spot
        base_asset_id:
          type: integer
          format: int16
          example: 1
        quote_asset_id:
          type: integer
          format: int16
          example: 3
        status:
          type: string
          example: active
          enum:
          - inactive
          - active
        taker_fee:
          type: string
          example: '0.0000'
        maker_fee:
          type: string
          example: '0.0000'
        liquidation_fee:
          type: string
          example: '0.0000'
        min_base_amount:
          type: string
          example: '0.0001'
        min_quote_amount:
          type: string
          example: '0.000001'
        order_quote_limit:
          type: string
          example: '2500000.000000'
        supported_size_decimals:
          type: integer
          format: uint8
          example: 4
        supported_price_decimals:
          type: integer
          format: uint8
          example: 2
        supported_quote_decimals:
          type: integer
          format: uint8
          example: 6
        size_decimals:
          type: integer
          format: uint8
          example: 4
        price_decimals:
          type: integer
          format: uint8
          example: 2
        last_trade_price:
          type: number
          format: double
          example: 2731.79
        daily_trades_count:
          type: integer
          format: int64
          example: 126993
        daily_base_token_volume:
          type: number
          format: double
          example: 1203.0962
        daily_quote_token_volume:
          type: number
          format: double
          example: 3516374.947553
        daily_price_low:
          type: number
          format: double
          example: 2717.47
        daily_price_high:
          type: number
          format: double
          example: 3044.21
        daily_price_change:
          type: number
          format: double
          example: -10.2389493724579
        daily_chart:
          type: object
          example: '{1640995200:3024.66}'
          additionalProperties:
            type: number
            format: double
        is_maker_fee_enabled:
          type: boolean
          example: true
        is_taker_fee_enabled:
          type: boolean
          example: true
      title: SpotOrderBookDetail
      required:
      - symbol
      - market_id
      - market_type
      - base_asset_id
      - quote_asset_id
      - status
      - taker_fee
      - is_taker_fee_enabled
      - maker_fee
      - is_maker_fee_enabled
      - liquidation_fee
      - min_base_amount
      - min_quote_amount
      - order_quote_limit
      - supported_size_decimals
      - supported_price_decimals
      - supported_quote_decimals
      - size_decimals
      - price_decimals
      - last_trade_price
      - daily_trades_count
      - daily_base_token_volume
      - daily_quote_token_volume
      - daily_price_low
      - daily_price_high
      - daily_price_change
      - daily_chart
    RespGetExecuteStats:
      type: object
      properties:
        period:
          type: string
          enum:
          - d
          - w
          - m
          - q
          - y
          - all
        result:
          typ

# --- truncated at 32 KB (46 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lighter/refs/heads/main/openapi/lighter-order-api-openapi.yml