{ "openapi": "3.1.0", "info": { "title": "Loopscale API", "version": "0.1.0" }, "servers": [ { "url": "https://tars.loopscale.com/v1", "description": "Loopscale Production Server" } ], "paths": { "/markets/loans/info": { "post": { "tags": [ "loans_data" ], "summary": "Get loan information", "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" } } } } }, "description": "Returns a list of loans filtered by request. Results support pagination." } } }, "components": { "schemas": { "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" } } }, "ChartMarkerMetadata": { "oneOf": [ { "$ref": "#/components/schemas/ChartMarkerMetadataRollover" } ], "description": "Marker payload union (untagged so we don't duplicate the top-level `type` discriminator)." }, "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" } } }, "ChartMarkerType": { "type": "string", "description": "Marker type for charts.", "enum": [ "rollover" ] }, "CollateralBreakdown": { "type": "object", "required": [ "assetIdentifier", "usd" ], "properties": { "assetIdentifier": { "type": "string" }, "usd": { "type": "number", "format": "double" } } }, "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." } } }, "ErrorResponse": { "type": "object", "description": "Canonical error envelope for every endpoint. The `x-request-id` response\nheader carries the correlation id for the failing request.", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorDetails", "description": "error detail" } } }, "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\ncollateral 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 } } }, "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 } } }, "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\n`exclude_collateral_identifiers` (which filters on `asset_identifier`).\nFor plain SPL collateral the two columns are equal; for LP/pool\ncollateral `asset_identifier` is the pool_id, so excluding by mint\nalone 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\nin parallel with the list-side pricing pass and stamps a\n`LoanPnlDetails` onto each `LoanSummaryItem`. Off by default so the\ndropdown/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 }, "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" } } }, "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\n(`collateralPnl_ui × currentCollateralPrice`) — the value the loop\nposition card shows for non-leverage loops. `Some` only for loop loans\nwith single-token collateral and an available current price; `None` for\nnon-loop loans, CLMM/LP collateral, or missing price (FE falls back to\n`usdPnl`). Leverage loops carry it too, but the card uses `usdPnl`." }, "usdPnl": { "type": [ "number", "null" ], "format": "double" }, "usdPnlPctChange": { "type": [ "number", "null" ], "format": "double" } } }, "LoansAggregate": { "type": "object", "description": "Filter-scoped aggregate over the full matched loan set. USD fields use the\nrequest's pinned oracle snapshot. APYs are returned in fractional form\n(0.085 = 8.5%), not cbps.\n\n`dailyInterestUsd`, `dailyCollateralYieldUsd`, and `dailyPrincipalYieldUsd`\nare role-neutral primitives. The FE composes role-specific composites:\n - Borrower daily net carry: `dailyCollateralYieldUsd − dailyInterestUsd`\n - Lender daily net carry: `dailyInterestUsd`\n - Loop net daily yield: `dailyCollateralYieldUsd − dailyInterestUsd − dailyPrincipalYieldUsd`\n (loops borrow yield-bearing principals like JLP/mSOL where the borrowed\n asset itself appreciates — that appreciation is a real cost on the debt\n leg captured by `dailyPrincipalYieldUsd`).\n\n**`interestEarnedAllTimeUsd` is currently always 0** on this endpoint —\nclosed loans have `interest_outstanding = 0` so a SUM-by-mint approach can't\nrecover the realized interest. Lender lifetime interest should be sourced\nfrom `/strategy/infos` (which uses `strategy.cumulative_interest_accrued`).\nBorrower lifetime interest is not currently computable; revisit by parsing\n`loan_events_v1.action_metadata` for `RepayPrincipal` events if needed.\n\n`pnlUsd` is computed as `collateralUsd − principalUsd − interestAccruedUsd\n− Σ netInflowUsd` where net inflow is the borrower's net dollar contribution\nfrom `account_balance_changes` (cached event-time USD). Reflects realized +\nunrealized 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\nscope, priced at the snapshot. Zero on non-loop *group* aggregates —\nsee `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\nscope = `Σ(collateralUsd × cyl.apy) / 365`. Same unrounded-numerator\napproach as `dailyInterestUsd`." }, "dailyInterestUsd": { "type": "number", "format": "double", "description": "Borrower's daily interest carry in USD across the rows in scope =\n`Σ(principalUsd × apy) / 365`. Computed off the unrounded weighted\nnumerator (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\nyield-bearing). Zero for plain USDC/etc. borrows. Used to compute loop\nnet APY; safe to ignore for non-loop filters." }, "interestAccruedUsd": { "type": "number", "format": "double", "description": "Sum of `interest_outstanding` (accrued-but-unpaid) across active\nledgers 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\n(sum of `lp_fees_usd` over matching `asset_mint`s in scope). Zero for\nnon-LP collateral." }, "pnlUsd": { "type": [ "number", "null" ], "format": "double", "description": "`collateralUsd − principalUsd − interestAccruedUsd − Σ netInflowUsd`.\nNegative = net loss (including borrower's cost basis from collateral\ndeposits). Positive = net gain. See struct doc for full details.\n\n`Option` only to allow omission in edge cases; in practice always set.\nFor loop aggregates this is the cost-basis `usdPnl` (Σ per-loan); paired\nwith `tokenUsdPnl` (in-kind), the FE picks which to display per its\nleverage rule." }, "principalUsd": { "type": "number", "format": "double", "description": "Sum of outstanding principal `(principal_due − principal_repaid)`\nacross 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\ncurrent collateral price) across the loop loans in scope. `Some` for\nloop aggregates; `None` when no loop loan contributed a value (e.g. all\nCLMM/LP collateral — FE falls back to `pnlUsd`)." }, "wAvgApy": { "type": "number", "format": "double", "description": "USD-weighted average of `ledgers.apy` (borrow rate), weighted by\n`principalUsd`." }, "wAvgCollateralApy": { "type": "number", "format": "double", "description": "USD-weighted average of collateral yield APY (`cyl.apy`), weighted by\n`collateralUsd`." } } }, "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" } } }, "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\nper-loan breakdown the standalone `/loans/pnl` endpoint returns\n(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\n(`/loans/info`, `/strategy/infos`, `/loop/info/v2`, `/lending_vaults/user/v2`).\n`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\nthe 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).\nWhat \"item\" counts as depends on the endpoint — for grouped\nendpoints this is the count of distinct groups, not loans/rows.", "minimum": 0 }, "totalPages": { "type": "integer", "format": "int64", "description": "`ceil(totalItems / pageSize)`.", "minimum": 0 } } }, "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" } } }, "PnLGraphData": { "type": "object", "description": "PnL graph data", "required": [ "dataPoints" ], "properties": { "dataPoints": { "type": "array", "items": { "$ref": "#/components/schemas/PnLDataPoint" } } } }, "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" } } }, "PositionValueGraphData": { "type": "object", "description": "Position value graph data", "required": [ "dataPoints" ], "properties": { "dataPoints": { "type": "array", "items": { "$ref": "#/components/schemas/PositionValueDataPoint" } } } }, "PrincipalCollateralPair": { "type": "object", "required": [ "principalAssetIdentifier", "collateralAssetIdentifier" ], "properties": { "collateralAssetIdentifier": { "type": "string" }, "principalAssetIdentifier": { "type": "string" } } }, "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%)" } } }, "RateHistoryGraphData": { "type": "object", "description": "Rate history graph data", "required": [ "dataPoints" ], "properties": { "dataPoints": { "type": "array", "items": { "$ref": "#/components/schemas/RateHistoryDataPoint" } } } } } } }