feat: add jup lend earn command

Author: AaronCQL

CLAUDE.md

@@ -24,12 +24,13 @@ bun run ci
 
 ## Architecture
 
-**Entry point:** `src/index.ts` — initializes config, registers 4 command groups with Commander.
+**Entry point:** `src/index.ts` — initializes config, registers 5 command groups with Commander.
 
 **Commands** (`src/commands/`): Static classes that register subcommands. Each delegates to library modules.
 
 - `ConfigCommand` — `config list`, `config set`
 - `KeysCommand` — `keys list/add/delete/edit/use/solana-import`
+- `LendCommand` — `lend earn tokens/positions/deposit/withdraw`
 - `PerpsCommand` — `perps positions/markets/open/set/close`
 - `SpotCommand` — `spot tokens/quote/swap/portfolio/transfer`
 
@@ -41,17 +42,21 @@ bun run ci
 - `KeyPair` — generates/recovers keypairs (BIP39 mnemonics, BIP32 derivation)
 - `Output` — renders data as table (via cli-table3) or JSON based on config; also provides display formatters (`formatDollar`, `formatBoolean`, `formatPercentageChange`)
 - `NumberConverter` — converts between human-readable and on-chain decimal amounts
+- `Swap` — shared swap execution logic used by SpotCommand and LendCommand
 
 **API Clients** (`src/clients/`):
 
 - `DatapiClient` — Jupiter token data/search API
 - `UltraClient` — Jupiter Ultra swap API (quote + execute)
 - `PerpsClient` — Jupiter Perps API v2 (positions, orders, TP/SL)
+- `LendClient` — Jupiter Lend API (earn tokens, positions, earnings)
 
-**Spot swap flow:** token search → UltraClient.getOrder → Signer.signTransaction → UltraClient.postExecute
+**Spot swap flow:** token search → Swap.execute → UltraClient.getOrder → Signer.signTransaction → UltraClient.postExecute
 
 **Perps flow:** PerpsClient.post* → Signer.signTransaction → PerpsClient.postExecute
 
+**Lend deposit/withdraw flow:** LendClient.getTokens → resolve jlToken → Swap.execute → LendClient.getPositions (updated state)
+
 ## CLI Conventions
 
 When adding new commands, both input (options/arguments) and output (JSON/table) must be consistent with existing commands so that both humans and AI agents can reliably use and parse them. Check `docs/` for the canonical command shapes.

README.md

@@ -40,6 +40,13 @@ jup spot swap --from SOL --to USDC --amount 1
 jup perps open --asset SOL --side long --amount 10 --input USDC --leverage 3
 # View your perps positions
 jup perps positions
+
+# View lending tokens and APY
+jup lend earn tokens
+# Deposit 100 USDC into lending
+jup lend earn deposit --token USDC --amount 100
+# View your lending positions
+jup lend earn positions
 ```
 
 ## Docs
@@ -54,6 +61,7 @@ jup perps positions
 - [Keys](docs/keys.md): Private key management
 - [Spot](docs/spot.md): Spot trading, transfers, token search and portfolio data
 - [Perps](docs/perps.md): Perps trading (leveraged longs/shorts)
+- [Lend](docs/lend.md): Lending and yield farming
 
 ## Changelog
 

docs/lend.md

@@ -0,0 +1,140 @@
+# Lending
+
+Requires: an active key for `deposit` and `withdraw` commands. See [setup](setup.md).
+
+## Commands
+
+### View available tokens
+
+```bash
+jup lend earn tokens
+```
+
+- Shows all tokens available for lending with APY, TVL, and withdrawable liquidity
+
+```js
+// Example JSON response:
+{
+  "tokens": [
+    {
+      "token": { "id": "EPjF...USDC", "symbol": "USDC", "decimals": 6 }, // underlying token
+      "jlToken": { "id": "jl1U...xxx", "symbol": "jlUSDC", "decimals": 6 }, // lending token
+      "apyPct": 5.97, // total APY; 5.97 means 5.97%
+      "supplyApyPct": 4.50, // supply rate portion
+      "rewardsApyPct": 1.47, // rewards rate portion
+      "totalTvlUsd": 125000000, // total TVL in USD
+      "withdrawableUsd": 80000000, // available withdrawable liquidity in USD
+      "priceUsd": 1.00 // underlying token price
+    }
+  ]
+}
+```
+
+### View positions
+
+```bash
+jup lend earn positions
+jup lend earn positions --key mykey
+jup lend earn positions --address <wallet-address>
+jup lend earn positions --token USDC
+```
+
+- With no options, uses the active key's wallet
+- `--address` looks up any wallet without needing a key
+- `--token` filters by underlying token (symbol or mint address)
+
+```js
+// Example JSON response:
+{
+  "positions": [
+    {
+      "token": { "id": "EPjF...USDC", "symbol": "USDC", "decimals": 6 }, // underlying token
+      "jlToken": { "id": "jl1U...xxx", "symbol": "jlUSDC", "decimals": 6 }, // derivative token
+      "positionAmount": 1025.30, // current position value in underlying token units, including earnings
+      "positionUsd": 1025.30, // current position value in USD
+      "earningsAmount": 24.80, // accrued interest in underlying token units
+      "earningsUsd": 24.80, // accrued interest in USD
+      "apyPct": 5.97 // current APY; 5.97 means 5.97%
+    }
+  ]
+}
+```
+
+### Deposit
+
+```bash
+jup lend earn deposit --token USDC --amount 100
+jup lend earn deposit --token SOL --amount 1.5 --key mykey
+jup lend earn deposit --token USDC --raw-amount 100000000
+```
+
+- `--token` (required) — underlying token to deposit (symbol or mint address)
+- `--amount` uses human-readable units (e.g. `100` USDC = 100 USDC)
+- `--raw-amount` uses on-chain units (e.g. `100000000` = 100 USDC)
+- Exactly one of `--amount` or `--raw-amount` is required
+- `--key` overrides the active key for this transaction
+
+```js
+// Example JSON response:
+{
+  "token": { "id": "EPjF...USDC", "symbol": "USDC", "decimals": 6 },
+  "depositedAmount": "100", // human-readable amount just deposited
+  "depositedUsd": 100.00, // USD value of deposit
+  "positionAmount": 1125.30, // total position after deposit
+  "positionUsd": 1125.30, // total position USD value
+  "apyPct": 5.97, // current APY; 5.97 means 5.97%
+  "signature": "3dV9...8zG1" // tx signature
+}
+```
+
+### Withdraw
+
+```bash
+jup lend earn withdraw --token USDC --amount 50
+jup lend earn withdraw --token USDC                   # withdraw entire position
+jup lend earn withdraw --token jlUSDC --amount 50     # also accepts jlToken directly
+jup lend earn withdraw --token USDC --raw-amount 50000000
+```
+
+- `--token` (required) — token to withdraw (accepts underlying symbol/address or jlToken symbol/address)
+- `--amount` in human-readable units of the underlying token
+- `--raw-amount` in on-chain units of the jlToken
+- When neither `--amount` nor `--raw-amount` is provided, withdraws the entire position
+- `--key` overrides the active key for this transaction
+
+```js
+// Example JSON response:
+{
+  "token": { "id": "EPjF...USDC", "symbol": "USDC", "decimals": 6 },
+  "withdrawnAmount": "50", // human-readable amount just withdrawn
+  "withdrawnUsd": 50.00, // USD value of withdrawal
+  "positionAmount": 975.30, // remaining position after withdrawal (0 if fully withdrawn)
+  "positionUsd": 975.30, // remaining position USD value
+  "apyPct": 5.97, // current APY; 5.97 means 5.97%
+  "signature": "5YhT...9AKU" // tx signature
+}
+```
+
+## Workflows
+
+### Check available tokens then deposit
+
+```bash
+jup lend earn tokens
+# Pick a token with good APY
+jup lend earn deposit --token USDC --amount 100
+```
+
+### Check positions then withdraw
+
+```bash
+jup lend earn positions
+# Review current value and earnings
+jup lend earn withdraw --token USDC --amount 50
+```
+
+### Withdraw entire position
+
+```bash
+jup lend earn withdraw --token USDC
+```

src/clients/DatapiClient.ts

@@ -154,4 +154,15 @@ export class DatapiClient {
     }
     return this.#ky.get("_datapi/v1/txs/users", { searchParams }).json();
   }
+
+  public static async resolveToken(input: string): Promise<Token> {
+    const [token] = await this.getTokensSearch({
+      query: input,
+      limit: "1",
+    });
+    if (!token) {
+      throw new Error(`Token not found: ${input}`);
+    }
+    return token;
+  }
 }

src/clients/LendClient.ts

@@ -0,0 +1,83 @@
+import ky from "ky";
+
+import { ClientConfig } from "./ClientConfig.ts";
+
+export type LendAsset = {
+  address: string;
+  chain_id: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+  logo_url: string;
+  price: string;
+  coingecko_id: string;
+};
+
+export type LiquiditySupplyData = {
+  modeWithInterest: boolean;
+  supply: string;
+  withdrawalLimit: string;
+  lastUpdateTimestamp: string;
+  expandPercent: string;
+  expandDuration: string;
+  baseWithdrawalLimit: string;
+  withdrawableUntilLimit: string;
+  withdrawable: string;
+};
+
+export type LendToken = {
+  id: number;
+  address: string;
+  name: string;
+  symbol: string;
+  decimals: number;
+  assetAddress: string;
+  asset: LendAsset;
+  totalAssets: string;
+  totalSupply: string;
+  convertToShares: string;
+  convertToAssets: string;
+  rewardsRate: string;
+  supplyRate: string;
+  totalRate: string;
+  rebalanceDifference: string;
+  liquiditySupplyData: LiquiditySupplyData;
+};
+
+export type LendPosition = {
+  token: LendToken;
+  ownerAddress: string;
+  shares: string;
+  underlyingAssets: string;
+  underlyingBalance: string;
+  allowance: string;
+};
+
+export type LendEarning = {
+  address: string;
+  ownerAddress: string;
+  earnings: number;
+  slot: number;
+};
+
+export class LendClient {
+  static readonly #ky = ky.create({
+    prefixUrl: `${ClientConfig.host}/lend/v1`,
+    headers: ClientConfig.headers,
+  });
+
+  public static async getTokens(): Promise<LendToken[]> {
+    return this.#ky.get("earn/tokens").json();
+  }
+
+  public static async getPositions(users: string): Promise<LendPosition[]> {
+    return this.#ky.get("earn/positions", { searchParams: { users } }).json();
+  }
+
+  public static async getEarnings(req: {
+    user: string;
+    positions: string;
+  }): Promise<LendEarning[]> {
+    return this.#ky.get("earn/earnings", { searchParams: req }).json();
+  }
+}