@jup-ag/lend-read
v0.0.11
Published
utils for jup lend
Maintainers
hjchan
dicksonp
arowana
siong
zhengyutay
ryoid
thimerosa
jjsb
aaroncql
prady_v
thrilokkumar
kabbouchiKeywords
Readme
Jupiter Lend Read SDK
Read-only TypeScript SDK for Jupiter Lend on-chain programs. Provides typed access to Liquidity pools, Lending (jlToken) markets, and Vaults on Solana.
Installation
pnpm add @jup-ag/lend-read
# or
npm install @jup-ag/lend-readQuick Start
Using the Unified Client (Recommended)
import { Client } from "@jup-ag/lend-read";
import { PublicKey } from "@solana/web3.js";
// Initialize with default mainnet RPC
const client = new Client();
// Or use a custom RPC endpoint
const client = new Client("https://your-rpc-url.com");
// Or pass an existing Connection
import { Connection } from "@solana/web3.js";
const connection = new Connection("https://your-rpc-url.com");
const client = new Client(connection);Using Individual Modules
import { Liquidity, Lending, Vault } from "@jup-ag/lend-read";
const liquidity = new Liquidity("https://your-rpc-url.com");
const lending = new Lending("https://your-rpc-url.com");
const vault = new Vault("https://your-rpc-url.com");Liquidity Module
Access liquidity pool data, interest rates, and user supply/borrow positions.
Usage Examples
const USDC = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const SOL = new PublicKey("So11111111111111111111111111111111111111112");
const user = new PublicKey("YOUR_ADDRESS");
// List all supported tokens
const tokens = await client.liquidity.listedTokens();
// Get market data for a token
const data = await client.liquidity.getOverallTokenData(USDC);
// Batch fetch multiple tokens
const allData = await client.liquidity.getOverallTokensData([USDC, SOL]);
// Get user supply position
const { userSupplyData } = await client.liquidity.getUserSupplyData(user, USDC);
// Get user borrow position
const { userBorrowData } = await client.liquidity.getUserBorrowData(user, USDC);
// Get combined supply + borrow across multiple tokens
const combined = await client.liquidity.getUserMultipleBorrowSupplyData(
user,
[USDC, SOL], // supply tokens
[USDC], // borrow tokens
);Methods
| Method | Parameters | Returns | Description |
| ------------------------------------------------------------------- | -------------------------------------- | ------------------------------------------- | ----------------------------------------------------------- |
| listedTokens() | - | PublicKey[] | All token mints with reserves in the liquidity program |
| getLiquidityAccount() | - | LiquidityAccount | Main liquidity account with authority, auths, and guardians |
| getRevenueCollector() | - | PublicKey | Revenue collector address |
| getRevenue(token) | token: PublicKey | BN | Calculated revenue for a token |
| getOverallTokenData(token) | token: PublicKey | OverallTokenData | Complete market data for a single token |
| getOverallTokensData(tokens) | tokens: PublicKey[] | OverallTokenData[] | Batch market data for multiple tokens |
| getAllOverallTokensData() | - | OverallTokenData[] | Market data for all listed tokens |
| getExchangePricesAndConfig(token) | token: PublicKey | ExchangePricesAndConfig | Exchange prices and rate configuration |
| getRateConfig(token) | token: PublicKey | RateModelAccount \| null | Interest rate model parameters |
| getTotalAmounts(token) | token: PublicKey | TotalAmounts \| null | Total supply/borrow amounts |
| getUserSupply(user, token) | user: PublicKey, token: PublicKey | UserSupplyPositionAccount \| BN | Raw user supply position (BN(0) if none) |
| getUserBorrow(user, token) | user: PublicKey, token: PublicKey | UserBorrowPositionAccount \| BN | Raw user borrow position (BN(0) if none) |
| getUserSupplyData(user, token) | user: PublicKey, token: PublicKey | { userSupplyData, overallTokenData } | Processed user supply with market context |
| getUserBorrowData(user, token) | user: PublicKey, token: PublicKey | { userBorrowData, overallTokenData } | Processed user borrow with market context |
| getUserMultipleSupplyData(user, tokens) | user: PublicKey, tokens: PublicKey[] | { userSuppliesData, overallTokensData } | Batch supply data across tokens |
| getUserMultipleBorrowData(user, tokens) | user: PublicKey, tokens: PublicKey[] | { userBorrowingsData, overallTokensData } | Batch borrow data across tokens |
| getUserMultipleBorrowSupplyData(user, supplyTokens, borrowTokens) | user, supplyTokens[], borrowTokens[] | Combined supply + borrow data | Efficient batch fetch for both |
| getAllUserPositions() | - | Array<{ user, supply, borrow }> | All user positions across the protocol |
| calculateExchangePrice(config) | config: ExchangePricesAndConfig | ExchangePriceResult | Calculate current exchange prices |
Return Types
OverallTokenData
| Field | Type | Description |
| ----------------------- | ---------- | ---------------------------------------------------------------- |
| rateData | RateData | Interest rate model configuration |
| supplyExchangePrice | BN | Current supply exchange price (scales raw amounts to actual) |
| borrowExchangePrice | BN | Current borrow exchange price |
| borrowRate | BN | Current borrow interest rate |
| supplyRate | BN | Current supply interest rate |
| fee | BN | Protocol fee on interest (basis points) |
| lastStoredUtilization | BN | Last stored utilization percentage |
| lastUpdateTimestamp | BN | Unix timestamp of last on-chain update |
| maxUtilization | BN | Maximum allowed utilization (basis points, e.g. 9500 = 95%) |
| supplyRawInterest | BN | Total raw supply with interest |
| supplyInterestFree | BN | Total supply without interest |
| borrowRawInterest | BN | Total raw borrow with interest |
| borrowInterestFree | BN | Total borrow without interest |
| totalSupply | BN | Total supply (interest + interest-free, exchange-price adjusted) |
| totalBorrow | BN | Total borrow (interest + interest-free, exchange-price adjusted) |
| revenue | BN | Protocol revenue (balance + borrow - claims - supply) |
UserSupplyData
| Field | Type | Description |
| ------------------------ | --------- | ---------------------------------------------------------- |
| modeWithInterest | boolean | Whether position accrues interest |
| supply | BN | Current supply amount (exchange-price adjusted) |
| withdrawalLimit | BN | Current withdrawal limit |
| lastUpdateTimestamp | BN | Last position update timestamp |
| expandPercent | BN | Rate at which withdrawal limit expands |
| expandDuration | BN | Duration over which limit fully expands |
| baseWithdrawalLimit | BN | Base withdrawal limit before expansion |
| withdrawableUntilLimit | BN | Amount withdrawable up to the current limit |
| withdrawable | BN | Actual withdrawable amount (capped by available liquidity) |
UserBorrowData
| Field | Type | Description |
| ------------------------ | --------- | -------------------------------------------------------- |
| modeWithInterest | boolean | Whether position accrues interest |
| borrow | BN | Current borrow amount (exchange-price adjusted) |
| borrowLimit | BN | Current borrow/debt ceiling |
| lastUpdateTimestamp | BN | Last position update timestamp |
| expandPercent | BN | Rate at which borrow limit expands |
| expandDuration | BN | Duration over which limit fully expands |
| baseBorrowLimit | BN | Base borrow limit before expansion |
| maxBorrowLimit | BN | Hard cap on borrow limit |
| borrowLimitUtilization | BN | Borrow limit based on pool utilization |
| borrowableUntilLimit | BN | Amount borrowable up to the limit |
| borrowable | BN | Actual borrowable amount (capped by available liquidity) |
ExchangePricesAndConfig
| Field | Type | Description |
| ----------------------- | ----- | ------------------------------------------- |
| supplyExchangePrice | BN | Exchange price for supply (raw -> actual) |
| borrowExchangePrice | BN | Exchange price for borrow (raw -> actual) |
| borrowRate | BN | Current borrow rate |
| fee | BN | Fee on interest |
| lastStoredUtilization | BN | Last stored utilization |
| lastUpdateTimestamp | BN | Last update timestamp |
| maxUtilization | BN | Max utilization cap |
| supplyRatio | BN? | Supply ratio between interest/interest-free |
| borrowRatio | BN? | Borrow ratio between interest/interest-free |
Lending Module
Access jlToken (Jupiter Lend token) markets, exchange prices, rewards, and user positions.
Usage Examples
const USDC = new PublicKey("EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v");
const user = new PublicKey("YOUR_ADDRESS");
// Get all jlToken mints
const jlTokens = await client.lending.getAllJlTokens();
// Get jlToken details (rates, supply, conversion)
const details = await client.lending.getJlTokenDetails(USDC);
// Get all jlToken details at once
const allDetails = await client.lending.getAllJlTokenDetails();
// Get user position
const position = await client.lending.getUserPosition(USDC, user);
// Get all user positions
const allPositions = await client.lending.getUserPositions(user);
// Preview deposit/withdraw
import BN from "bn.js";
const previews = await client.lending.getPreviews(
USDC,
new BN(1_000_000), // 1 USDC
new BN(0),
);
// Get rewards config
const rewardsConfig = await client.lending.getJlTokenRewardsRateModelConfig(
USDC,
);
// Get latest exchange price (via on-chain simulation)
const price = await client.lending.getExchangePrice(USDC);Methods
| Method | Parameters | Returns | Description |
| ---------------------------------------- | ---------------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| getAllJlTokens() | - | PublicKey[] | All jlToken mint addresses |
| getJlTokenDetails(mint) | mint: PublicKey | JlTokenDetails | Complete jlToken market data |
| getAllJlTokenDetails() | - | JlTokenDetails[] | All jlToken details in one call |
| getJlTokenInternalData(mint) | mint: PublicKey | JlTokenInternalData | Internal jlToken data (programs, balances, prices) |
| getExchangePrice(mint) | mint: PublicKey | BN | Latest exchange price (simulation with fallback) |
| getLatestExchangePriceView(mint) | mint: PublicKey | { tokenExchangePrice, liquidityExchangePrice } \| null | Exchange price via on-chain simulation |
| getUserPosition(mint, user) | mint: PublicKey, user: PublicKey | UserPosition | User's jlToken position |
| getUserPositions(user) | user: PublicKey | JlTokenDetailsUserPosition[] | All user positions across jlTokens |
| getJlTokenRewards(mint) | mint: PublicKey | [PublicKey, BN] | Rewards rate model address and current rate |
| getJlTokenRewardsRateModelConfig(mint) | mint: PublicKey | RewardsRateModelConfig | Rewards configuration |
| getPreviews(mint, assets, shares) | mint, assets: BN, shares: BN | PreviewData | Preview deposit/mint/withdraw/redeem |
| getLendingAdminData() | - | DecodedLendingAdminAccount | Admin account data |
| getLendingAdminAuthority() | - | PublicKey | Admin authority |
| getLendingAdminRebalancer() | - | PublicKey | Rebalancer address |
| getLendingAdminAuths() | - | PublicKey[] | Authorized addresses |
| isLendingAuth(auth) | auth: PublicKey | boolean | Check if address is authorized |
Return Types
JlTokenDetails
| Field | Type | Description |
| ------------------------ | ---------------- | ------------------------------------------------- |
| tokenAddress | PublicKey | jlToken mint address |
| name | string | Token name (e.g. "JupLend USDC") |
| symbol | string | Token symbol |
| decimals | number | Token decimal places |
| underlyingAddress | PublicKey | Underlying token mint |
| totalAssets | BN | Total underlying assets backing jlTokens |
| totalSupply | BN | Total jlToken supply (shares) |
| conversionRateToShares | BN | Assets -> jlToken shares conversion rate |
| conversionRateToAssets | BN | jlToken shares -> assets conversion rate |
| rewardsRate | BN | Current rewards APR |
| supplyRate | BN | Base supply rate from liquidity pool |
| rebalanceDifference | BN | Difference between liquidity balance and total assets |
| userSupplyData | UserSupplyData | Lending protocol's supply position on liquidity |
UserPosition (Lending)
| Field | Type | Description |
| ------------------- | ---- | --------------------------------------- |
| jlTokenShares | BN | User's jlToken balance (shares) |
| underlyingAssets | BN | Value in underlying tokens |
| underlyingBalance | BN | User's underlying token wallet balance |
| allowance | BN | Token allowance |
PreviewData
| Field | Type | Description |
| ----------------- | ---- | --------------------------------------- |
| previewDeposit | BN | Shares received for depositing assets |
| previewMint | BN | Assets needed to mint shares |
| previewWithdraw | BN | Shares burned to withdraw assets |
| previewRedeem | BN | Assets received for redeeming shares |
RewardsRateModelConfig
| Field | Type | Description |
| -------------- | ---- | ----------------------------------- |
| duration | BN | Rewards program duration (seconds) |
| startTime | BN | Rewards start timestamp |
| endTime | BN | Rewards end timestamp |
| startTvl | BN | Minimum TVL for rewards to activate |
| maxRate | BN | Maximum rewards rate cap |
| rewardAmount | BN | Total reward amount for the period |
JlTokenInternalData
| Field | Type | Description |
| ------------------------- | ----------- | ------------------------------- |
| liquidity | PublicKey | Liquidity program PDA |
| lendingFactory | PublicKey | Lending admin PDA |
| lendingRewardsRateModel | PublicKey | Rewards rate model address |
| rebalancer | PublicKey | Rebalancer address |
| liquidityBalance | BN | Current liquidity pool balance |
| liquidityExchangePrice | BN | Liquidity exchange price |
| tokenExchangePrice | BN | jlToken exchange price |
Vault Module
Access vault configurations, positions, exchange prices, liquidation data, and risk metrics.
Usage Examples
const vaultId = 1;
// Get total vaults
const total = await client.vault.getTotalVaults();
// Get vault config and state
const config = await client.vault.getVaultConfig(vaultId);
const state = await client.vault.getVaultState(vaultId);
// Get comprehensive vault data (config + state + rates + limits)
const data = await client.vault.getVaultByVaultId(vaultId);
// Get all vaults
const allVaults = await client.vault.getAllVaults();
// Get a user position
const position = await client.vault.getUserPosition({ vaultId, positionId: 1 });
// Get position by NFT ID with vault context
const { userPosition, vaultData } = await client.vault.getPositionByVaultId(
vaultId,
1,
);
// Get all positions with risk ratios
const positions = await client.vault.getAllPositionsWithRiskRatio(vaultId);
// Simulate position changes
import BN from "bn.js";
const final = await client.vault.getFinalPosition({
vaultId,
positionId: 1,
newColAmount: new BN(1_000_000),
newDebtAmount: new BN(500_000),
});
// Get oracle price
const oracle = config.oracle;
const prices = await client.vault.getOraclePrice(oracle);Methods
| Method | Parameters | Returns | Description |
| ----------------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
| getTotalVaults() | - | number | Total number of vaults |
| getVaultConfig(vaultId) | vaultId: number | VaultConfig | Vault configuration (tokens, rates, thresholds) |
| getVaultState(vaultId) | vaultId: number | VaultState | Current vault state (supply, borrow, branches) |
| getVaultByVaultId(vaultId) | vaultId: number | VaultEntireData | Complete vault data in one call |
| getAllVaults() | - | VaultEntireData[] | All vaults data with bounded concurrency |
| getVaultAdmin() | - | VaultAdmin \| null | Vault admin account |
| getUserPosition({ vaultId, positionId }) | { vaultId, positionId } | UserPosition \| null | Single user position |
| batchGetUserPositions(positions) | Array<{ vaultId, positionId }> | Array<UserPosition \| null> | Batch fetch positions |
| getCurrentPositionState({ vaultId, position }) | { vaultId, position } | UserPositionWithDebt | Current position with debt/liquidation |
| getFinalPosition({ vaultId, positionId, newColAmount, newDebtAmount }) | See params | UserPositionWithDebt | Simulate position after changes |
| calculateFinalPosition({ vaultId, currentPosition, newColAmount, newDebtAmount }) | See params | UserPositionWithDebt | Calculate final position from current state |
| getAllPositionsWithRiskRatio(vaultId) | vaultId: number | Array<NftPosition & { riskRatio }> | All positions with borrow/supply risk ratio |
| getAllPositionIdsForVault(vaultId) | vaultId: number | number[] | All position IDs for a vault |
| getPositionByVaultId(vaultId, nftId) | vaultId: number, nftId: number | { userPosition, vaultData } | Position + vault data by NFT ID |
| getNftOwner(mint) | mint: PublicKey | PublicKey | Owner of a position NFT |
| getOraclePrice(oracle) | oracle: PublicKey | { operatePrice, liquidatePrice } | Oracle prices |
| getVaultMetadata({ vaultId }) | { vaultId } | VaultMetadata \| null | Vault metadata (cached) |
| getTick({ vaultId, tick }) | { vaultId, tick } | TickData \| null | Tick data for a vault |
| batchGetTicks(ticks) | Array<{ vaultId, tick }> | Array<TickData \| null> | Batch fetch ticks |
| getBranch({ vaultId, branchId }) | { vaultId, branchId } | BranchData \| null | Branch data |
| batchGetBranches(branches) | Array<{ vaultId, branchId }> | Array<BranchData \| null> | Batch fetch branches |
| getAllBranches({ vaultId }) | { vaultId } | BranchData[] | All branches for a vault |
| updateExchangePrices(...) | Supply/borrow mints + prices | { vaultSupplyExchangePrice, vaultBorrowExchangePrice } | Calculate updated vault exchange prices |
Return Types
VaultEntireData
| Field | Type | Description |
| ------------------------- | ------------------------ | ----------------------------------------- |
| vault | PublicKey | Vault config PDA |
| isSmartCol | boolean | Smart collateral enabled |
| isSmartDebt | boolean | Smart debt enabled |
| constantViews | ConstantViews | Static vault addresses and IDs |
| configs | Configs | Rate magnifiers, thresholds, oracle |
| exchangePricesAndRates | ExchangePricesAndRates | All exchange prices and interest rates |
| limitsAndAvailability | LimitsAndAvailability | Withdrawal/borrow limits and availability |
| liquidityUserSupplyData | UserSupplyData | Vault's supply position on liquidity |
| liquidityUserBorrowData | UserBorrowData | Vault's borrow position on liquidity |
| vaultState | VaultState | Current vault state |
| totalSupplyAndBorrow | TotalSupplyAndBorrow | Aggregated supply/borrow amounts |
VaultConfig
| Field | Type | Description |
| ---------------------- | ----------- | --------------------------------- |
| vaultId | number | Vault identifier |
| supplyToken | PublicKey | Collateral token mint |
| borrowToken | PublicKey | Debt token mint |
| supplyRateMagnifier | number | Supply rate multiplier |
| borrowRateMagnifier | number | Borrow rate multiplier |
| collateralFactor | number | Max LTV ratio |
| liquidationThreshold | number | Liquidation trigger threshold |
| liquidationMaxLimit | number | Maximum liquidation amount |
| liquidationPenalty | number | Penalty on liquidation |
| withdrawGap | number | Withdrawal gap buffer |
| borrowFee | number | Fee on new borrows (basis points) |
| oracle | PublicKey | Price oracle address |
| rebalancer | PublicKey | Rebalancer address |
VaultState
| Field | Type | Description |
| ------------------------------ | --------------------- | ------------------------------------- |
| topTick | number | Highest active tick |
| currentBranch | number | Active branch ID |
| totalBranch | number | Total branches created |
| totalSupply | BN | Total raw supply |
| totalBorrow | BN | Total raw borrow |
| totalPositions | number | Number of positions |
| nextPositionId | number | Next available position ID |
| branchLiquidated | boolean | Whether current branch is liquidated |
| currentBranchState | CurrentBranchState? | Current branch details |
| vaultSupplyExchangePrice | BN | Vault supply exchange price |
| vaultBorrowExchangePrice | BN | Vault borrow exchange price |
| liquiditySupplyExchangePrice | BN | Liquidity supply exchange price |
| liquidityBorrowExchangePrice | BN | Liquidity borrow exchange price |
| absorbedDebtAmount | BN | Debt absorbed from liquidations |
| absorbedColAmount | BN | Collateral absorbed from liquidations |
ExchangePricesAndRates
| Field | Type | Description |
| ---------------------------------------- | ---- | ---------------------------------- |
| lastStoredLiquiditySupplyExchangePrice | BN | Last stored liquidity supply price |
| lastStoredLiquidityBorrowExchangePrice | BN | Last stored liquidity borrow price |
| lastStoredVaultSupplyExchangePrice | BN | Last stored vault supply price |
| lastStoredVaultBorrowExchangePrice | BN | Last stored vault borrow price |
| liquiditySupplyExchangePrice | BN | Current liquidity supply price |
| liquidityBorrowExchangePrice | BN | Current liquidity borrow price |
| vaultSupplyExchangePrice | BN | Current vault supply price |
| vaultBorrowExchangePrice | BN | Current vault borrow price |
| supplyRateLiquidity | BN | Liquidity supply APR |
| borrowRateLiquidity | BN | Liquidity borrow APR |
| supplyRateVault | BN | Vault supply APR |
| borrowRateVault | BN | Vault borrow APR |
| rewardsOrFeeRateSupply | BN | Supply-side rewards or fee rate |
| rewardsOrFeeRateBorrow | BN | Borrow-side rewards or fee rate |
LimitsAndAvailability
| Field | Type | Description |
| ------------------------ | ---- | ----------------------------------------- |
| withdrawLimit | BN | Maximum withdrawal limit |
| withdrawableUntilLimit | BN | Amount withdrawable before hitting limit |
| withdrawable | BN | Actual withdrawable (capped by liquidity) |
| borrowLimit | BN | Maximum borrow limit |
| borrowLimitUtilization | BN | Borrow limit from pool utilization |
| borrowableUntilLimit | BN | Amount borrowable before hitting limit |
| borrowable | BN | Actual borrowable (capped by liquidity) |
| minimumBorrowing | BN | Minimum borrow amount |
UserPosition (Vault)
| Field | Type | Description |
| ---------------------- | ------------------- | ------------------------------------------ |
| vaultId | number | Vault ID |
| nftId | number | Position NFT ID |
| positionMint | PublicKey | Position NFT mint |
| isSupplyOnlyPosition | number \| boolean | Whether supply-only (no debt) |
| tick | number | Tick representing collateral-to-debt ratio |
| tickId | number | ID within the tick |
| supplyAmount | BN | Raw collateral amount |
| dustDebtAmount | BN | Small residual debt |
NftPosition
| Field | Type | Description |
| ------------------ | ----------- | ------------------------------------ |
| nftId | number | Position NFT ID |
| owner | PublicKey | Position owner |
| isSupplyPosition | boolean | Whether supply-only |
| supply | BN | Collateral (exchange-price adjusted) |
| beforeSupply | BN | Raw collateral before adjustment |
| borrow | BN | Debt (exchange-price adjusted) |
| beforeBorrow | BN | Raw debt before adjustment |
| dustBorrow | BN | Dust debt (exchange-price adjusted) |
| beforeDustBorrow | BN | Raw dust debt |
| tick | number | Current tick |
| tickId | number | Tick ID |
| isLiquidated | boolean | Whether position was liquidated |
UserPositionWithDebt
| Field | Type | Description |
| ------------------------- | ---------- | ------------------------------- |
| tick | number | Position tick |
| tickId | number | Tick ID |
| colRaw | BN | Raw collateral |
| debtRaw | BN | Raw debt |
| dustDebtRaw | BN | Raw dust debt |
| finalAmount | BN | Net collateral after debt |
| isSupplyOnlyPosition | boolean | Whether supply-only |
| userLiquidationStatus | boolean? | Whether position was liquidated |
| postLiquidationBranchId | number? | Branch ID after liquidation |
Program IDs (Mainnet)
| Program | Address |
| ------------------------- | --------------------------------------------- |
| Liquidity | jupeiUmn818Jg1ekPURTpr4mFo29p46vygyykFJ3wZC |
| Lending | jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9 |
| Lending Reward Rate Model | jup7TthsMgcR9Y3L277b8Eo9uboVSmu1utkuXHNUKar |
| Vaults | jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi |
| Oracle | jupnw4B6Eqs7ft6rxpzYLJZYSnrpRgPcr589n5Kv4oc |
| Flashloan | jupgfSgfuAXv4B6R2Uxu85Z1qdzgju79s6MfZekN6XS |
All modules are read-only -- they fetch and decode on-chain accounts via RPC but never submit transactions.