--- title: "Get loan information" method: POST path: "/markets/loans/info" tags: ["loans_data"] --- # Get loan information `POST /markets/loans/info` Returns a list of loans filtered by request. Results support pagination. ## Request body - LoanFilter - `assetTypes` integer[] - `borrowers` string[] — loan borrower - `collateralIdentifiers` string[] - `collateralMints` string[] - `excludeCollateralIdentifiers` string[] - `excludeCollateralMints` string[] — 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` string[] - `filterType` integer, nullable — filter type enum - `includePnl` boolean — 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` string[] — loan lender - `loanAddresses` string[] — loan address - `loopVaultPrincipalCollateralPairs` PrincipalCollateralPair[] - `collateralAssetIdentifier` string, required - `principalAssetIdentifier` string, required - `orderFundingTypes` integer, nullable - `page` integer, nullable - `pageSize` integer, nullable - `principalMints` string[] — principal - `sortSide` integer — Sort direction: `0` = ascending, `1` = descending. - `sortType` integer — Sort key (see `LoanInfoSorting` discriminants). ## Response `200` List of loan data - LoanSummary - `aggregate` LoansAggregate, required — 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. - `collateralUsd` number, double, required — 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` integer, required — Number of loans folded into this aggregate (dedup'd by `loans.address`). - `dailyCollateralYieldUsd` number, double, required — Borrower's daily collateral-yield carry in USD across the rows in scope = `Σ(collateralUsd × cyl.apy) / 365`. Same unrounded-numerator approach as `dailyInterestUsd`. - `dailyInterestUsd` number, double, required — 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` number, double, required — 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` number, double, required — Sum of `interest_outstanding` (accrued-but-unpaid) across active ledgers in scope, priced at the snapshot. - `interestEarnedAllTimeUsd` number, double, required — Always 0 on this endpoint — see struct doc comment. - `pendingYieldUsd` number, double, required — 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` number, double, nullable — `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` number, double, required — Sum of outstanding principal `(principal_due − principal_repaid)` across active ledgers in scope, priced at the snapshot. - `tokenUsdPnl` number, double, nullable — Σ 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` number, double, required — USD-weighted average of `ledgers.apy` (borrow rate), weighted by `principalUsd`. - `wAvgCollateralApy` number, double, required — USD-weighted average of collateral yield APY (`cyl.apy`), weighted by `collateralUsd`. - `collateralMints` string[], required - `items` LoanSummaryItem[], required — Per-loan items (each flattens the loan snapshot + USD/risk fields). - `collateral` LoanCollateral[], required - `amount` integer, required - `assetIdentifier` string, required - `assetMint` string, required - `assetType` integer, required - `id` integer - `index` integer, required - `lastInteractedTime` integer - `lastInteractedTxn` string - `loan` string, required - `writeVersion` integer - `collateralYieldPct` number, double, required - `ledgers` Ledger[], required - `apy` integer, required - `duration` integer, required - `durationType` integer, required - `endTime` integer, required - `id` integer - `interestOutstanding` integer, required - `interestPerSecond` number, double, required - `isLoop` integer - `lastInteractedTime` integer, required - `lastInteractedTxn` string, required - `lastInterestUpdatedTime` integer, required - `ledgerIndex` integer, required - `loan` string, required - `lqtRatios` integer[], required — Per-collateral liquidation thresholds (cbps), same index order as `weights`. - `ltvRatios` integer[], required — Per-collateral loan-to-value ratios (cbps), same index order as `weights`. - `marketInformation` string, required - `principalDue` integer, required - `principalMint` string, required - `principalRepaid` integer, required - `startTime` integer, required - `status` integer, required - `strategy` string, required - `weights` integer[], required — Weight matrix: per-collateral weight (cbps), indexed by the market's collateral map. Drives how each collateral backs this ledger's principal. - `writeVersion` integer - `loan` Loan, required - `address` string, required - `borrower` string, required - `bump` integer, required - `closed` boolean, required - `id` integer - `lastInteractedTime` integer, required - `lastInteractedTxn` string, required - `loanStatus` integer, required - `nonce` integer, required - `startTime` integer, required - `writeVersion` integer, required - `loanType` integer, required - `principalYieldPct` number, double, required - `collateralBreakdown` CollateralBreakdown[], required - `assetIdentifier` string, required - `usd` number, double, required - `collateralUsd` number, double, required - `collateralUsdRisk` number, double, required - `interestAccruedUsd` number, double, required - `pendingYieldUsd` number, double, required - `pnl` LoanPnlDetails - `collateralPnl` integer, nullable - `collateralPnlPctChange` number, double, nullable - `initialUserCollateralContribution` integer, nullable - `initialUserCollateralContributionUsd` number, double, nullable - `markers` ChartDataMarker[] — Rollover and other chart annotations (same list for all charts; derived from PnL series). - `date` integer, required - `metadata` ChartMarkerMetadata — Optional payload for chart markers (payload only; marker kind lives on `ChartDataMarker.type`). - `newCollateralMint` string, required - `previousCollateralMint` string, required - `type` 'rollover', required — Marker type for charts. - `netCollateralInflow` integer, nullable - `netCollateralUsdInflow` number, double, nullable - `netPrincipalInflow` integer, nullable - `netPrincipalUsdInflow` number, double, nullable - `pnlData` PnLGraphData — PnL graph data - `dataPoints` PnLDataPoint[], required - `collateralPrice` number, double, nullable — Collateral token price in USD at this timestamp - `collateralValueUsd` number, double, nullable — Collateral value in USD - `date` integer, required — Unix timestamp - `isProjection` boolean — Whether this is a projection - `netCollateralTransferTokenAmount` number, double, nullable — Net collateral transfer in collateral token amount (UI amount) - `netCollateralTransferUsdAmount` number, double, nullable — Net collateral transfer USD amount (cost basis) - `netPositionValueTokenAmount` number, double, nullable — Net position value in collateral token amount (UI amount) - `netPositionValueUsd` number, double, nullable — Net position value in USD - `principalValueUsd` number, double, nullable — Principal value in USD - `tokenPnl` integer, nullable — Token PnL (in collateral token base units) - `usdPnl` number, double, nullable — USD PnL - `positionValueData` PositionValueGraphData — Position value graph data - `dataPoints` PositionValueDataPoint[], required - `collateralMint` string, required — Active collateral mint at this timestamp (can change during rollovers) - `collateralTokenAmount` number, double, nullable — Collateral token amount (UI amount) - `collateralTokenAmountOfDebt` number, double, nullable — Collateral token amount of debt (UI amount) - `collateralValueUsd` number, double, nullable — Collateral value in USD - `date` integer, required — Unix timestamp - `isProjection` boolean — Whether this is a projection - `netPositionValueTokenAmount` number, double, nullable — Net position value in collateral token amount (UI amount) - `netPositionValueUsd` number, double, nullable — Net position value in USD - `principalValueUsd` number, double, nullable — Principal value in USD - `rateHistoryData` RateHistoryGraphData — Rate history graph data - `dataPoints` RateHistoryDataPoint[], required - `borrowApy` number, double, nullable — Borrow APY (as percentage) - `collateralApy` number, double, nullable — Collateral/Yield APY (as percentage) - `collateralMint` string, required — Active collateral mint at this timestamp (can change during rollovers) - `date` integer, required — Unix timestamp - `isProjection` boolean — Whether this is a projection - `netApy` number, double, nullable — Net leveraged APY (as percentage, e.g., 15.5 for 15.5%) - `tokenUsdPnl` number, double, nullable — 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` number, double, nullable - `usdPnlPctChange` number, double, nullable - `pnlUsd` number, double, required - `principalUsd` number, double, required - `principalUsdRisk` number, double, required - `pageInfo` PageInfo, required — 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. - `page` integer, required — 0-indexed page number echoed back from the request. - `pageSize` integer, required — 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). - `totalItems` integer, required — 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. - `totalPages` integer, required — `ceil(totalItems / pageSize)`. - `principalMints` string[], required - `snapshotTs` integer, required ## Other responses - `400` - `401` - `500` --- [API](https://skmtc.dev/loopscale/apis/loopscale-api.md) · [All operations](https://skmtc.dev/loopscale/apis/loopscale-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/loopscale/loopscale-api/revisions/531f64dbe09c/schema)