@imbingox/acex 0.3.0-beta.4 → 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()`
 
@@ -618,7 +638,9 @@ const btcPosition = client.account.getPosition({
 const risk = client.account.getRiskSnapshot("main-binance");
 ```
 
-所有数量字段（`free` / `used` / `total` / `size` / `entryPrice` / `equity` / ...）都是 `BigNumber`。
+所有数量字段（`free` / `used` / `total` / `size` / `entryPrice` / `netEquity` / `riskEquity` / ...）都是 `BigNumber`。
+
+`RiskSnapshot.netEquity` 表示不含风控折算的净资产价值；`riskEquity` 表示抵押系数或清算阈值折算后的风控净权益。Binance 使用 `actualEquity` / `accountEquity` 映射这两个字段；Juplend 使用 `totalCollateralUsd - totalDebtUsd` / `Σ(suppliedValue × liquidationThreshold) - totalDebtUsd`。
 
 > **注意**：`AccountSnapshot.balances` 是 `Record<string, BalanceSnapshot>`，不是数组；需要数组视图用 `getBalances()`。
 
@@ -938,6 +960,8 @@ interface AccountRuntimeOptions {
   };
   juplend?: {
     pollIntervalMs?: number;
+    rpcUrl?: string;
+    jupApiKey?: string;
   };
 }
 
@@ -961,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 =
   | {
@@ -980,7 +1007,7 @@ type RegisterAccountInput =
   | {
       accountId: string;
       venue: "juplend";
-      credentials: JuplendAccountCredentials;
+      credentials?: AccountCredentials;
       options: JuplendAccountOptions;
     };
 
@@ -1222,9 +1249,10 @@ interface PositionSnapshot {
 interface RiskSnapshot {
   accountId: string;
   venue: Venue;
-  equity?: BigNumber;
+  netEquity?: BigNumber;
+  riskEquity?: BigNumber;
   riskRatio?: BigNumber;
-  actualLeverage?: BigNumber;
+  riskLeverage?: BigNumber;
   initialMargin?: BigNumber;
   maintenanceMargin?: BigNumber;
   exchangeTs?: number;
@@ -1441,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 报错 |
@@ -1455,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.4",
+  "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/binance/private-adapter.ts

@@ -38,6 +38,7 @@ interface BinancePapiBalance {
 
 interface BinancePapiAccount {
   accountEquity?: string;
+  actualEquity?: string;
   totalEquity?: string;
   accountInitialMargin?: string;
   totalInitialMargin?: string;
@@ -292,12 +293,14 @@ function mapAccountRisk(
   const riskRatio = uniMmr
     ? new BigNumber(1).dividedBy(uniMmr).toString(10)
     : undefined;
-  const equity = firstString(input.accountEquity, input.totalEquity);
-  const actualLeverage = calculateActualLeverage(equity, positions);
+  const netEquity = firstString(input.actualEquity);
+  const riskEquity = firstString(input.accountEquity, input.totalEquity);
+  const riskLeverage = calculateRiskLeverage(riskEquity, positions);
   const risk: RawRiskUpdate = {
-    equity,
+    netEquity,
+    riskEquity,
     riskRatio,
-    actualLeverage,
+    riskLeverage,
     initialMargin: firstString(
       input.accountInitialMargin,
       input.totalInitialMargin,
@@ -311,9 +314,10 @@ function mapAccountRisk(
   };
 
   if (
-    !risk.equity &&
+    !risk.netEquity &&
+    !risk.riskEquity &&
     !risk.riskRatio &&
-    !risk.actualLeverage &&
+    !risk.riskLeverage &&
     !risk.initialMargin &&
     !risk.maintenanceMargin
   ) {
@@ -323,16 +327,16 @@ function mapAccountRisk(
   return risk;
 }
 
-function calculateActualLeverage(
-  equity: string | undefined,
+function calculateRiskLeverage(
+  riskEquity: string | undefined,
   positions: BinancePapiUmPosition[],
 ): string | undefined {
-  if (!equity) {
+  if (!riskEquity) {
     return undefined;
   }
 
-  const equityValue = new BigNumber(equity);
-  if (!equityValue.isFinite() || equityValue.isZero()) {
+  const riskEquityValue = new BigNumber(riskEquity);
+  if (!riskEquityValue.isFinite() || riskEquityValue.isZero()) {
     return undefined;
   }
 
@@ -348,7 +352,7 @@ function calculateActualLeverage(
 
   return grossExposure.isZero()
     ? undefined
-    : grossExposure.dividedBy(equityValue).toString(10);
+    : grossExposure.dividedBy(riskEquityValue).toString(10);
 }
 
 function mapUmPosition(

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>();
+}