> ## Documentation Index
> Fetch the complete documentation index at: https://docs.loopscale.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get historical collateral holders

> Returns, for each holder, the integral of their collateral balance over the requested time window — expressed as deposit-seconds (decimal-adjusted collateral units multiplied by seconds held). Useful for time-weighted depositor rewards, retroactive incentive splits, etc.

Event sources folded in:
  * AddCollateral (+amount, decimal-adjusted)
  * RemoveCollateral (−amount)
  * Liquidate (−sum of collateralTransfers[] matching the target mint where toLiquidator = true; the row's top-level amount is principal repaid and is ignored for collateral accounting)

Events with eventTime < rangeStart are collapsed into a single bucket at rangeStart so they establish the starting balance for the window. Events at exactly rangeEnd contribute zero seconds.

The mint filter is applied against loan_events_v1.asset_identifier for Add/Remove events and against per-transfer assetMint inside Liquidate metadata. For single-mint collateral these are equal; for CLP/LP collateral, asset_identifier is the pool id — callers should pass the pool id, not an underlying token mint.



## OpenAPI

````yaml post /markets/collateral/holders/historical
openapi: 3.1.3
info:
  title: Loopscale API
  version: 1.0.0
servers:
  - url: https://tars.loopscale.com/v1
    description: Loopscale Production Server
security: []
paths:
  /markets/collateral/holders/historical:
    post:
      summary: Time-weighted historical collateral deposits per holder
      description: >-
        Returns, for each holder, the integral of their collateral balance over
        the requested time window — expressed as deposit-seconds
        (decimal-adjusted collateral units multiplied by seconds held). Useful
        for time-weighted depositor rewards, retroactive incentive splits, etc.


        Event sources folded in:
          * AddCollateral (+amount, decimal-adjusted)
          * RemoveCollateral (−amount)
          * Liquidate (−sum of collateralTransfers[] matching the target mint where toLiquidator = true; the row's top-level amount is principal repaid and is ignored for collateral accounting)

        Events with eventTime < rangeStart are collapsed into a single bucket at
        rangeStart so they establish the starting balance for the window. Events
        at exactly rangeEnd contribute zero seconds.


        The mint filter is applied against loan_events_v1.asset_identifier for
        Add/Remove events and against per-transfer assetMint inside Liquidate
        metadata. For single-mint collateral these are equal; for CLP/LP
        collateral, asset_identifier is the pool id — callers should pass the
        pool id, not an underlying token mint.
      operationId: getHistoricalCollateralHolders
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HistoricalCollateralHolderFilter'
      responses:
        '200':
          $ref: '#/components/responses/HistoricalCollateralHoldersResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/GeneralError'
components:
  schemas:
    HistoricalCollateralHolderFilter:
      type: object
      required:
        - mint
        - rangeStart
        - rangeEnd
      properties:
        mint:
          type: string
          description: >-
            Collateral identifier to query. For standard SPL tokens this is the
            token mint; for CLP/LP positions it is the pool id (whatever is
            stored as asset_identifier on the loan event). Unknown mints return
            an empty result rather than an error.
          example: So11111111111111111111111111111111111111112
        rangeStart:
          type: integer
          format: int64
          description: >-
            Window start, unix seconds. Events before this timestamp are
            collapsed into a single starting-balance bucket at rangeStart.
          example: 1735689600
        rangeEnd:
          type: integer
          format: int64
          description: >-
            Window end, unix seconds. Must be >= rangeStart. Events with
            eventTime == rangeEnd contribute zero seconds (boundary).
          example: 1738368000
        pdas:
          type: boolean
          default: false
          description: >-
            Controls the holder identity in the response keys: false (default) —
            aggregate by loans.borrower (wallet). true — aggregate by loan
            address (le.loan). Each loan is a separate holder.
    HistoricalCollateralHolderStats:
      type: object
      required:
        - collateralMint
        - rangeStart
        - rangeEnd
        - userDepositSeconds
      properties:
        collateralMint:
          type: string
          description: Echo of the request mint.
        rangeStart:
          type: integer
          format: int64
          description: Echo of the request rangeStart.
        rangeEnd:
          type: integer
          format: int64
          description: Echo of the request rangeEnd.
        userDepositSeconds:
          type: object
          additionalProperties:
            type: number
            format: double
          description: >-
            Map of holder → integral of balance over the window. Units:
            decimal-adjusted token units × seconds. Keys: borrower wallet when
            pdas=false, loan address when pdas=true. Holders whose integrated
            value is within f64::EPSILON of zero are omitted.
  responses:
    HistoricalCollateralHoldersResponse:
      description: >-
        Array containing a single entry for the requested mint. Returned as an
        array (rather than a bare object) for parity with the active
        /collateral/holders endpoint, which fans out across multiple mints.
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/HistoricalCollateralHolderStats'
          examples:
            example:
              value:
                - collateralMint: So11111111111111111111111111111111111111112
                  rangeStart: 1735689600
                  rangeEnd: 1738368000
                  userDepositSeconds:
                    9xQe...borrower1: 2678400
                    Bz4k...borrower2: 1339200
    BadRequest:
      description: Bad Request
      content:
        text/plain:
          schema:
            type: string
            example: 'Something went wrong: You have an error in your SQL syntax.'
    GeneralError:
      description: General Server Error
      content:
        text/plain:
          schema:
            type: string
            example: >-
              Failed to deserialize the JSON body into the target type: missing
              field `mints` at line 1 column 1.

````