Lighter account API

openapi: 3.0.0
info:
  title: Lighter account API
  version: ''
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:
    ReqCreateRFQ:
      type: object
      properties:
        market_index:
          type: integer
          format: int16
        base_amount:
          type: string
        quote_amount:
          type: string
        direction:
          type: integer
          format: int16
          enum:
          - '0'
          - '1'
        metadata:
          type: string
      title: ReqCreateRFQ
      required:
      - market_index
      - direction
    AccountLimits:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        max_llp_percentage:
          type: integer
          format: int32
          example: '25'
        user_tier:
          type: string
          example: std
        can_create_public_pool:
          type: boolean
          format: boolean
          example: 'true'
        max_llp_amount:
          type: string
          example: '1000000'
        current_maker_fee_tick:
          type: integer
          format: int32
          example: '0'
        current_taker_fee_tick:
          type: integer
          format: int32
          example: '0'
        effective_lit_stakes:
          type: string
          description: Effective staked LIT shares including active leases.
        leased_lit:
          type: string
          description: Total actively leased LIT.
        user_tier_name:
          type: string
          example: standard
        user_tier_last_update:
          type: integer
          format: int64
      title: AccountLimits
      required:
      - code
      - max_llp_percentage
      - user_tier
      - can_create_public_pool
      - max_llp_amount
      - current_maker_fee_tick
      - current_taker_fee_tick
      - effective_lit_stakes
      - leased_lit
      - user_tier_name
    AccountMetadata:
      type: object
      properties:
        account_index:
          type: integer
          format: int64
        name:
          type: string
        description:
          type: string
        can_invite:
          type: boolean
          format: boolean
          description: ' Remove After FE uses L1 meta endpoint'
        referral_points_percentage:
          type: string
          description: ' Remove After FE uses L1 meta endpoint'
        created_at:
          type: integer
          format: int64
        can_rfq:
          type: boolean
          format: boolean
        can_rfq_market_ids:
          type: array
          items:
            type: string
      title: AccountMetadata
      required:
      - account_index
      - name
      - description
      - can_invite
      - referral_points_percentage
      - can_rfq
      - can_rfq_market_ids
      - created_at
    PublicPoolInfo:
      type: object
      properties:
        status:
          type: integer
          format: uint8
          example: '0'
        operator_fee:
          type: string
          example: '100'
        min_operator_share_rate:
          type: string
          example: '200'
        total_shares:
          type: integer
          format: int64
          example: '100000'
        operator_shares:
          type: integer
          format: int64
          example: '20000'
        annual_percentage_yield:
          type: number
          format: double
          example: '20.5000'
        daily_returns:
          type: array
          items:
            $ref: '#/components/schemas/DailyReturn'
        share_prices:
          type: array
          items:
            $ref: '#/components/schemas/SharePrice'
        sharpe_ratio:
          type: number
          format: double
        strategies:
          type: array
          items:
            $ref: '#/components/schemas/Strategy'
      title: PublicPoolInfo
      required:
      - status
      - operator_fee
      - min_operator_share_rate
      - total_shares
      - operator_shares
      - annual_percentage_yield
      - daily_returns
      - share_prices
      - sharpe_ratio
      - strategies
    RespListRFQs:
      type: object
      properties:
        code:
          type: integer
          format: int32
          example: '200'
        message:
          type: string
        rfqs:
          type: array
          items:
            $ref: '#/components/schemas/RFQEntry'
        next_cursor:
          type: string
      title: RespListRFQs
      required:
      - code
      - rfqs
    DailyReturn:
      type: object
      properties:
        timestamp:
          type: integer
          format: int64
          example: '1640995200'
        daily

# --- 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