Lighter zkLighter WebSocket API

asyncapi: 3.0.0
info:
  title: Lighter zkLighter WebSocket API
  version: '1.0.0'
  description: |
    Real-time streaming surface for the zkLighter decentralized perpetuals exchange.

    Generated by the API Evangelist enrichment pipeline from Lighter's published WebSocket
    reference (https://apidocs.lighter.xyz/docs/websocket-reference). Lighter documents these
    channels and message shapes but does not publish an AsyncAPI document of its own; every
    channel, parameter and message field below is transcribed from that reference. Nothing here
    is invented.

    Subscriptions are sent as `{"type": "subscribe", "channel": "<channel>"}` over a single
    connection. Transactions may also be submitted over the same socket using the
    `jsonapi/sendtx` and `jsonapi/sendtxbatch` message types.
  contact:
    name: Lighter API Support
    url: https://discord.gg/lighterxyz
  externalDocs:
    url: https://apidocs.lighter.xyz/docs/websocket-reference
defaultContentType: application/json
servers:
  mainnet:
    host: mainnet.zklighter.elliot.ai
    pathname: /stream
    protocol: wss
    description: >-
      Mainnet stream. Append ?readonly=true for read-only market data access, which also works
      from restricted regions.
  testnet:
    host: testnet.zklighter.elliot.ai
    pathname: /stream
    protocol: wss
    description: Testnet stream.
channels:
  orderBook:
    address: 'order_book/{marketIndex}'
    description: Order book snapshots and deltas for a market.
    parameters:
      marketIndex:
        description: Market index, for example 0.
    messages:
      orderBookUpdate:
        $ref: '#/components/messages/OrderBookUpdate'
  trade:
    address: 'trade/{marketIndex}'
    description: Public trade prints for a market.
    parameters:
      marketIndex: {description: Market index.}
    messages:
      trade:
        $ref: '#/components/messages/Trade'
  ticker:
    address: 'ticker/{marketIndex}'
    description: Ticker updates for a market.
    parameters:
      marketIndex: {description: Market index.}
    messages:
      ticker:
        $ref: '#/components/messages/Generic'
  marketStats:
    address: 'market_stats/{marketIndex}'
    description: Perpetual market statistics. Use market_stats/all for every market.
    parameters:
      marketIndex: {description: Market index, or the literal "all".}
    messages:
      marketStats:
        $ref: '#/components/messages/Generic'
  spotMarketStats:
    address: 'spot_market_stats/{marketIndex}'
    description: Spot market statistics. Use spot_market_stats/all for every spot market.
    parameters:
      marketIndex: {description: Spot market index, for example 2048, or the literal "all".}
    messages:
      spotMarketStats:
        $ref: '#/components/messages/Generic'
  candle:
    address: 'candle/{marketId}/{resolution}'
    description: Candlestick series for a market at a resolution.
    parameters:
      marketId: {description: Market id.}
      resolution: {description: 'Candle resolution, for example 1m.'}
    messages:
      candle:
        $ref: '#/components/messages/Generic'
  markPriceCandle:
    address: 'mark_price_candle/{marketId}/{resolution}'
    description: Mark-price candlestick series for a market at a resolution.
    parameters:
      marketId: {description: Market id.}
      resolution: {description: 'Candle resolution, for example 1m.'}
    messages:
      markPriceCandle:
        $ref: '#/components/messages/Generic'
  height:
    address: height
    description: zkLighter L2 block height updates.
    messages:
      height:
        $ref: '#/components/messages/Generic'
  rfq:
    address: rfq
    description: perpRFQ request-for-quote stream.
    messages:
      rfq:
        $ref: '#/components/messages/Generic'
  accountAll:
    address: 'account_all/{accountId}'
    description: Consolidated account stream covering orders, trades and positions.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      accountAll:
        $ref: '#/components/messages/Generic'
  accountAllOrders:
    address: 'account_all_orders/{accountId}'
    description: All order updates for an account across markets.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      order:
        $ref: '#/components/messages/Order'
  accountAllTrades:
    address: 'account_all_trades/{accountId}'
    description: All trade fills for an account across markets.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      trade:
        $ref: '#/components/messages/Trade'
  accountAllPositions:
    address: 'account_all_positions/{accountId}'
    description: Position updates for an account across markets.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      position:
        $ref: '#/components/messages/Position'
  accountAllAssets:
    address: 'account_all_assets/{accountId}'
    description: Asset balance updates for an account.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      assets:
        $ref: '#/components/messages/Generic'
  accountSpotAvgEntryPrices:
    address: 'account_spot_avg_entry_prices/{accountId}'
    description: Average spot entry prices for an account.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      avgEntryPrices:
        $ref: '#/components/messages/Generic'
  accountMarket:
    address: 'account_market/{marketId}/{accountId}'
    description: Per-market account stream of orders, trades and position for one market.
    parameters:
      marketId: {description: Market index.}
      accountId: {description: Lighter account index.}
    messages:
      accountMarket:
        $ref: '#/components/messages/Generic'
  accountOrders:
    address: 'account_orders/{marketIndex}/{accountId}'
    description: Order updates for an account in one market.
    parameters:
      marketIndex: {description: Market index.}
      accountId: {description: Lighter account index.}
    messages:
      order:
        $ref: '#/components/messages/Order'
  accountTx:
    address: 'account_tx/{accountId}'
    description: Transaction lifecycle updates for an account.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      transaction:
        $ref: '#/components/messages/Transaction'
  userStats:
    address: 'user_stats/{accountId}'
    description: Aggregate account statistics.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      userStats:
        $ref: '#/components/messages/Generic'
  notification:
    address: 'notification/{accountId}'
    description: Account notifications. Acknowledge via the notification_ack REST operation.
    parameters:
      accountId: {description: Lighter account index.}
    messages:
      notification:
        $ref: '#/components/messages/Generic'
  poolData:
    address: 'pool_data/{accountId}'
    description: Public pool data updates.
    parameters:
      accountId: {description: Public pool account index.}
    messages:
      poolData:
        $ref: '#/components/messages/Generic'
  poolInfo:
    address: 'pool_info/{accountId}'
    description: Public pool metadata updates.
    parameters:
      accountId: {description: Public pool account index.}
    messages:
      poolInfo:
        $ref: '#/components/messages/Generic'
operations:
  subscribeOrderBook:
    action: receive
    channel: {$ref: '#/channels/orderBook'}
  subscribeTrade:
    action: receive
    channel: {$ref: '#/channels/trade'}
  subscribeTicker:
    action: receive
    channel: {$ref: '#/channels/ticker'}
  subscribeMarketStats:
    action: receive
    channel: {$ref: '#/channels/marketStats'}
  subscribeSpotMarketStats:
    action: receive
    channel: {$ref: '#/channels/spotMarketStats'}
  subscribeCandle:
    action: receive
    channel: {$ref: '#/channels/candle'}
  subscribeMarkPriceCandle:
    action: receive
    channel: {$ref: '#/channels/markPriceCandle'}
  subscribeHeight:
    action: receive
    channel: {$ref: '#/channels/height'}
  subscribeRfq:
    action: receive
    channel: {$ref: '#/channels/rfq'}
  subscribeAccountAll:
    action: receive
    channel: {$ref: '#/channels/accountAll'}
  subscribeAccountAllOrders:
    action: receive
    channel: {$ref: '#/channels/accountAllOrders'}
  subscribeAccountAllTrades:
    action: receive
    channel: {$ref: '#/channels/accountAllTrades'}
  subscribeAccountAllPositions:
    action: receive
    channel: {$ref: '#/channels/accountAllPositions'}
  subscribeAccountAllAssets:
    action: receive
    channel: {$ref: '#/channels/accountAllAssets'}
  subscribeAccountSpotAvgEntryPrices:
    action: receive
    channel: {$ref: '#/channels/accountSpotAvgEntryPrices'}
  subscribeAccountMarket:
    action: receive
    channel: {$ref: '#/channels/accountMarket'}
  subscribeAccountOrders:
    action: receive
    channel: {$ref: '#/channels/accountOrders'}
  subscribeAccountTx:
    action: receive
    channel: {$ref: '#/channels/accountTx'}
  subscribeUserStats:
    action: receive
    channel: {$ref: '#/channels/userStats'}
  subscribeNotification:
    action: receive
    channel: {$ref: '#/channels/notification'}
  subscribePoolData:
    action: receive
    channel: {$ref: '#/channels/poolData'}
  subscribePoolInfo:
    action: receive
    channel: {$ref: '#/channels/poolInfo'}
components:
  messages:
    Generic:
      name: ChannelUpdate
      contentType: application/json
      payload:
        type: object
        description: >-
          Channel update envelope. The Lighter reference documents the payload shape per channel in
          prose; only the channels with an explicitly published JSON structure are typed below.
        properties:
          type: {type: string}
          channel: {type: string}
    OrderBookUpdate:
      name: OrderBookUpdate
      contentType: application/json
      payload:
        type: object
        properties:
          channel: {type: string}
          order_book:
            type: object
            description: Bids and asks for the market.
    Order:
      name: Order
      contentType: application/json
      payload:
        $ref: '#/components/schemas/Order'
    Trade:
      name: Trade
      contentType: application/json
      payload:
        $ref: '#/components/schemas/Trade'
    Position:
      name: Position
      contentType: application/json
      payload:
        $ref: '#/components/schemas/Position'
    Transaction:
      name: Transaction
      contentType: application/json
      payload:
        $ref: '#/components/schemas/Transaction'
  schemas:
    Order:
      type: object
      properties:
        order_index: {type: integer}
        client_order_index: {type: integer}
        order_id: {type: string}
        client_order_id: {type: string}
        market_index: {type: integer}
        owner_account_index: {type: integer}
        initial_base_amount: {type: string}
        price: {type: string}
        nonce: {type: integer}
        remaining_base_amount: {type: string}
        is_ask: {type: boolean}
        filled_base_amount: {type: string}
        filled_quote_amount: {type: string}
        side: {type: string}
        type:
          type: string
          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]
        reduce_only: {type: boolean}
        trigger_price: {type: string}
        order_expiry: {type: integer}
        status:
          type: string
          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
          enum: [na, ready, mark-price, twap, parent-order]
        trigger_time: {type: integer}
        parent_order_index: {type: integer}
        block_height: {type: integer}
        timestamp: {type: integer}
        created_at: {type: integer}
        updated_at: {type: integer}
        transaction_time: {type: integer}
    Trade:
      type: object
      properties:
        trade_id: {type: integer}
        trade_id_str: {type: string}
        tx_hash: {type: string}
        type:
          type: string
          enum: [trade, liquidation, deleverage, market-settlement]
        market_id: {type: integer}
        size: {type: string}
        price: {type: string}
        usd_amount: {type: string}
        ask_id: {type: integer}
        bid_id: {type: integer}
        ask_account_id: {type: integer}
        bid_account_id: {type: integer}
        is_maker_ask: {type: boolean}
        block_height: {type: integer}
        timestamp: {type: integer}
        taker_fee: {type: integer}
        maker_fee: {type: integer}
        transaction_time: {type: integer}
    Position:
      type: object
      properties:
        market_id: {type: integer}
        symbol: {type: string}
        initial_margin_fraction: {type: string}
        open_order_count: {type: integer}
        pending_order_count: {type: integer}
        position_tied_order_count: {type: integer}
        sign: {type: integer}
    Transaction:
      type: object
      properties:
        hash: {type: string}
        type: {type: integer}
        info: {type: string, description: JSON object as string, attributes depend on tx type}
        event_info: {type: string, description: JSON object as string, attributes depend on tx type}
        status: {type: integer, description: '0 Failed, 1 Pending, 2 Executed, 3 Pending final state'}
        transaction_index: {type: integer}
        l1_address: {type: string}
        account_index: {type: integer}
        nonce: {type: integer}
        expire_at: {type: integer}
        block_height: {type: integer}
        queued_at: {type: integer}
        executed_at: {type: integer}
        sequence_index: {type: integer}
        parent_hash: {type: string}
        api_key_index: {type: integer}
        transaction_time: {type: integer}
x-apievangelist:
  generated: '2026-07-19'
  method: generated
  source: https://apidocs.lighter.xyz/docs/websocket-reference
  note: >-
    Lighter publishes no AsyncAPI document. This specification was generated from the published
    WebSocket reference by the API Evangelist enrichment pipeline and is not a Lighter artifact.