perp-cli 0.3.18 → 0.4.0

package/README.md

@@ -3,8 +3,11 @@
 Multi-DEX perpetual futures CLI — **Pacifica** (Solana), **Hyperliquid** (HyperEVM), **Lighter** (Ethereum).
 
 ```bash
-npm install -g perp-cli
+npm install -g perp-cli       # global install
 perp --json portfolio
+
+# Or without global install (restricted environments)
+npx -y perp-cli --json portfolio
 ```
 
 ## Features

package/dist/commands/agent.js

@@ -134,7 +134,7 @@ export function registerAgentCommands(program, getAdapter, isJson) {
                         "perp account orders --json",
                         "perp account history --json",
                         "perp account trades --json",
-                        "perp status --json",
+                        "perp portfolio --json",
                     ],
                     description: "Read account state: balances, positions, open orders, trade history",
                 },
@@ -170,13 +170,21 @@ export function registerAgentCommands(program, getAdapter, isJson) {
                     category: "arbitrage",
                     commands: [
                         "perp arb funding --json",
-                        "perp arb rates --json",
+                        "perp arb scan --min 5 --json",
                         "perp arb scan --json",
+                        "perp arb exec <SYM> <longEx> <shortEx> <$> --leverage 2 --isolated --json",
+                        "perp arb status --json",
+                        "perp arb close <SYM> --json",
+                        "perp arb close <SYM> --dry-run --json",
+                        "perp arb close <SYM> --pair <longEx>:<shortEx> --json",
+                        "perp arb funding-earned --json",
+                        "perp arb funding-earned --period 30 --json",
+                        "perp arb history --json",
                         "perp arb dex --json",
                         "perp arb dex-monitor --min 10",
                         "perp gap show --json",
                     ],
-                    description: "Cross-exchange + cross-dex funding arb, price gaps, HIP-3 deployed dex arb",
+                    description: "Cross-exchange funding arb: scan → exec → status → funding-earned → close. Plus cross-dex arb and price gaps.",
                 },
                 {
                     category: "risk_management",
@@ -338,10 +346,10 @@ export function registerAgentCommands(program, getAdapter, isJson) {
             }
         }
         else if (g.includes("arb") || g.includes("arbitrage") || g.includes("funding")) {
-            steps.push({ step: 1, command: "perp arb rates --json", description: "Compare funding rates across exchanges" }, { step: 2, command: "perp arb scan --json", description: "Find high-spread opportunities" }, { step: 3, command: "perp gap show --json", description: "Check price gaps" }, { step: 4, command: "perp arb auto --dry-run --min-spread 30", description: "Dry-run auto arb bot" });
+            steps.push({ step: 1, command: "perp arb scan --min 5 --json", description: "Scan funding rate arbitrage opportunities" }, { step: 2, command: "perp arb exec <SYM> <longEx> <shortEx> <$> --leverage 2 --isolated --dry-run --json", description: "Dry-run arb execution" });
         }
         else if (g.includes("status") || g.includes("check") || g.includes("overview")) {
-            steps.push({ step: 1, command: "perp status --json", description: "Full account overview" }, { step: 2, command: "perp account positions --json", description: "Detailed positions" }, { step: 3, command: "perp account orders --json", description: "Open orders" });
+            steps.push({ step: 1, command: "perp portfolio --json", description: "Balances + positions + risk" }, { step: 2, command: "perp account positions --json", description: "Detailed positions" }, { step: 3, command: "perp account orders --json", description: "Open orders" });
         }
         else if (g.includes("deposit")) {
             const amount = extractNumber(g) || "100";
@@ -357,7 +365,7 @@ export function registerAgentCommands(program, getAdapter, isJson) {
             }
         }
         else {
-            steps.push({ step: 1, command: "perp agent capabilities", description: "List all available capabilities" }, { step: 2, command: "perp status --json", description: "Check account status" });
+            steps.push({ step: 1, command: "perp agent capabilities", description: "List all available capabilities" }, { step: 2, command: "perp portfolio --json", description: "Check account status" });
         }
         printJson(jsonOk({
             goal,

package/dist/commands/arb/index.js

@@ -165,6 +165,16 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                     // Net PnL
                     const totalUpnl = longPos.unrealizedPnl + shortPos.unrealizedPnl;
                     const netPnl = totalUpnl + estimatedFundingIncome - totalFees;
+                    // Daily funding estimate from current spread
+                    const dailyFundingEstimate = currentSpread
+                        ? (currentSpread / 100) / 365 * avgNotional
+                        : 0;
+                    // Breakeven analysis
+                    const totalCosts = totalFees; // entry+exit fees
+                    const remainingToBreakeven = totalCosts - estimatedFundingIncome - totalUpnl;
+                    const daysToBreakeven = dailyFundingEstimate > 0 && remainingToBreakeven > 0
+                        ? remainingToBreakeven / dailyFundingEstimate
+                        : remainingToBreakeven <= 0 ? 0 : null;
                     arbPairs.push({
                         symbol,
                         longExchange: longPos.exchange,
@@ -195,12 +205,33 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                         estimatedFees: totalFees,
                         unrealizedPnl: totalUpnl,
                         netPnl,
+                        dailyFundingEstimate,
+                        breakeven: {
+                            daysToBreakeven,
+                            dailyIncome: dailyFundingEstimate,
+                            totalCosts,
+                            remainingToBreakeven: Math.max(0, remainingToBreakeven),
+                        },
                     });
                 }
             }
         }
         if (isJson()) {
-            return printJson(jsonOk(arbPairs));
+            const totalNotionalJ = arbPairs.reduce((s, p) => s + (p.longPosition.notionalUsd + p.shortPosition.notionalUsd) / 2, 0);
+            const totalDailyJ = arbPairs.reduce((s, p) => s + p.dailyFundingEstimate, 0);
+            return printJson(jsonOk({
+                pairs: arbPairs,
+                aggregate: {
+                    positions: arbPairs.length,
+                    totalNotionalUsd: totalNotionalJ,
+                    unrealizedPnl: arbPairs.reduce((s, p) => s + p.unrealizedPnl, 0),
+                    estimatedFunding: arbPairs.reduce((s, p) => s + p.estimatedFundingIncome, 0),
+                    estimatedFees: arbPairs.reduce((s, p) => s + p.estimatedFees, 0),
+                    netPnl: arbPairs.reduce((s, p) => s + p.netPnl, 0),
+                    dailyFundingEstimate: totalDailyJ,
+                    annualizedApr: totalNotionalJ > 0 ? (totalDailyJ * 365 / totalNotionalJ) * 100 : 0,
+                },
+            }));
         }
         if (arbPairs.length === 0) {
             console.log(chalk.gray("  No open arb positions found.\n"));
@@ -240,12 +271,20 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
         const totalFunding = arbPairs.reduce((s, p) => s + p.estimatedFundingIncome, 0);
         const totalFees = arbPairs.reduce((s, p) => s + p.estimatedFees, 0);
         const totalNet = arbPairs.reduce((s, p) => s + p.netPnl, 0);
+        const totalDailyFunding = arbPairs.reduce((s, p) => s + p.dailyFundingEstimate, 0);
+        const totalNotional = arbPairs.reduce((s, p) => s + (p.longPosition.notionalUsd + p.shortPosition.notionalUsd) / 2, 0);
+        const portfolioApr = totalNotional > 0 ? (totalDailyFunding * 365 / totalNotional) * 100 : 0;
         console.log(chalk.white.bold("\n  Summary"));
         console.log(`    Positions:       ${arbPairs.length}`);
+        console.log(`    Total Notional:  $${formatUsd(totalNotional)}`);
         console.log(`    Unrealized PnL:  ${formatPnl(totalUpnl)}`);
         console.log(`    Est. Funding:    ${chalk.yellow(`$${totalFunding.toFixed(4)}`)}`);
         console.log(`    Est. Fees:       ${chalk.red(`-$${totalFees.toFixed(4)}`)}`);
         console.log(`    Net PnL:         ${formatPnl(totalNet)}`);
+        console.log(`    Daily Income:    ${chalk.cyan(`$${totalDailyFunding.toFixed(4)}/day`)}`);
+        if (portfolioApr > 0) {
+            console.log(`    Portfolio APR:   ${chalk.cyan(`${portfolioApr.toFixed(1)}%`)}`);
+        }
         console.log(chalk.gray(`    (Fees assume ${(TAKER_FEE * 100).toFixed(3)}% taker for entry + exit.)\n`));
     });
     // ── arb close ──
@@ -389,44 +428,66 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
             console.log(chalk.yellow(`    BUY ${shortPos.size} ${shortPos.rawSymbol} on ${shortPos.exchange} (close short)\n`));
             return;
         }
-        // Execute close on both exchanges
+        // Execute close on both exchanges with retry
+        const MAX_RETRIES = 2;
         const results = [];
-        // Close both legs concurrently
-        const closePromises = [
-            (async () => {
+        async function closeWithRetry(exchange, rawSymbol, side, size, label) {
+            let lastError = "";
+            for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
                 try {
-                    const adapter = await getAdapterForExchange(longPos.exchange);
-                    await adapter.marketOrder(longPos.rawSymbol, "sell", String(longPos.size));
-                    results.push({ exchange: longPos.exchange, action: "sell (close long)", status: "success" });
+                    const adapter = await getAdapterForExchange(exchange);
+                    await adapter.marketOrder(rawSymbol, side, String(size));
+                    results.push({ exchange, action: `${side} (close ${label})`, status: "success", retries: attempt });
                     if (!isJson())
-                        console.log(chalk.green(`  Closed long on ${longPos.exchange}: SELL ${longPos.size} ${sym}`));
+                        console.log(chalk.green(`  Closed ${label} on ${exchange}: ${side.toUpperCase()} ${size} ${sym}${attempt > 0 ? ` (retry ${attempt})` : ""}`));
+                    return;
                 }
                 catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    results.push({ exchange: longPos.exchange, action: "sell (close long)", status: "failed", error: msg });
-                    if (!isJson())
-                        console.error(chalk.red(`  Failed to close long on ${longPos.exchange}: ${msg}`));
+                    lastError = err instanceof Error ? err.message : String(err);
+                    if (attempt < MAX_RETRIES) {
+                        if (!isJson())
+                            console.log(chalk.yellow(`  Retry ${attempt + 1}/${MAX_RETRIES} for ${label} on ${exchange}...`));
+                        await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
+                    }
                 }
-            })(),
-            (async () => {
+            }
+            results.push({ exchange, action: `${side} (close ${label})`, status: "failed", error: lastError, retries: MAX_RETRIES });
+            if (!isJson())
+                console.error(chalk.red(`  Failed to close ${label} on ${exchange}: ${lastError}`));
+        }
+        // Close both legs concurrently
+        await Promise.all([
+            closeWithRetry(longPos.exchange, longPos.rawSymbol, "sell", longPos.size, "long"),
+            closeWithRetry(shortPos.exchange, shortPos.rawSymbol, "buy", shortPos.size, "short"),
+        ]);
+        const allSuccess = results.every(r => r.status === "success");
+        const anySuccess = results.some(r => r.status === "success");
+        // Verify positions are actually closed
+        let verification;
+        if (anySuccess) {
+            verification = [];
+            for (const r of results) {
+                if (r.status !== "success")
+                    continue;
                 try {
-                    const adapter = await getAdapterForExchange(shortPos.exchange);
-                    await adapter.marketOrder(shortPos.rawSymbol, "buy", String(shortPos.size));
-                    results.push({ exchange: shortPos.exchange, action: "buy (close short)", status: "success" });
-                    if (!isJson())
-                        console.log(chalk.green(`  Closed short on ${shortPos.exchange}: BUY ${shortPos.size} ${sym}`));
+                    const adapter = await getAdapterForExchange(r.exchange);
+                    const positions = await adapter.getPositions();
+                    const remaining = positions.find(p => p.symbol.replace("-PERP", "").toUpperCase() === sym);
+                    verification.push({
+                        exchange: r.exchange,
+                        remainingSize: remaining ? Math.abs(Number(remaining.size)) : 0,
+                        closed: !remaining || Math.abs(Number(remaining.size)) < 0.0001,
+                    });
                 }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    results.push({ exchange: shortPos.exchange, action: "buy (close short)", status: "failed", error: msg });
-                    if (!isJson())
-                        console.error(chalk.red(`  Failed to close short on ${shortPos.exchange}: ${msg}`));
+                catch {
+                    verification.push({ exchange: r.exchange, remainingSize: -1, closed: false });
                 }
-            })(),
-        ];
-        await Promise.all(closePromises);
-        const allSuccess = results.every(r => r.status === "success");
-        const anySuccess = results.some(r => r.status === "success");
+            }
+            const notClosed = verification.filter(v => !v.closed);
+            if (notClosed.length > 0 && !isJson()) {
+                console.log(chalk.yellow(`\n  Warning: Position may not be fully closed on: ${notClosed.map(v => v.exchange).join(", ")}`));
+            }
+        }
         // Log to execution log
         const arbPairId = `${sym}:${longPos.exchange}:${shortPos.exchange}`;
         logExecution({
@@ -459,6 +520,7 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                 estimatedFees: totalFees,
                 netPnl,
                 results,
+                verification,
             }));
         }
         if (!allSuccess && anySuccess) {
@@ -918,4 +980,184 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
             console.log(chalk.yellow("\n  To execute, use: perp rebalance execute --auto-bridge\n"));
         }
     });
+    // ── arb funding-earned ──
+    arb
+        .command("funding-earned")
+        .description("Actual funding payments received/paid for arb positions")
+        .option("--period <days>", "Number of days to look back", "7")
+        .option("--symbol <symbol>", "Filter by symbol")
+        .action(async (opts) => {
+        const periodDays = parseInt(opts.period);
+        const filterSym = opts.symbol?.toUpperCase();
+        if (!isJson())
+            console.log(chalk.cyan(`\n  Fetching funding payments (last ${periodDays} days)...\n`));
+        // Fetch positions to identify arb pairs
+        const allPositions = [];
+        for (const exName of EXCHANGES) {
+            try {
+                const adapter = await getAdapterForExchange(exName);
+                const positions = await adapter.getPositions();
+                for (const p of positions) {
+                    const normalized = p.symbol.replace("-PERP", "").toUpperCase();
+                    allPositions.push({
+                        exchange: exName,
+                        symbol: normalized,
+                        side: p.side,
+                        size: Math.abs(Number(p.size)),
+                        markPrice: Number(p.markPrice),
+                    });
+                }
+            }
+            catch {
+                // exchange not configured
+            }
+        }
+        // Identify arb pairs (long on one exchange, short on another)
+        const arbPairKeys = new Set();
+        const arbPairInfo = new Map();
+        const longs = allPositions.filter(p => p.side === "long");
+        const shorts = allPositions.filter(p => p.side === "short");
+        for (const l of longs) {
+            for (const s of shorts) {
+                if (l.exchange !== s.exchange && l.symbol === s.symbol) {
+                    const key = l.symbol;
+                    arbPairKeys.add(key);
+                    arbPairInfo.set(key, {
+                        longExchange: l.exchange,
+                        shortExchange: s.exchange,
+                        notionalUsd: (l.size * l.markPrice + s.size * s.markPrice) / 2,
+                    });
+                }
+            }
+        }
+        const allPayments = [];
+        const cutoff = Date.now() - periodDays * 24 * 60 * 60 * 1000;
+        for (const exName of EXCHANGES) {
+            try {
+                const adapter = await getAdapterForExchange(exName);
+                const payments = await adapter.getFundingPayments(200);
+                for (const p of payments) {
+                    if (p.time < cutoff)
+                        continue;
+                    const sym = p.symbol.replace("-PERP", "").toUpperCase();
+                    if (filterSym && sym !== filterSym)
+                        continue;
+                    allPayments.push({
+                        time: p.time,
+                        exchange: exName,
+                        symbol: sym,
+                        payment: typeof p.payment === "string" ? parseFloat(p.payment) : Number(p.payment),
+                    });
+                }
+            }
+            catch {
+                // exchange not configured or no payments
+            }
+        }
+        // Group by symbol, then by exchange
+        const bySymbol = new Map();
+        for (const p of allPayments) {
+            if (!bySymbol.has(p.symbol))
+                bySymbol.set(p.symbol, []);
+            bySymbol.get(p.symbol).push(p);
+        }
+        const pairs = [];
+        for (const [symbol, payments] of bySymbol) {
+            const isArb = arbPairKeys.has(symbol);
+            const pairInfo = arbPairInfo.get(symbol);
+            // Group by exchange
+            const byEx = new Map();
+            for (const p of payments) {
+                if (!byEx.has(p.exchange))
+                    byEx.set(p.exchange, []);
+                byEx.get(p.exchange).push(p);
+            }
+            const exchangeSummaries = [];
+            let totalReceived = 0;
+            let totalPaid = 0;
+            for (const [exchange, exPayments] of byEx) {
+                const received = exPayments.filter(p => p.payment > 0).reduce((s, p) => s + p.payment, 0);
+                const paid = exPayments.filter(p => p.payment < 0).reduce((s, p) => s + Math.abs(p.payment), 0);
+                const net = received - paid;
+                totalReceived += received;
+                totalPaid += paid;
+                exchangeSummaries.push({ exchange, totalReceived: received, totalPaid: paid, net, payments: exPayments.length });
+            }
+            const netEarned = totalReceived - totalPaid;
+            const dailyAvg = periodDays > 0 ? netEarned / periodDays : 0;
+            const notionalUsd = pairInfo?.notionalUsd || 0;
+            const annualizedApr = notionalUsd > 0 ? (dailyAvg * 365 / notionalUsd) * 100 : 0;
+            pairs.push({
+                symbol,
+                isArbPair: isArb,
+                longExchange: pairInfo?.longExchange ?? null,
+                shortExchange: pairInfo?.shortExchange ?? null,
+                notionalUsd,
+                byExchange: exchangeSummaries,
+                totalReceived,
+                totalPaid,
+                netEarned,
+                dailyAvg,
+                annualizedApr,
+                payments: payments.length,
+            });
+        }
+        // Sort: arb pairs first, then by netEarned
+        pairs.sort((a, b) => {
+            if (a.isArbPair !== b.isArbPair)
+                return a.isArbPair ? -1 : 1;
+            return b.netEarned - a.netEarned;
+        });
+        // Totals
+        const totals = {
+            totalReceived: pairs.reduce((s, p) => s + p.totalReceived, 0),
+            totalPaid: pairs.reduce((s, p) => s + p.totalPaid, 0),
+            netEarned: pairs.reduce((s, p) => s + p.netEarned, 0),
+            dailyAvg: pairs.reduce((s, p) => s + p.dailyAvg, 0),
+            totalNotional: pairs.filter(p => p.isArbPair).reduce((s, p) => s + p.notionalUsd, 0),
+            arbPairs: pairs.filter(p => p.isArbPair).length,
+            period: periodDays,
+        };
+        const totalArbNotional = totals.totalNotional;
+        const portfolioApr = totalArbNotional > 0
+            ? (totals.dailyAvg * 365 / totalArbNotional) * 100
+            : 0;
+        if (isJson()) {
+            return printJson(jsonOk({
+                pairs,
+                totals: { ...totals, annualizedApr: portfolioApr },
+            }));
+        }
+        if (pairs.length === 0) {
+            console.log(chalk.gray("  No funding payments found.\n"));
+            return;
+        }
+        console.log(chalk.cyan.bold("  Funding Payments Earned\n"));
+        const rows = pairs.map(p => {
+            const arbTag = p.isArbPair ? chalk.green("ARB") : chalk.gray("---");
+            const exchanges = p.byExchange.map(e => e.exchange.slice(0, 3).toUpperCase()).join("+");
+            return [
+                chalk.white.bold(p.symbol),
+                arbTag,
+                exchanges,
+                chalk.green(`$${p.totalReceived.toFixed(4)}`),
+                chalk.red(`-$${p.totalPaid.toFixed(4)}`),
+                formatPnl(p.netEarned),
+                `$${p.dailyAvg.toFixed(4)}/d`,
+                p.annualizedApr > 0 ? `${p.annualizedApr.toFixed(1)}%` : "-",
+                String(p.payments),
+            ];
+        });
+        console.log(makeTable(["Symbol", "Type", "Exchanges", "Received", "Paid", "Net", "Daily Avg", "APR", "#"], rows));
+        console.log(chalk.white.bold("\n  Totals"));
+        console.log(`    Period:       ${periodDays} days`);
+        console.log(`    Received:     ${chalk.green(`$${totals.totalReceived.toFixed(4)}`)}`);
+        console.log(`    Paid:         ${chalk.red(`-$${totals.totalPaid.toFixed(4)}`)}`);
+        console.log(`    Net Earned:   ${formatPnl(totals.netEarned)}`);
+        console.log(`    Daily Avg:    $${totals.dailyAvg.toFixed(4)}/day`);
+        if (portfolioApr > 0) {
+            console.log(`    Portfolio APR: ${chalk.cyan(`${portfolioApr.toFixed(1)}%`)} (on $${formatUsd(totalArbNotional)} arb notional)`);
+        }
+        console.log();
+    });
 }

package/dist/commands/init.js

@@ -231,7 +231,7 @@ export function registerInitCommand(program) {
                 }
             }
             console.log(chalk.white.bold("\n  Next steps:"));
-            console.log(`    ${chalk.green("perp status")}                     account overview`);
+            console.log(`    ${chalk.green("perp portfolio")}                  balances + positions + risk`);
             if (selected.includes("hyperliquid")) {
                 console.log(`    ${chalk.green("perp deposit hyperliquid <amt>")}   deposit USDC`);
             }

package/dist/commands/wallet.js

@@ -400,10 +400,15 @@ export function registerWalletCommands(program, isJson) {
                 lighterApiSetup = { error: e instanceof Error ? e.message : String(e) };
             }
         }
+        const settings = loadSettings();
+        const referralHint = !settings.referrals
+            ? { referrals: false, hint: "Optional: 'perp settings referrals on' to support perp-cli development (no extra fees — exchange rebates only)" }
+            : undefined;
         if (isJson())
             return printJson(jsonOk({
                 exchange: resolved, address, envFile: ENV_FILE, default: !!opts.default,
                 ...(resolved === "lighter" && { lighterApiKey: lighterApiSetup }),
+                ...(referralHint && { referralHint }),
             }));
         console.log(chalk.green(`\n  ${resolved} configured.`));
         console.log(`  Address:  ${chalk.green(address)}`);
@@ -419,6 +424,10 @@ export function registerWalletCommands(program, isJson) {
                 console.log(chalk.gray(`  You can retry: perp -e lighter manage setup-api-key`));
             }
         }
+        if (!settings.referrals) {
+            console.log(chalk.gray(`  Optional: ${chalk.cyan("perp settings referrals on")} to support perp-cli development`));
+            console.log(chalk.gray(`  (no extra fees — exchange rebates only)`));
+        }
         console.log();
     });
     // ── show (show configured exchanges with public addresses) ──

package/dist/exchanges/lighter.js

@@ -878,7 +878,52 @@ export class LighterAdapter {
         }
         const result = await sendRes.json();
         if (result.code !== 200) {
-            throw new Error(`ChangePubKey failed: ${result.message ?? JSON.stringify(result)}`);
+            // Retry with fresh nonce if invalid nonce (pending tx or stale nonce)
+            if (result.message && /invalid nonce/i.test(result.message)) {
+                const MAX_NONCE_RETRIES = 3;
+                let lastError = result.message;
+                for (let attempt = 1; attempt <= MAX_NONCE_RETRIES; attempt++) {
+                    await new Promise(r => setTimeout(r, 500 * attempt));
+                    // Re-fetch nonce from API (may have updated since first call)
+                    const freshNonceRes = await this.restGet("/nextNonce", {
+                        account_index: String(this._accountIndex),
+                        api_key_index: String(apiKeyIndex),
+                    });
+                    const freshNonce = (freshNonceRes.nonce ?? freshNonceRes.next_nonce ?? nonce) + attempt;
+                    const retrySigned = await client.signChangePubKey({
+                        pubkey: publicKey, nonce: freshNonce, apiKeyIndex, accountIndex: this._accountIndex,
+                    });
+                    if (retrySigned.error || !retrySigned.txInfo || !retrySigned.messageToSign) {
+                        lastError = retrySigned.error ?? "incomplete response";
+                        continue;
+                    }
+                    const retryTxInfo = JSON.parse(retrySigned.txInfo);
+                    retryTxInfo.L1Sig = await wallet.signMessage(retrySigned.messageToSign);
+                    const retryRes = await fetch(`${this._baseUrl}/api/v1/sendTx`, {
+                        method: "POST",
+                        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                        body: new URLSearchParams({
+                            tx_type: String(retrySigned.txType ?? 0),
+                            tx_info: JSON.stringify(retryTxInfo),
+                        }),
+                    });
+                    if (!retryRes.ok) {
+                        lastError = `sendTx ${retryRes.status}: ${await retryRes.text()}`;
+                        continue;
+                    }
+                    const retryResult = await retryRes.json();
+                    if (retryResult.code === 200) {
+                        return { privateKey, publicKey }; // Success on retry
+                    }
+                    lastError = retryResult.message ?? JSON.stringify(retryResult);
+                    if (!/invalid nonce/i.test(lastError))
+                        break; // Different error, stop retrying
+                }
+                throw new Error(`ChangePubKey failed after ${MAX_NONCE_RETRIES} nonce retries: ${lastError}`);
+            }
+            else {
+                throw new Error(`ChangePubKey failed: ${result.message ?? JSON.stringify(result)}`);
+            }
         }
         return { privateKey, publicKey };
     }

package/dist/exchanges/pacifica.js

@@ -242,7 +242,7 @@ export class PacificaAdapter {
         return history.slice(0, limit).map((h) => ({
             time: Number(h.created_at ?? 0),
             symbol: String(h.symbol ?? ""),
-            payment: String(h.amount ?? "0"),
+            payment: String(h.payout ?? "0"),
         }));
     }
 }

package/dist/index.js

@@ -388,20 +388,20 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                 process.env.LIGHTER_PRIVATE_KEY);
             if (!status.hasWallets && !hasEnvKey && !settings.defaultExchange) {
                 // Fresh install — onboarding
-                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray("  v0.3.7\n"));
+                console.log(chalk.cyan.bold("\n  Welcome to perp-cli!") + chalk.gray(`  v${_pkg.version}\n`));
                 console.log("  Multi-DEX perpetual futures CLI for Pacifica, Hyperliquid, and Lighter.\n");
-                console.log(`  Get started:  ${chalk.cyan("perp init")}`);
+                console.log(`  Get started:  ${chalk.cyan("perp wallet set <exchange> <key>")}`);
                 console.log(chalk.gray(`\n  Or explore without a wallet:`));
                 console.log(`    ${chalk.green("perp market list")}              available markets`);
                 console.log(`    ${chalk.green("perp -e hyperliquid market list")}  Hyperliquid markets`);
-                console.log(`    ${chalk.green("perp arb rates")}                funding rate comparison`);
+                console.log(`    ${chalk.green("perp arb scan")}                 funding rate arbitrage`);
                 console.log(`    ${chalk.green("perp --help")}                   all commands\n`);
             }
             else {
                 // Configured — show status overview
                 const defaultEx = settings.defaultExchange || "pacifica";
                 const activeEntries = Object.entries(status.active);
-                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray("  v0.3.7\n"));
+                console.log(chalk.cyan.bold("\n  perp-cli") + chalk.gray(`  v${_pkg.version}\n`));
                 console.log(`  Default exchange: ${chalk.cyan(defaultEx)}`);
                 if (activeEntries.length > 0) {
                     console.log(chalk.white.bold("\n  Wallets:"));
@@ -432,10 +432,10 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
                     }
                 }
                 console.log(chalk.white.bold("\n  Quick commands:"));
-                console.log(`    ${chalk.green("perp status")}       account overview`);
+                console.log(`    ${chalk.green("perp portfolio")}     balances + positions + risk`);
                 console.log(`    ${chalk.green("perp market list")}   available markets`);
+                console.log(`    ${chalk.green("perp arb scan")}      funding rate arbitrage`);
                 console.log(`    ${chalk.green("perp dashboard")}     live monitoring`);
-                console.log(`    ${chalk.green("perp arb rates")}     funding rate comparison`);
                 console.log(`    ${chalk.green("perp --help")}        all commands\n`);
             }
         }

package/dist/mcp-server.js

@@ -333,7 +333,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: `perp -e ${ex} --json account orders`, description: "List open orders to find order ID" }, { step: 2, command: `perp -e ${ex} --json trade edit <symbol> <orderId> <newPrice> <newSize>`, description: "Modify the order", dangerous: true });
         }
         else if (g.includes("arb") || g.includes("arbitrage")) {
-            steps.push({ step: 1, command: "perp --json arb rates", description: "Compare funding rates across exchanges" }, { step: 2, command: "perp --json arb scan", description: "Find high-spread opportunities" }, { step: 3, command: "perp --json gap show", description: "Check cross-exchange price gaps" }, { step: 4, command: "perp --json arb dex", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
+            steps.push({ step: 1, command: "perp --json arb scan --min 5", description: "Scan funding rate arbitrage opportunities" }, { step: 2, command: "perp --json arb scan", description: "Find high-spread opportunities" }, { step: 3, command: "perp --json gap show", description: "Check cross-exchange price gaps" }, { step: 4, command: "perp --json arb dex", description: "HIP-3 cross-dex arb opportunities (Hyperliquid)" });
         }
         else if (g.includes("funding")) {
             const symbol = extractSymbol(g);
@@ -712,7 +712,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp status", "perp portfolio"],
+                relatedCommands: ["perp portfolio", "perp portfolio"],
             };
         }
         else if (category === "arb") {
@@ -731,7 +731,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: ["auto" === sub ? "Auto-executes trades on both exchanges" : ""].filter(Boolean),
                 category: sub === "auto" || sub === "close" ? "write" : "analysis",
-                relatedCommands: ["perp arb rates", "perp arb scan", "perp gap show"],
+                relatedCommands: ["perp arb scan", "perp arb scan", "perp gap show"],
             };
         }
         else if (category === "bridge") {
@@ -837,7 +837,7 @@ server.tool("explain_command", "Explain what a perp CLI command does, its parame
                 parameters: [],
                 risks: [],
                 category: "read",
-                relatedCommands: ["perp funding rates", "perp arb rates"],
+                relatedCommands: ["perp funding rates", "perp arb scan"],
             };
         }
         else if (category === "backtest") {
@@ -1028,7 +1028,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             arb: {
                 description: "Funding rate arbitrage & basis trading",
                 subcommands: {
-                    rates: { usage: "perp arb rates", description: "Compare funding rates" },
+                    rates: { usage: "perp arb scan", description: "Compare funding rates" },
                     scan: { usage: "perp arb scan --min <bps>", description: "Find arb opportunities" },
                     funding: { usage: "perp arb funding", description: "Detailed funding analysis" },
                     dex: { usage: "perp arb dex", description: "HIP-3 cross-dex arb" },
@@ -1167,7 +1167,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             deposit: { usage: "perp deposit <exchange> <amount>", description: "Deposit USDC to exchange" },
             withdraw: { usage: "perp withdraw <exchange> <amount>", description: "Withdraw USDC from exchange" },
             portfolio: { usage: "perp portfolio", description: "Cross-exchange portfolio summary" },
-            status: { usage: "perp status", description: "Full account overview" },
+            status: { usage: "perp portfolio", description: "Full account overview" },
             health: { usage: "perp health", description: "Exchange connectivity check" },
             settings: {
                 description: "CLI settings",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.3.18",
+  "version": "0.4.0",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "dist/index.js",

package/skills/perp-cli/SKILL.md

@@ -5,7 +5,7 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.3.18"
+  version: "0.4.0"
 ---
 
 # perp-cli Agent Guide
@@ -21,12 +21,21 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 5. **NEVER trade without user confirmation.**
 6. **NEVER read ~/.perp/.env or key files.**
 
-## Install
+## Install (run this FIRST)
 
 ```bash
-npm install -g perp-cli
+# 1. Check if perp exists and is current (must be ≥ 0.3.19)
+perp --version 2>/dev/null
+
+# 2. If not found or outdated:
+npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
+
+# 3. If version is still old (npx cache), clear cache first:
+npx -y clear-npx-cache 2>/dev/null; npx -y perp-cli@latest --json --version
 ```
-No sudo: `npm install -g perp-cli --prefix ~/.npm-global && export PATH="$HOME/.npm-global/bin:$PATH"`
+
+**IMPORTANT:** Always use `@latest` with npx — without it, npx uses a stale cached version.
+Use `perp` if global install works, otherwise `npx -y perp-cli@latest` as prefix for all commands.
 
 ## Wallet Setup
 
@@ -94,7 +103,11 @@ All string outputs are auto-sanitized (control chars stripped, prompt injection
    → executes BOTH legs simultaneously
    → verifies positions exist after execution
    → auto-rollback if one leg fails
-5. perp --json portfolio                    → verify positions
+5. perp --json arb status                   → monitor: PnL, funding income, daily estimate, breakeven
+6. perp --json arb funding-earned           → actual funding payments received/paid + APR
+7. perp --json arb close <SYM>             → close both legs simultaneously (retry + verify)
+   → --dry-run: preview without executing
+   → --pair <longEx>:<shortEx>: specify which pair if multiple
 ```
 
 ## Position Sizing
@@ -128,10 +141,11 @@ Check `canTrade` before any order. If `false`, do NOT trade.
 ## Monitoring (while positions open)
 
 ```
-Every 15 min: perp --json portfolio
-Every 1 hour: perp --json arb scan --min 5
+Every 15 min: perp --json arb status               → PnL, daily income, breakeven analysis
+Every 1 hour: perp --json arb scan --min 5          → check if spread still profitable
+Daily:        perp --json arb funding-earned         → verify actual funding payments
 Exit if: spread < breakeven or one leg closed unexpectedly.
-Close both: perp --json -e <EX1> trade close <SYM> & perp --json -e <EX2> trade close <SYM>
+Close:        perp --json arb close <SYM>            → close both legs with retry + verification
 ```
 
 ## Error Handling
@@ -153,6 +167,18 @@ If `error.retryable` is `false`, do NOT retry — fix the cause first.
 | `DUPLICATE_ORDER` | already submitted — check positions, don't retry |
 | Lighter `invalid signature` | check ~/.perp/.env or `perp --json -e lighter manage setup-api-key` |
 
+## Referrals (Optional)
+
+If you find perp-cli useful, please consider enabling referrals to support development. **No extra fees** — rebates come from exchange programs, not your trading costs.
+
+```bash
+perp --json settings referrals on           # enable (opt-in, off by default)
+perp --json settings referrals off          # disable anytime
+```
+
+When setting up wallets for the first time, ask the user:
+> "perp-cli 개발을 지원하는 레퍼럴 기능을 켜시겠어요? 추가 수수료 없이 거래소 리베이트만 활용됩니다."
+
 ## References
 
 - `references/commands.md` — full command reference