@imbingox/acex 0.3.0-beta.5 → 0.3.0-beta.6

package/README.md

@@ -60,7 +60,7 @@ await client.stop();
 
 ### 同一个 client 同时使用 Binance + Juplend
 
-`createClient({ account: { binance: { riskPollIntervalMs }, juplend: { pollIntervalMs } } })` 只是分别配置 Binance 风险/仓位校准间隔和 Juplend 账户 polling 间隔，不代表这个 client 只能注册某个 venue。一个 `AcexClient` 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户，用同一个 `AccountManager` 对比风险值。
+`createClient({ account: { binance: { riskPollIntervalMs }, juplend: { pollIntervalMs, rpcUrl, jupApiKey } } })` 只是分别配置 Binance 风险/仓位校准间隔和 Juplend 账户 polling / RPC / Jup API，不代表这个 client 只能注册某个 venue。一个 `AcexClient` 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户，用同一个 `AccountManager` 对比风险值。
 
 ```ts
 const client = createClient({
@@ -70,6 +70,8 @@ const client = createClient({
     },
     juplend: {
       pollIntervalMs: 30_000,
+      rpcUrl: process.env.SOL_HELIUS_RPC,
+      jupApiKey: process.env.JUP_API,
     },
   },
 });
@@ -87,15 +89,21 @@ await client.registerAccount({
 await client.registerAccount({
   accountId: "jup-loop-a",
   venue: "juplend",
-  credentials: {
-    apiKey: process.env.JUPITER_API_KEY!,
-  },
   options: {
     walletAddress: "<solana-wallet-address>",
     positionId: "<optional-nft-position-id>",
   },
 });
 
+await client.registerAccount({
+  accountId: "jup-loop-direct",
+  venue: "juplend",
+  options: {
+    vaultId: "<vault-id>",
+    positionId: "<nft-position-id>",
+  },
+});
+
 await client.account.subscribeAccount({ accountId: "jup-loop-a" });
 await client.account.subscribeAccount({ accountId: "main-binance" });
 await client.order.subscribeOrders({ accountId: "main-binance" });
@@ -115,7 +123,7 @@ console.log({
 await client.stop();
 ```
 
-Juplend 使用 Jupiter Portfolio API 读取 Solana 钱包的借贷仓位，不需要私钥，也不支持 supply / borrow / repay / withdraw 等写操作。`accountId` 是你自定义的 SDK 账户名；Solana 钱包地址放在 `options.walletAddress`。如果只想观察某个 Juplend NFT position，可传 `options.positionId`。
+Juplend 使用 `@jup-ag/lend-read` 通过 Solana RPC 读取原生借贷仓位，不需要私钥，也不支持 supply / borrow / repay / withdraw 等写操作。`accountId` 是你自定义的 SDK 账户名。聚合钱包全部仓位时传 `options.walletAddress`；只想观察单个仓位时，可直接传 `options.vaultId + options.positionId`，这样不会先扫整个钱包。`account.juplend.rpcUrl` 可显式指定 RPC；未指定时默认读取 `SOL_HELIUS_RPC`，再 fallback 到 SDK 默认 RPC。token metadata / price 优先走 Jup 官方 `Tokens V2 + Price V3`，可通过 `account.juplend.jupApiKey` 或环境变量 `JUP_API` 注入；拿不到时退回 lite vault metadata。
 
 ### 查询 venue 能力
 
@@ -151,7 +159,7 @@ const capabilities = client.listVenueCapabilities();
 
 - 运行时 market/order 能力只支持 `binance`；`okx` / `bybit` / `gate` 仅类型定义
 - 账户视图支持 Binance PAPI UM 与 Juplend 只读借贷账户
-- Juplend 只读，不支持订单和链上写操作；token 数量来自 USD / oracle price 反算
+- Juplend 只读，不支持订单和链上写操作；仓位数量来自 `@jup-ag/lend-read` 原生 position 数据
 - Funding Rate 仅支持 Binance 永续合约，来自 mark price websocket；不支持现货和交割合约
 - `createOrder()` 只支持 `limit` / `market`；条件单、改单、账户级全撤不支持
 - 双向持仓账户下单时必须显式传 `positionSide`
@@ -209,14 +217,15 @@ bun run test:live:order:soak
 
 - `market`：`loadMarkets()`、`subscribeL1Book()`、`subscribeFundingRate()`、`getL1Book()` / `getL1Books()`、`getFundingRate()` / `getFundingRates()`、对应事件流和可选断线重连（`--disconnect-target funding` 可单独验证资金费率重连）
 - `account`：Binance PAPI UM 账户 bootstrap、余额/仓位/风险投影、private stream 更新和可选重连
-- `juplend`：Jupiter Portfolio API / vault 元数据连通性、lending balance facet、账户级 `riskRatio`、可选 `--position-id` 过滤单个 NFT position
+- `juplend`：`@jup-ag/lend-read` + Jup Tokens/Price API 连通性、lending balance facet、账户级 `riskRatio`、支持 `--wallet-address` 聚合或 `--vault-id + --position-id` 单仓直读
 - `order`：open orders bootstrap、`subscribeOrders()`、订单事件投影和可选重连
 
 Juplend live smoke 示例：
 
 ```bash
-JUPITER_API_KEY=... JUPLEND_WALLET_ADDRESS=<wallet> bun run test:live:juplend -- --show-amounts
-JUPITER_API_KEY=... bun run test:live:juplend -- --account-id jup-loop-a --wallet-address <wallet> --position-id <nftId> --show-amounts
+SOL_HELIUS_RPC=... JUPLEND_WALLET_ADDRESS=<wallet> bun run test:live:juplend -- --show-amounts
+bun run test:live:juplend -- --account-id jup-loop-a --wallet-address <wallet> --position-id <nftId> --rpc-url <rpc> --show-amounts
+bun run test:live:juplend -- --account-id jup-loop-a --vault-id <vaultId> --position-id <nftId> --rpc-url <rpc> --show-amounts
 ```
 
 ### 发布流程

package/docs/api.md

@@ -64,7 +64,7 @@ for await (const event of client.market.events.l1BookUpdates({
 await client.stop();
 ```
 
-同一个 client 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户。`account.binance.riskPollIntervalMs` 只配置 Binance 风险/仓位校准间隔；`account.juplend.pollIntervalMs` 只配置 Juplend polling 间隔，不会把 client 限定为某个 venue：
+同一个 client 可以同时注册 Binance 交易账户和 Juplend 借贷只读账户。`account.binance.riskPollIntervalMs` 只配置 Binance 风险/仓位校准间隔；`account.juplend.pollIntervalMs` / `rpcUrl` / `jupApiKey` 只配置 Juplend polling、RPC 和 Jup API，不会把 client 限定为某个 venue：
 
 ```ts
 const client = createClient({
@@ -74,6 +74,8 @@ const client = createClient({
     },
     juplend: {
       pollIntervalMs: 30_000,
+      rpcUrl: process.env.SOL_HELIUS_RPC,
+      jupApiKey: process.env.JUP_API,
     },
   },
 });
@@ -91,13 +93,21 @@ await client.registerAccount({
 await client.registerAccount({
   accountId: "jup-loop-a",
   venue: "juplend",
-  credentials: { apiKey: process.env.JUPITER_API_KEY! },
   options: {
     walletAddress: "<solana-wallet-address>",
     positionId: "<optional-nft-position-id>",
   },
 });
 
+await client.registerAccount({
+  accountId: "jup-loop-direct",
+  venue: "juplend",
+  options: {
+    vaultId: "<vault-id>",
+    positionId: "<nft-position-id>",
+  },
+});
+
 await client.account.subscribeAccount({ accountId: "main-binance" });
 await client.account.subscribeAccount({ accountId: "jup-loop-a" });
 
@@ -216,6 +226,7 @@ const client = createClient({
     },
     juplend: {
       pollIntervalMs: 30_000,
+      rpcUrl: process.env.SOL_HELIUS_RPC,
     },
   },
 });
@@ -295,12 +306,20 @@ await client.registerAccount({
 await client.registerAccount({
   accountId: "jup-loop-a",
   venue: "juplend",
-  credentials: { apiKey: jupiterApiKey },
   options: {
     walletAddress,
     positionId: "101", // 可选；不传则聚合该钱包全部 Juplend positions
   },
 });
+
+await client.registerAccount({
+  accountId: "jup-loop-direct",
+  venue: "juplend",
+  options: {
+    vaultId: "1",
+    positionId: "101", // 直接读取单个 vault 内的 NFT position
+  },
+});
 ```
 
 约束：
@@ -309,7 +328,8 @@ await client.registerAccount({
 - 凭证校验发生在 `subscribeAccount()` / `subscribeOrders()` 时，不是注册时
 - `updateAccountCredentials()` 可以在私有订阅活跃时调用，SDK 会按需重建私有链路
 - `removeAccount()` 比 `unsubscribeAccount()` 更彻底：账户配置、凭证、账户级缓存都会清理
-- Juplend 的 `accountId` 是自定义逻辑账户名；Solana 钱包地址必须放在 `options.walletAddress`，可用 `options.positionId` 把同钱包下单个 NFT position 映射为独立账户
+- Juplend 的 `accountId` 是自定义逻辑账户名；可传 `options.walletAddress` 聚合钱包全部仓位，或传 `options.vaultId + options.positionId` 直接读取单个仓位
+- Juplend 不要求 `credentials`；原生 read 默认读取 `SOL_HELIUS_RPC`，也可通过 `account.juplend.rpcUrl` 显式覆盖；token metadata / price 优先读取 `account.juplend.jupApiKey` 或环境变量 `JUP_API`
 
 ### 4.5 `getStatus()` / `getHealth()`
 
@@ -940,6 +960,8 @@ interface AccountRuntimeOptions {
   };
   juplend?: {
     pollIntervalMs?: number;
+    rpcUrl?: string;
+    jupApiKey?: string;
   };
 }
 
@@ -963,14 +985,17 @@ interface BinanceAccountOptions {
   recvWindow?: number;
 }
 
-interface JuplendAccountCredentials {
-  apiKey: string;
-}
-
-interface JuplendAccountOptions {
-  walletAddress: string;
-  positionId?: string;
-}
+type JuplendAccountOptions =
+  | {
+      walletAddress: string;
+      vaultId?: string;
+      positionId?: string;
+    }
+  | {
+      walletAddress?: string;
+      vaultId: string;
+      positionId: string;
+    };
 
 type RegisterAccountInput =
   | {
@@ -982,7 +1007,7 @@ type RegisterAccountInput =
   | {
       accountId: string;
       venue: "juplend";
-      credentials: JuplendAccountCredentials;
+      credentials?: AccountCredentials;
       options: JuplendAccountOptions;
     };
 
@@ -1444,8 +1469,8 @@ try {
 | `MARKET_STREAM_TIMEOUT` | market stream 首条消息超时 |
 | `ACCOUNT_ALREADY_EXISTS` | 重复注册同一个 `accountId` |
 | `ACCOUNT_NOT_FOUND` | `accountId` 未注册或已被移除 |
-| `ACCOUNT_BOOTSTRAP_FAILED` | `subscribeAccount()` 过程中账户快照拉取失败，例如 Juplend HTTP/API 失败或缺 `options.walletAddress` |
-| `CREDENTIALS_MISSING` | 私有订阅 / 下单缺必要凭证，例如 Binance 缺 `apiKey/secret` 或 Juplend 缺 `apiKey` |
+| `ACCOUNT_BOOTSTRAP_FAILED` | `subscribeAccount()` 过程中账户快照拉取失败，例如 Juplend HTTP/API 失败、缺 `options.walletAddress`，或 direct 模式下缺失/提供了无效的 `options.vaultId`、`options.positionId` |
+| `CREDENTIALS_MISSING` | 私有订阅 / 下单缺必要凭证，例如 Binance 缺 `apiKey/secret` |
 | `ORDER_BOOTSTRAP_FAILED` | `subscribeOrders()` 过程中 open orders 拉取失败 |
 | `ORDER_INPUT_INVALID` | 下单/撤单本地输入校验失败（如缺 price、缺 id） |
 | `ORDER_CREATE_FAILED` | 交易所拒单 / REST 报错 |
@@ -1458,7 +1483,7 @@ try {
 - **市场数据**：真实落地 Binance L1 Book（Spot + USDⓈ-M + COIN-M）和 Binance 永续 Funding Rate
 - **私有链路**：Binance PAPI UM 使用 listenKey/WebSocket；Juplend 使用 HTTP polling，只提供账户只读视图
 - **Juplend 写操作**：不支持 supply / borrow / repay / withdraw，不支持 `OrderManager` 下单撤单
-- **Juplend 数量精度**：Portfolio API 提供 USD 聚合值，token 数量由 USD / vault oracle price 反算
+- **Juplend 数据源**：账户主数据来自 `@jup-ag/lend-read` 原生 position read；token metadata / spot price 优先来自 Jup 官方 `Tokens V2 + Price V3`，lite vault metadata 只做 fallback
 - **Funding Rate**：仅永续合约支持，来自 mark price websocket；不支持现货和交割合约
 - **下单类型**：`createOrder()` 仅支持 `limit` / `market`；条件单、改单不支持
 - **撤单范围**：`cancelAllOrders()` 必须传 `symbol`，不支持账户级全撤

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imbingox/acex",
-  "version": "0.3.0-beta.5",
+  "version": "0.3.0-beta.6",
   "description": "Multi-exchange trading SDK for market data, account, and order management",
   "repository": {
     "type": "git",
@@ -53,6 +53,8 @@
     "typescript": "^6.0.2"
   },
   "dependencies": {
+    "@jup-ag/lend-read": "^0.0.12",
+    "@solana/web3.js": "^1.98.4",
     "bignumber.js": "^11.0.0"
   }
 }

package/src/adapters/juplend/lend-read.ts

@@ -0,0 +1,150 @@
+import { Client, DEFAULT_RPC_URL } from "@jup-ag/lend-read";
+import { PublicKey } from "@solana/web3.js";
+
+interface StringLike {
+  toString(): string;
+}
+
+export interface JuplendVaultLike {
+  constantViews: {
+    vaultId: number;
+    supplyToken: StringLike;
+    borrowToken: StringLike;
+  };
+  configs: {
+    liquidationThreshold: StringLike;
+  };
+  exchangePricesAndRates: {
+    supplyRateVault: StringLike;
+    borrowRateVault: StringLike;
+  };
+}
+
+export interface JuplendPositionLike {
+  nftId: number;
+  supply: StringLike;
+  borrow: StringLike;
+  dustBorrow: StringLike;
+  vault: JuplendVaultLike;
+}
+
+export interface JuplendVaultReader {
+  getAllUserPositions(user: PublicKey): Promise<JuplendPositionLike[]>;
+  getPositionByVaultId(
+    vaultId: number,
+    nftId: number,
+  ): Promise<JuplendPositionLike>;
+}
+
+export interface JuplendReadSdkLike {
+  createVaultReader(rpcUrl: string): JuplendVaultReader;
+}
+
+export interface JuplendReadPosition {
+  nftId: string;
+  vaultId: string;
+  supplyAmount: string;
+  borrowAmount: string;
+  dustBorrowAmount: string;
+  liquidationThresholdRaw: string;
+  supplyRateRaw: string;
+  borrowRateRaw: string;
+  supplyMintAddress: string;
+  borrowMintAddress: string;
+}
+
+const defaultSdk: JuplendReadSdkLike = {
+  createVaultReader(rpcUrl: string): JuplendVaultReader {
+    return new Client(rpcUrl).vault;
+  },
+};
+
+let activeSdk: JuplendReadSdkLike = defaultSdk;
+let readerCache = new Map<string, JuplendVaultReader>();
+
+export function getJuplendRpcUrl(explicitRpcUrl?: string): string {
+  return explicitRpcUrl || process.env.SOL_HELIUS_RPC || DEFAULT_RPC_URL;
+}
+
+function getVaultReader(rpcUrl: string): JuplendVaultReader {
+  const cached = readerCache.get(rpcUrl);
+  if (cached) {
+    return cached;
+  }
+
+  const created = activeSdk.createVaultReader(rpcUrl);
+  readerCache.set(rpcUrl, created);
+  return created;
+}
+
+function toJuplendId(value: string, field: "vaultId" | "positionId"): number {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`Invalid Juplend ${field}: ${value}`);
+  }
+
+  return parsed;
+}
+
+function mapReadPosition(position: JuplendPositionLike): JuplendReadPosition {
+  const vaultId = position.vault.constantViews.vaultId;
+
+  return {
+    nftId: `${position.nftId}`,
+    vaultId: `${vaultId}`,
+    supplyAmount: position.supply.toString(),
+    borrowAmount: position.borrow.toString(),
+    dustBorrowAmount: position.dustBorrow.toString(),
+    liquidationThresholdRaw:
+      position.vault.configs.liquidationThreshold.toString(),
+    supplyRateRaw:
+      position.vault.exchangePricesAndRates.supplyRateVault.toString(),
+    borrowRateRaw:
+      position.vault.exchangePricesAndRates.borrowRateVault.toString(),
+    supplyMintAddress: position.vault.constantViews.supplyToken.toString(),
+    borrowMintAddress: position.vault.constantViews.borrowToken.toString(),
+  };
+}
+
+export async function readJuplendPositions(input: {
+  walletAddress?: string;
+  vaultId?: string;
+  positionId?: string;
+  explicitRpcUrl?: string;
+}): Promise<{
+  rpcUrl: string;
+  positions: JuplendReadPosition[];
+}> {
+  const rpcUrl = getJuplendRpcUrl(input.explicitRpcUrl);
+  const reader = getVaultReader(rpcUrl);
+  const rawPositions =
+    input.vaultId && input.positionId
+      ? [
+          await reader.getPositionByVaultId(
+            toJuplendId(input.vaultId, "vaultId"),
+            toJuplendId(input.positionId, "positionId"),
+          ),
+        ]
+      : input.walletAddress
+        ? await reader.getAllUserPositions(new PublicKey(input.walletAddress))
+        : (() => {
+            throw new Error(
+              "Juplend read requires options.walletAddress or options.vaultId + options.positionId",
+            );
+          })();
+
+  return {
+    rpcUrl,
+    positions: rawPositions.map((position) => mapReadPosition(position)),
+  };
+}
+
+export function setJuplendReadSdkForTests(sdk: JuplendReadSdkLike): void {
+  activeSdk = sdk;
+  readerCache = new Map<string, JuplendVaultReader>();
+}
+
+export function resetJuplendReadSdkForTests(): void {
+  activeSdk = defaultSdk;
+  readerCache = new Map<string, JuplendVaultReader>();
+}

package/src/adapters/juplend/private-adapter.ts

@@ -18,42 +18,29 @@ import type {
   RawRiskUpdate,
   StreamHandle,
 } from "../types.ts";
+import { readJuplendPositions } from "./lend-read.ts";
 
-interface JuplendPortfolioResponse {
-  elements?: JuplendPortfolioElement[];
-}
-
-interface JuplendPortfolioElement {
-  data?: {
-    link?: string;
-    suppliedValue?: number | string;
-    borrowedValue?: number | string;
-    value?: number | string;
-  };
-}
-
-interface JuplendVaultResponse {
-  data?: JuplendVault[];
+interface JuplendTokenMetadata {
+  address?: string;
+  id?: string;
+  symbol?: string;
+  uiSymbol?: string;
+  decimals?: number | string;
+  price?: number | string;
+  usdPrice?: number | string;
+  oraclePrice?: number | string;
 }
 
-interface JuplendVault {
+interface JuplendVaultMetadata {
   id?: number | string;
   vaultId?: number | string;
-  supplyToken?: JuplendToken;
-  borrowToken?: JuplendToken;
+  supplyToken?: JuplendTokenMetadata;
+  borrowToken?: JuplendTokenMetadata;
   liquidationThreshold?: number | string;
-  loanToValue?: number | string;
   supplyRate?: number | string;
   borrowRate?: number | string;
 }
 
-interface JuplendToken {
-  symbol?: string;
-  asset?: string;
-  oraclePrice?: number | string;
-  price?: number | string;
-}
-
 interface JuplendMappedAccount {
   balances: RawBalanceUpdate[];
   risk?: RawRiskUpdate;
@@ -68,88 +55,125 @@ interface BalanceAccumulator {
 }
 
 interface JuplendAccountOptions {
-  walletAddress: string;
+  walletAddress?: string;
+  vaultId?: string;
   positionId?: string;
 }
 
-const PORTFOLIO_BASE_URL = "https://api.jup.ag/portfolio/v1";
-const VAULTS_URL = "https://lite-api.jup.ag/lend/v1/borrow/vaults";
-const DEFAULT_POLL_INTERVAL_MS = 30_000;
-const VAULT_CACHE_TTL_MS = 60 * 60 * 1_000;
-const LINK_PATTERN = /\/borrow\/([^/]+)\/nfts\/([^/?#]+)/;
+interface JuplendPriceApiEntry {
+  usdPrice?: number | string;
+  price?: number | string;
+  decimals?: number | string;
+}
 
-let vaultCache:
-  | {
-      loadedAt: number;
-      vaults: Map<string, JuplendVault>;
-    }
-  | undefined;
-let vaultCachePromise: Promise<Map<string, JuplendVault>> | undefined;
+interface JuplendTokenSearchEntry {
+  id?: string;
+  address?: string;
+  symbol?: string;
+  name?: string;
+  decimals?: number | string;
+  usdPrice?: number | string;
+}
 
-function requireApiKey(credentials: AccountCredentials): string {
-  if (!credentials.apiKey) {
-    throw new Error("credentials.apiKey required");
-  }
+const JUP_API_BASE_URL = "https://api.jup.ag";
+const JUP_LITE_API_BASE_URL = "https://lite-api.jup.ag";
+const TOKENS_SEARCH_PATH = "/tokens/v2/search";
+const PRICE_V3_PATH = "/price/v3";
+const LEND_VAULTS_PATH = "/lend/v1/borrow/vaults";
+const DEFAULT_POLL_INTERVAL_MS = 30_000;
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
+// lend-read returns exchange-price-adjusted amounts on a fixed 1e9 scale,
+// not mint-atomic token amounts.
+const POSITION_AMOUNT_SCALE_DECIMALS = 9;
+const VAULT_CACHE_TTL_MS = 60 * 60 * 1_000;
 
-  return credentials.apiKey;
+interface JuplendVaultEnrichmentCacheEntry {
+  loadedAt: number;
+  vaults: Map<string, JuplendVaultMetadata>;
+  enriched: boolean;
 }
 
+let enrichmentCache = new Map<string, JuplendVaultEnrichmentCacheEntry>();
+let enrichmentCachePromise = new Map<
+  string,
+  Promise<Map<string, JuplendVaultMetadata>>
+>();
+
 function getJuplendAccountOptions(
   accountOptions?: Record<string, unknown>,
 ): JuplendAccountOptions {
   const walletAddress = accountOptions?.walletAddress;
-  if (typeof walletAddress !== "string" || !walletAddress) {
-    throw new Error("options.walletAddress required");
+  if (walletAddress !== undefined && typeof walletAddress !== "string") {
+    throw new Error("options.walletAddress must be a string");
   }
 
-  const positionId = accountOptions.positionId;
+  const vaultId = accountOptions?.vaultId;
+  if (vaultId !== undefined && typeof vaultId !== "string") {
+    throw new Error("options.vaultId must be a string");
+  }
+  const positionId = accountOptions?.positionId;
   if (positionId !== undefined && typeof positionId !== "string") {
     throw new Error("options.positionId must be a string");
   }
 
+  const hasWalletAddress = Boolean(walletAddress);
+  const hasDirectPosition = Boolean(vaultId && positionId);
+  if (!hasWalletAddress && !hasDirectPosition) {
+    throw new Error(
+      "options.walletAddress or options.vaultId + options.positionId required",
+    );
+  }
+
   return {
-    walletAddress,
+    walletAddress: walletAddress || undefined,
+    vaultId: vaultId || undefined,
     positionId: positionId || undefined,
   };
 }
 
-function toBigNumber(value: number | string | undefined): BigNumber {
-  return value === undefined ? new BigNumber(0) : new BigNumber(value);
+function toBigNumber(
+  value: BigNumber.Value | undefined,
+  fallback = new BigNumber(0),
+): BigNumber {
+  return value === undefined ? fallback : new BigNumber(value);
 }
 
-function normalizeThreshold(value: number | string | undefined): BigNumber {
+function normalizeThreshold(value: BigNumber.Value | undefined): BigNumber {
   const threshold = toBigNumber(value);
   return threshold.gt(1) ? threshold.dividedBy(1000) : threshold;
 }
 
-function tokenAsset(token: JuplendToken | undefined): string | undefined {
-  return token?.symbol ?? token?.asset;
-}
-
-function tokenPrice(token: JuplendToken | undefined): BigNumber | undefined {
-  const price = toBigNumber(token?.oraclePrice ?? token?.price);
-  return price.gt(0) ? price : undefined;
-}
-
-function extractPositionLink(
-  link: string | undefined,
-): { vaultId: string; positionId: string } | undefined {
-  if (!link) {
+function normalizeRate(
+  value: BigNumber.Value | undefined,
+): BigNumber | undefined {
+  if (value === undefined) {
     return undefined;
   }
 
-  const match = LINK_PATTERN.exec(link);
-  if (!match?.[1] || !match[2]) {
+  const rate = new BigNumber(value);
+  if (!rate.isFinite()) {
     return undefined;
   }
 
-  return {
-    vaultId: match[1],
-    positionId: match[2],
-  };
+  return rate.gt(1) ? rate.dividedBy(10_000) : rate;
 }
 
-function getVaultId(vault: JuplendVault): string | undefined {
+function tokenAsset(
+  token: JuplendTokenMetadata | undefined,
+): string | undefined {
+  return token?.uiSymbol ?? token?.symbol;
+}
+
+function tokenPrice(
+  token: JuplendTokenMetadata | undefined,
+): BigNumber | undefined {
+  const price = toBigNumber(
+    token?.usdPrice ?? token?.price ?? token?.oraclePrice,
+  );
+  return price.gt(0) ? price : undefined;
+}
+
+function getVaultId(vault: JuplendVaultMetadata): string | undefined {
   const id = vault.id ?? vault.vaultId;
   return id === undefined ? undefined : `${id}`;
 }
@@ -237,119 +261,361 @@ function buildRisk(input: {
 }
 
 async function readJson<T>(url: string, init?: RequestInit): Promise<T> {
-  const response = await fetch(url, init);
-  if (!response.ok) {
-    throw new Error(`Juplend HTTP ${response.status}: ${response.statusText}`);
+  const controller = new AbortController();
+  const upstreamSignal = init?.signal;
+  let timedOut = false;
+  const onUpstreamAbort = () => {
+    controller.abort();
+  };
+
+  if (upstreamSignal?.aborted) {
+    controller.abort();
+  } else if (upstreamSignal) {
+    upstreamSignal.addEventListener("abort", onUpstreamAbort, { once: true });
   }
 
-  return (await response.json()) as T;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    controller.abort();
+  }, DEFAULT_HTTP_TIMEOUT_MS);
+
+  try {
+    const response = await fetch(url, {
+      ...init,
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      throw new Error(
+        `Juplend HTTP ${response.status}: ${response.statusText}`,
+      );
+    }
+
+    return (await response.json()) as T;
+  } catch (error) {
+    if (error instanceof Error && error.name === "AbortError") {
+      throw new Error(
+        timedOut
+          ? `Juplend fetch timeout after ${DEFAULT_HTTP_TIMEOUT_MS}ms`
+          : "Juplend fetch aborted",
+      );
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    if (upstreamSignal) {
+      upstreamSignal.removeEventListener("abort", onUpstreamAbort);
+    }
+  }
 }
 
-async function loadVaults(now: number): Promise<Map<string, JuplendVault>> {
-  if (vaultCache && now - vaultCache.loadedAt < VAULT_CACHE_TTL_MS) {
-    return vaultCache.vaults;
+function getJupApiKey(explicitApiKey?: string): string | undefined {
+  return explicitApiKey || process.env.JUP_API || undefined;
+}
+
+function getEnrichmentCacheKey(apiKey?: string): string {
+  return apiKey || "__no_jup_api_key__";
+}
+
+function buildApiHeaders(apiKey?: string): Record<string, string> | undefined {
+  return apiKey ? { "x-api-key": apiKey } : undefined;
+}
+
+function withBaseUrl(baseUrl: string, path: string): string {
+  return new URL(path, `${baseUrl}/`).toString();
+}
+
+async function loadVaultMetadataFromLiteApi(
+  apiKey?: string,
+): Promise<Map<string, JuplendVaultMetadata>> {
+  const response = await readJson<
+    JuplendVaultMetadata[] | { data?: JuplendVaultMetadata[] }
+  >(withBaseUrl(JUP_LITE_API_BASE_URL, LEND_VAULTS_PATH), {
+    headers: buildApiHeaders(apiKey),
+  });
+  const rawVaults = Array.isArray(response) ? response : response.data;
+  const vaults = new Map<string, JuplendVaultMetadata>();
+
+  for (const vault of rawVaults ?? []) {
+    const id = getVaultId(vault);
+    if (id) {
+      vaults.set(id, vault);
+    }
   }
 
-  if (!vaultCachePromise) {
-    vaultCachePromise = readJson<JuplendVaultResponse | JuplendVault[]>(
-      VAULTS_URL,
-    )
-      .then((response) => {
-        const rawVaults = Array.isArray(response) ? response : response.data;
-        const vaults = new Map<string, JuplendVault>();
-        for (const vault of rawVaults ?? []) {
-          const id = getVaultId(vault);
-          if (id) {
-            vaults.set(id, vault);
-          }
-        }
-        vaultCache = { loadedAt: now, vaults };
-        return vaults;
-      })
-      .finally(() => {
-        vaultCachePromise = undefined;
-      });
+  return vaults;
+}
+
+async function loadTokenSearchMap(
+  mintAddresses: string[],
+  apiKey?: string,
+): Promise<Map<string, JuplendTokenMetadata>> {
+  if (mintAddresses.length === 0) {
+    return new Map();
   }
 
-  try {
-    return await vaultCachePromise;
-  } catch (error) {
-    if (vaultCache) {
-      return vaultCache.vaults;
+  const query = encodeURIComponent(mintAddresses.join(","));
+  const response = await readJson<JuplendTokenSearchEntry[]>(
+    `${withBaseUrl(JUP_API_BASE_URL, TOKENS_SEARCH_PATH)}?query=${query}`,
+    {
+      headers: buildApiHeaders(apiKey),
+    },
+  );
+
+  const tokens = new Map<string, JuplendTokenMetadata>();
+  for (const token of response ?? []) {
+    const mint = token.id ?? token.address;
+    if (!mint) {
+      continue;
     }
-    throw error;
+
+    tokens.set(mint, {
+      address: mint,
+      id: mint,
+      symbol: token.symbol,
+      uiSymbol: token.symbol,
+      decimals: token.decimals,
+      usdPrice: token.usdPrice,
+      oraclePrice: token.usdPrice,
+    });
   }
+
+  return tokens;
 }
 
-async function loadPortfolio(
-  walletAddress: string,
-  apiKey: string,
-): Promise<JuplendPortfolioResponse> {
-  return readJson<JuplendPortfolioResponse>(
-    `${PORTFOLIO_BASE_URL}/positions/${walletAddress}?platforms=jupiter-exchange`,
+async function loadPriceMap(
+  mintAddresses: string[],
+  apiKey?: string,
+): Promise<Map<string, JuplendPriceApiEntry>> {
+  if (mintAddresses.length === 0) {
+    return new Map();
+  }
+
+  const ids = encodeURIComponent(mintAddresses.join(","));
+  const response = await readJson<Record<string, JuplendPriceApiEntry>>(
+    `${withBaseUrl(JUP_API_BASE_URL, PRICE_V3_PATH)}?ids=${ids}`,
     {
-      headers: {
-        "X-API-KEY": apiKey,
-      },
+      headers: buildApiHeaders(apiKey),
     },
   );
+
+  return new Map(Object.entries(response ?? {}));
 }
 
-function mapAccount(
-  portfolio: JuplendPortfolioResponse,
-  vaults: Map<string, JuplendVault>,
+function mergeTokenMetadata(
+  baseToken: JuplendTokenMetadata | undefined,
+  searchedToken: JuplendTokenMetadata | undefined,
+  pricedToken: JuplendPriceApiEntry | undefined,
+): JuplendTokenMetadata | undefined {
+  if (!baseToken && !searchedToken && !pricedToken) {
+    return undefined;
+  }
+
+  return {
+    ...baseToken,
+    ...searchedToken,
+    price:
+      pricedToken?.usdPrice ??
+      pricedToken?.price ??
+      searchedToken?.usdPrice ??
+      baseToken?.usdPrice ??
+      baseToken?.price ??
+      baseToken?.oraclePrice,
+    usdPrice:
+      pricedToken?.usdPrice ??
+      pricedToken?.price ??
+      searchedToken?.usdPrice ??
+      baseToken?.usdPrice ??
+      baseToken?.price ??
+      baseToken?.oraclePrice,
+    oraclePrice: baseToken?.oraclePrice,
+    decimals:
+      searchedToken?.decimals ?? pricedToken?.decimals ?? baseToken?.decimals,
+  };
+}
+
+async function enrichVaultsWithJupApi(input: {
+  apiKey?: string;
+  baseVaults: Map<string, JuplendVaultMetadata>;
+}): Promise<Map<string, JuplendVaultMetadata>> {
+  const mintAddresses = new Set<string>();
+  for (const vault of input.baseVaults.values()) {
+    const supplyMint = vault.supplyToken?.address;
+    const borrowMint = vault.borrowToken?.address;
+    if (supplyMint) {
+      mintAddresses.add(supplyMint);
+    }
+    if (borrowMint) {
+      mintAddresses.add(borrowMint);
+    }
+  }
+
+  const [tokenMap, priceMap] = await Promise.all([
+    loadTokenSearchMap([...mintAddresses], input.apiKey),
+    loadPriceMap([...mintAddresses], input.apiKey),
+  ]);
+
+  const enriched = new Map<string, JuplendVaultMetadata>();
+  for (const [vaultId, vault] of input.baseVaults.entries()) {
+    const supplyMint = vault.supplyToken?.address;
+    const borrowMint = vault.borrowToken?.address;
+
+    enriched.set(vaultId, {
+      ...vault,
+      supplyToken: mergeTokenMetadata(
+        vault.supplyToken,
+        supplyMint ? tokenMap.get(supplyMint) : undefined,
+        supplyMint ? priceMap.get(supplyMint) : undefined,
+      ),
+      borrowToken: mergeTokenMetadata(
+        vault.borrowToken,
+        borrowMint ? tokenMap.get(borrowMint) : undefined,
+        borrowMint ? priceMap.get(borrowMint) : undefined,
+      ),
+    });
+  }
+
+  return enriched;
+}
+
+async function loadVaults(
+  now: number,
+  apiKey?: string,
+): Promise<Map<string, JuplendVaultMetadata>> {
+  const cacheKey = getEnrichmentCacheKey(apiKey);
+  const cached = enrichmentCache.get(cacheKey);
+  const cacheFresh =
+    cached !== undefined && now - cached.loadedAt < VAULT_CACHE_TTL_MS;
+  if (cacheFresh && (cached.enriched || !apiKey)) {
+    return cached.vaults;
+  }
+
+  const inflight = enrichmentCachePromise.get(cacheKey);
+  if (!inflight) {
+    const nextPromise = (async () => {
+      const baseVaults = await loadVaultMetadataFromLiteApi(apiKey);
+      if (!apiKey) {
+        enrichmentCache.set(cacheKey, {
+          loadedAt: now,
+          vaults: baseVaults,
+          enriched: false,
+        });
+        return baseVaults;
+      }
+
+      try {
+        const enrichedVaults = await enrichVaultsWithJupApi({
+          apiKey,
+          baseVaults,
+        });
+        enrichmentCache.set(cacheKey, {
+          loadedAt: now,
+          vaults: enrichedVaults,
+          enriched: true,
+        });
+        return enrichedVaults;
+      } catch {
+        return baseVaults;
+      }
+    })().finally(() => {
+      enrichmentCachePromise.delete(cacheKey);
+    });
+
+    enrichmentCachePromise.set(cacheKey, nextPromise);
+  }
+
+  try {
+    return await (enrichmentCachePromise.get(cacheKey) as Promise<
+      Map<string, JuplendVaultMetadata>
+    >);
+  } catch (error) {
+    const fallbackCached = enrichmentCache.get(cacheKey);
+    if (fallbackCached) {
+      return fallbackCached.vaults;
+    }
+    throw error;
+  }
+}
+
+function dividePositionAmount(value: BigNumber): BigNumber {
+  return value.dividedBy(new BigNumber(10).pow(POSITION_AMOUNT_SCALE_DECIMALS));
+}
+
+async function mapAccount(
+  accountOptions: JuplendAccountOptions,
   receivedAt: number,
-  positionId?: string,
-): JuplendMappedAccount {
+  rpcUrl: string | undefined,
+  jupApiKey: string | undefined,
+): Promise<JuplendMappedAccount> {
+  const [vaults, positionResult] = await Promise.all([
+    loadVaults(receivedAt, jupApiKey),
+    readJuplendPositions({
+      walletAddress: accountOptions.walletAddress,
+      vaultId: accountOptions.vaultId,
+      positionId: accountOptions.positionId,
+      explicitRpcUrl: rpcUrl,
+    }),
+  ]);
+
   const balances = new Map<string, BalanceAccumulator>();
   let totalCollateralUsd = new BigNumber(0);
   let totalDebtUsd = new BigNumber(0);
   let weightedLiquidationValueUsd = new BigNumber(0);
 
-  for (const element of portfolio.elements ?? []) {
-    const positionLink = extractPositionLink(element.data?.link);
-    if (!positionLink) {
-      continue;
-    }
-
-    if (positionId && positionLink.positionId !== positionId) {
+  for (const position of positionResult.positions) {
+    if (
+      accountOptions.walletAddress &&
+      accountOptions.positionId &&
+      position.nftId !== accountOptions.positionId
+    ) {
       continue;
     }
 
-    const vault = vaults.get(positionLink.vaultId);
-    if (!vault) {
-      continue;
-    }
+    const vault = vaults.get(position.vaultId);
+    const suppliedQuantity = dividePositionAmount(
+      toBigNumber(position.supplyAmount),
+    );
+    const borrowedQuantity = dividePositionAmount(
+      toBigNumber(position.borrowAmount),
+    );
 
-    const suppliedValue = toBigNumber(element.data?.suppliedValue);
-    const borrowedValue = toBigNumber(element.data?.borrowedValue);
     const liquidationThreshold = normalizeThreshold(
-      vault.liquidationThreshold ?? vault.loanToValue,
-    );
-    totalCollateralUsd = totalCollateralUsd.plus(suppliedValue);
-    totalDebtUsd = totalDebtUsd.plus(borrowedValue);
-    weightedLiquidationValueUsd = weightedLiquidationValueUsd.plus(
-      suppliedValue.multipliedBy(liquidationThreshold),
+      position.liquidationThresholdRaw ?? vault?.liquidationThreshold,
     );
 
-    const supplyAsset = tokenAsset(vault.supplyToken);
-    const supplyPrice = tokenPrice(vault.supplyToken);
-    if (supplyAsset && supplyPrice) {
+    const supplyAsset =
+      tokenAsset(vault?.supplyToken) ?? vault?.supplyToken?.address;
+    if (supplyAsset) {
       const accumulator = setAccumulator(balances, supplyAsset);
-      accumulator.supplied = accumulator.supplied.plus(
-        suppliedValue.dividedBy(supplyPrice),
-      );
-      accumulator.supplyAPY = toBigNumber(vault.supplyRate);
+      accumulator.supplied = accumulator.supplied.plus(suppliedQuantity);
+      accumulator.supplyAPY =
+        normalizeRate(vault?.supplyRate ?? position.supplyRateRaw) ??
+        accumulator.supplyAPY;
     }
 
-    const borrowAsset = tokenAsset(vault.borrowToken);
-    const borrowPrice = tokenPrice(vault.borrowToken);
-    if (borrowAsset && borrowPrice) {
+    const borrowAsset =
+      tokenAsset(vault?.borrowToken) ?? vault?.borrowToken?.address;
+    if (borrowAsset) {
       const accumulator = setAccumulator(balances, borrowAsset);
-      accumulator.borrowed = accumulator.borrowed.plus(
-        borrowedValue.dividedBy(borrowPrice),
+      accumulator.borrowed = accumulator.borrowed.plus(borrowedQuantity);
+      accumulator.borrowAPY =
+        normalizeRate(vault?.borrowRate ?? position.borrowRateRaw) ??
+        accumulator.borrowAPY;
+    }
+
+    const supplyPrice = tokenPrice(vault?.supplyToken);
+    if (supplyPrice) {
+      const collateralUsd = suppliedQuantity.multipliedBy(supplyPrice);
+      totalCollateralUsd = totalCollateralUsd.plus(collateralUsd);
+      weightedLiquidationValueUsd = weightedLiquidationValueUsd.plus(
+        collateralUsd.multipliedBy(liquidationThreshold),
+      );
+    }
+
+    const borrowPrice = tokenPrice(vault?.borrowToken);
+    if (borrowPrice) {
+      totalDebtUsd = totalDebtUsd.plus(
+        borrowedQuantity.multipliedBy(borrowPrice),
       );
-      accumulator.borrowAPY = toBigNumber(vault.borrowRate);
     }
   }
 
@@ -379,7 +645,7 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
     positions: "unsupported",
     risk: "supported",
     lending: "supported",
-    credentialsRequired: true,
+    credentialsRequired: false,
   };
   readonly orderCapabilities: VenueOrderCapabilities = {
     supported: false,
@@ -397,22 +663,22 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
     reason: "read_only",
   };
 
+  constructor(
+    private readonly rpcUrl?: string,
+    private readonly jupApiKey?: string,
+  ) {}
+
   async bootstrapAccount(
-    credentials: AccountCredentials,
+    _credentials: AccountCredentials,
     accountOptions?: Record<string, unknown>,
   ): Promise<RawAccountBootstrap> {
     const receivedAt = Date.now();
-    const apiKey = requireApiKey(credentials);
     const juplendOptions = getJuplendAccountOptions(accountOptions);
-    const [portfolio, vaults] = await Promise.all([
-      loadPortfolio(juplendOptions.walletAddress, apiKey),
-      loadVaults(receivedAt),
-    ]);
-    const mapped = mapAccount(
-      portfolio,
-      vaults,
+    const mapped = await mapAccount(
+      juplendOptions,
       receivedAt,
-      juplendOptions.positionId,
+      this.rpcUrl,
+      getJupApiKey(this.jupApiKey),
     );
 
     return {
@@ -477,6 +743,7 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
         if (closed) {
           return;
         }
+
         callbacks.onAccountSnapshot(bootstrap);
       } catch (error) {
         callbacks.onError(
@@ -513,6 +780,9 @@ export class JuplendPrivateAdapter implements PrivateUserDataAdapter {
 }
 
 export function resetJuplendVaultCacheForTests(): void {
-  vaultCache = undefined;
-  vaultCachePromise = undefined;
+  enrichmentCache = new Map<string, JuplendVaultEnrichmentCacheEntry>();
+  enrichmentCachePromise = new Map<
+    string,
+    Promise<Map<string, JuplendVaultMetadata>>
+  >();
 }

package/src/client/context.ts

@@ -108,7 +108,7 @@ export function hasPrivateCredentials(
   venue?: Venue,
 ): boolean {
   if (venue === "juplend") {
-    return Boolean(credentials?.apiKey);
+    return true;
   }
 
   return Boolean(credentials?.apiKey && credentials.secret);

package/src/client/private-subscription-coordinator.ts

@@ -467,7 +467,7 @@ export class PrivateSubscriptionCoordinator {
     account: RegisteredAccountRecord,
   ): Promise<void> {
     const credentials = account.credentials;
-    if (!credentials) {
+    if (!credentials && record.venue !== "juplend") {
       throw new AcexError(
         "CREDENTIALS_MISSING",
         `Account credentials are required for private subscriptions: ${account.accountId}`,
@@ -476,7 +476,7 @@ export class PrivateSubscriptionCoordinator {
 
     const adapter = this.getAdapter(record.venue);
     const stream = adapter.createPrivateStream(
-      credentials,
+      credentials ?? {},
       {
         onAccountSnapshot: (snapshot) => {
           if (!record.accountSubscribed) {

package/src/client/runtime.ts

@@ -106,7 +106,10 @@ export class AcexClientImpl implements AcexClient, ClientContext {
     this.marketAdapters = new Map([[marketAdapter.venue, marketAdapter]]);
     const privateAdapters = [
       new BinancePrivateAdapter(),
-      new JuplendPrivateAdapter(),
+      new JuplendPrivateAdapter(
+        options.account?.juplend?.rpcUrl,
+        options.account?.juplend?.jupApiKey,
+      ),
     ];
     this.privateAdapters = new Map(
       privateAdapters.map((adapter) => [adapter.venue, adapter]),

package/src/managers/order-manager.ts

@@ -101,6 +101,13 @@ export class OrderManagerImpl
   async subscribeOrders(input: SubscribeOrdersInput): Promise<void> {
     this.context.assertStarted();
     const account = this.context.getRegisteredAccount(input.accountId);
+    if (account.venue === "juplend") {
+      throw this.createError(
+        "VENUE_NOT_SUPPORTED",
+        `Venue does not support private order subscriptions: ${account.venue}`,
+        { accountId: input.accountId, venue: account.venue },
+      );
+    }
     this.context.ensurePrivateCredentials(input.accountId);
 
     const record = this.getOrCreateRecord(input.accountId, account.venue);
@@ -635,6 +642,7 @@ export class OrderManagerImpl
 
   private createError(
     code:
+      | "VENUE_NOT_SUPPORTED"
       | "ORDER_CANCEL_ALL_FAILED"
       | "ORDER_CANCEL_FAILED"
       | "ORDER_CREATE_FAILED"

package/src/types/shared.ts

@@ -41,6 +41,8 @@ export interface AccountRuntimeOptions {
   };
   juplend?: {
     pollIntervalMs?: number;
+    rpcUrl?: string;
+    jupApiKey?: string;
   };
 }
 
@@ -64,14 +66,17 @@ export interface BinanceAccountOptions {
   recvWindow?: number;
 }
 
-export interface JuplendAccountCredentials {
-  apiKey: string;
-}
-
-export interface JuplendAccountOptions {
-  walletAddress: string;
-  positionId?: string;
-}
+export type JuplendAccountOptions =
+  | {
+      walletAddress: string;
+      vaultId?: string;
+      positionId?: string;
+    }
+  | {
+      walletAddress?: string;
+      vaultId: string;
+      positionId: string;
+    };
 
 export interface RegisterCexAccountInput {
   accountId: string;
@@ -83,7 +88,7 @@ export interface RegisterCexAccountInput {
 export interface RegisterJuplendAccountInput {
   accountId: string;
   venue: "juplend";
-  credentials: JuplendAccountCredentials;
+  credentials?: AccountCredentials;
   options: JuplendAccountOptions;
 }