perp-cli 0.3.3

package/dist/__tests__/integration/new-commands-e2e.integration.test.js

@@ -0,0 +1,236 @@
+/**
+ * E2E integration tests for new atomic commands and api-spec.
+ * These tests spawn the actual CLI process and verify JSON output.
+ *
+ * - api-spec: no adapter needed, always works
+ * - market mid: needs HL mainnet (read-only, no key needed for public data)
+ * - error envelopes: verify structured errors across commands
+ */
+import "dotenv/config";
+import { execSync } from "child_process";
+import { describe, it, expect } from "vitest";
+const CLI_CWD = "/Users/hik/Documents/GitHub/pacifica/packages/cli";
+const CLI_CMD = "npx tsx src/index.ts";
+function runCli(args) {
+    return execSync(`${CLI_CMD} ${args}`, {
+        encoding: "utf-8",
+        cwd: CLI_CWD,
+        timeout: 25000,
+        env: { ...process.env, NODE_NO_WARNINGS: "1" },
+    });
+}
+function runCliSafe(args) {
+    try {
+        const stdout = execSync(`${CLI_CMD} ${args}`, {
+            encoding: "utf-8",
+            cwd: CLI_CWD,
+            timeout: 25000,
+            env: { ...process.env, NODE_NO_WARNINGS: "1" },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        return { stdout, stderr: "", exitCode: 0 };
+    }
+    catch (err) {
+        const e = err;
+        return {
+            stdout: e.stdout ?? "",
+            stderr: e.stderr ?? "",
+            exitCode: e.status ?? 1,
+        };
+    }
+}
+describe("New Commands E2E Integration", { timeout: 30000 }, () => {
+    // ══════════════════════════════════════════════════════════
+    // api-spec — no adapter needed
+    // ══════════════════════════════════════════════════════════
+    describe("perp api-spec", () => {
+        let spec;
+        it("outputs valid JSON envelope with ok:true", () => {
+            const output = runCli("api-spec");
+            spec = JSON.parse(output);
+            expect(spec.ok).toBe(true);
+            expect(spec.data).toBeDefined();
+            expect(spec.meta).toBeDefined();
+            expect(spec.meta.timestamp).toBeDefined();
+        });
+        it("data contains name, version, commands, errorCodes", () => {
+            const output = runCli("api-spec");
+            spec = JSON.parse(output);
+            const data = spec.data;
+            expect(data.name).toBe("perp");
+            expect(data.version).toBeDefined();
+            expect(data.description).toBeDefined();
+            expect(Array.isArray(data.commands)).toBe(true);
+            expect(typeof data.errorCodes).toBe("object");
+            expect(Array.isArray(data.exchanges)).toBe(true);
+            expect(Array.isArray(data.tips)).toBe(true);
+        });
+        it("commands include all major command groups with subcommands", () => {
+            const output = runCli("api-spec");
+            spec = JSON.parse(output);
+            const data = spec.data;
+            const commands = data.commands;
+            const names = commands.map((c) => c.name);
+            expect(names).toContain("market");
+            expect(names).toContain("account");
+            expect(names).toContain("trade");
+            expect(names).toContain("arb");
+            expect(names).toContain("status");
+            expect(names).toContain("health");
+            expect(names).toContain("portfolio");
+            expect(names).toContain("risk");
+            expect(names).toContain("api-spec");
+            // market should have subcommands including mid
+            const market = commands.find((c) => c.name === "market");
+            expect(market?.subcommands).toBeDefined();
+            const marketSubs = market.subcommands.map((s) => s.name);
+            expect(marketSubs).toContain("mid");
+            expect(marketSubs).toContain("list");
+            expect(marketSubs).toContain("info");
+            expect(marketSubs).toContain("book");
+            // account should have margin subcommand
+            const account = commands.find((c) => c.name === "account");
+            const accountSubs = account.subcommands.map((s) => s.name);
+            expect(accountSubs).toContain("margin");
+            expect(accountSubs).toContain("info");
+            expect(accountSubs).toContain("positions");
+            // trade should have status and fills subcommands
+            const trade = commands.find((c) => c.name === "trade");
+            const tradeSubs = trade.subcommands.map((s) => s.name);
+            expect(tradeSubs).toContain("status");
+            expect(tradeSubs).toContain("fills");
+        });
+        it("errorCodes have consistent structure", () => {
+            const output = runCli("api-spec");
+            spec = JSON.parse(output);
+            const data = spec.data;
+            const errorCodes = data.errorCodes;
+            const codes = Object.keys(errorCodes);
+            expect(codes.length).toBeGreaterThanOrEqual(15);
+            for (const [code, info] of Object.entries(errorCodes)) {
+                expect(typeof info.status).toBe("number");
+                expect(typeof info.retryable).toBe("boolean");
+                expect(typeof info.description).toBe("string");
+                expect(info.description.length).toBeGreaterThan(0);
+                // HTTP status codes should be in valid range
+                expect(info.status).toBeGreaterThanOrEqual(400);
+                expect(info.status).toBeLessThanOrEqual(599);
+            }
+            // Retryable codes should have 5xx status
+            expect(errorCodes.EXCHANGE_UNREACHABLE.retryable).toBe(true);
+            expect(errorCodes.RATE_LIMITED.retryable).toBe(true);
+            expect(errorCodes.TIMEOUT.retryable).toBe(true);
+            // Non-retryable codes
+            expect(errorCodes.INVALID_PARAMS.retryable).toBe(false);
+            expect(errorCodes.INSUFFICIENT_BALANCE.retryable).toBe(false);
+        });
+        it("globalOptions include --json, --exchange, --dry-run", () => {
+            const output = runCli("api-spec");
+            spec = JSON.parse(output);
+            const data = spec.data;
+            const opts = data.globalOptions;
+            const allFlags = opts.map((o) => o.flags).join(" ");
+            expect(allFlags).toContain("--json");
+            expect(allFlags).toContain("--exchange");
+            expect(allFlags).toContain("--dry-run");
+            expect(allFlags).toContain("--dex");
+        });
+        it("tips array includes referral nudge", () => {
+            const output = runCli("api-spec");
+            spec = JSON.parse(output);
+            const data = spec.data;
+            const tips = data.tips;
+            expect(tips.length).toBeGreaterThanOrEqual(5);
+            const joined = tips.join("\n");
+            expect(joined).toContain("referrals");
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // market mid — uses HL mainnet read-only (public data)
+    // ══════════════════════════════════════════════════════════
+    const HAS_KEY = !!(process.env.HYPERLIQUID_PRIVATE_KEY || process.env.HL_PRIVATE_KEY);
+    describe.skipIf(!HAS_KEY)("perp --json -e hyperliquid market mid BTC", () => {
+        it("returns valid mid price envelope", () => {
+            const output = runCli("--json -e hyperliquid market mid BTC");
+            const parsed = JSON.parse(output);
+            expect(parsed.ok).toBe(true);
+            expect(parsed.meta?.timestamp).toBeDefined();
+            const data = parsed.data;
+            expect(data.symbol).toBe("BTC");
+            expect(typeof data.mid).toBe("string");
+            expect(typeof data.bid).toBe("string");
+            expect(typeof data.ask).toBe("string");
+            expect(typeof data.spread).toBe("string");
+            // Price sanity
+            const mid = parseFloat(data.mid);
+            expect(mid).toBeGreaterThan(100);
+            const bid = parseFloat(data.bid);
+            const ask = parseFloat(data.ask);
+            expect(bid).toBeLessThan(ask);
+            expect(bid).toBeGreaterThan(0);
+            // Spread should be tiny for BTC
+            const spread = parseFloat(data.spread);
+            expect(spread).toBeGreaterThanOrEqual(0);
+            expect(spread).toBeLessThan(1); // < 1%
+        });
+        it("returns ETH mid price with reasonable values", () => {
+            const output = runCli("--json -e hyperliquid market mid ETH");
+            const parsed = JSON.parse(output);
+            expect(parsed.ok).toBe(true);
+            const mid = parseFloat(parsed.data.mid);
+            expect(mid).toBeGreaterThan(10);
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // Error envelope consistency
+    // ══════════════════════════════════════════════════════════
+    describe("--json error envelope consistency", () => {
+        it("unknown command returns CLI_ERROR with meta.timestamp", () => {
+            const { stdout } = runCliSafe("--json fakecmd123");
+            const parsed = JSON.parse(stdout);
+            expect(parsed.ok).toBe(false);
+            expect(parsed.error).toBeDefined();
+            expect(parsed.error.code).toBe("CLI_ERROR");
+            expect(typeof parsed.error.message).toBe("string");
+            expect(parsed.meta).toBeDefined();
+            expect(parsed.meta.timestamp).toBeDefined();
+            // Timestamp should be valid ISO 8601
+            expect(new Date(parsed.meta.timestamp).toISOString()).toBe(parsed.meta.timestamp);
+        });
+        it("plan validate with nonexistent file returns structured error", () => {
+            const { stdout } = runCliSafe("--json plan validate /tmp/__nonexistent_99999.json");
+            const parsed = JSON.parse(stdout);
+            expect(parsed.ok).toBe(false);
+            expect(parsed.error.code).toBeDefined();
+            expect(parsed.error.message).toContain("ENOENT");
+            expect(parsed.meta.timestamp).toBeDefined();
+        });
+        it("api-spec always returns ok:true even without --json flag", () => {
+            const output = runCli("api-spec");
+            const parsed = JSON.parse(output);
+            expect(parsed.ok).toBe(true);
+        });
+    });
+    // ══════════════════════════════════════════════════════════
+    // help output validation
+    // ══════════════════════════════════════════════════════════
+    describe("help output includes new commands", () => {
+        it("market --help lists mid subcommand", () => {
+            const { stdout } = runCliSafe("market --help");
+            expect(stdout).toContain("mid");
+        });
+        it("account --help lists margin subcommand", () => {
+            const { stdout } = runCliSafe("account --help");
+            expect(stdout).toContain("margin");
+        });
+        it("trade --help lists status and fills subcommands", () => {
+            const { stdout } = runCliSafe("trade --help");
+            expect(stdout).toContain("status");
+            expect(stdout).toContain("fills");
+        });
+        it("top-level --help lists api-spec", () => {
+            const { stdout } = runCliSafe("--help");
+            expect(stdout).toContain("api-spec");
+        });
+    });
+});

package/dist/__tests__/integration/order-verification.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration/order-verification.integration.test.js

@@ -0,0 +1,321 @@
+/**
+ * Integration tests: Order Verification against Hyperliquid Mainnet
+ *
+ * READ-ONLY tests — no orders are placed, no funds are touched.
+ * Uses a dummy private key to instantiate the adapter for market data queries.
+ * All assertions use reasonable ranges to accommodate live price fluctuations.
+ */
+import { describe, it, expect, beforeAll } from "vitest";
+import { HyperliquidAdapter } from "../../exchanges/hyperliquid.js";
+import { validateTrade } from "../../trade-validator.js";
+// Dummy key — only used for read-only info queries, never signs a transaction
+const DUMMY_KEY = "0x" + "1".repeat(64);
+/** Find a market by base symbol, tolerating a -PERP suffix. */
+function findMarket(markets, base) {
+    const b = base.toUpperCase();
+    return markets.find((m) => m.symbol.toUpperCase() === b ||
+        m.symbol.toUpperCase() === `${b}-PERP` ||
+        m.symbol.toUpperCase().replace(/-PERP$/, "") === b);
+}
+describe("Hyperliquid mainnet — order verification (read-only)", () => {
+    let adapter;
+    let markets;
+    beforeAll(async () => {
+        adapter = new HyperliquidAdapter(DUMMY_KEY, false);
+        await adapter.init();
+        markets = await adapter.getMarkets();
+        // Sanity: the exchange must expose at least a handful of markets
+        expect(markets.length).toBeGreaterThan(10);
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 1. "Buy 0.001 BTC" — validation with real data
+    // ────────────────────────────────────────────────────────────
+    it("validates a 0.001 BTC market buy with sane estimates", async () => {
+        const result = await validateTrade(adapter, {
+            symbol: "BTC",
+            side: "buy",
+            size: 0.001,
+            type: "market",
+        });
+        // Symbol must be found
+        const symCheck = result.checks.find((c) => c.check === "symbol_valid");
+        expect(symCheck).toBeDefined();
+        expect(symCheck.passed).toBe(true);
+        // Mark price: BTC should be well above $10 000
+        expect(result.marketInfo).toBeDefined();
+        expect(result.marketInfo.markPrice).toBeGreaterThan(10_000);
+        // Estimated cost: 0.001 BTC at ~$60-120k → notional $60-$120
+        // Margin at max leverage (~50x) ≈ $1.2-$2.4
+        // Fee at 0.05% ≈ $0.03-$0.06
+        expect(result.estimatedCost).toBeDefined();
+        expect(result.estimatedCost.margin).toBeGreaterThan(0.5);
+        expect(result.estimatedCost.margin).toBeLessThan(20);
+        expect(result.estimatedCost.fee).toBeGreaterThan(0.01);
+        expect(result.estimatedCost.fee).toBeLessThan(1);
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 2. "Buy 1 ETH" — cost estimation accuracy
+    // ────────────────────────────────────────────────────────────
+    it("validates a 1 ETH market buy with accurate cost estimation", async () => {
+        const result = await validateTrade(adapter, {
+            symbol: "ETH",
+            side: "buy",
+            size: 1.0,
+            type: "market",
+        });
+        expect(result.marketInfo).toBeDefined();
+        const ethPrice = result.marketInfo.markPrice;
+        // ETH price should be in a broad but reasonable range
+        expect(ethPrice).toBeGreaterThan(500);
+        expect(ethPrice).toBeLessThan(20_000);
+        // Margin at max leverage: notional / maxLev
+        // At 50x: margin ~$36-$400 depending on price
+        expect(result.estimatedCost).toBeDefined();
+        expect(result.estimatedCost.margin).toBeGreaterThan(5);
+        expect(result.estimatedCost.margin).toBeLessThan(500);
+        // Fee: 0.05% of notional ($500-$20k) → $0.25 - $10
+        expect(result.estimatedCost.fee).toBeGreaterThan(0.1);
+        expect(result.estimatedCost.fee).toBeLessThan(15);
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 3. "Buy 0.1 SOL" — smaller asset
+    // ────────────────────────────────────────────────────────────
+    it("validates a 0.1 SOL buy — smaller asset sanity", async () => {
+        const result = await validateTrade(adapter, {
+            symbol: "SOL",
+            side: "buy",
+            size: 0.1,
+            type: "market",
+        });
+        const symCheck = result.checks.find((c) => c.check === "symbol_valid");
+        expect(symCheck).toBeDefined();
+        expect(symCheck.passed).toBe(true);
+        expect(result.marketInfo).toBeDefined();
+        expect(result.marketInfo.markPrice).toBeGreaterThan(10);
+        // Notional ~$1-$100 at current prices — cost should be small but positive
+        expect(result.estimatedCost).toBeDefined();
+        expect(result.estimatedCost.margin).toBeGreaterThan(0);
+        expect(result.estimatedCost.fee).toBeGreaterThan(0);
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 4. "Sell 100 BTC" — liquidity / slippage check
+    // ────────────────────────────────────────────────────────────
+    it("detects liquidity/slippage concern for a 100 BTC sell", async () => {
+        const result = await validateTrade(adapter, {
+            symbol: "BTC",
+            side: "sell",
+            size: 100,
+            type: "market",
+        });
+        // 100 BTC ≈ $6-12M notional — the validator should either:
+        //   a) flag insufficient liquidity in the visible orderbook, or
+        //   b) flag high slippage, or
+        //   c) flag a risk-limits violation (max position size $5k default)
+        const liqCheck = result.checks.find((c) => c.check === "liquidity_ok");
+        const riskCheck = result.checks.find((c) => c.check === "risk_limits");
+        // At least one of these should flag the absurd size
+        const anyFlagged = (liqCheck && !liqCheck.passed) || (riskCheck && !riskCheck.passed);
+        expect(anyFlagged).toBe(true);
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 5. Orderbook consistency — bid < ask
+    // ────────────────────────────────────────────────────────────
+    it("verifies orderbook bid < ask and spread near mark for BTC, ETH, SOL", async () => {
+        const symbols = ["BTC", "ETH", "SOL"];
+        for (const sym of symbols) {
+            const book = await adapter.getOrderbook(sym);
+            // Must have at least one level on each side
+            expect(book.bids.length).toBeGreaterThan(0);
+            expect(book.asks.length).toBeGreaterThan(0);
+            const bestBid = Number(book.bids[0][0]);
+            const bestAsk = Number(book.asks[0][0]);
+            // Best bid must be strictly less than best ask (positive spread)
+            expect(bestBid).toBeLessThan(bestAsk);
+            // Spread should be tiny relative to price (< 0.1%)
+            const spread = (bestAsk - bestBid) / bestBid;
+            expect(spread).toBeLessThan(0.001); // 0.1%
+            // Both sides should be near the mark price (within 0.1%)
+            const market = findMarket(markets, sym);
+            expect(market).toBeDefined();
+            const mark = Number(market.markPrice);
+            if (mark > 0) {
+                expect(Math.abs(bestBid - mark) / mark).toBeLessThan(0.001);
+                expect(Math.abs(bestAsk - mark) / mark).toBeLessThan(0.001);
+            }
+        }
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 6. Position side mapping — close logic
+    // ────────────────────────────────────────────────────────────
+    it("maps position close side correctly (long → sell, short → buy)", () => {
+        // Pure logic check using real market context types
+        const scenarios = [
+            { side: "long", expectedClose: "sell" },
+            { side: "short", expectedClose: "buy" },
+        ];
+        for (const { side, expectedClose } of scenarios) {
+            // The universal close-position rule: to close, you place
+            // the opposite side order.
+            const closeSide = side === "long" ? "sell" : "buy";
+            expect(closeSide).toBe(expectedClose);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 7. Leverage bounds from real API
+    // ────────────────────────────────────────────────────────────
+    it("reports maxLeverage >= 20 for BTC and ETH, lower for small-caps", () => {
+        const btc = findMarket(markets, "BTC");
+        const eth = findMarket(markets, "ETH");
+        expect(btc).toBeDefined();
+        expect(eth).toBeDefined();
+        // HL allows 40-50x on BTC/ETH
+        expect(btc.maxLeverage).toBeGreaterThanOrEqual(20);
+        expect(eth.maxLeverage).toBeGreaterThanOrEqual(20);
+        // Find a lower-liquidity asset (take the last market, or one with low volume)
+        const lowCap = markets
+            .filter((m) => m.symbol !== "BTC" &&
+            m.symbol !== "ETH" &&
+            m.symbol !== "SOL" &&
+            Number(m.volume24h) > 0)
+            .sort((a, b) => Number(a.volume24h) - Number(b.volume24h))[0];
+        if (lowCap) {
+            // Low-cap coins typically have lower max leverage than BTC
+            // Allow equality since some may still be 50x; the key check is that the
+            // field is populated and numeric
+            expect(lowCap.maxLeverage).toBeGreaterThan(0);
+            expect(lowCap.maxLeverage).toBeLessThanOrEqual(btc.maxLeverage);
+        }
+    });
+    // ────────────────────────────────────────────────────────────
+    // 8. Funding rate sanity
+    // ────────────────────────────────────────────────────────────
+    it("returns funding rates in -1% to 1% range for BTC and ETH", () => {
+        const btc = findMarket(markets, "BTC");
+        const eth = findMarket(markets, "ETH");
+        expect(btc).toBeDefined();
+        expect(eth).toBeDefined();
+        const btcFunding = Number(btc.fundingRate);
+        const ethFunding = Number(eth.fundingRate);
+        // Hourly funding rates should be tiny decimals (e.g., 0.0001 = 0.01%)
+        // Anything outside +-1% would indicate a parsing error
+        expect(btcFunding).toBeGreaterThan(-0.01);
+        expect(btcFunding).toBeLessThan(0.01);
+        expect(ethFunding).toBeGreaterThan(-0.01);
+        expect(ethFunding).toBeLessThan(0.01);
+    });
+    // ────────────────────────────────────────────────────────────
+    // 9. Invalid symbol rejection
+    // ────────────────────────────────────────────────────────────
+    it("rejects an invalid symbol (XYZNOTREAL999)", async () => {
+        const result = await validateTrade(adapter, {
+            symbol: "XYZNOTREAL999",
+            side: "buy",
+            size: 1,
+            type: "market",
+        });
+        expect(result.valid).toBe(false);
+        const symCheck = result.checks.find((c) => c.check === "symbol_valid");
+        expect(symCheck).toBeDefined();
+        expect(symCheck.passed).toBe(false);
+        expect(symCheck.message).toContain("not found");
+    }, 30_000);
+    it("handles an empty symbol gracefully", async () => {
+        const result = await validateTrade(adapter, {
+            symbol: "",
+            side: "buy",
+            size: 1,
+            type: "market",
+        });
+        expect(result.valid).toBe(false);
+        const symCheck = result.checks.find((c) => c.check === "symbol_valid");
+        expect(symCheck).toBeDefined();
+        expect(symCheck.passed).toBe(false);
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 10. Reduce-only without position
+    // ────────────────────────────────────────────────────────────
+    it("rejects reduce-only when no position exists (dummy account)", async () => {
+        const result = await validateTrade(adapter, {
+            symbol: "BTC",
+            side: "sell",
+            size: 0.01,
+            type: "market",
+            reduceOnly: true,
+        });
+        // The dummy key has no positions, so the position_exists check should fail
+        const posCheck = result.checks.find((c) => c.check === "position_exists");
+        expect(posCheck).toBeDefined();
+        expect(posCheck.passed).toBe(false);
+        expect(posCheck.message).toContain("No position found");
+        expect(posCheck.message).toContain("reduce-only");
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 11. Price freshness with real data
+    // ────────────────────────────────────────────────────────────
+    it("passes price freshness at mark +-1% and fails at +-15%", async () => {
+        // Fetch the current BTC mark price
+        const btcMarket = findMarket(markets, "BTC");
+        expect(btcMarket).toBeDefined();
+        const mark = Number(btcMarket.markPrice);
+        expect(mark).toBeGreaterThan(10_000);
+        // Limit order at mark + 1% → should pass freshness
+        const closeResult = await validateTrade(adapter, {
+            symbol: "BTC",
+            side: "buy",
+            size: 0.001,
+            type: "limit",
+            price: mark * 1.01,
+        });
+        const closeFresh = closeResult.checks.find((c) => c.check === "price_fresh");
+        expect(closeFresh).toBeDefined();
+        expect(closeFresh.passed).toBe(true);
+        // Limit order at mark + 15% → should fail freshness (>10% deviation)
+        const farResult = await validateTrade(adapter, {
+            symbol: "BTC",
+            side: "buy",
+            size: 0.001,
+            type: "limit",
+            price: mark * 1.15,
+        });
+        const farFresh = farResult.checks.find((c) => c.check === "price_fresh");
+        expect(farFresh).toBeDefined();
+        expect(farFresh.passed).toBe(false);
+        expect(farFresh.message).toContain("deviates");
+    }, 30_000);
+    // ────────────────────────────────────────────────────────────
+    // 12. Cross-exchange spread: native HL vs HIP-3 dex
+    // ────────────────────────────────────────────────────────────
+    it("compares BTC price on native HL against a HIP-3 dex (hyna)", async () => {
+        // Native HL BTC price
+        const btcNative = findMarket(markets, "BTC");
+        expect(btcNative).toBeDefined();
+        const nativePrice = Number(btcNative.markPrice);
+        expect(nativePrice).toBeGreaterThan(10_000);
+        // Try to get hyna dex markets — if dex doesn't exist or BTC isn't listed,
+        // skip gracefully (the dex landscape changes over time).
+        let dexPrice = null;
+        try {
+            const dexAdapter = new HyperliquidAdapter(DUMMY_KEY, false);
+            await dexAdapter.init();
+            dexAdapter.setDex("hyna");
+            // Re-init asset map for the dex context
+            const dexMarkets = await dexAdapter.getMarkets();
+            const btcDex = findMarket(dexMarkets, "BTC");
+            if (btcDex) {
+                dexPrice = Number(btcDex.markPrice);
+            }
+        }
+        catch {
+            // hyna dex may not exist — skip comparison
+        }
+        if (dexPrice !== null && dexPrice > 0) {
+            // Prices should be within 0.5% of each other (same underlying)
+            const divergence = Math.abs(nativePrice - dexPrice) / nativePrice;
+            expect(divergence).toBeLessThan(0.005);
+        }
+        else {
+            // No comparable dex market — test passes vacuously with a note
+            console.log("Skipped cross-dex comparison: hyna BTC market not available");
+        }
+    }, 30_000);
+});

package/dist/__tests__/integration/pacifica.integration.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/integration/pacifica.integration.test.js

@@ -0,0 +1,75 @@
+import { describe, it, expect, beforeAll } from "vitest";
+import { PacificaAdapter } from "../../exchanges/pacifica.js";
+import { parseSolanaKeypair } from "../../config.js";
+/**
+ * Integration tests for Pacifica exchange adapter (Solana Devnet).
+ *
+ * Prerequisites:
+ *   1. Set PACIFICA_PRIVATE_KEY env var (base58 or JSON array)
+ *   2. Have devnet SOL:  solana airdrop 2 --url devnet
+ *   3. Have devnet USDC deposited into Pacifica testnet
+ *
+ * Run: PACIFICA_PRIVATE_KEY=<key> pnpm --filter perp-cli test -- --testPathPattern integration/pacifica
+ */
+const SKIP = !process.env.PACIFICA_PRIVATE_KEY;
+describe.skipIf(SKIP)("Pacifica Integration (Devnet)", () => {
+    let adapter;
+    beforeAll(() => {
+        const keypair = parseSolanaKeypair(process.env.PACIFICA_PRIVATE_KEY);
+        adapter = new PacificaAdapter(keypair, "testnet");
+    });
+    describe("Read-only operations", () => {
+        it("fetches markets", async () => {
+            const markets = await adapter.getMarkets();
+            expect(markets.length).toBeGreaterThan(0);
+            expect(markets[0].symbol).toBeTruthy();
+            expect(Number(markets[0].maxLeverage)).toBeGreaterThan(0);
+        });
+        it("fetches orderbook for BTC", async () => {
+            const book = await adapter.getOrderbook("BTC");
+            expect(book).toHaveProperty("bids");
+            expect(book).toHaveProperty("asks");
+        });
+        it("fetches balance", async () => {
+            const balance = await adapter.getBalance();
+            expect(balance).toHaveProperty("equity");
+            expect(balance).toHaveProperty("available");
+            expect(Number(balance.equity)).toBeGreaterThanOrEqual(0);
+        });
+        it("fetches positions", async () => {
+            const positions = await adapter.getPositions();
+            expect(Array.isArray(positions)).toBe(true);
+        });
+        it("fetches open orders", async () => {
+            const orders = await adapter.getOpenOrders();
+            expect(Array.isArray(orders)).toBe(true);
+        });
+    });
+    describe("Trading operations", () => {
+        // WARNING: These tests place REAL orders on testnet
+        const TEST_SYMBOL = "BTC";
+        let limitOrderId;
+        it("places a limit buy order (far from market)", async () => {
+            // Place far below market so it won't fill
+            const result = await adapter.limitOrder(TEST_SYMBOL, "buy", "10000", "0.001");
+            expect(result).toBeTruthy();
+            // Check it appears in open orders
+            const orders = await adapter.getOpenOrders();
+            const myOrder = orders.find((o) => o.symbol === TEST_SYMBOL && o.side === "buy" && o.price === "10000");
+            if (myOrder) {
+                limitOrderId = myOrder.orderId;
+                expect(myOrder.status).toBe("open");
+            }
+        });
+        it("cancels the limit order", async () => {
+            if (!limitOrderId)
+                return;
+            const result = await adapter.cancelOrder(TEST_SYMBOL, limitOrderId);
+            expect(result).toBeTruthy();
+        });
+        it("cancel all orders succeeds", async () => {
+            const result = await adapter.cancelAllOrders();
+            expect(result).toBeTruthy();
+        });
+    });
+});

package/dist/__tests__/integration/response-shapes.integration.test.d.ts

@@ -0,0 +1 @@
+export {};