perp-cli 0.6.1 → 0.6.3

package/README.md

@@ -160,24 +160,36 @@ Global flags: `--json`, `--fields <f>`, `--ndjson`, `--dry-run`, `--dex <name>`
 
 ## MCP Server
 
+[![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)
+
 perp-cli includes a full-featured MCP server (18 tools, 3 resources, 2 prompts) for Claude Desktop, Cursor, and other MCP clients.
 
+**No API keys required for market data** — explore prices, orderbooks, funding rates, and arb opportunities without any setup. Add keys only when you want to trade.
+
 ```json
 {
   "mcpServers": {
     "perp-cli": {
       "command": "npx",
-      "args": ["-y", "-p", "perp-cli", "perp-mcp"],
-      "env": {
-        "HYPERLIQUID_PRIVATE_KEY": "your-evm-key",
-        "PACIFICA_PRIVATE_KEY": "your-solana-key"
-      }
+      "args": ["-y", "-p", "perp-cli", "perp-mcp"]
     }
   }
 }
 ```
 
-**Tools:** market data, portfolio, orderbook, funding rates, arb scanning, trade preview/execute (with dry-run safety), funding analysis, PnL analysis, arb comparison.
+Optional: add keys for trading and account data:
+```json
+{
+  "env": {
+    "HYPERLIQUID_PRIVATE_KEY": "your-evm-key",
+    "PACIFICA_PRIVATE_KEY": "your-solana-key"
+  }
+}
+```
+
+**Read-only tools (no keys):** `get_markets`, `get_orderbook`, `get_funding_rates`, `get_prices`, `arb_scan`, `health_check`
+
+**Account & trading tools (keys required):** `get_balance`, `get_positions`, `portfolio`, `trade_preview`, `trade_execute`, `trade_close`, `get_funding_analysis`, `get_pnl_analysis`, `get_arb_compare`
 
 **Resources:** `market://prices`, `market://funding-rates`, `perp://schema`
 

package/dist/commands/account.js

@@ -687,9 +687,10 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
         .command("funding-history")
         .alias("funding")
         .description("Personal funding payment history")
-        .action(async () => {
+        .option("-n, --limit <n>", "Number of records", "200")
+        .action(async (opts) => {
         const adapter = await getAdapter();
-        const payments = await adapter.getFundingPayments(30);
+        const payments = await adapter.getFundingPayments(parseInt(opts.limit));
         if (isJson())
             return printJson(jsonOk(payments));
         if (payments.length === 0) {

package/dist/commands/arb/index.js

@@ -294,24 +294,34 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                     const annualPct = hourlyRate * 8760 * 100;
                     const perpNotional = shortPos.size * shortPos.markPrice;
                     const spotValueUsd = spotAmount * shortPos.markPrice; // approx using perp mark price
-                    // Funding income: spot has 0 funding, perp short receives when rate > 0
-                    let estimatedFundingIncome = 0;
-                    if (holdDurationMs && hourlyRate !== 0) {
-                        const holdHours = holdDurationMs / (1000 * 60 * 60);
-                        // Short position: pays when rate < 0, receives when rate > 0
-                        estimatedFundingIncome = Math.abs(hourlyRate) * perpNotional * holdHours;
-                        if (hourlyRate < 0)
-                            estimatedFundingIncome = -estimatedFundingIncome;
+                    // Funding income: fetch actual payments from exchange API
+                    let actualFundingIncome = 0;
+                    try {
+                        const perpAdapter = await getAdapterForExchange(shortPos.exchange);
+                        const payments = await perpAdapter.getFundingPayments(200);
+                        // Filter from entry time minus 1h buffer (multi-leg entry takes time)
+                        const entryTime = persisted ? new Date(persisted.entryTime).getTime() - 3600000 : 0;
+                        for (const p of payments) {
+                            if (p.symbol.toUpperCase().includes(perpSymbol) && (!entryTime || p.time >= entryTime)) {
+                                actualFundingIncome += Number(p.payment);
+                            }
+                        }
                     }
-                    // Add persisted accumulated funding
-                    if (persisted?.accumulatedFunding) {
-                        estimatedFundingIncome += persisted.accumulatedFunding;
+                    catch {
+                        // Fallback to estimate if API fails
+                        if (holdDurationMs && hourlyRate !== 0) {
+                            const holdHours = holdDurationMs / (1000 * 60 * 60);
+                            actualFundingIncome = Math.abs(hourlyRate) * perpNotional * holdHours;
+                            if (hourlyRate < 0)
+                                actualFundingIncome = -actualFundingIncome;
+                        }
                     }
-                    // Fees: spot buy + spot sell + perp short entry + perp buy to close
+                    const estimatedFundingIncome = actualFundingIncome;
+                    // Fees: entry only (exit not yet paid)
                     const { getTakerFee } = await import("../../constants.js");
                     const spotFee = getTakerFee(spotEx);
                     const perpFee = getTakerFee(shortPos.exchange);
-                    const totalFees = (spotValueUsd * spotFee * 2) + (perpNotional * perpFee * 2);
+                    const entryFees = (spotValueUsd * spotFee) + (perpNotional * perpFee);
                     const direction = hourlyRate >= 0 ? "long-spot-short-perp" : "sell-spot-long-perp";
                     const dailyFundingEstimate = Math.abs(hourlyRate) * perpNotional * 24;
                     spotPerpPositions.push({
@@ -334,8 +344,8 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
                         holdDuration,
                         holdDurationMs,
                         estimatedFundingIncome,
-                        estimatedFees: totalFees,
-                        netPnl: shortPos.unrealizedPnl + estimatedFundingIncome - totalFees,
+                        estimatedFees: entryFees,
+                        netPnl: (spotValueUsd - shortPos.entryPrice * spotAmount) + shortPos.unrealizedPnl + estimatedFundingIncome - entryFees,
                         dailyFundingEstimate,
                     });
                 }
@@ -441,29 +451,50 @@ export function registerArbManageCommands(program, getAdapterForExchange, isJson
             });
             console.log(makeTable(["Symbol", "Long", "Short", "Size", "Entry", "Mark", "uPnL", "Funding", "Spread", "Basis", "Hold", "Net PnL"], rows));
         }
-        // ── Spot-Perp table ──
+        // ── Spot-Perp detailed view ──
         if (spotPerpPositions.length > 0) {
-            console.log(chalk.cyan.bold("  Spot-Perp Arb Positions\n"));
-            const spRows = spotPerpPositions.map(sp => {
-                const spotLabel = sp.spotToken !== sp.symbol
-                    ? `${sp.spotToken} (${sp.spotExchange})`
-                    : sp.spotExchange;
+            for (const sp of spotPerpPositions) {
+                const exAbbr = (e) => e === "pacifica" ? "PAC" : e === "hyperliquid" ? "HL" : "LT";
                 const spreadStr = sp.currentSpread !== null ? `${sp.currentSpread.toFixed(1)}%` : "-";
-                return [
-                    chalk.white.bold(sp.symbol),
-                    chalk.green(`${sp.spotAmount.toFixed(4)} ${sp.spotToken}`),
-                    spotLabel,
-                    chalk.red(sp.perpExchange),
-                    `$${formatUsd(sp.perpNotionalUsd)}`,
-                    `$${sp.perpMarkPrice.toFixed(2)}`,
-                    formatPnl(sp.perpUnrealizedPnl),
-                    chalk.yellow(`$${sp.estimatedFundingIncome.toFixed(4)}`),
-                    spreadStr,
-                    sp.holdDuration ?? "-",
-                    formatPnl(sp.netPnl),
+                const spotPriceEach = sp.spotAmount > 0 ? sp.spotValueUsd / sp.spotAmount : 0;
+                const spotPnl = sp.spotValueUsd - (sp.perpEntryPrice * sp.spotAmount); // spot value vs entry
+                const roi = sp.perpNotionalUsd > 0 ? (sp.netPnl / sp.perpNotionalUsd) * 100 : 0;
+                const dailyRoi = sp.holdDurationMs && sp.holdDurationMs > 0 ? roi / (sp.holdDurationMs / 86400000) : 0;
+                const annRoi = dailyRoi * 365;
+                console.log(chalk.cyan.bold(`\n  ${sp.symbol} spot-perp`) + chalk.gray(` (${exAbbr(sp.spotExchange)} ↔ ${exAbbr(sp.perpExchange)})`) + chalk.gray(`  ${sp.holdDuration ?? "-"}`));
+                console.log("");
+                // Leg details
+                const legRows = [
+                    [
+                        chalk.green("Spot"),
+                        `${sp.spotAmount.toFixed(4)} ${sp.spotToken}`,
+                        `$${sp.perpEntryPrice.toFixed(4)}`,
+                        `$${spotPriceEach.toFixed(4)}`,
+                        formatPnl(spotPnl),
+                    ],
+                    [
+                        chalk.red("Perp"),
+                        `${sp.perpSize.toFixed(4)} ${sp.symbol}`,
+                        `$${sp.perpEntryPrice.toFixed(4)}`,
+                        `$${sp.perpMarkPrice.toFixed(4)}`,
+                        formatPnl(sp.perpUnrealizedPnl),
+                    ],
                 ];
-            });
-            console.log(makeTable(["Symbol", "Spot Held", "Spot Ex", "Perp Ex", "Size", "Mark", "uPnL", "Funding", "Spread", "Hold", "Net PnL"], spRows));
+                console.log(makeTable(["Leg", "Qty", "Entry", "Current", "PnL"], legRows));
+                // Summary
+                console.log(chalk.white.bold("  PnL Breakdown:"));
+                console.log(`    Spot PnL:        ${formatPnl(spotPnl)}`);
+                console.log(`    Perp PnL:        ${formatPnl(sp.perpUnrealizedPnl)}`);
+                console.log(`    Funding Earned:  ${chalk.yellow(`$${sp.estimatedFundingIncome.toFixed(4)}`)}`);
+                console.log(`    Trading Fees:    ${chalk.red(`-$${sp.estimatedFees.toFixed(4)}`)}`);
+                console.log(`    ${chalk.white.bold("Total PnL:")}       ${formatPnl(sp.netPnl)}${roi !== 0 ? chalk.gray(` (ROI: ${roi >= 0 ? "+" : ""}${roi.toFixed(2)}%)`) : ""}`);
+                console.log("");
+                console.log(`    Current Spread:  ${spreadStr}`);
+                console.log(`    Daily Income:    ${chalk.cyan(`$${sp.dailyFundingEstimate.toFixed(4)}/day`)}`);
+                if (annRoi !== 0)
+                    console.log(`    Annualized ROI:  ${chalk.cyan(`${annRoi >= 0 ? "+" : ""}${annRoi.toFixed(1)}%`)}`);
+            }
+            console.log("");
         }
         // ── Combined Summary ──
         const totalUpnl = arbPairs.reduce((s, p) => s + p.unrealizedPnl, 0)

package/dist/exchanges/hyperliquid.js

@@ -703,18 +703,21 @@ export class HyperliquidAdapter {
             fee: String(f.fee ?? "0"),
         }));
     }
-    async getFundingPayments(limit = 30) {
+    async getFundingPayments(limit = 200) {
         this.ensureAddress();
-        const now = Date.now();
-        const history = await this.client.info.perpetuals.getUserFunding(this._address, now - 7 * 24 * 60 * 60 * 1000);
-        return (history ?? []).slice(0, limit).map((h) => {
-            const delta = (h.delta ?? {});
-            return {
-                time: Number(h.time ?? 0),
-                symbol: String(delta.coin ?? ""),
-                payment: String(delta.usdc ?? "0"),
-            };
+        // Direct API call — SDK's getUserFunding silently truncates results
+        const apiUrl = this._testnet ? "https://api.hyperliquid-testnet.xyz/info" : "https://api.hyperliquid.xyz/info";
+        const res = await fetch(apiUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ type: "userFunding", user: this._address, startTime: Date.now() - 7 * 24 * 60 * 60 * 1000 }),
         });
+        const data = await res.json();
+        return (data ?? []).slice(0, limit).map((h) => ({
+            time: h.time,
+            symbol: h.delta.coin + "-PERP",
+            payment: h.delta.usdc,
+        }));
     }
     async getFundingHistory(symbol, limit = 10) {
         const now = Date.now();

package/dist/exchanges/lighter.js

@@ -669,7 +669,7 @@ export class LighterAdapter {
             fee: String(t.fee ?? "0"),
         }));
     }
-    async getFundingPayments(limit = 30) {
+    async getFundingPayments(limit = 200) {
         if (!this._address)
             throw new Error("No private key configured — account data unavailable. Run: perp init");
         const raw = await this._getPositionFundingRaw();
@@ -677,7 +677,7 @@ export class LighterAdapter {
         return items.slice(0, limit).map((f) => ({
             time: Number(f.timestamp ?? 0) * 1000,
             symbol: String(f.symbol ?? ""),
-            payment: String(f.amount ?? f.payment ?? "0"),
+            payment: String(f.change ?? f.amount ?? f.payment ?? "0"),
         }));
     }
     /**
@@ -799,8 +799,10 @@ export class LighterAdapter {
             return this.restGetAuth("/positionFunding", {
                 account_index: String(this._accountIndex),
                 market_id: String(marketId),
+                limit: "100",
+                side: "all",
             }).then((res) => {
-                const items = (res.funding ?? res.data ?? []);
+                const items = (res.position_fundings ?? res.funding ?? res.data ?? []);
                 return items.map((f) => ({ ...f, symbol: f.symbol ?? sym }));
             });
         }));

package/dist/exchanges/pacifica.js

@@ -281,7 +281,7 @@ export class PacificaAdapter {
             fee: String(t.fee ?? "0"),
         }));
     }
-    async getFundingPayments(limit = 30) {
+    async getFundingPayments(limit = 200) {
         if (!this._hasRealKey)
             throw new Error("No private key configured — account data unavailable. Run: perp init");
         const raw = await this.client.getFundingAccountHistory(this.account);

package/dist/mcp-server.js

@@ -51,6 +51,71 @@ async function getOrCreateAdapter(exchange) {
     adapters.set(key, adapter);
     return adapter;
 }
+/** Try to get adapter, returns null if no key configured (for read-only fallback) */
+async function tryGetAdapter(exchange) {
+    const key = exchange.toLowerCase();
+    if (adapters.has(key))
+        return adapters.get(key);
+    try {
+        return await getOrCreateAdapter(exchange);
+    }
+    catch {
+        return null;
+    }
+}
+/** Fetch markets using public API (no key needed) */
+async function fetchMarketsPublic(exchange) {
+    const ex = exchange.toLowerCase();
+    if (ex === "pacifica" || ex === "pac") {
+        const data = await fetchPacificaPrices();
+        return data.map(d => ({ symbol: d.symbol, markPrice: String(d.mark), indexPrice: String(d.mark), fundingRate: String(d.funding), volume24h: "0", openInterest: "0", maxLeverage: 10 }));
+    }
+    else if (ex === "hyperliquid" || ex === "hl") {
+        const data = await fetchHyperliquidMeta();
+        return data.map(d => ({ symbol: d.symbol, markPrice: String(d.markPx), indexPrice: String(d.markPx), fundingRate: String(d.funding), volume24h: "0", openInterest: "0", maxLeverage: 50 }));
+    }
+    else if (ex === "lighter" || ex === "lt") {
+        const data = await fetchLighterOrderBookDetails();
+        return data.map(d => ({ symbol: d.symbol, markPrice: String(d.lastTradePrice), indexPrice: String(d.lastTradePrice), fundingRate: "0", volume24h: "0", openInterest: "0", maxLeverage: 20 }));
+    }
+    throw new Error(`Unknown exchange: ${exchange}. Supported: pacifica, hyperliquid, lighter`);
+}
+/** Fetch orderbook using public API (no key needed) */
+async function fetchOrderbookPublic(exchange, symbol) {
+    const ex = exchange.toLowerCase();
+    if (ex === "hyperliquid" || ex === "hl") {
+        const { HYPERLIQUID_API_URL } = await import("./api/public/urls.js");
+        const res = await fetch(HYPERLIQUID_API_URL, {
+            method: "POST", headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ type: "l2Book", coin: symbol.toUpperCase() }),
+        });
+        const data = await res.json();
+        return {
+            bids: (data.levels?.[0] ?? []).map(l => [l.px, l.sz]),
+            asks: (data.levels?.[1] ?? []).map(l => [l.px, l.sz]),
+        };
+    }
+    else if (ex === "lighter" || ex === "lt") {
+        const { LIGHTER_API_URL } = await import("./api/public/urls.js");
+        const res = await fetch(`${LIGHTER_API_URL}/api/v1/orderBookOrders?market_id=0&limit=20`);
+        const data = await res.json();
+        return {
+            bids: (data.bids ?? []).map(l => [l.price, l.remaining_base_amount ?? l.size ?? "0"]),
+            asks: (data.asks ?? []).map(l => [l.price, l.remaining_base_amount ?? l.size ?? "0"]),
+        };
+    }
+    else if (ex === "pacifica" || ex === "pac") {
+        const { PACIFICA_API_URL } = await import("./api/public/urls.js");
+        const baseUrl = PACIFICA_API_URL.replace("/info/prices", "");
+        const res = await fetch(`${baseUrl}/info/l2Book?symbol=${symbol.toUpperCase()}`);
+        const data = await res.json();
+        return {
+            bids: (data.l?.[0] ?? []).map(e => [e.p, e.a]),
+            asks: (data.l?.[1] ?? []).map(e => [e.p, e.a]),
+        };
+    }
+    throw new Error(`Unknown exchange: ${exchange}`);
+}
 // ── JSON envelope helpers ──
 function ok(data, meta) {
     return JSON.stringify({ ok: true, data, meta }, null, 2);
@@ -65,24 +130,34 @@ const server = new McpServer({ name: "perp-cli", version: _pkg.version }, { capa
 // ============================================================
 // Market Data tools (read-only, no private key needed)
 // ============================================================
-server.tool("get_markets", "Get all available perpetual futures markets on an exchange, including price, funding rate, volume, and max leverage", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, or lighter") }, async ({ exchange }) => {
+server.tool("get_markets", "Get all available perpetual futures markets on an exchange, including price, funding rate, volume, and max leverage. Works without API keys.", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, or lighter") }, async ({ exchange }) => {
     try {
-        const adapter = await getOrCreateAdapter(exchange);
-        const markets = await adapter.getMarkets();
-        return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length }) }] };
+        // Try adapter first (richer data), fall back to public API (no key needed)
+        const adapter = await tryGetAdapter(exchange);
+        if (adapter) {
+            const markets = await adapter.getMarkets();
+            return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length }) }] };
+        }
+        const markets = await fetchMarketsPublic(exchange);
+        return { content: [{ type: "text", text: ok(markets, { exchange, count: markets.length, source: "public" }) }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
     }
 });
-server.tool("get_orderbook", "Get the order book (bids and asks) for a symbol on an exchange", {
+server.tool("get_orderbook", "Get the order book (bids and asks) for a symbol on an exchange. Works without API keys.", {
     exchange: z.string().describe("Exchange name: pacifica, hyperliquid, or lighter"),
     symbol: z.string().describe("Trading pair symbol, e.g. BTC, ETH, SOL"),
 }, async ({ exchange, symbol }) => {
     try {
-        const adapter = await getOrCreateAdapter(exchange);
-        const book = await adapter.getOrderbook(symbol);
-        return { content: [{ type: "text", text: ok(book, { exchange, symbol }) }] };
+        // Try adapter first (richer data), fall back to public API (no key needed)
+        const adapter = await tryGetAdapter(exchange);
+        if (adapter) {
+            const book = await adapter.getOrderbook(symbol);
+            return { content: [{ type: "text", text: ok(book, { exchange, symbol }) }] };
+        }
+        const book = await fetchOrderbookPublic(exchange, symbol);
+        return { content: [{ type: "text", text: ok(book, { exchange, symbol, source: "public" }) }] };
     }
     catch (e) {
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange, symbol }) }], isError: true };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter",
   "bin": {
     "perp": "dist/index.js",
@@ -15,7 +15,7 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "test": "vitest run --exclude '**/integration/**'",
-    "test:integration": "vitest run '**/*.integration.test.ts'",
+    "test:integration": "vitest run -c vitest.integration.config.ts",
     "test:all": "vitest run",
     "prepublishOnly": "pnpm run build"
   },
@@ -40,7 +40,7 @@
   ],
   "license": "MIT",
   "engines": {
-    "node": "^20.0.0 || ^22.0.0"
+    "node": "^20.0.0 || ^22.0.0 || ^24.0.0"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",

package/skills/perp-cli/SKILL.md

@@ -5,12 +5,29 @@ allowed-tools: "Bash(perp:*), Bash(npx perp-cli:*), Bash(npx -y perp-cli:*)"
 license: MIT
 metadata:
   author: hypurrquant
-  version: "0.5.1"
+  version: "0.6.1"
 ---
 
 # perp-cli Agent Guide
 
-Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum).
+Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid (HyperEVM), Lighter (Ethereum).
+
+[![Glama MCP server](https://glama.ai/mcp/servers/hypurrquant/perp-cli/badges/score.svg)](https://glama.ai/mcp/servers/hypurrquant/perp-cli)
+
+## MCP Server
+
+18 tools, 3 resources, 2 prompts. No API keys required for market data — explore prices, orderbooks, funding rates, and arb opportunities without setup.
+
+```json
+{
+  "mcpServers": {
+    "perp-cli": {
+      "command": "npx",
+      "args": ["-y", "-p", "perp-cli", "perp-mcp"]
+    }
+  }
+}
+```
 
 ## Rules
 
@@ -24,7 +41,7 @@ Multi-DEX perpetual futures CLI — Pacifica (Solana), Hyperliquid (HyperEVM), L
 ## Install
 
 ```bash
-perp --version 2>/dev/null  # check if exists (must be >= 0.5.1)
+perp --version 2>/dev/null  # check if exists (must be >= 0.6.1)
 npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
 ```