Lighter account API

openapi: 3.2.0
info:
  title: Lighter Account API
  version: '1.0'
servers:
- url: https://mainnet.zklighter.elliot.ai
tags:
- name: account
paths:
  /api/v1/account:
    get:
      summary: account
      operationId: account
      tags:
      - account
      description: Get account by an account's index, or L1 address
      parameters:
      - name: by
        in: query
        required: true
        schema:
          type: string
          enum:
          - index
          - l1_address
      - name: value
        in: query
        required: true
        schema:
          type: string
      - name: active_only
        in: query
        required: false
        description: Hide markets for which leverage and margin settings are present (meaning the account traded it at least once), but with no active position.
        schema:
          type: boolean
          default: false
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DetailedAccounts'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/accountLimits:
    get:
      summary: accountLimits
      operationId: accountLimits
      tags:
      - account
      description: 'Get account limits. For more details on account types, see this page: https://apidocs.lighter.xyz/docs/account-types'
      parameters:
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountLimits'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/accountMetadata:
    get:
      summary: accountMetadata
      operationId: accountMetadata
      tags:
      - account
      description: Get account metadatas
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
      - name: by
        in: query
        required: true
        schema:
          type: string
          enum:
          - index
          - l1_address
      - name: value
        in: query
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountMetadatas'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/accountsByL1Address:
    get:
      summary: accountsByL1Address
      operationId: accountsByL1Address
      tags:
      - account
      description: Returns all accounts associated with the given L1 address
      parameters:
      - name: l1_address
        in: query
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubAccounts'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/apikeys:
    get:
      summary: apikeys
      operationId: apikeys
      tags:
      - account
      description: Get account api key. Set `api_key_index` to 255 to retrieve all api keys associated with the account.
      parameters:
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: api_key_index
        in: query
        required: false
        schema:
          type: integer
          format: uint8
          default: '255'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountApiKeys'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/changeAccountTier:
    post:
      summary: changeAccountTier
      operationId: changeAccountTier
      tags:
      - account
      description: Change account tier. You can only perform this action once every 24 hours, and with no orders or positions open.
      parameters:
      - name: authorization
        in: header
        required: false
        description: ' make required after integ is done'
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqChangeAccountTier'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespChangeAccountTier'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/l1Metadata:
    get:
      summary: l1Metadata
      operationId: l1Metadata
      tags:
      - account
      description: Get L1 metadata
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      - name: l1_address
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/L1Metadata'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/liquidations:
    get:
      summary: liquidations
      operationId: liquidations
      tags:
      - account
      description: Get liquidation infos
      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: cursor
        in: query
        required: false
        schema:
          type: string
      - 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/LiquidationInfos'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/pnl:
    get:
      summary: pnl
      operationId: pnl
      tags:
      - account
      description: Get account PnL chart
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
      - name: by
        in: query
        required: true
        schema:
          type: string
          enum:
          - index
      - name: value
        in: query
        required: true
        schema:
          type: string
      - name: resolution
        in: query
        required: true
        schema:
          type: string
          enum:
          - 1m
          - 5m
          - 15m
          - 1h
          - 4h
          - 1d
      - name: start_timestamp
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 0
          maximum: 5000000000000
      - name: end_timestamp
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 0
          maximum: 5000000000000
      - name: count_back
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: ignore_transfers
        in: query
        required: false
        schema:
          type: boolean
          format: boolean
          default: 'false'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountPnL'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/positionFunding:
    get:
      summary: positionFunding
      operationId: positionFunding
      tags:
      - account
      description: Get accounts position fundings
      parameters:
      - name: authorization
        in: header
        required: false
        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: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 100
      - name: side
        in: query
        required: false
        schema:
          type: string
          enum:
          - long
          - short
          - all
          default: all
      - name: start_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: end_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionFundings'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/publicPoolsMetadata:
    get:
      summary: publicPoolsMetadata
      operationId: publicPoolsMetadata
      tags:
      - account
      description: Get public pools metadata. `auth` is required in case you specify an account_index. You will see public pools with an index that starts an n-1 of the one you specify. To see staking pools, use `filter=stake`
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
      - name: filter
        in: query
        required: false
        schema:
          type: string
          enum:
          - all
          - user
          - protocol
          - account_index
          - stake
      - name: index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        required: true
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 100
      - name: account_index
        in: query
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespPublicPoolsMetadata'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/tokens:
    get:
      summary: tokens
      operationId: tokens
      tags:
      - account
      description: Get read only auth tokens for an account
      parameters:
      - name: authorization
        in: header
        required: false
        description: ' make required after integ is done'
        schema:
          type: string
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGetApiTokens'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/tokens/create:
    post:
      summary: tokens_create
      operationId: tokens_create
      tags:
      - account
      description: Create an API token for read-only access
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqPostApiToken'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespPostApiToken'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/tokens/revoke:
    post:
      summary: tokens_revoke
      operationId: tokens_revoke
      tags:
      - account
      description: Revoke read only auth token for an account
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqRevokeApiToken'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespRevokeApiToken'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/leaseOptions:
    get:
      summary: leaseOptions
      operationId: leaseOptions
      tags:
      - account
      description: Returns available lease duration/rate tiers, sorted by duration descending.
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGetLeaseOptions'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/leases:
    get:
      summary: leases
      operationId: leases
      tags:
      - account
      description: Returns paginated lease entries for an account, most recent first. Supports read-only auth via signature/account_index/timestamp query params.
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
        description: API token authorization
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
        description: Account index to fetch leases for
      - name: cursor
        in: query
        required: false
        schema:
          type: string
        description: Pagination cursor from a previous response
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          format: uint64
          minimum: 1
          maximum: 100
        description: Number of results to return (1–100, default 20)
      - name: auth
        in: query
        required: false
        schema:
          type: string
        description: Read-only auth (alternative to header authorization)
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGetLeases'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/litLease:
    post:
      summary: litLease
      operationId: litLease
      tags:
      - account
      description: 'Submit a LIT lease transfer. The server calculates the required fee based on lease_amount and duration_days, then executes the transfer. Fee formula (integer arithmetic): fee = lease_amount × (annual_rate × 100) × duration_days / (360 × 10000).'
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
        description: API token authorization
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqLITLease'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TxHash'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/referral/userReferrals:
    get:
      summary: userReferrals
      operationId: referral_userReferrals
      tags:
      - account
      description: Get user referrals
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
      - name: l1_address
        in: query
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: auth
        in: query
        required: false
        schema:
          type: string
      - name: stats_start_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: stats_end_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int64
          minimum: 1
          maximum: 300
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserReferrals'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/getMakerOnlyApiKeys:
    get:
      summary: getMakerOnlyApiKeys
      operationId: getMakerOnlyApiKeys
      tags:
      - account
      description: Get maker-only API key indexes
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGetMakerOnlyApiKeys'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/setMakerOnlyApiKeys:
    post:
      summary: setMakerOnlyApiKeys
      operationId: setMakerOnlyApiKeys
      tags:
      - account
      description: Set maker-only API key indexes. This replaces the current list; pass all indexes you want marked as maker-only. Pass [] to clear all maker-only restrictions.
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqSetMakerOnlyApiKeys'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ReqSetMakerOnlyApiKeys'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespSetMakerOnlyApiKeys'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/partnerStats:
    get:
      summary: partnerStats
      operationId: partnerStats
      description: Get partner stats. If timestamps are not provided, all-time stats will be returned.
      tags:
      - account
      parameters:
      - name: account_index
        in: query
        required: true
        schema:
          type: integer
          format: int64
      - name: start_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
      - name: end_timestamp
        in: query
        required: false
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerStats'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/rfq/respond:
    post:
      summary: rfq_respond
      operationId: rfq_respond
      tags:
      - account
      description: Respond to RFQ
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqRespondToRFQ'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespRespondToRFQ'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/rfq/list:
    get:
      summary: rfq_list
      operationId: rfq_list
      tags:
      - account
      description: List RFQs
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      - name: account_index
        in: query
        required: false
        schema:
          type: integer
          format: int64
          default: '281474976710655'
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - opened
          - order_created
          - closed
      - name: cursor
        in: query
        required: false
        schema:
          type: string
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int64
          default: '20'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespListRFQs'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/rfq/get:
    get:
      summary: rfq_get
      operationId: rfq_get
      tags:
      - account
      description: Get RFQ by ID
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      - name: rfq_id
        in: query
        required: true
        schema:
          type: integer
          format: int64
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespGetRFQ'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/rfq/create:
    post:
      summary: rfq_create
      operationId: rfq_create
      tags:
      - account
      description: Create RFQ
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqCreateRFQ'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespCreateRFQ'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
  /api/v1/rfq/update:
    post:
      summary: rfq_update
      operationId: rfq_update
      tags:
      - account
      description: Update RFQ status
      parameters:
      - name: authorization
        in: header
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ReqUpdateRFQ'
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RespUpdateRFQ'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResultCode'
components:
  schemas:
    Account:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        account_type:
          type: integer
          format: uint8
          example: '1'
        account_trading_mode:
          type: integer
          format: uint8
          example: '1'
          description: Classic=0 and Unified=1
        index:
          type: integer
          format: int64
          example: '1'
        l1_address:
          type: string
          example: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8'
        cancel_all_time:
          type: integer
          format: int64
          example: '1640995200'
        total_order_count:
          type: integer
          format: int64
          example: '100'
        total_isolated_order_count:
          type: integer
          format: int64
          example: '100'
        pending_order_count:
          type: integer
          format: int64
          example: '100'
        available_balance:
          type: string
          example: '19995'
        status:
          type: integer
          format: uint8
          example: '1'
        collateral:
          type: string
          example: '46342'
        transaction_time:
          type: integer
          format: int64
      title: Account
      required:
      - code
      - account_type
      - index
      - l1_address
      - cancel_all_time
      - total_order_count
      - total_isolated_order_count
      - pending_order_count
      - available_balance
      - status
      - collateral
      - account_trading_mode
      - transaction_time
    AccountPnL:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        resolution:
          type: string
          example: 15m
        pnl:
          type: array
          items:
            $ref: '#/components/schemas/PnLEntry'
      title: AccountPnL
      required:
      - code
      - resolution
      - pnl
    RFQResponseEntry:
      type: object
      properties:
        account_index:
          type: integer
          format: int64
        status:
          type: string
          enum:
          - acknowledged
          - liquidity_provided
          - not_interested
        responded_at:
          type: integer
          format: int64
        updated_at:
          type: integer
          format: int64
      title: RFQResponseEntry
      required:
      - account_index
      - status
      - responded_at
      - updated_at
    PnLEntry:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          example: '1640995200'
        trade_pnl:
          type: number
          format: double
          example: '12.0'
        inflow:
          type: number
          format: double
          example: '12.0'
        outflow:
          type: number
          format: double
          example: '12.0'
        pool_pnl:
          type: number
          format: double
          example: '12.0'
        pool_inflow:
          type: number
          format: double
          example: '12.0'
        pool_outflow:
          type: number
          format: double
          example: '12.0'
        pool_total_shares:
          type: number
          format: double
          example: '12.0'
        spot_inflow:
          type: number
          format: double
          example: '12.0'
        spot_outflow:
          type: number
          format: double
          example: '12.0'
        staked_lit:
          type: number
          format: double
          example: '12.0'
        staking_inflow:
          type: number
          format: double
          example: '12.0'
        staking_outflow:
          type: number
          format: double
          example: '12.0'
        staking_pnl:
          type: number
          format: double
          example: '12.0'
        trade_spot_pnl:
          type: number
          format: double
          example: '12.0'
        volume:
          type: number
          format: double
          example: '12.0'
      title: PnLEntry
      required:
      - timestamp
      - trade_pnl
      - inflow
      - outflow
      - pool_pnl
      - pool_inflow
      - pool_outflow
      - pool_total_shares
      - spot_inflow
      - spot_outflow
      - staked_lit
      - staking_inflow
      - staking_outflow
      - staking_pnl
      - trade_spot_pnl
      - volume
    ReqUpdateRFQ:
      type: object
      properti

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