jupiter-lend

What this skill does

# Jupiter Lend Protocol

Jupiter Lend (powered by Fluid Protocol) is a lending and borrowing protocol on Solana. It offers **Liquidity Pools**, **Lending Markets (jlTokens)**, and **Vaults** for leveraged positions.

The protocol uses two main SDKs:

- `@jup-ag/lend-read`: Read-only queries for all programs (Liquidity, Lending, Vaults)
- `@jup-ag/lend`: Write operations (deposit, withdraw, borrow, repay)

## Agent usage

Example prompts you can use to demo Jupiter Lend integrations:

- Discover all available vaults and list them
- Fetch all vault positions for a user
- Deposit collateral and borrow in a single transaction
- Repay max debt and withdraw max collateral for a position
- Get user Earn (jlToken) positions and underlying balances
- Build a flashloan for arbitrage or liquidation
- Get liquidity rates and APY for a token
- Create a new vault position (positionId 0), deposit collateral, and borrow

## SDK Installation

```bash
# For read operations (queries, prices, positions)
npm install @jup-ag/lend-read

# For write operations (transactions)
npm install @jup-ag/lend
```

---

# 1. Key Concepts & Protocol Jargon

Understanding the architecture and terminology of Jupiter Lend will help you build better integrations.

### Architecture: The Two-Layer Model

- **Liquidity Layer (Single Orderbook)**: The foundational layer where all assets reside. It manages token limits, rate curves, and unified liquidity. Users never interact with this directly.
- **Protocol Layer**: User-facing modules (Lending and Vaults) that sit on top of the Liquidity Layer and interact with it via Cross-Program Invocations (CPIs).

### Terminology

- **jlToken (Jupiter Lend Token)**: The yield-bearing asset you receive when supplying tokens to the Lending protocol (e.g., `jlUSDC`). As interest accrues, the exchange rate increases, making your `jlToken` worth more underlying `USDC`.
- **Exchange Price**: The conversion rate used to translate between "raw" stored amounts and actual token amounts. It continuously increases as interest is earned on supply or accrued on debt.
- **Collateral Factor (CF)**: The maximum Loan-to-Value (LTV) ratio allowed when opening or managing a position.
- **Liquidation Threshold (LT)**: The LTV at which a position becomes undercollateralized and eligible for liquidation.
- **Liquidation Max Limit (LML)**: The absolute maximum LTV limit. If a position's risk ratio exceeds this boundary, it is automatically absorbed by the protocol to protect liquidity providers.
- **Liquidation Penalty**: The discount percentage offered to liquidators when they repay debt on behalf of a risky position.
- **Rebalance**: An operation that synchronizes the upper protocol layer's accounting (Vaults/Lending) with its actual position on the Liquidity layer. It also syncs the orderbook to account for any active accrued rewards.
- **Tick-based Architecture**: The Vaults protocol groups positions into "ticks" based on their risk level (debt-to-collateral ratio). This allows the protocol to efficiently manage risk and process liquidations at scale.
- **Dust Borrow**: A tiny residual amount of debt intentionally kept on positions to handle division rounding complexities.
- **Sentinel Values**: Constants like `MAX_WITHDRAW_AMOUNT` and `MAX_REPAY_AMOUNT` that tell the protocol to dynamically calculate and withdraw/repay the maximum mathematically possible amount for a position.

### Amounts and units

All SDK amounts use **base units** (smallest token unit, e.g. `1_000_000` = 1 USDC for 6 decimals).

---

# 2. Jupiter Earn (Lending)

Jupiter Earn allows users to supply assets to earn yield. In return, users receive yield-bearing `jlTokens` (e.g., `jlUSDC`).

### Lending Module (jlTokens)

Access jlToken (Jupiter Lend token) markets, exchange prices, and user positions.

```typescript
// Get all jlToken details at once
const allDetails = await client.lending.getAllJlTokenDetails();

// Get user's jlToken balance
const position = await client.lending.getUserPosition(USDC, userPublicKey);
```

## Lending (Earn)

Deposit underlying assets to receive yield-bearing tokens, or withdraw them.

```typescript
import { getDepositIxs, getWithdrawIxs } from "@jup-ag/lend/earn";
import BN from "bn.js";

// Deposit 1 USDC (base units: 1_000_000 for 6 decimals)
const { ixs: depositIxs } = await getDepositIxs({
  amount: new BN(1_000_000),
  asset: USDC_PUBKEY,
  signer: userPublicKey,
  connection,
});

// Withdraw 0.1 USDC (100_000 base units @ 6 decimals)
const { ixs: withdrawIxs } = await getWithdrawIxs({
  amount: new BN(100_000),
  asset: USDC_PUBKEY,
  signer: userPublicKey,
  connection,
});
```

---

# 3. Jupiter Borrow (Vaults)

Vaults handle collateral deposits and debt borrowing.

### Vault Module & Discovery

Access vault configurations, positions, exchange prices, and liquidation data. This is crucial for dynamically listing all available leverage markets.

```typescript
// Discover all available vaults
const allVaults = await client.vault.getAllVaults();
const totalVaults = allVaults.length;

// Get comprehensive vault data (config + state + rates + limits) for a specific vault
const vaultId = 1;
const vaultData = await client.vault.getVaultByVaultId(vaultId);

// Check borrowing limits dynamically before prompting users
const borrowLimit = vaultData.limitsAndAvailability.borrowLimit;
const borrowable = vaultData.limitsAndAvailability.borrowable;
```

---

### Finding User Vault Positions

Before making Vault operations (like deposit, borrow, or repay), you need to know a user's existing `positionId` (which maps to an NFT).

```typescript
const userPublicKey = new PublicKey("YOUR_WALLET_PUBKEY");

// Retrieve all positions owned by the user
// Each position includes full vault data: NftPosition & { vault: VaultEntireData }
const positions = await client.vault.getAllUserPositions(userPublicKey);

positions.forEach((p) => {
  console.log(`Position ID (nftId): ${p.nftId}`);
  console.log(`Vault ID: ${p.vault.constantViews.vaultId}`);
  console.log(`Collateral Supplied: ${p.supply.toString()}`);
  console.log(`Debt Borrowed: ${p.borrow.toString()}`);
});
```

## Vaults (Borrow)

Vaults handle collateral deposits and debt borrowing. **All vault operations use the `getOperateIx` function.**

The direction of the operation is determined by the sign of `colAmount` and `debtAmount`:

- **Deposit**: `colAmount` > 0, `debtAmount` = 0
- **Withdraw**: `colAmount` < 0, `debtAmount` = 0
- **Borrow**: `colAmount` = 0, `debtAmount` > 0
- **Repay**: `colAmount` = 0, `debtAmount` < 0

**Sentinels**: `MAX_REPAY_AMOUNT` and `MAX_WITHDRAW_AMOUNT` are already signed (negative); pass them as-is—do not call `.neg()` on them.

**Important**: If `positionId` is `0`, a new position NFT is created, and the SDK returns the new `positionId`.

### Common Vault Patterns

**1. Deposit Collateral**

```typescript
import { getOperateIx } from "@jup-ag/lend/borrow";

// Deposit 1 USDC (base units: 1_000_000 for 6 decimals)
const { ixs, addressLookupTableAccounts, positionId: newPositionId } = await getOperateIx({
  vaultId: 1,
  positionId: 0, // 0 = create new position
  colAmount: new BN(1_000_000), // Positive = Deposit
  debtAmount: new BN(0),
  connection,
  signer,
});
```

**2. Borrow Debt**

```typescript
// Borrow 0.5 USDC (500_000 base units @ 6 decimals)
const { ixs, addressLookupTableAccounts } = await getOperateIx({
  vaultId: 1,
  positionId: EXISTING_POSITION_ID, // Use the nftId retrieved from the read SDK
  colAmount: new BN(0),
  debtAmount: new BN(500_000), // Positive = Borrow (0.5 USDC @ 6 decimals)
  connection,
  signer,
});
```

**3. Repay Debt (Using Max Sentinel)**
When users want to repay their *entire* debt, do not try to calculate exact dust amounts. Use the `MAX_REPAY_AMOUNT` sentinel exported by the SDK.

```typescript
import { getOperateIx, MAX_REPAY_AMOUNT } from "@jup-ag/lend/borrow";

const { ixs, addressLookupTableAccounts } = await getOperateIx({
  vaultId: 1,
  positionId