# User positions (index-hinted, experimental) Endpoint reference for the 1delta API. Index: https://docs.1delta.io/llms.txt · every endpoint: https://docs.1delta.io/llms-full.txt --- ### GET /v1/data/lending/user-positions/hinted - operationId: `user-positions-index-hinted-experimental` - docs: https://docs.1delta.io/1delta-api/user-positions-index-hinted-experimental/ - markdown: https://docs.1delta.io/1delta-api/user-positions-index-hinted-experimental.md - tags: User Positions User positions (index-hinted, experimental) The same response as `/v1/data/lending/user-positions`, reading only the lenders the position index says the wallet can hold. Every value is still read live on chain; the index only narrows WHICH lenders are queried. Per chain, the index answers whether its hint is usable. Only then is the read narrowed to the lenders the wallet's last full read found, the ones it entered since, and every lender the index cannot observe. Otherwise — no full read on record, the index behind it, an unfollowed chain, the index slow or unreachable, or an explicit `lenders=` — the chain is read in full, exactly as the plain route does. The response adds `hints: { ms, chains: { [chainId]: { mode: 'hinted' | 'full', reason, lenders? } } }`. **Parameters** | Name | In | Type | Required | Description | | --- | --- | --- | --- | --- | | `account` | query | string | yes | EVM account address (0x-prefixed, 40 hex chars) | | `chains` | query | string | yes | Comma-separated chain IDs | | `lenders` | query | string | no | Comma-separated lender IDs. When given, the index is not consulted. See the `LenderId` schema for the full set of accepted values. | **Response `200`** — User position data with portfolio summary | Field | Type | Description | | --- | --- | --- | | `success` | true | | | `data` | object | User lending positions as a flat array with portfolio summary and per-chain breakdowns. | | `data.items` | object[] | Flat array of lender entries sorted by net worth (descending). Each entry fuses position data with aggregated summary metrics. | | `data.items[].lender` | string | Lender identifier | | `data.items[].chainId` | string | Chain ID | | `data.items[].account` | string | User account address | | `data.items[].data` | object[] | Sub-account position data | | `data.items[].data[].accountId` | string | Sub-account identifier (e.g., "0" for default, NFT ID for Init) | | `data.items[].data[].health` | number | Health factor (null if no debt). Values > 1 are healthy, < 1 at risk of liquidation. | | `data.items[].data[].borrowCapacityUSD` | number | Total USD borrowable while maintaining health >= 1 | | `data.items[].data[].balanceData` | object | Aggregated balance data for a sub-account. | | `data.items[].data[].balanceData.deposits` | number | Total deposits in USD | | `data.items[].data[].balanceData.debt` | number | Total debt in USD | | `data.items[].data[].balanceData.adjustedDebt` | number | Debt adjusted for borrow factors | | `data.items[].data[].balanceData.collateral` | number | Collateral value in USD | | `data.items[].data[].balanceData.collateralAllActive` | number | Collateral if all assets were enabled | | `data.items[].data[].balanceData.borrowDiscountedCollateral` | number | Collateral discounted by borrow factors | | `data.items[].data[].balanceData.borrowDiscountedCollateralAllActive` | number | Discounted collateral if all enabled | | `data.items[].data[].balanceData.nav` | number | Net asset value (deposits - debt) | | `data.items[].data[].balanceData.deposits24h` | number | Deposits 24h ago (for change calculation) | | `data.items[].data[].balanceData.debt24h` | number | Debt 24h ago | | `data.items[].data[].balanceData.nav24h` | number | NAV 24h ago | | `data.items[].data[].balanceData.rewards` | object[] | Pending reward token claims. Each entry represents a single reward program. | | `data.items[].data[].aprData` | object | APR breakdown for a sub-account. | | `data.items[].data[].aprData.apr` | number | Net APR (deposit - borrow) | | `data.items[].data[].aprData.depositApr` | number | Weighted deposit APR | | `data.items[].data[].aprData.borrowApr` | number | Weighted borrow APR | | `data.items[].data[].aprData.rewardApr` | number | Total reward APR | | `data.items[].data[].aprData.rewardDepositApr` | number | Reward APR on deposits | | `data.items[].data[].aprData.rewardBorrowApr` | number | Reward APR on borrows | | `data.items[].data[].aprData.intrinsicApr` | number | Intrinsic yield APR (e.g., stETH staking) | | `data.items[].data[].aprData.intrinsicDepositApr` | number | Intrinsic yield APR portion from deposits | | `data.items[].data[].aprData.intrinsicBorrowApr` | number | Intrinsic yield APR portion from borrows | | `data.items[].data[].aprData.rewards` | object | Per-reward-token APR breakdown. Keys are reward token addresses. | | `data.items[].data[].positions` | object[] | Individual asset positions in this sub-account | | `data.items[].data[].positions[].marketUid` | string | Unique market identifier (format: `{lender}:{chainId}:{address}`) | | `data.items[].data[].positions[].deposits` | string | Deposit amount in token units (wei) | | `data.items[].data[].positions[].debt` | string | Variable debt in token units | | `data.items[].data[].positions[].debtStable` | string | Stable debt in token units | | `data.items[].data[].positions[].debtShares` | string | Debt share amount (protocol-specific, present when the protocol uses share-based accounting) | | `data.items[].data[].positions[].depositShares` | string | Deposit share amount (protocol-specific, present when the protocol uses share-based accounting) | | `data.items[].data[].positions[].depositsUSD` | number | Deposits in USD (market price) | | `data.items[].data[].positions[].debtUSD` | number | Variable debt in USD (market price) | | `data.items[].data[].positions[].debtStableUSD` | number | Stable debt in USD (market price) | | `data.items[].data[].positions[].depositsUSDOracle` | number | Deposits in USD using on-chain oracle price (used for risk/health calculations) | | `data.items[].data[].positions[].debtUSDOracle` | number | Variable debt in USD using on-chain oracle price | | `data.items[].data[].positions[].debtStableUSDOracle` | number | Stable debt in USD using on-chain oracle price | | `data.items[].data[].positions[].collateralEnabled` | boolean | Whether this asset is enabled as collateral | | `data.items[].data[].positions[].claimableRewards` | number | Claimable rewards in USD | | `data.items[].data[].positions[].withdrawable` | string | Max tokens withdrawable while maintaining health >= 1. Equals full deposit balance if collateral is not enabled. | | `data.items[].data[].positions[].borrowable` | string | Max tokens borrowable against remaining credit line. Zero if borrowing is disabled, reserve is frozen, or debt is disabled for the active mode. | | `data.items[].data[].positions[].underlyingInfo` | object | Nested asset metadata, oracle prices, and market prices for a lending market. | | `data.items[].data[].positions[].loanId` | string | Lista DAO brokered markets only: identifies a single fixed-term loan (the broker posId; the dynamic/flex position uses `type(uint128).max`). Present on per-loan breakdown rows; absent on the aggregate debt row and on the shared collateral row. Pass to `/v1/actions/lending/repay?loanId=…`. | | `data.items[].data[].positions[].term` | object | Per-loan fixed-term detail attached to a user position (`LendingPosition.term`), one per open loan. Emitted by Lista broker, Exactly, TermMax and Teller — several fields are lender-specific, and the repay economics behind them differ sharply per protocol (see FIXED_TERM_REPAY_TERMS.md). Lista only: the flexible/dynamic position uses `isDynamic = true` and the `type(uint128).max` `loanId` sentinel. | | `data.items[].data[].userConfig` | object | User configuration for a sub-account. | | `data.items[].data[].userConfig.selectedMode` | string | Mode/config key (e.g. e-mode category or vault address) | | `data.items[].data[].userConfig.id` | string | Config identifier | | `data.items[].data[].userConfig.isWhitelisted` | boolean | Whether user is whitelisted (for permissioned markets) | | `data.items[].balanceData` | object | Summary-level balance data (without discounted/adjusted fields). | | `data.items[].balanceData.deposits` | number | Total deposits in USD | | `data.items[].balanceData.debt` | number | Total debt in USD | | `data.items[].balanceData.collateral` | number | Collateral value in USD | | `data.items[].balanceData.collateralAllActive` | number | Collateral if all assets were enabled | | `data.items[].balanceData.nav` | number | Net asset value (deposits - debt) | | `data.items[].balanceData.deposits24h` | number | Deposits 24h ago | | `data.items[].balanceData.debt24h` | number | Debt 24h ago | | `data.items[].balanceData.nav24h` | number | NAV 24h ago | | `data.items[].balanceData.rewards` | object[] | Pending reward token claims. Each entry represents a single reward program. | | `data.items[].balanceData.rewards[].asset` | string | Reward token contract address | | `data.items[].balanceData.rewards[].totalRewards` | number | Total accumulated rewards (token units) | | `data.items[].balanceData.rewards[].claimableRewards` | number | Immediately claimable rewards (token units) | | `data.items[].aprData` | object | Summary-level APR breakdown. | | `data.items[].aprData.apr` | number | Net APR (deposit - borrow) | | `data.items[].aprData.depositApr` | number | Weighted deposit APR | | `data.items[].aprData.borrowApr` | number | Weighted borrow APR | | `data.items[].aprData.rewardApr` | number | Total reward APR | | `data.items[].aprData.rewardDepositApr` | number | Reward APR on deposits | | `data.items[].aprData.rewardBorrowApr` | number | Reward APR on borrows | | `data.items[].aprData.intrinsicApr` | number | Intrinsic yield APR (e.g., stETH staking) | | `data.items[].aprData.intrinsicDepositApr` | number | Intrinsic yield APR portion from deposits | | `data.items[].aprData.intrinsicBorrowApr` | number | Intrinsic yield APR portion from borrows | | `data.items[].aprData.rewards` | object | Per-reward-token APR breakdown. Keys are reward token addresses. | | `data.items[].leverage` | number | Leverage ratio (deposits / nav) | | `data.summary` | object | Portfolio-wide totals with per-chain breakdowns. Per-lender summaries are fused into each LenderDataEntry in the items array. | | `data.summary.balanceData` | object | Summary-level balance data (without discounted/adjusted fields). | | `data.summary.balanceData.deposits` | number | Total deposits in USD | | `data.summary.balanceData.debt` | number | Total debt in USD | | `data.summary.balanceData.collateral` | number | Collateral value in USD | | `data.summary.balanceData.collateralAllActive` | number | Collateral if all assets were enabled | | `data.summary.balanceData.nav` | number | Net asset value (deposits - debt) | | `data.summary.balanceData.deposits24h` | number | Deposits 24h ago | | `data.summary.balanceData.debt24h` | number | Debt 24h ago | | `data.summary.balanceData.nav24h` | number | NAV 24h ago | | `data.summary.balanceData.rewards` | object[] | Pending reward token claims. Each entry represents a single reward program. | | `data.summary.balanceData.rewards[].asset` | string | Reward token contract address | | `data.summary.balanceData.rewards[].totalRewards` | number | Total accumulated rewards (token units) | | `data.summary.balanceData.rewards[].claimableRewards` | number | Immediately claimable rewards (token units) | | `data.summary.aprData` | object | Summary-level APR breakdown. | | `data.summary.aprData.apr` | number | Net APR (deposit - borrow) | | `data.summary.aprData.depositApr` | number | Weighted deposit APR | | `data.summary.aprData.borrowApr` | number | Weighted borrow APR | | `data.summary.aprData.rewardApr` | number | Total reward APR | | `data.summary.aprData.rewardDepositApr` | number | Reward APR on deposits | | `data.summary.aprData.rewardBorrowApr` | number | Reward APR on borrows | | `data.summary.aprData.intrinsicApr` | number | Intrinsic yield APR (e.g., stETH staking) | | `data.summary.aprData.intrinsicDepositApr` | number | Intrinsic yield APR portion from deposits | | `data.summary.aprData.intrinsicBorrowApr` | number | Intrinsic yield APR portion from borrows | | `data.summary.aprData.rewards` | object | Per-reward-token APR breakdown. Keys are reward token addresses. | | `data.summary.leverage` | number | Overall leverage ratio (deposits / nav) | | `data.summary.activeLenders` | integer | Number of lenders with positions | | `data.summary.activeChains` | integer | Number of chains with positions | | `data.partial` | boolean | Present and true when at least one lender could not be read in full (RPC error or reverted call). Totals are then a lower bound — a lender whose reads all failed is omitted rather than reported as an empty position. | | `data.incompleteLenders` | string[] | Present only when `partial` is set: the `chainId:lender` pairs whose on-chain reads (partly) failed. | | `actions` | null | | **Example response** ```json { "success": true, "data": { "items": [ { "lender": "AAVE_V3", "chainId": "1", "account": "0xbadA9c382165b31419F4CC0eDf0Fa84f80A3C8E5", "data": [ { "accountId": "0", "health": 1.85, "borrowCapacityUSD": 3000, "balanceData": { "deposits": 10000.5, "debt": 5000.25, "adjustedDebt": 5500, "collateral": 9000, "collateralAllActive": 10000.5, "borrowDiscountedCollateral": 8000, "borrowDiscountedCollateralAllActive": 9000, "nav": 5000.25, "deposits24h": 9800, "debt24h": 4900, "nav24h": 4900, "rewards": [ { "asset": "0xc00e94Cb662C3520282E6f5717214004A7f26888", "totalRewards": 12.5, "claimableRewards": 12.5 } ] }, "aprData": { "apr": 2.5, "depositApr": 3.5, "borrowApr": 5.2, "rewardApr": 1.2, "rewardDepositApr": 0.8, "rewardBorrowApr": 0.4, "intrinsicApr": 0, "intrinsicDepositApr": 0, "intrinsicBorrowApr": 0, "rewards": {} }, "positions": [ { "marketUid": "AAVE_V3:1:0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2", "deposits": "1000000000000000000", "debt": "0", "debtStable": "0", "debtShares": "0", "depositShares": "0", "depositsUSD": 2500, "debtUSD": 0, "debtStableUSD": 0, "depositsUSDOracle": 2510, "debtUSDOracle": 0, "debtStableUSDOracle": 0, "collateralEnabled": true, "claimableRewards": 0.5, "withdrawable": "0.5", "borrowable": "100", "underlyingInfo": { "asset": {}, "oraclePrice": {}, "prices": {} }, "loanId": "450", "term": { "loanId": "450", "termId": 2, "isDynamic": false, "debt": "14.5003", "apr": 3.85, "maturity": 1781789025, "termDays": 7, "accruedInterest": "0.000358", "earlyRepayPenalty": "0.001211", "isMatured": false, "faceValue": "100.0", "earlyRepayDiscount": "1.0", "latePenalty": "2.25", "latePenaltyPerDay": "0.225", "latePenaltyApr": 164.24, "secondsLate": 0 } } ], "userConfig": { "selectedMode": "0", "id": "0", "isWhitelisted": true } } ], "balanceData": { "deposits": 10000.5, "debt": 5000.25, "collateral": 9000, "collateralAllActive": 10000.5, "nav": 5000.25, "deposits24h": 9800, "debt24h": 4900, "nav24h": 4900, "rewards": [ { "asset": "0xc00e94Cb662C3520282E6f5717214004A7f26888", "totalRewards": 12.5, "claimableRewards": 12.5 } ] }, "aprData": { "apr": 2.5, "depositApr": 3.5, "borrowApr": 5.2, "rewardApr": 1.2, "rewardDepositApr": 0.8, "rewardBorrowApr": 0.4, "intrinsicApr": 0, "intrinsicDepositApr": 0, "intrinsicBorrowApr": 0, "rewards": {} }, "leverage": 2 } ], "summary": { "balanceData": { "deposits": 10000.5, "debt": 5000.25, "collateral": 9000, "collateralAllActive": 10000.5, "nav": 5000.25, "deposits24h": 9800, "debt24h": 4900, "nav24h": 4900, "rewards": [ { "asset": "0xc00e94Cb662C3520282E6f5717214004A7f26888", "totalRewards": 12.5, "claimableRewards": 12.5 } ] }, "aprData": { "apr": 2.5, "depositApr": 3.5, "borrowApr": 5.2, "rewardApr": 1.2, "rewardDepositApr": 0.8, "rewardBorrowApr": 0.4, "intrinsicApr": 0, "intrinsicDepositApr": 0, "intrinsicBorrowApr": 0, "rewards": {} }, "leverage": 2, "activeLenders": 3, "activeChains": 2 }, "partial": true, "incompleteLenders": [ "1:AAVE_V3", "1:COMPOUND_V3_USDC" ] } } ``` **Response `400`** — Validation error **Response `429`** — Rate limited. Unauthenticated callers share a per-IP budget; send an `x-api-key` header to lift it. Retry with exponential backoff. **Response `500`** — Unexpected server error. Safe to retry with backoff. **Response `502`** — An upstream data source or protocol origin failed (`error.code` is `ORIGIN_FAILED`). `error.details` carries the per-origin status. This is also what a missing or malformed required parameter currently returns, rather than a 400.