perp-cli 0.4.2 → 0.4.9

package/dist/exchanges/pacifica.js

@@ -1,22 +1,37 @@
-import nacl from "tweetnacl";
 import { PacificaClient } from "../pacifica/index.js";
-function makeSignMessage(keypair) {
-    return async (message) => {
-        return nacl.sign.detached(message, keypair.secretKey);
-    };
-}
+import { LocalSolanaSigner } from "../signer/solana-local.js";
 export class PacificaAdapter {
     name = "pacifica";
     client;
-    keypair;
+    _solanaSigner;
+    _hasRealKey;
     account;
     signMessage;
     // In-memory caches removed — using file-based cache (src/cache.ts) for cross-process dedup
-    constructor(keypair, network = "mainnet", builderCode) {
-        this.keypair = keypair;
-        this.account = keypair.publicKey.toBase58();
+    constructor(keypair, network = "mainnet", builderCode, hasRealKey = true) {
+        this._solanaSigner = new LocalSolanaSigner(keypair);
+        this._hasRealKey = hasRealKey;
+        this.account = this._solanaSigner.getPublicKeyBase58();
         this.client = new PacificaClient({ network, builderCode });
-        this.signMessage = makeSignMessage(keypair);
+        this.signMessage = (msg) => this._solanaSigner.signMessage(msg);
+    }
+    ensureSigner() {
+        if (!this._hasRealKey) {
+            throw new Error("No private key configured. Run: perp init");
+        }
+    }
+    /** Inject an external Solana signer. */
+    setSigner(signer) {
+        this._solanaSigner = signer;
+        this.account = signer.getPublicKeyBase58();
+        this.signMessage = (msg) => this._solanaSigner.signMessage(msg);
+    }
+    /** Access the underlying Keypair (only available with LocalSolanaSigner). */
+    get keypair() {
+        if (this._solanaSigner instanceof LocalSolanaSigner) {
+            return this._solanaSigner._keypair;
+        }
+        throw new Error("keypair not available with external signer");
     }
     async _getPrices() {
         const { fetchAndCache, TTL_ACCOUNT } = await import("../cache.js");
@@ -62,24 +77,15 @@ export class PacificaAdapter {
         };
     }
     async getBalance() {
-        const [info, positions, prices] = await Promise.all([
+        if (!this._hasRealKey)
+            throw new Error("No private key configured — account data unavailable. Run: perp init");
+        const [info, positions] = await Promise.all([
             this.client.getAccount(this.account),
             this._getPositions(),
-            this._getPrices(),
         ]);
         const raw = info;
-        const priceMap = new Map(prices.map((p) => [p.symbol, Number(p.mark)]));
-        // Sum actual unrealized PnL from positions (mark vs entry)
-        let totalPnl = 0;
-        for (const p of positions) {
-            const mark = priceMap.get(p.symbol) ?? 0;
-            const entry = Number(p.entry_price);
-            const amount = Number(p.amount);
-            const side = p.side === "bid" ? "long" : "short";
-            totalPnl += side === "long"
-                ? (mark - entry) * amount
-                : (entry - mark) * amount;
-        }
+        // Use API-provided unrealized PnL from positions
+        const totalPnl = positions.reduce((sum, p) => sum + Number(p.unrealized_pnl ?? 0), 0);
         return {
             equity: info.account_equity,
             available: info.available_to_spend,
@@ -88,6 +94,8 @@ export class PacificaAdapter {
         };
     }
     async getPositions() {
+        if (!this._hasRealKey)
+            throw new Error("No private key configured — account data unavailable. Run: perp init");
         const [positions, prices] = await Promise.all([
             this._getPositions(),
             this._getPrices(),
@@ -104,14 +112,8 @@ export class PacificaAdapter {
             // Settings API may not be available
         }
         return positions.map((p) => {
-            const mark = priceMap.get(p.symbol)?.mark ?? "0";
-            const entryPrice = Number(p.entry_price);
-            const amount = Number(p.amount);
-            const markNum = Number(mark);
+            const mark = priceMap.get(p.symbol)?.mark ?? p.mark_price ?? "0";
             const side = p.side === "bid" ? "long" : "short";
-            const pnl = side === "long"
-                ? (markNum - entryPrice) * amount
-                : (entryPrice - markNum) * amount;
             return {
                 symbol: p.symbol,
                 side: side,
@@ -119,12 +121,14 @@ export class PacificaAdapter {
                 entryPrice: String(p.entry_price),
                 markPrice: mark,
                 liquidationPrice: String(p.liquidation_price ?? "N/A"),
-                unrealizedPnl: pnl.toFixed(4),
-                leverage: levMap.get(String(p.symbol)) ?? 1,
+                unrealizedPnl: String(p.unrealized_pnl ?? "0"),
+                leverage: p.leverage ?? levMap.get(String(p.symbol)) ?? 1,
             };
         });
     }
     async getOpenOrders() {
+        if (!this._hasRealKey)
+            throw new Error("No private key configured — account data unavailable. Run: perp init");
         const orders = await this.client.getOrders(this.account);
         return orders.map((o) => {
             const raw = o;
@@ -141,21 +145,37 @@ export class PacificaAdapter {
         });
     }
     async marketOrder(symbol, side, size) {
+        this.ensureSigner();
         return this.client.createMarketOrder({ symbol, amount: size, side: side === "buy" ? "bid" : "ask", reduce_only: false, slippage_percent: "1" }, this.account, this.signMessage);
     }
     async limitOrder(symbol, side, price, size, opts) {
+        this.ensureSigner();
         return this.client.createLimitOrder({ symbol, price, amount: size, side: side === "buy" ? "bid" : "ask", reduce_only: opts?.reduceOnly ?? false, tif: (opts?.tif ?? "GTC") }, this.account, this.signMessage);
     }
     async cancelOrder(symbol, orderId) {
+        this.ensureSigner();
         return this.client.cancelOrder({ symbol, order_id: Number(orderId) }, this.account, this.signMessage);
     }
-    async cancelAllOrders(_symbol) {
+    async cancelAllOrders(symbol) {
+        this.ensureSigner();
+        if (symbol) {
+            // Cancel only orders for this symbol: fetch open orders, filter, cancel individually
+            const orders = await this.getOpenOrders();
+            const filtered = orders.filter(o => o.symbol.toUpperCase() === symbol.toUpperCase());
+            const results = [];
+            for (const o of filtered) {
+                results.push(await this.cancelOrder(o.symbol, o.orderId));
+            }
+            return results;
+        }
         return this.client.cancelAllOrders({ all_symbols: true, exclude_reduce_only: false }, this.account, this.signMessage);
     }
     async editOrder(symbol, orderId, price, size) {
+        this.ensureSigner();
         return this.client.editOrder({ symbol, order_id: Number(orderId), price, amount: size }, this.account, this.signMessage);
     }
     async setLeverage(symbol, leverage, marginMode = "cross") {
+        this.ensureSigner();
         await this.client.updateLeverage({ symbol, leverage }, this.account, this.signMessage);
         if (marginMode === "isolated") {
             await this.client.updateMarginMode({ symbol, is_isolated: true }, this.account, this.signMessage);
@@ -163,6 +183,7 @@ export class PacificaAdapter {
         return { symbol, leverage, marginMode };
     }
     async stopOrder(symbol, side, size, triggerPrice, opts) {
+        this.ensureSigner();
         return this.client.createStopOrder({
             symbol,
             side: side === "buy" ? "bid" : "ask",
@@ -173,12 +194,12 @@ export class PacificaAdapter {
     async getRecentTrades(symbol, _limit = 20) {
         const trades = await this.client.getTrades(symbol);
         return trades.slice(0, _limit).map((t) => ({
-            time: new Date(t.created_at).getTime(),
+            time: Number(t.created_at ?? 0),
             symbol,
             side: t.side === "bid" ? "buy" : "sell",
             price: t.price,
             size: t.amount,
-            fee: "0",
+            fee: String(t.fee ?? "0"),
         }));
     }
     async getFundingHistory(symbol, limit = 10) {
@@ -205,6 +226,8 @@ export class PacificaAdapter {
         }));
     }
     async getOrderHistory(limit = 30) {
+        if (!this._hasRealKey)
+            throw new Error("No private key configured — account data unavailable. Run: perp init");
         const result = await this.client.getOrderHistory(this.account);
         const data = (result.data ?? result.orders ?? []);
         if (!Array.isArray(data))
@@ -221,6 +244,8 @@ export class PacificaAdapter {
         }));
     }
     async getTradeHistory(limit = 30) {
+        if (!this._hasRealKey)
+            throw new Error("No private key configured — account data unavailable. Run: perp init");
         const raw = await this.client.getTradeHistory(this.account);
         const trades = (raw.data ?? raw);
         if (!Array.isArray(trades))
@@ -235,6 +260,8 @@ export class PacificaAdapter {
         }));
     }
     async getFundingPayments(limit = 30) {
+        if (!this._hasRealKey)
+            throw new Error("No private key configured — account data unavailable. Run: perp init");
         const raw = await this.client.getFundingAccountHistory(this.account);
         const history = (raw.data ?? raw);
         if (!Array.isArray(history))

package/dist/exchanges/spot-interface.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Spot trading interface for exchanges that support both spot and perp.
+ * Separate from ExchangeAdapter because spot uses balance-based tracking
+ * (not position-based) and has no leverage, liquidation, or funding concepts.
+ *
+ * Supported: Hyperliquid, Lighter (Pacifica is perp-only)
+ */
+export interface SpotMarketInfo {
+    symbol: string;
+    baseToken: string;
+    quoteToken: string;
+    markPrice: string;
+    volume24h: string;
+    sizeDecimals: number;
+    priceDecimals: number;
+}
+export interface SpotBalance {
+    token: string;
+    total: string;
+    available: string;
+    held: string;
+}
+export interface SpotAdapter {
+    readonly name: string;
+    getSpotMarkets(): Promise<SpotMarketInfo[]>;
+    getSpotOrderbook(symbol: string): Promise<{
+        bids: [string, string][];
+        asks: [string, string][];
+    }>;
+    getSpotBalances(): Promise<SpotBalance[]>;
+    spotMarketOrder(symbol: string, side: "buy" | "sell", size: string): Promise<unknown>;
+    spotLimitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
+        tif?: string;
+    }): Promise<unknown>;
+    spotCancelOrder(symbol: string, orderId: string): Promise<unknown>;
+}
+/**
+ * U-token (Unit protocol) → underlying perp symbol mapping.
+ * These are bridged tokens on HyperEVM with the same price as the underlying (~0.1% deviation).
+ */
+export declare const SPOT_PERP_TOKEN_MAP: Record<string, string>;
+/** Reverse: perp symbol → U-token spot name on HL */
+export declare const PERP_TO_SPOT_MAP: Record<string, string>;
+/** Maximum price deviation (%) between spot and perp to be considered same underlying */
+export declare const MAX_PRICE_DEVIATION_PCT = 5;

package/dist/exchanges/spot-interface.js

@@ -0,0 +1,22 @@
+/**
+ * Spot trading interface for exchanges that support both spot and perp.
+ * Separate from ExchangeAdapter because spot uses balance-based tracking
+ * (not position-based) and has no leverage, liquidation, or funding concepts.
+ *
+ * Supported: Hyperliquid, Lighter (Pacifica is perp-only)
+ */
+// ── Token mapping & price verification ──
+/**
+ * U-token (Unit protocol) → underlying perp symbol mapping.
+ * These are bridged tokens on HyperEVM with the same price as the underlying (~0.1% deviation).
+ */
+export const SPOT_PERP_TOKEN_MAP = {
+    UBTC: "BTC",
+    UETH: "ETH",
+    USOL: "SOL",
+    UFART: "FARTCOIN",
+};
+/** Reverse: perp symbol → U-token spot name on HL */
+export const PERP_TO_SPOT_MAP = Object.fromEntries(Object.entries(SPOT_PERP_TOKEN_MAP).map(([k, v]) => [v, k]));
+/** Maximum price deviation (%) between spot and perp to be considered same underlying */
+export const MAX_PRICE_DEVIATION_PCT = 5;

package/dist/execution-log.d.ts

@@ -1,14 +1,14 @@
 export interface ExecutionRecord {
     id: string;
     timestamp: string;
-    type: "market_order" | "limit_order" | "cancel" | "stop_order" | "edit_order" | "rebalance" | "arb_entry" | "arb_close" | "bridge";
+    type: "market_order" | "limit_order" | "cancel" | "stop_order" | "edit_order" | "rebalance" | "arb_entry" | "arb_close" | "bridge" | "multi_leg" | "multi_leg_rollback" | "split_order";
     exchange: string;
     symbol: string;
     side: string;
     size: string;
     price?: string;
     notional?: number;
-    status: "success" | "failed" | "simulated";
+    status: "success" | "failed" | "simulated" | "unverified";
     error?: string;
     meta?: Record<string, unknown>;
     dryRun: boolean;

package/dist/funding/rates.d.ts

@@ -43,3 +43,39 @@ export declare function fetchAllFundingRates(opts?: {
  * Fetch rates for a single symbol across all exchanges.
  */
 export declare function fetchSymbolFundingRates(symbol: string): Promise<SymbolFundingComparison | null>;
+export interface SpotPerpSpread {
+    symbol: string;
+    /** Perp exchange with the highest absolute funding rate */
+    perpExchange: string;
+    /** Spot exchange(s) available for the hedge leg */
+    spotExchanges: string[];
+    /** Perp funding rate (raw) */
+    perpFundingRate: number;
+    /** Perp funding hourly rate */
+    perpHourlyRate: number;
+    /** Annualized spread % (spot funding = 0, so spread = |perp annual rate|) */
+    annualSpreadPct: number;
+    /** Best mark price */
+    bestMarkPrice: number;
+    /** Direction: "long-spot-short-perp" when perp funding > 0, else "sell-spot-long-perp" */
+    direction: "long-spot-short-perp" | "sell-spot-long-perp";
+    /** Estimated hourly income for $1000 notional */
+    estHourlyIncomeUsd: number;
+}
+/**
+ * Fetch spot+perp funding rate spreads.
+ * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
+ * Only includes symbols available on at least one spot exchange (HL or LT).
+ *
+ * Key safety checks:
+ * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
+ * - Price validation: spot mid price must be within 5% of perp mark price
+ *   (filters out same-ticker-different-token issues like HIP-1 TRUMP ≠ perp TRUMP)
+ */
+export declare function fetchSpotPerpSpreads(opts?: {
+    symbols?: string[];
+    minSpread?: number;
+}): Promise<{
+    timestamp: string;
+    spreads: SpotPerpSpread[];
+}>;

package/dist/funding/rates.js

@@ -8,6 +8,7 @@
 import { toHourlyRate, annualizeRate, computeAnnualSpread, estimateHourlyFunding } from "./normalize.js";
 import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates as fetchLtFundingRates, } from "../shared-api.js";
 import { getHistoricalAverages } from "./history.js";
+import { SPOT_PERP_TOKEN_MAP, MAX_PRICE_DEVIATION_PCT } from "../exchanges/spot-interface.js";
 // ── Default top symbols to track ──
 export const TOP_SYMBOLS = [
     "BTC", "ETH", "SOL", "DOGE", "SUI", "AVAX", "LINK", "ARB",
@@ -170,3 +171,148 @@ export async function fetchSymbolFundingRates(symbol) {
     const snapshot = await fetchAllFundingRates({ symbols: [symbol.toUpperCase()] });
     return snapshot.symbols[0] ?? null;
 }
+/**
+ * Fetch spot+perp funding rate spreads.
+ * Since spot has 0 funding cost, the spread is simply |perp funding rate|.
+ * Only includes symbols available on at least one spot exchange (HL or LT).
+ *
+ * Key safety checks:
+ * - U-token mapping: UBTC→BTC, UETH→ETH, USOL→SOL, UFART→FARTCOIN
+ * - Price validation: spot mid price must be within 5% of perp mark price
+ *   (filters out same-ticker-different-token issues like HIP-1 TRUMP ≠ perp TRUMP)
+ */
+export async function fetchSpotPerpSpreads(opts) {
+    // Fetch all perp funding rates
+    const [hlRates, ltRates, pacRates] = await Promise.all([
+        fetchHyperliquidRates(),
+        fetchLighterRates(),
+        fetchPacificaRates(),
+    ]);
+    // Build actual spot availability maps + spot prices for cross-validation
+    // hlSpotByPerp: perpSymbol → { spotToken, exchange }
+    const hlSpotByPerp = new Map(); // perpSymbol → spotTokenName
+    const hlSpotPrices = new Map(); // perpSymbol → spot mid price
+    const ltSpotSymbols = new Set();
+    const ltSpotPrices = new Map(); // symbol → spot mid price
+    try {
+        // HL: spotMetaAndAssetCtxs → universe + prices in one call
+        const hlMetaCtx = await fetch("https://api.hyperliquid.xyz/info", {
+            method: "POST", headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ type: "spotMetaAndAssetCtxs" }),
+        }).then(r => r.json());
+        const meta = hlMetaCtx[0];
+        const ctxs = hlMetaCtx[1] ?? [];
+        const tokenNames = new Map();
+        for (const t of meta.tokens ?? [])
+            tokenNames.set(t.index, t.name);
+        const usdcIdx = meta.tokens?.find(t => t.name === "USDC")?.index ?? 0;
+        // We need to match universe entries to ctxs by index.
+        // API returns ctxs in same order as universe entries.
+        for (let i = 0; i < (meta.universe ?? []).length; i++) {
+            const u = meta.universe[i];
+            if (u.tokens[1] !== usdcIdx)
+                continue; // only /USDC pairs
+            const base = tokenNames.get(u.tokens[0])?.toUpperCase();
+            if (!base)
+                continue;
+            const ctx = ctxs[i];
+            const spotPrice = Number(ctx?.midPx ?? ctx?.markPx ?? 0);
+            // Map to perp symbol: UBTC→BTC, or direct if no mapping
+            const perpSymbol = SPOT_PERP_TOKEN_MAP[base] ?? base;
+            // Only keep the best-priced entry per perp symbol (prefer higher-volume)
+            if (!hlSpotByPerp.has(perpSymbol) || spotPrice > 0) {
+                hlSpotByPerp.set(perpSymbol, base);
+                if (spotPrice > 0)
+                    hlSpotPrices.set(perpSymbol, spotPrice);
+            }
+        }
+    }
+    catch { /* non-critical */ }
+    try {
+        // LT: explorer API → symbols with "/"
+        const ltMarkets = await fetch("https://explorer.elliot.ai/api/markets")
+            .then(r => r.json());
+        for (const m of ltMarkets) {
+            if (m.symbol.includes("/")) {
+                ltSpotSymbols.add(m.symbol.split("/")[0].toUpperCase());
+            }
+        }
+        // Fetch LT spot prices from orderbook for price validation
+        for (const sym of ltSpotSymbols) {
+            try {
+                const book = await fetch(`https://mainnet.zklighter.elliot.ai/api/v1/orderBookOrders?market_id=${
+                // We don't have market_id here, skip detailed price fetch for LT
+                // LT tokens (ETH, LINK, etc.) are direct names, low risk of mismatch
+                ""}`);
+                // Skip — LT uses direct token names, not indices
+            }
+            catch { /* skip */ }
+        }
+    }
+    catch { /* non-critical */ }
+    // Merge all perp rates by symbol
+    const perpRateMap = new Map();
+    for (const r of [...hlRates, ...ltRates, ...pacRates]) {
+        if (!r.symbol)
+            continue;
+        if (opts?.symbols && !opts.symbols.includes(r.symbol.toUpperCase()))
+            continue;
+        const key = r.symbol.toUpperCase();
+        if (!perpRateMap.has(key))
+            perpRateMap.set(key, []);
+        perpRateMap.get(key).push(r);
+    }
+    const spreads = [];
+    const minSpread = opts?.minSpread ?? 0;
+    for (const [symbol, rates] of perpRateMap) {
+        rates.sort((a, b) => Math.abs(b.hourlyRate) - Math.abs(a.hourlyRate));
+        const bestPerp = rates[0];
+        // Spot exchanges: only include if symbol has a verified spot market
+        const uniqueSpot = [];
+        // HL spot: check U-token mapped availability
+        if (hlSpotByPerp.has(symbol)) {
+            // Price cross-validation: spot price must be close to perp mark price
+            const spotPrice = hlSpotPrices.get(symbol);
+            const perpPrice = bestPerp.markPrice;
+            if (spotPrice && perpPrice > 0) {
+                const deviation = Math.abs(spotPrice - perpPrice) / perpPrice * 100;
+                if (deviation <= MAX_PRICE_DEVIATION_PCT) {
+                    uniqueSpot.push("hyperliquid");
+                }
+                // else: same ticker, different token (e.g., HIP-1 TRUMP ≠ perp TRUMP) → skip
+            }
+            else if (spotPrice === undefined) {
+                // No price data (empty orderbook) → skip, can't verify
+            }
+        }
+        // LT spot: direct token names, low mismatch risk
+        if (ltSpotSymbols.has(symbol))
+            uniqueSpot.push("lighter");
+        if (uniqueSpot.length === 0)
+            continue;
+        const annualSpreadPct = Math.abs(bestPerp.annualizedPct);
+        if (annualSpreadPct < minSpread)
+            continue;
+        const direction = bestPerp.hourlyRate > 0
+            ? "long-spot-short-perp"
+            : "sell-spot-long-perp";
+        const notional = 1000;
+        const estHourlyIncomeUsd = Math.abs(bestPerp.hourlyRate) * notional;
+        spreads.push({
+            symbol,
+            perpExchange: bestPerp.exchange,
+            spotExchanges: uniqueSpot,
+            perpFundingRate: bestPerp.fundingRate,
+            perpHourlyRate: bestPerp.hourlyRate,
+            annualSpreadPct,
+            bestMarkPrice: bestPerp.markPrice,
+            direction,
+            estHourlyIncomeUsd,
+        });
+    }
+    spreads.sort((a, b) => b.annualSpreadPct - a.annualSpreadPct);
+    return {
+        timestamp: new Date().toISOString(),
+        spreads,
+    };
+}