@jup-ag/lend-read
v0.0.13
Published
utils for jup lend
Keywords
Readme
Jupiter Lend Read SDK
Read-only TypeScript SDK for Jupiter Lend on-chain programs. Provides typed access to Liquidity pools, Lending (jlToken) markets, Vaults, and the DEX 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, Dex } 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");
const dex = new Dex("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 |
DEX Module
Access DEX pool configuration, prices, collateral/debt reserves, swap limits, per-protocol positions, and pure off-chain swap / liquidity estimates.
A pool is identified by a numeric dexId (1..getTotalDexes()) and trades a token0 / token1 pair. A pool can enable smart collateral (isSmartCollateralEnabled) and/or smart debt (isSmartDebtEnabled); collateralReserves is null when smart collateral is off, and debtReserves is null when smart debt is off. All numeric values are BN. On Solana a pool's "users" are the child protocols that supply/borrow against it (e.g. T2/T3/T4 vaults), keyed by their protocol PublicKey.
Pools with an external center-price source have their center price fetched automatically from the oracle program (via a read-only simulateTransaction); internal-center-price pools skip that call. Estimates are computed fully off-chain from a single pool snapshot and mirror the on-chain program's rounding bit-for-bit.
new Dex(rpc?, opts?, market?, simulationPayer?);simulationPayer is the fee payer used for the read-only oracle simulation. It only needs to be a funded, system-owned account (no signature/lamports are spent) and defaults to a long-lived mainnet account; override it for other clusters.
Usage Examples
import BN from "bn.js";
import { PublicKey } from "@solana/web3.js";
const dexId = 1;
// Enumerate pools
const total = await client.dex.getTotalDexes();
const addresses = await client.dex.getAllDexAddresses();
const { token0, token1 } = await client.dex.getDexTokens(dexId);
// Complete pool data (configs + prices + reserves + state + swap limits)
const data = await client.dex.getDexEntireData(dexId);
const all = await client.dex.getAllDexEntireDatas();
// Targeted reads
const configs = await client.dex.getDexConfigs(dexId);
const pex = await client.dex.getDexPricesAndExchangePrices(dexId);
const colReserves = await client.dex.getDexCollateralReserves(dexId); // null if smart-col off
const debtReserves = await client.dex.getDexDebtReserves(dexId); // null if smart-debt off
const state = await client.dex.getDexState(dexId);
const limits = await client.dex.getDexSwapLimitsAndAvailability(dexId);
// Per-protocol (e.g. a vault) position on the pool
const protocol = new PublicKey("...");
const supply = await client.dex.getUserSupplyData(dexId, protocol);
const borrow = await client.dex.getUserBorrowData(dexId, protocol);
// Swap estimates (pure, off-chain)
const swapIn = await client.dex.estimateSwapIn(dexId, true, new BN(1_000_000));
const swapOut = await client.dex.estimateSwapOut(
dexId,
true,
new BN(1_000_000),
);
// Liquidity estimates
const shares = await client.dex.estimateDeposit(
dexId,
new BN(1_000_000),
new BN(1_000_000),
);
const { token0Amt, token1Amt } = await client.dex.estimateDepositPerfect(
dexId,
new BN(1_000_000),
);
const oneToken = await client.dex.estimateWithdrawPerfectInOneToken(
dexId,
new BN(1_000_000),
true,
);
// Reuse one snapshot for many pure computations
const snap = await client.dex.snapshot(dexId);Methods
| Method | Parameters | Returns | Description |
| ------------------------------------------------------------ | ------------------------------------------------------------------ | ---------------------------- | ------------------------------------------------ |
| getTotalDexes() | - | number | Total pools created (ids 1..N) |
| getAllDexAddresses() | - | PublicKey[] | Addresses of all pools |
| getDexAddress(dexId) | dexId: number | PublicKey | Pool PDA |
| getDexMetadataAddress(dexId) | dexId: number | PublicKey | Pool metadata PDA |
| getDexAdmin() | - | DexAdmin | DEX factory/admin account |
| getDexTokens(dexId) | dexId: number | { token0, token1 } | Pool token mints |
| snapshot(dexId, opts?) | dexId: number, { externalCenterPrice?: BN, nowSeconds?: number } | DexSnapshot | Fetch + decode a pool; base for all reads |
| getDexPricesAndExchangePrices(dexId) | dexId: number | PricesAndExchangePrice | Center price, ranges, exchange prices |
| getDexCollateralReserves(dexId) | dexId: number | CollateralReserves \| null | Collateral reserves (null if smart-col off) |
| getDexDebtReserves(dexId) | dexId: number | DebtReserves \| null | Debt reserves (null if smart-debt off) |
| getDexConfigs(dexId) | dexId: number | DexConfigs | Fee, ranges, thresholds, limits |
| getDexState(dexId) | dexId: number | DexState | Live prices, shifts, per-share reserves |
| getDexSwapLimitsAndAvailability(dexId) | dexId: number | SwapLimitsAndAvailability | Liquidity limits + utilization headroom |
| getDexEntireData(dexId) | dexId: number | DexEntireData | Complete pool data in one call |
| getDexEntireDatas(dexIds) | dexIds: number[] | DexEntireData[] | Complete data for several pools |
| getAllDexEntireDatas() | - | DexEntireData[] | Complete data for every pool |
| getUserSupplyData(dexId, protocol, nowSeconds?) | dexId, protocol: PublicKey, nowSeconds? | DexUserSupplyData | A protocol's supply position on the pool |
| getUserBorrowData(dexId, protocol, nowSeconds?) | dexId, protocol: PublicKey, nowSeconds? | DexUserBorrowData | A protocol's borrow position on the pool |
| getUserSupplyDatas(dexId, protocols, nowSeconds?) | dexId, protocols: PublicKey[] | DexUserSupplyData[] | Supply data for several protocols |
| getUserBorrowDatas(dexId, protocols, nowSeconds?) | dexId, protocols: PublicKey[] | DexUserBorrowData[] | Borrow data for several protocols |
| getUserBorrowSupplyDatas(dexId, protocols, nowSeconds?) | dexId, protocols: PublicKey[] | { supply: [], borrow: [] } | Both supply + borrow for several protocols |
| estimateSwapIn(dexId, swap0to1, amountIn, amountOutMin?) | dexId, swap0to1: boolean, amountIn: BN, amountOutMin?: BN | SwapResult | Exact-input swap estimate |
| estimateSwapOut(dexId, swap0to1, amountOut, amountInMax?) | dexId, swap0to1: boolean, amountOut: BN, amountInMax?: BN | SwapResult | Exact-output swap estimate |
| estimateDeposit(dexId, token0Amt, token1Amt) | dexId, token0Amt: BN, token1Amt: BN | BN | Shares minted for a token deposit |
| estimateDepositPerfect(dexId, shares) | dexId, shares: BN | { token0Amt, token1Amt } | Tokens required to mint exact shares |
| estimateWithdraw(dexId, token0Amt, token1Amt) | dexId, token0Amt: BN, token1Amt: BN | BN | Shares burned for a token withdraw |
| estimateWithdrawPerfect(dexId, shares) | dexId, shares: BN | { token0Amt, token1Amt } | Tokens out for burning exact shares |
| estimateWithdrawPerfectInOneToken(dexId, shares, inToken0) | dexId, shares: BN, inToken0: boolean | BN | Single-token amount out for exact shares |
| estimateBorrow(dexId, token0Amt, token1Amt) | dexId, token0Amt: BN, token1Amt: BN | BN | Shares minted for a token borrow |
| estimateBorrowPerfect(dexId, shares) | dexId, shares: BN | { token0Amt, token1Amt } | Tokens out for borrowing exact shares |
| estimatePayback(dexId, token0Amt, token1Amt) | dexId, token0Amt: BN, token1Amt: BN | BN | Shares burned for a token payback |
| estimatePaybackPerfect(dexId, shares) | dexId, shares: BN | { token0Amt, token1Amt } | Tokens required to burn exact shares |
| estimatePaybackPerfectInOneToken(dexId, shares, inToken0) | dexId, shares: BN, inToken0: boolean | BN | Single-token amount to pay exact shares |
| fetchExternalCenterPrice(oracle) | oracle: PublicKey | BN | Center price from the oracle program (0 on fail) |
Return Types
DexEntireData
| Field | Type | Description |
| ------------------------- | ---------------------------- | --------------------------------------- |
| dex | PublicKey | Pool PDA |
| dexId | number | Pool identifier |
| token0 | PublicKey | token0 mint |
| token1 | PublicKey | token1 mint |
| configs | DexConfigs | Fee, ranges, thresholds, limits |
| pricesAndExchangePrices | PricesAndExchangePrice | Prices + exchange prices |
| collateralReserves | CollateralReserves \| null | Collateral reserves (null if col off) |
| debtReserves | DebtReserves \| null | Debt reserves (null if debt off) |
| dexState | DexState | Live pool state |
| limitsAndAvailability | SwapLimitsAndAvailability | Liquidity limits + utilization headroom |
DexConfigs
| Field | Type | Description |
| -------------------------- | ----------- | ------------------------------------------- |
| isSmartCollateralEnabled | boolean | Smart collateral enabled |
| isSmartDebtEnabled | boolean | Smart debt enabled |
| fee | BN | Swap fee (4-dec, 1% = 10000) |
| revenueCut | BN | Revenue cut of fee |
| upperRange | BN | Upper price range |
| lowerRange | BN | Lower price range |
| upperShiftThreshold | BN | Upper rebalance threshold |
| lowerShiftThreshold | BN | Lower rebalance threshold |
| shiftingTime | BN | Range shift duration |
| centerPriceAddress | PublicKey | External center-price oracle (or default) |
| maxCenterPrice | BN | Center-price upper bound |
| minCenterPrice | BN | Center-price lower bound |
| utilizationLimitToken0 | BN | token0 utilization cap (1e3 = 100%) |
| utilizationLimitToken1 | BN | token1 utilization cap (1e3 = 100%) |
| maxSupplyShares | BN | Max supply shares |
| maxBorrowShares | BN | Max borrow shares |
PricesAndExchangePrice
| Field | Type | Description |
| ----------------- | ---------------- | ---------------------------------------- |
| lastStoredPrice | BN | Pool price after the most recent swap |
| centerPrice | BN | Center price (ranges derive from this) |
| upperRange | BN | Upper price range |
| lowerRange | BN | Lower price range |
| geometricMean | BN | Geometric mean of the range |
| exchangePrices | ExchangePrices | token0/1 supply + borrow exchange prices |
CollateralReserves / DebtReserves
| Field | Type | Description |
| ------------------------- | ---- | --------------------------------- |
| token0RealReserves | BN | token0 real reserves |
| token1RealReserves | BN | token1 real reserves |
| token0ImaginaryReserves | BN | token0 imaginary reserves |
| token1ImaginaryReserves | BN | token1 imaginary reserves |
| token0Debt* | BN | token0 debt (DebtReserves only) |
| token1Debt* | BN | token1 debt (DebtReserves only) |
SwapResult
| Field | Type | Description |
| ------------- | ---- | --------------------------------- |
| amountOut | BN | Total output amount |
| amountIn | BN | Total input amount |
| colWithdraw | BN | Output routed via collateral pool |
| debtBorrow | BN | Output routed via debt pool |
| colDeposit | BN | Input routed into collateral pool |
| debtPayback | BN | Input routed into debt pool |
| newPrice | BN | Pool price after the swap |
| centerPrice | BN | Center price used |
DexState
| Field | Type | Description |
| -------------------------- | -------------- | ------------------------------------------ |
| lastToLastStoredPrice | BN | Price two swaps ago |
| lastStoredPrice | BN | Price after the most recent swap |
| centerPrice | BN | Stored center price |
| lastUpdateTimestamp | BN | Last update unix time |
| lastUpdateSlot | BN | Last update slot |
| totalSupplyShares | BN | Total supply shares |
| totalBorrowShares | BN | Total borrow shares |
| isSwapAndArbitragePaused | boolean | Whether swaps/arbitrage are paused |
| shifts | ShiftChanges | Active range/threshold/center-price shifts |
| token0PerSupplyShare | BN | token0 per 1e9 supply shares |
| token1PerSupplyShare | BN | token1 per 1e9 supply shares |
| token0PerBorrowShare | BN | token0 per 1e9 borrow shares |
| token1PerBorrowShare | BN | token1 per 1e9 borrow shares |
SwapLimitsAndAvailability
| Field | Type | Description |
| ------------------------------------------------------- | ------------------ | -------------------------------------- |
| liquiditySupplyToken0 / ...Token1 | BN | Liquidity-layer total supply per token |
| liquidityBorrowToken0 / ...Token1 | BN | Liquidity-layer total borrow per token |
| liquidityWithdrawableToken0 / ...Token1 | BN | Withdrawable from liquidity per token |
| liquidityBorrowableToken0 / ...Token1 | BN | Borrowable from liquidity per token |
| utilizationLimitToken0 / ...Token1 | BN | Configured utilization cap amount |
| withdrawableUntilUtilizationLimitToken0 / ...Token1 | BN | Withdrawable before utilization cap |
| borrowableUntilUtilizationLimitToken0 / ...Token1 | BN | Borrowable before utilization cap |
| liquidityUserSupplyDataToken0 / ...Token1 | UserSupplyData | Pool's supply position on liquidity |
| liquidityUserBorrowDataToken0 / ...Token1 | UserBorrowData | Pool's borrow position on liquidity |
| liquidityTokenData0 / ...Data1 | OverallTokenData | Liquidity token data per token |
DexUserSupplyData
| Field | Type | Description |
| --------------------------------------------- | ------------------ | --------------------------------------- |
| isAllowed | boolean | Whether the protocol's supply is active |
| supply | BN | Supply shares |
| withdrawalLimit | BN | Current expanded withdrawal limit |
| lastUpdateTimestamp | BN | Last update unix time |
| expandPercent | BN | Withdrawal-limit expand percent |
| expandDuration | BN | Withdrawal-limit expand duration |
| baseWithdrawalLimit | BN | Base withdrawal limit |
| withdrawableUntilLimit | BN | Shares withdrawable before the limit |
| withdrawable | BN | Withdrawable shares |
| liquidityUserSupplyDataToken0 / ...Token1 | UserSupplyData | Pool's supply on liquidity per token |
| liquidityTokenData0 / ...Data1 | OverallTokenData | Liquidity token data per token |
DexUserBorrowData
| Field | Type | Description |
| --------------------------------------------- | ------------------ | --------------------------------------- |
| isAllowed | boolean | Whether the protocol's borrow is active |
| borrow | BN | Borrow shares |
| borrowLimit | BN | Current expanded borrow limit |
| lastUpdateTimestamp | BN | Last update unix time |
| expandPercent | BN | Borrow-limit expand percent |
| expandDuration | BN | Borrow-limit expand duration |
| baseBorrowLimit | BN | Base borrow limit (debt ceiling) |
| maxBorrowLimit | BN | Max borrow limit |
| borrowableUntilLimit | BN | Shares borrowable before the limit |
| borrowable | BN | Borrowable shares |
| liquidityUserBorrowDataToken0 / ...Token1 | UserBorrowData | Pool's borrow on liquidity per token |
| liquidityTokenData0 / ...Data1 | OverallTokenData | Liquidity token data per token |
Program IDs (Mainnet)
| Program | Address |
| ------------------------- | --------------------------------------------- |
| Liquidity | jupeiUmn818Jg1ekPURTpr4mFo29p46vygyykFJ3wZC |
| Lending | jup3YeL8QhtSx1e253b2FDvsMNC87fDrgQZivbrndc9 |
| Lending Reward Rate Model | jup7TthsMgcR9Y3L277b8Eo9uboVSmu1utkuXHNUKar |
| Vaults | jupr81YtYssSyPt8jbnGuiWon5f6x9TcDEFxYe3Bdzi |
| DEX | jupZ4m2GqUCJ5iueMfzQf8khFfH31d4XAQt3RzCT9Vd |
| Oracle | jupnw4B6Eqs7ft6rxpzYLJZYSnrpRgPcr589n5Kv4oc |
| Flashloan | jupgfSgfuAXv4B6R2Uxu85Z1qdzgju79s6MfZekN6XS |
All modules are read-only -- they fetch and decode on-chain accounts via RPC but never submit transactions.