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

> Returns a list of loans filtered by request. Results support pagination.



## OpenAPI

````yaml post /markets/loans/info
openapi: 3.1.0
info:
  title: Loopscale API
  version: 0.1.0
servers:
  - url: https://tars.loopscale.com/v1
    description: Loopscale Production Server
security: []
paths:
  /markets/loans/info:
    post:
      tags:
        - loans_data
      summary: Get loan information
      description: Returns a list of loans filtered by request. Results support pagination.
      operationId: route_get_loan_infos
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoanFilter'
        required: true
      responses:
        '200':
          description: List of loan data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoanSummary'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    LoanFilter:
      type: object
      properties:
        assetTypes:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
        borrowers:
          type: array
          items:
            type: string
          description: loan borrower
        collateralIdentifiers:
          type: array
          items:
            type: string
        collateralMints:
          type: array
          items:
            type: string
        excludeCollateralIdentifiers:
          type: array
          items:
            type: string
        excludeCollateralMints:
          type: array
          items:
            type: string
          description: >-
            Filters on `loan_collateral.asset_mint`, complementing

            `exclude_collateral_identifiers` (which filters on
            `asset_identifier`).

            For plain SPL collateral the two columns are equal; for LP/pool

            collateral `asset_identifier` is the pool_id, so excluding by mint

            alone won't catch those rows. Set both to cover both cases.
        excludePrincipalMints:
          type: array
          items:
            type: string
        filterType:
          type:
            - integer
            - 'null'
          format: int32
          description: filter type enum
          minimum: 0
        includePnl:
          type: boolean
          description: >-
            When true, `/loans/info` runs the PnL pipeline against the page's
            loans

            in parallel with the list-side pricing pass and stamps a

            `LoanPnlDetails` onto each `LoanSummaryItem`. Off by default so the

            dropdown/filter-edit calls that don't render PnL stay cheap.
        lenders:
          type: array
          items:
            type: string
          description: loan lender
        loanAddresses:
          type: array
          items:
            type: string
          description: loan address
        loopVaultPrincipalCollateralPairs:
          type: array
          items:
            $ref: '#/components/schemas/PrincipalCollateralPair'
        orderFundingTypes:
          type:
            - integer
            - 'null'
          format: int32
          minimum: 0
        page:
          type:
            - integer
            - 'null'
          format: int64
          minimum: 0
        pageSize:
          type:
            - integer
            - 'null'
          format: int64
          minimum: 0
        principalMints:
          type: array
          items:
            type: string
          description: principal
        sortSide:
          type: integer
          format: int32
          description: 'Sort direction: `0` = ascending, `1` = descending.'
          minimum: 0
        sortType:
          type: integer
          format: int32
          description: Sort key (see `LoanInfoSorting` discriminants).
          minimum: 0
      additionalProperties: false
    LoanSummary:
      type: object
      required:
        - items
        - pageInfo
        - aggregate
        - snapshotTs
        - principalMints
        - collateralMints
      properties:
        aggregate:
          $ref: '#/components/schemas/LoansAggregate'
        collateralMints:
          type: array
          items:
            type: string
        items:
          type: array
          items:
            $ref: '#/components/schemas/LoanSummaryItem'
          description: Per-loan items (each flattens the loan snapshot + USD/risk fields).
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
        principalMints:
          type: array
          items:
            type: string
        snapshotTs:
          type: integer
          format: int64
    ErrorResponse:
      type: object
      description: |-
        Canonical error envelope for every endpoint. The `x-request-id` response
        header carries the correlation id for the failing request.
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetails'
          description: error detail
    PrincipalCollateralPair:
      type: object
      required:
        - principalAssetIdentifier
        - collateralAssetIdentifier
      properties:
        collateralAssetIdentifier:
          type: string
        principalAssetIdentifier:
          type: string
    LoansAggregate:
      type: object
      description: >-
        Filter-scoped aggregate over the full matched loan set. USD fields use
        the

        request's pinned oracle snapshot. APYs are returned in fractional form

        (0.085 = 8.5%), not cbps.


        `dailyInterestUsd`, `dailyCollateralYieldUsd`, and
        `dailyPrincipalYieldUsd`

        are role-neutral primitives. The FE composes role-specific composites:
          - Borrower daily net carry: `dailyCollateralYieldUsd − dailyInterestUsd`
          - Lender daily net carry:   `dailyInterestUsd`
          - Loop net daily yield:     `dailyCollateralYieldUsd − dailyInterestUsd − dailyPrincipalYieldUsd`
            (loops borrow yield-bearing principals like JLP/mSOL where the borrowed
            asset itself appreciates — that appreciation is a real cost on the debt
            leg captured by `dailyPrincipalYieldUsd`).

        **`interestEarnedAllTimeUsd` is currently always 0** on this endpoint —

        closed loans have `interest_outstanding = 0` so a SUM-by-mint approach
        can't

        recover the realized interest. Lender lifetime interest should be
        sourced

        from `/strategy/infos` (which uses
        `strategy.cumulative_interest_accrued`).

        Borrower lifetime interest is not currently computable; revisit by
        parsing

        `loan_events_v1.action_metadata` for `RepayPrincipal` events if needed.


        `pnlUsd` is computed as `collateralUsd − principalUsd −
        interestAccruedUsd

        − Σ netInflowUsd` where net inflow is the borrower's net dollar
        contribution

        from `account_balance_changes` (cached event-time USD). Reflects
        realized +

        unrealized PnL combined.
      required:
        - count
        - collateralUsd
        - principalUsd
        - interestAccruedUsd
        - interestEarnedAllTimeUsd
        - wAvgApy
        - wAvgCollateralApy
        - pendingYieldUsd
        - dailyInterestUsd
        - dailyCollateralYieldUsd
        - dailyPrincipalYieldUsd
      properties:
        collateralUsd:
          type: number
          format: double
          description: |-
            Sum of `loan_collateral.amount × snapshot_price` across the rows in
            scope, priced at the snapshot. Zero on non-loop *group* aggregates —
            see `ApiUserLoanGroup.aggregate` for the rationale.
        count:
          type: integer
          format: int64
          description: >-
            Number of loans folded into this aggregate (dedup'd by
            `loans.address`).
          minimum: 0
        dailyCollateralYieldUsd:
          type: number
          format: double
          description: |-
            Borrower's daily collateral-yield carry in USD across the rows in
            scope = `Σ(collateralUsd × cyl.apy) / 365`. Same unrounded-numerator
            approach as `dailyInterestUsd`.
        dailyInterestUsd:
          type: number
          format: double
          description: >-
            Borrower's daily interest carry in USD across the rows in scope =

            `Σ(principalUsd × apy) / 365`. Computed off the unrounded weighted

            numerator (not `principalUsd × wAvgApy`) to avoid post-rounding
            drift.
        dailyPrincipalYieldUsd:
          type: number
          format: double
          description: >-
            Daily yield foregone on the borrowed principal (when principal mint
            is

            yield-bearing). Zero for plain USDC/etc. borrows. Used to compute
            loop

            net APY; safe to ignore for non-loop filters.
        interestAccruedUsd:
          type: number
          format: double
          description: |-
            Sum of `interest_outstanding` (accrued-but-unpaid) across active
            ledgers in scope, priced at the snapshot.
        interestEarnedAllTimeUsd:
          type: number
          format: double
          description: Always 0 on this endpoint — see struct doc comment.
        pendingYieldUsd:
          type: number
          format: double
          description: >-
            Pending unclaimed LP fees in USD for CLMM-style collateral positions

            (sum of `lp_fees_usd` over matching `asset_mint`s in scope). Zero
            for

            non-LP collateral.
        pnlUsd:
          type:
            - number
            - 'null'
          format: double
          description: >-
            `collateralUsd − principalUsd − interestAccruedUsd − Σ
            netInflowUsd`.

            Negative = net loss (including borrower's cost basis from collateral

            deposits). Positive = net gain. See struct doc for full details.


            `Option` only to allow omission in edge cases; in practice always
            set.

            For loop aggregates this is the cost-basis `usdPnl` (Σ per-loan);
            paired

            with `tokenUsdPnl` (in-kind), the FE picks which to display per its

            leverage rule.
        principalUsd:
          type: number
          format: double
          description: |-
            Sum of outstanding principal `(principal_due − principal_repaid)`
            across active ledgers in scope, priced at the snapshot.
        tokenUsdPnl:
          type:
            - number
            - 'null'
          format: double
          description: >-
            Σ of per-loan `tokenUsdPnl` (in-kind collateral PnL re-priced at the

            current collateral price) across the loop loans in scope. `Some` for

            loop aggregates; `None` when no loop loan contributed a value (e.g.
            all

            CLMM/LP collateral — FE falls back to `pnlUsd`).
        wAvgApy:
          type: number
          format: double
          description: |-
            USD-weighted average of `ledgers.apy` (borrow rate), weighted by
            `principalUsd`.
        wAvgCollateralApy:
          type: number
          format: double
          description: >-
            USD-weighted average of collateral yield APY (`cyl.apy`), weighted
            by

            `collateralUsd`.
    LoanSummaryItem:
      allOf:
        - $ref: '#/components/schemas/LoanInfoSnapshot'
        - type: object
          required:
            - collateralUsd
            - principalUsd
            - interestAccruedUsd
            - collateralUsdRisk
            - principalUsdRisk
            - collateralBreakdown
            - pendingYieldUsd
            - pnlUsd
          properties:
            collateralBreakdown:
              type: array
              items:
                $ref: '#/components/schemas/CollateralBreakdown'
            collateralUsd:
              type: number
              format: double
            collateralUsdRisk:
              type: number
              format: double
            interestAccruedUsd:
              type: number
              format: double
            pendingYieldUsd:
              type: number
              format: double
            pnl:
              oneOf:
                - type: 'null'
                - $ref: '#/components/schemas/LoanPnlDetails'
                  description: >-
                    Populated only when the request set
                    `LoanFilter.include_pnl=true`. Same

                    per-loan breakdown the standalone `/loans/pnl` endpoint
                    returns

                    (omitting graph series, which only the detail page uses).
            pnlUsd:
              type: number
              format: double
            principalUsd:
              type: number
              format: double
            principalUsdRisk:
              type: number
              format: double
    PageInfo:
      type: object
      description: >-
        Pagination envelope shared across paginated listing endpoints

        (`/loans/info`, `/strategy/infos`, `/loop/info/v2`,
        `/lending_vaults/user/v2`).

        `totalItems` / `totalPages` are filter-scoped, not page-scoped.
      required:
        - page
        - pageSize
        - totalItems
        - totalPages
      properties:
        page:
          type: integer
          format: int64
          description: 0-indexed page number echoed back from the request.
          minimum: 0
        pageSize:
          type: integer
          format: int64
          description: |-
            Maximum item count per page applied by the server (may differ from
            the request's `pageSize` if the request was 0 or above the cap).
          minimum: 0
        totalItems:
          type: integer
          format: int64
          description: |-
            Total item count across the *filter* scope (not just this page).
            What "item" counts as depends on the endpoint — for grouped
            endpoints this is the count of distinct groups, not loans/rows.
          minimum: 0
        totalPages:
          type: integer
          format: int64
          description: '`ceil(totalItems / pageSize)`.'
          minimum: 0
    ErrorDetails:
      type: object
      description: Inner detail of the [`ErrorResponse`] envelope.
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: HTTP status code, mirrored in the response status line
          example: 400
          minimum: 0
        message:
          type: string
          description: human-readable, client-safe message (sensitive data redacted)
          example: Request could not be processed.
    LoanInfoSnapshot:
      type: object
      required:
        - loan
        - loanType
        - ledgers
        - collateral
        - collateralYieldPct
        - principalYieldPct
      properties:
        collateral:
          type: array
          items:
            $ref: '#/components/schemas/LoanCollateral'
        collateralYieldPct:
          type: number
          format: double
        ledgers:
          type: array
          items:
            $ref: '#/components/schemas/Ledger'
        loan:
          $ref: '#/components/schemas/Loan'
        loanType:
          type: integer
          format: int32
          minimum: 0
        principalYieldPct:
          type: number
          format: double
    CollateralBreakdown:
      type: object
      required:
        - assetIdentifier
        - usd
      properties:
        assetIdentifier:
          type: string
        usd:
          type: number
          format: double
    LoanPnlDetails:
      type: object
      properties:
        collateralPnl:
          type:
            - integer
            - 'null'
          format: int64
        collateralPnlPctChange:
          type:
            - number
            - 'null'
          format: double
        initialUserCollateralContribution:
          type:
            - integer
            - 'null'
          format: int64
        initialUserCollateralContributionUsd:
          type:
            - number
            - 'null'
          format: double
        markers:
          type: array
          items:
            $ref: '#/components/schemas/ChartDataMarker'
          description: >-
            Rollover and other chart annotations (same list for all charts;
            derived from PnL series).
        netCollateralInflow:
          type:
            - integer
            - 'null'
          format: int64
        netCollateralUsdInflow:
          type:
            - number
            - 'null'
          format: double
        netPrincipalInflow:
          type:
            - integer
            - 'null'
          format: int64
        netPrincipalUsdInflow:
          type:
            - number
            - 'null'
          format: double
        pnlData:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PnLGraphData'
        positionValueData:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/PositionValueGraphData'
        rateHistoryData:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/RateHistoryGraphData'
        tokenUsdPnl:
          type:
            - number
            - 'null'
          format: double
          description: >-
            In-kind PnL re-priced at the **current** collateral spot price

            (`collateralPnl_ui × currentCollateralPrice`) — the value the loop

            position card shows for non-leverage loops. `Some` only for loop
            loans

            with single-token collateral and an available current price; `None`
            for

            non-loop loans, CLMM/LP collateral, or missing price (FE falls back
            to

            `usdPnl`). Leverage loops carry it too, but the card uses `usdPnl`.
        usdPnl:
          type:
            - number
            - 'null'
          format: double
        usdPnlPctChange:
          type:
            - number
            - 'null'
          format: double
    LoanCollateral:
      type: object
      required:
        - loan
        - index
        - assetType
        - assetIdentifier
        - assetMint
        - amount
      properties:
        amount:
          type: integer
          format: int64
          minimum: 0
        assetIdentifier:
          type: string
        assetMint:
          type: string
        assetType:
          type: integer
          format: int32
          minimum: 0
        id:
          type: integer
          format: int32
          minimum: 0
        index:
          type: integer
          format: int32
          minimum: 0
        lastInteractedTime:
          type: integer
          format: int64
          minimum: 0
        lastInteractedTxn:
          type: string
        loan:
          type: string
        writeVersion:
          type: integer
          format: int64
          minimum: 0
    Ledger:
      type: object
      required:
        - ledgerIndex
        - loan
        - status
        - strategy
        - principalMint
        - marketInformation
        - principalDue
        - principalRepaid
        - interestOutstanding
        - lastInterestUpdatedTime
        - interestPerSecond
        - duration
        - durationType
        - startTime
        - endTime
        - apy
        - weights
        - ltvRatios
        - lqtRatios
        - lastInteractedTime
        - lastInteractedTxn
      properties:
        apy:
          type: integer
          format: int64
          minimum: 0
        duration:
          type: integer
          format: int32
          minimum: 0
        durationType:
          type: integer
          format: int32
          minimum: 0
        endTime:
          type: integer
          format: int64
          minimum: 0
        id:
          type: integer
          format: int32
          minimum: 0
        interestOutstanding:
          type: integer
          format: int64
          minimum: 0
        interestPerSecond:
          type: number
          format: double
        isLoop:
          type: integer
          format: int32
        lastInteractedTime:
          type: integer
          format: int64
          minimum: 0
        lastInteractedTxn:
          type: string
        lastInterestUpdatedTime:
          type: integer
          format: int64
          minimum: 0
        ledgerIndex:
          type: integer
          format: int32
          minimum: 0
        loan:
          type: string
        lqtRatios:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
          description: >-
            Per-collateral liquidation thresholds (cbps), same index order as
            `weights`.
        ltvRatios:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
          description: >-
            Per-collateral loan-to-value ratios (cbps), same index order as
            `weights`.
        marketInformation:
          type: string
        principalDue:
          type: integer
          format: int64
          minimum: 0
        principalMint:
          type: string
        principalRepaid:
          type: integer
          format: int64
          minimum: 0
        startTime:
          type: integer
          format: int64
          minimum: 0
        status:
          type: integer
          format: int32
          minimum: 0
        strategy:
          type: string
        weights:
          type: array
          items:
            type: integer
            format: int32
            minimum: 0
          description: >-
            Weight matrix: per-collateral weight (cbps), indexed by the market's

            collateral map. Drives how each collateral backs this ledger's
            principal.
        writeVersion:
          type: integer
          format: int64
          minimum: 0
    Loan:
      type: object
      required:
        - address
        - bump
        - loanStatus
        - nonce
        - borrower
        - startTime
        - closed
        - lastInteractedTime
        - lastInteractedTxn
        - writeVersion
      properties:
        address:
          type: string
        borrower:
          type: string
        bump:
          type: integer
          format: int32
          minimum: 0
        closed:
          type: boolean
        id:
          type: integer
          format: int32
          minimum: 0
        lastInteractedTime:
          type: integer
          format: int64
          minimum: 0
        lastInteractedTxn:
          type: string
        loanStatus:
          type: integer
          format: int32
          minimum: 0
        nonce:
          type: integer
          format: int64
          minimum: 0
        startTime:
          type: integer
          format: int64
          minimum: 0
        writeVersion:
          type: integer
          format: int64
          minimum: 0
    ChartDataMarker:
      type: object
      description: >-
        Chart annotation: timestamp + marker kind + optional payload (not nested
        on series rows).
      required:
        - date
        - type
      properties:
        date:
          type: integer
          format: int64
        metadata:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ChartMarkerMetadata'
        type:
          $ref: '#/components/schemas/ChartMarkerType'
    PnLGraphData:
      type: object
      description: PnL graph data
      required:
        - dataPoints
      properties:
        dataPoints:
          type: array
          items:
            $ref: '#/components/schemas/PnLDataPoint'
    PositionValueGraphData:
      type: object
      description: Position value graph data
      required:
        - dataPoints
      properties:
        dataPoints:
          type: array
          items:
            $ref: '#/components/schemas/PositionValueDataPoint'
    RateHistoryGraphData:
      type: object
      description: Rate history graph data
      required:
        - dataPoints
      properties:
        dataPoints:
          type: array
          items:
            $ref: '#/components/schemas/RateHistoryDataPoint'
    ChartMarkerMetadata:
      oneOf:
        - $ref: '#/components/schemas/ChartMarkerMetadataRollover'
      description: >-
        Marker payload union (untagged so we don't duplicate the top-level
        `type` discriminator).
    ChartMarkerType:
      type: string
      description: Marker type for charts.
      enum:
        - rollover
    PnLDataPoint:
      type: object
      required:
        - date
      properties:
        collateralPrice:
          type:
            - number
            - 'null'
          format: double
          description: Collateral token price in USD at this timestamp
        collateralValueUsd:
          type:
            - number
            - 'null'
          format: double
          description: Collateral value in USD
        date:
          type: integer
          format: int64
          description: Unix timestamp
        isProjection:
          type: boolean
          description: Whether this is a projection
        netCollateralTransferTokenAmount:
          type:
            - number
            - 'null'
          format: double
          description: Net collateral transfer in collateral token amount (UI amount)
        netCollateralTransferUsdAmount:
          type:
            - number
            - 'null'
          format: double
          description: Net collateral transfer USD amount (cost basis)
        netPositionValueTokenAmount:
          type:
            - number
            - 'null'
          format: double
          description: Net position value in collateral token amount (UI amount)
        netPositionValueUsd:
          type:
            - number
            - 'null'
          format: double
          description: Net position value in USD
        principalValueUsd:
          type:
            - number
            - 'null'
          format: double
          description: Principal value in USD
        tokenPnl:
          type:
            - integer
            - 'null'
          format: int64
          description: Token PnL (in collateral token base units)
        usdPnl:
          type:
            - number
            - 'null'
          format: double
          description: USD PnL
    PositionValueDataPoint:
      type: object
      required:
        - date
        - collateralMint
      properties:
        collateralMint:
          type: string
          description: >-
            Active collateral mint at this timestamp (can change during
            rollovers)
        collateralTokenAmount:
          type:
            - number
            - 'null'
          format: double
          description: Collateral token amount (UI amount)
        collateralTokenAmountOfDebt:
          type:
            - number
            - 'null'
          format: double
          description: Collateral token amount of debt (UI amount)
        collateralValueUsd:
          type:
            - number
            - 'null'
          format: double
          description: Collateral value in USD
        date:
          type: integer
          format: int64
          description: Unix timestamp
        isProjection:
          type: boolean
          description: Whether this is a projection
        netPositionValueTokenAmount:
          type:
            - number
            - 'null'
          format: double
          description: Net position value in collateral token amount (UI amount)
        netPositionValueUsd:
          type:
            - number
            - 'null'
          format: double
          description: Net position value in USD
        principalValueUsd:
          type:
            - number
            - 'null'
          format: double
          description: Principal value in USD
    RateHistoryDataPoint:
      type: object
      required:
        - date
        - collateralMint
      properties:
        borrowApy:
          type:
            - number
            - 'null'
          format: double
          description: Borrow APY (as percentage)
        collateralApy:
          type:
            - number
            - 'null'
          format: double
          description: Collateral/Yield APY (as percentage)
        collateralMint:
          type: string
          description: >-
            Active collateral mint at this timestamp (can change during
            rollovers)
        date:
          type: integer
          format: int64
          description: Unix timestamp
        isProjection:
          type: boolean
          description: Whether this is a projection
        netApy:
          type:
            - number
            - 'null'
          format: double
          description: Net leveraged APY (as percentage, e.g., 15.5 for 15.5%)
    ChartMarkerMetadataRollover:
      type: object
      description: >-
        Optional payload for chart markers (payload only; marker kind lives on
        `ChartDataMarker.type`).
      required:
        - previousCollateralMint
        - newCollateralMint
      properties:
        newCollateralMint:
          type: string
        previousCollateralMint:
          type: string

````