perp-cli 0.12.12 → 0.12.14

package/dist/commands/portfolio.js

@@ -183,7 +183,14 @@ async function fetchExchangeEntry(exName, getAdapter) {
                         valueUsd: base === "USDC" ? Number(b.total) : (priceMap.get(base) ?? 0) * Number(b.total),
                     };
                 });
-                isUnified = !isDexCapable(adapter) || !adapter.dex;
+                // Read the actual abstraction mode (populated during init()) instead
+                // of assuming all main HL accounts are unified. Standard/default mode
+                // accounts must include spot USDC in totalAccountValueUsd because
+                // perp equity does NOT contain it. HIP-3 dex accounts always run
+                // standard semantics. Codex v0.12.12 final QA #1.
+                const hlAdapter = adapter;
+                const dexScoped = isDexCapable(adapter) && !!adapter.dex;
+                isUnified = !dexScoped && hlAdapter.isUnifiedAccount === true;
             }
             else if (exName === "lighter") {
                 const { LighterAdapter } = await import("../exchanges/lighter.js");

package/dist/errors.d.ts

@@ -163,7 +163,11 @@ export interface StructuredError {
 export declare function extractErrorMessage(err: unknown): string;
 /**
  * Classify an error from any exchange into a structured error code.
- * Pattern-matches on error messages to detect known error types.
+ *
+ * If the input is already a PerpError, return its structured payload verbatim
+ * — the typed code and remediation are the source of truth and must not be
+ * re-derived from message text. Pattern-matching only kicks in for plain
+ * Error instances or unknown thrown values. Codex v0.12.12 final QA #2.
  */
 export declare function classifyError(err: unknown, exchange?: string): StructuredError;
 /** Custom error class that carries a structured error code */

package/dist/errors.js

@@ -59,9 +59,19 @@ export function extractErrorMessage(err) {
 }
 /**
  * Classify an error from any exchange into a structured error code.
- * Pattern-matches on error messages to detect known error types.
+ *
+ * If the input is already a PerpError, return its structured payload verbatim
+ * — the typed code and remediation are the source of truth and must not be
+ * re-derived from message text. Pattern-matching only kicks in for plain
+ * Error instances or unknown thrown values. Codex v0.12.12 final QA #2.
  */
 export function classifyError(err, exchange) {
+    if (err instanceof PerpError) {
+        // Preserve the PerpError's typed shape; only fill in `exchange` if the
+        // caller provided one and the error didn't already attach it.
+        const ex = (err.structured.exchange ?? exchange);
+        return ex !== undefined ? { ...err.structured, exchange: ex } : { ...err.structured };
+    }
     const message = extractErrorMessage(err);
     const lower = message.toLowerCase();
     // Margin-specific checks first (before generic "insufficient" catch)

package/dist/exchanges/aster.d.ts

@@ -156,7 +156,11 @@ export declare class AsterAdapter implements ExchangeAdapter {
      * Same retry behavior as _signedGetEip712.
      */
     private _signedDeleteEip712;
-    /** Shared GET/DELETE retry loop with fresh-nonce per attempt. */
+    /** Shared GET/DELETE retry loop with fresh-nonce per attempt.
+     *
+     *  Total 4 attempts: initial + 3 retries with backoffs 2s, 4s, 8s.
+     *  Codex v0.12.12 final QA #3: previously MAX_ATTEMPTS = 3 truncated the
+     *  documented curve so the 8s backoff was never reachable in practice. */
     private _signedRequestWithRetry;
     /**
      * Unified response validator for ALL signed Aster requests.

package/dist/exchanges/aster.js

@@ -634,9 +634,13 @@ export class AsterAdapter {
     async _signedDeleteEip712(path, params, resolved) {
         return this._signedRequestWithRetry("DELETE", path, params, resolved);
     }
-    /** Shared GET/DELETE retry loop with fresh-nonce per attempt. */
+    /** Shared GET/DELETE retry loop with fresh-nonce per attempt.
+     *
+     *  Total 4 attempts: initial + 3 retries with backoffs 2s, 4s, 8s.
+     *  Codex v0.12.12 final QA #3: previously MAX_ATTEMPTS = 3 truncated the
+     *  documented curve so the 8s backoff was never reachable in practice. */
     async _signedRequestWithRetry(method, path, params, resolved) {
-        const MAX_ATTEMPTS = 3;
+        const MAX_ATTEMPTS = 4;
         let lastErr;
         for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
             // Rebuild signed query string with fresh nonce on each attempt.

package/dist/exchanges/hyperliquid.d.ts

@@ -6,7 +6,14 @@ export declare class HyperliquidAdapter implements ExchangeAdapter {
     readonly name = "hyperliquid";
     readonly chain = "evm";
     readonly aliases: readonly ["hl"];
-    readonly isUnifiedAccount = true;
+    /**
+     * Reflects whether perp + spot share the same USDC pool (true for unified /
+     * portfolio mode) or are separately margined (false for standard mode and
+     * HIP-3 dex accounts). Populated during init() from _getAbstractionMode();
+     * defaults to false until init resolves so callers never assume unified
+     * semantics for accounts that have never opted in. Codex v0.12.12 final QA #1.
+     */
+    isUnifiedAccount: boolean;
     private sdk;
     private _address;
     private _privateKey;

package/dist/exchanges/hyperliquid.js

@@ -5,7 +5,14 @@ export class HyperliquidAdapter {
     name = "hyperliquid";
     chain = "evm";
     aliases = ["hl"];
-    isUnifiedAccount = true;
+    /**
+     * Reflects whether perp + spot share the same USDC pool (true for unified /
+     * portfolio mode) or are separately margined (false for standard mode and
+     * HIP-3 dex accounts). Populated during init() from _getAbstractionMode();
+     * defaults to false until init resolves so callers never assume unified
+     * semantics for accounts that have never opted in. Codex v0.12.12 final QA #1.
+     */
+    isUnifiedAccount = false;
     sdk;
     _address;
     _privateKey;
@@ -147,6 +154,22 @@ export class HyperliquidAdapter {
         }
         // Build asset index map
         await this._loadAssetMap();
+        // Resolve abstraction mode → isUnifiedAccount flag for callers
+        // (portfolio accounting + spot-perp arb sizing). Standard/HIP-3 dex
+        // accounts are NOT unified (perp + spot are separately margined).
+        // Read-only paths (no address yet) can't query userAbstraction; leave the
+        // default false until a downstream caller invokes setAddress + the cache
+        // populates during getBalance(). Codex v0.12.12 final QA #1.
+        if (this._address) {
+            try {
+                const mode = await this._getAbstractionMode();
+                this.isUnifiedAccount = mode === "unified" || mode === "portfolio";
+            }
+            catch {
+                // If userAbstraction lookup fails, retain conservative default
+                // (false). getBalance() will surface the underlying error when called.
+            }
+        }
     }
     /** Load asset index map — supports native and HIP-3 dex. */
     async _loadAssetMap() {

package/dist/mcp-server.js

@@ -15,6 +15,7 @@ import { tryLoadPrivateKey, parseSolanaKeypair } from "./config.js";
 import { PacificaAdapter } from "./exchanges/pacifica.js";
 import { HyperliquidAdapter } from "./exchanges/hyperliquid.js";
 import { LighterAdapter } from "./exchanges/lighter.js";
+import { AsterAdapter } from "./exchanges/aster.js";
 import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, pingPacifica, pingHyperliquid, pingLighter, } from "./shared-api.js";
 import { fetchAllFundingRates } from "./funding-rates.js";
 import { loadArbState } from "./arb/state.js";
@@ -47,8 +48,14 @@ async function getOrCreateAdapter(exchange) {
             adapter = lt;
             break;
         }
+        case "aster": {
+            const ast = new AsterAdapter(pk);
+            await ast.init();
+            adapter = ast;
+            break;
+        }
         default:
-            throw new Error(`Unknown exchange: ${exchange}. Supported: pacifica, hyperliquid, lighter`);
+            throw new Error(`Unknown exchange: ${exchange}. Supported: pacifica, hyperliquid, lighter, aster`);
     }
     adapters.set(key, adapter);
     return adapter;
@@ -80,7 +87,14 @@ async function fetchMarketsPublic(exchange) {
         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`);
+    else if (ex === "aster" || ex === "ast") {
+        // Aster has no shared-api helper; AsterAdapter.getMarkets() uses
+        // public-only endpoints (exchangeInfo + ticker/24hr + premiumIndex).
+        const ast = new AsterAdapter();
+        await ast.init();
+        return ast.getMarkets();
+    }
+    throw new Error(`Unknown exchange: ${exchange}. Supported: pacifica, hyperliquid, lighter, aster`);
 }
 /** Fetch orderbook using public API (no key needed) */
 async function fetchOrderbookPublic(exchange, symbol) {
@@ -116,6 +130,12 @@ async function fetchOrderbookPublic(exchange, symbol) {
             asks: (data.l?.[1] ?? []).map(e => [e.p, e.a]),
         };
     }
+    else if (ex === "aster" || ex === "ast") {
+        // AsterAdapter.getOrderbook() uses /fapi/v1/depth (public).
+        const ast = new AsterAdapter();
+        await ast.init();
+        return ast.getOrderbook(symbol);
+    }
     throw new Error(`Unknown exchange: ${exchange}`);
 }
 // ── JSON envelope helpers ──
@@ -132,7 +152,7 @@ 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. Works without API keys.", { 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, lighter, or aster") }, async ({ exchange }) => {
     try {
         // Try adapter first (richer data), fall back to public API (no key needed)
         const adapter = await tryGetAdapter(exchange);
@@ -148,7 +168,7 @@ server.tool("get_markets", "Get all available perpetual futures markets on an ex
     }
 });
 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"),
+    exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster"),
     symbol: z.string().describe("Trading pair symbol, e.g. BTC, ETH, SOL"),
 }, async ({ exchange, symbol }) => {
     try {
@@ -165,7 +185,7 @@ server.tool("get_orderbook", "Get the order book (bids and asks) for a symbol on
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange, symbol }) }], isError: true };
     }
 });
-server.tool("get_funding_rates", "Compare funding rates across all 3 exchanges (Pacifica, Hyperliquid, Lighter). Returns rates per symbol with spread analysis", {
+server.tool("get_funding_rates", "Compare funding rates across all 4 exchanges (Pacifica, Hyperliquid, Lighter, Aster). Returns rates per symbol with spread analysis", {
     symbols: z
         .array(z.string())
         .optional()
@@ -185,17 +205,24 @@ server.tool("get_funding_rates", "Compare funding rates across all 3 exchanges (
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
     }
 });
-server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark prices from all 3 exchanges for comparison", {
+server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark prices from all 4 exchanges for comparison", {
     symbols: z
         .array(z.string())
         .optional()
         .describe("Symbols to fetch prices for (e.g. ['BTC','ETH']). Omit for top assets"),
 }, async ({ symbols }) => {
     try {
-        const [pacifica, hl, lighter] = await Promise.all([
+        // Aster has no shared-api helper; use AsterAdapter.getMarkets() (public).
+        const asterMarkets = (async () => {
+            const ast = new AsterAdapter();
+            await ast.init();
+            return ast.getMarkets();
+        })();
+        const [pacifica, hl, lighter, aster] = await Promise.all([
             fetchPacificaPrices(),
             fetchHyperliquidMeta(),
             fetchLighterOrderBookDetails(),
+            asterMarkets,
         ]);
         const filter = symbols ? new Set(symbols.map(s => s.toUpperCase())) : null;
         // Build symbol → exchange prices map
@@ -224,6 +251,14 @@ server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark p
                 priceMap.set(sym, {});
             priceMap.get(sym).lighter = m.lastTradePrice;
         }
+        for (const a of aster) {
+            const sym = a.symbol.toUpperCase();
+            if (filter && !filter.has(sym))
+                continue;
+            if (!priceMap.has(sym))
+                priceMap.set(sym, {});
+            priceMap.get(sym).aster = Number(a.markPrice);
+        }
         const data = Array.from(priceMap.entries()).map(([symbol, prices]) => ({ symbol, prices }));
         return { content: [{ type: "text", text: ok(data, { count: data.length }) }] };
     }
@@ -234,7 +269,7 @@ server.tool("get_prices", "Get cross-exchange prices for symbols. Fetches mark p
 // ============================================================
 // Account tools (need private key)
 // ============================================================
-server.tool("get_balance", "Get account balance (equity, available margin, margin used, unrealized PnL) on an exchange", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, or lighter") }, async ({ exchange }) => {
+server.tool("get_balance", "Get account balance (equity, available margin, margin used, unrealized PnL) on an exchange", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster") }, async ({ exchange }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
         const balance = await adapter.getBalance();
@@ -244,7 +279,7 @@ server.tool("get_balance", "Get account balance (equity, available margin, margi
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
     }
 });
-server.tool("get_positions", "Get all open positions on an exchange, including size, entry price, PnL, leverage", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, or lighter") }, async ({ exchange }) => {
+server.tool("get_positions", "Get all open positions on an exchange, including size, entry price, PnL, leverage", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster") }, async ({ exchange }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
         const positions = await adapter.getPositions();
@@ -254,7 +289,7 @@ server.tool("get_positions", "Get all open positions on an exchange, including s
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
     }
 });
-server.tool("get_open_orders", "Get all open/pending orders on an exchange", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, or lighter") }, async ({ exchange }) => {
+server.tool("get_open_orders", "Get all open/pending orders on an exchange", { exchange: z.string().describe("Exchange name: pacifica, hyperliquid, lighter, or aster") }, async ({ exchange }) => {
     try {
         const adapter = await getOrCreateAdapter(exchange);
         const orders = await adapter.getOpenOrders();
@@ -264,8 +299,8 @@ server.tool("get_open_orders", "Get all open/pending orders on an exchange", { e
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e), { exchange }) }], isError: true };
     }
 });
-server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions, and risk metrics across all exchanges", {}, async () => {
-    const EXCHANGES = ["pacifica", "hyperliquid", "lighter"];
+server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions, and risk metrics across all 4 exchanges", {}, async () => {
+    const EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
     const snapshots = await Promise.all(EXCHANGES.map(async (name) => {
         try {
             const adapter = await getOrCreateAdapter(name);
@@ -340,7 +375,7 @@ server.tool("portfolio", "Cross-exchange portfolio summary: balances, positions,
 // ============================================================
 server.tool("suggest_command", "Given a natural language trading goal, suggest the exact perp CLI commands to run. Does NOT execute anything — only returns commands for the user to review and run manually", {
     goal: z.string().describe("Natural language goal, e.g. 'buy 0.1 BTC on pacifica', 'close all positions', 'check funding arb opportunities'"),
-    exchange: z.string().optional().describe("Preferred exchange (default: pacifica). Options: pacifica, hyperliquid, lighter"),
+    exchange: z.string().optional().describe("Preferred exchange (default: pacifica). Options: pacifica, hyperliquid, lighter, aster"),
 }, async ({ goal, exchange }) => {
     try {
         const ex = exchange ?? "pacifica";
@@ -349,18 +384,18 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         if (g.includes("buy") || g.includes("long")) {
             const symbol = extractSymbol(g) || "BTC";
             const size = extractNumber(g) || "<size>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json account balance`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} buy ${size}`, description: "Pre-flight validation (dry run)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} buy ${size}`, description: `Buy ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} buy ${size}`, description: "Pre-flight validation (dry run)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} buy ${size}`, description: `Buy ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
         }
         else if (g.includes("sell") || g.includes("short")) {
             const symbol = extractSymbol(g) || "BTC";
             const size = extractNumber(g) || "<size>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json account balance`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} sell ${size}`, description: "Pre-flight validation (dry run)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} sell ${size}`, description: `Sell ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook and liquidity` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance and margin" }, { step: 3, command: `perp -e ${ex} --json trade check ${symbol} sell ${size}`, description: "Pre-flight validation (dry run)" }, { step: 4, command: `perp -e ${ex} --json trade market ${symbol} sell ${size}`, description: `Sell ${size} ${symbol} at market`, dangerous: true }, { step: 5, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
         }
         else if (g.includes("limit")) {
             const symbol = extractSymbol(g) || "BTC";
             const size = extractNumber(g) || "<size>";
             const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
-            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook for price levels` }, { step: 2, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 3, command: `perp -e ${ex} --json trade limit ${symbol} ${side} <price> ${size}`, description: `Place limit ${side} order`, dangerous: true }, { step: 4, command: `perp -e ${ex} --json account orders`, description: "Verify order placed" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook for price levels` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" }, { step: 3, command: `perp -e ${ex} --json trade limit ${symbol} ${side} <price> ${size}`, description: `Place limit ${side} order`, dangerous: true }, { step: 4, command: `perp -e ${ex} --json account orders`, description: "Verify order placed" });
         }
         else if (g.includes("close") || g.includes("exit") || g.includes("flatten")) {
             const symbol = extractSymbol(g);
@@ -382,7 +417,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         else if (g.includes("scale-in") || g.includes("scale in") || g.includes("dca in")) {
             const symbol = extractSymbol(g) || "<symbol>";
             const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
-            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: "Check current prices" }, { step: 2, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 3, command: `perp -e ${ex} --json trade scale-in ${symbol} ${side} --levels '<price1>:<size>,<price2>:<size>'`, description: "Place scaled entry orders at multiple levels", dangerous: true });
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: "Check current prices" }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" }, { step: 3, command: `perp -e ${ex} --json trade scale-in ${symbol} ${side} --levels '<price1>:<size>,<price2>:<size>'`, description: "Place scaled entry orders at multiple levels", dangerous: true });
         }
         else if (g.includes("tpsl") || g.includes("tp/sl") || g.includes("tp sl") || (g.includes("take profit") && g.includes("stop loss"))) {
             const symbol = extractSymbol(g) || "<symbol>";
@@ -401,13 +436,13 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             const symbol = extractSymbol(g) || "<symbol>";
             const amount = extractNumber(g) || "<usd>";
             const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
-            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook depth` }, { step: 2, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 3, command: `perp -e ${ex} --json trade split ${symbol} ${side} ${amount}`, description: `Split ${side} $${amount} ${symbol} into depth-based slices`, dangerous: true }, { step: 4, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json market book ${symbol}`, description: `Check ${symbol} orderbook depth` }, { step: 2, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" }, { step: 3, command: `perp -e ${ex} --json trade split ${symbol} ${side} ${amount}`, description: `Split ${side} $${amount} ${symbol} into depth-based slices`, dangerous: true }, { step: 4, command: `perp -e ${ex} --json account positions`, description: "Verify position opened" });
         }
         else if (g.includes("twap")) {
             const symbol = extractSymbol(g) || "<symbol>";
             const size = extractNumber(g) || "<size>";
             const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
-            steps.push({ step: 1, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 2, command: `perp -e ${ex} --json trade twap ${symbol} ${side} ${size} <duration>`, description: `TWAP ${side} ${size} ${symbol} over duration`, dangerous: true });
+            steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" }, { step: 2, command: `perp -e ${ex} --json trade twap ${symbol} ${side} ${size} <duration>`, description: `TWAP ${side} ${size} ${symbol} over duration`, dangerous: true });
         }
         else if (g.includes("reduce")) {
             const symbol = extractSymbol(g) || "<symbol>";
@@ -441,7 +476,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             else if (g.includes("dca")) {
                 const amount = extractNumber(g) || "<amount>";
                 const side = g.includes("sell") || g.includes("short") ? "sell" : "buy";
-                steps.push({ step: 1, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 2, command: `perp -e ${ex} --json strategy quick-dca ${symbol} ${side} ${amount} <interval>`, description: "Start DCA bot", dangerous: true }, { step: 3, command: "perp --json background list", description: "Verify bot is running" });
+                steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" }, { step: 2, command: `perp -e ${ex} --json strategy quick-dca ${symbol} ${side} ${amount} <interval>`, description: "Start DCA bot", dangerous: true }, { step: 3, command: "perp --json background list", description: "Verify bot is running" });
             }
             else {
                 steps.push({ step: 1, command: "perp --json strategy preset-list", description: "List available bot presets" }, { step: 2, command: `perp -e ${ex} --json strategy quick-arb`, description: "Start arb bot", dangerous: true }, { step: 3, command: "perp --json background list", description: "Verify bot is running" });
@@ -495,15 +530,15 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: "perp strategy plan example", description: "Show example execution plan format" }, { step: 2, command: "perp --json strategy plan validate <file>", description: "Validate plan file" }, { step: 3, command: "perp --json strategy plan execute <file> --dry-run", description: "Dry-run the plan", dangerous: true });
         }
         else if (g.includes("status") || g.includes("check") || g.includes("overview") || g.includes("portfolio")) {
-            steps.push({ step: 1, command: `perp -e ${ex} --json status`, description: "Full account overview" }, { step: 2, command: `perp -e ${ex} --json account positions`, description: "Detailed positions" }, { step: 3, command: `perp -e ${ex} --json account orders`, description: "Open orders" }, { step: 4, command: "perp --json portfolio", description: "Cross-exchange portfolio summary" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Single-exchange portfolio overview" }, { step: 2, command: `perp -e ${ex} --json account positions`, description: "Detailed positions" }, { step: 3, command: `perp -e ${ex} --json account orders`, description: "Open orders" }, { step: 4, command: "perp --json portfolio --arb", description: "Cross-exchange portfolio + top arb opportunities" });
         }
         else if (g.includes("deposit")) {
             const amount = extractNumber(g) || "<amount>";
-            steps.push({ step: 1, command: "perp --json wallet balance", description: "Check wallet balance" }, { step: 2, command: `perp --json funds deposit ${ex} ${amount}`, description: `Deposit $${amount} to ${ex}`, dangerous: true }, { step: 3, command: `perp -e ${ex} --json account balance`, description: "Verify deposit arrived" });
+            steps.push({ step: 1, command: "perp --json wallet balance", description: "Check wallet balance" }, { step: 2, command: `perp --json funds deposit ${ex} ${amount}`, description: `Deposit $${amount} to ${ex}`, dangerous: true }, { step: 3, command: `perp -e ${ex} --json portfolio`, description: "Verify deposit arrived" });
         }
         else if (g.includes("withdraw")) {
             const amount = extractNumber(g) || "<amount>";
-            steps.push({ step: 1, command: `perp -e ${ex} --json account balance`, description: "Check available balance" }, { step: 2, command: `perp --json funds withdraw ${ex} ${amount}`, description: `Withdraw $${amount} from ${ex}`, dangerous: true }, { step: 3, command: "perp --json wallet balance", description: "Verify withdrawal received" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Check available balance" }, { step: 2, command: `perp --json funds withdraw ${ex} ${amount}`, description: `Withdraw $${amount} from ${ex}`, dangerous: true }, { step: 3, command: "perp --json wallet balance", description: "Verify withdrawal received" });
         }
         else if (g.includes("leverage")) {
             const symbol = extractSymbol(g) || "<symbol>";
@@ -532,7 +567,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
             steps.push({ step: 1, command: "perp settings show", description: "Show current settings" }, { step: 2, command: "perp settings referrals on", description: "Enable referral codes (no extra fees, just volume tracking)" });
         }
         else {
-            steps.push({ step: 1, command: `perp -e ${ex} --json status`, description: "Check account status" }, { step: 2, command: `perp -e ${ex} --json account balance`, description: "Check exchange connectivity via balance fetch" });
+            steps.push({ step: 1, command: `perp -e ${ex} --json portfolio`, description: "Check account overview" }, { step: 2, command: `perp --json portfolio --health --exchanges ${ex}`, description: "Check exchange connectivity" });
         }
         return {
             content: [{
@@ -981,18 +1016,31 @@ server.tool("arb_scan", "Scan for funding rate arbitrage opportunities across ex
         return { content: [{ type: "text", text: err(e instanceof Error ? e.message : String(e)) }], isError: true };
     }
 });
-server.tool("health_check", "Ping all exchanges and return connectivity status and latency", {}, async () => {
+server.tool("health_check", "Ping all 4 exchanges and return connectivity status and latency", {}, async () => {
     try {
-        const [pacifica, hyperliquid, lighter] = await Promise.all([
+        // Aster has no shared-api ping helper; ping /fapi/v1/time directly.
+        const pingAster = async () => {
+            const start = Date.now();
+            try {
+                const res = await fetch("https://fapi.asterdex.com/fapi/v1/time");
+                return { ok: res.ok, latencyMs: Date.now() - start, status: res.status };
+            }
+            catch {
+                return { ok: false, latencyMs: Date.now() - start, status: 0 };
+            }
+        };
+        const [pacifica, hyperliquid, lighter, aster] = await Promise.all([
             pingPacifica(),
             pingHyperliquid(),
             pingLighter(),
+            pingAster(),
         ]);
         const result = {
             pacifica: { ...pacifica, statusText: pacifica.ok ? "healthy" : "unreachable" },
             hyperliquid: { ...hyperliquid, statusText: hyperliquid.ok ? "healthy" : "unreachable" },
             lighter: { ...lighter, statusText: lighter.ok ? "healthy" : "unreachable" },
-            allHealthy: pacifica.ok && hyperliquid.ok && lighter.ok,
+            aster: { ...aster, statusText: aster.ok ? "healthy" : "unreachable" },
+            allHealthy: pacifica.ok && hyperliquid.ok && lighter.ok && aster.ok,
         };
         return { content: [{ type: "text", text: ok(result) }] };
     }
@@ -1007,10 +1055,10 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
     const schema = {
         schemaVersion: "2.0",
         name: "perp",
-        description: "Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter)",
-        exchanges: ["pacifica", "hyperliquid", "lighter"],
+        description: "Multi-DEX Perpetual Futures CLI (Pacifica, Hyperliquid, Lighter, Aster)",
+        exchanges: ["pacifica", "hyperliquid", "lighter", "aster"],
         globalFlags: [
-            { flag: "-e, --exchange <name>", description: "Exchange to use (pacifica, hyperliquid, lighter)", default: "pacifica" },
+            { flag: "-e, --exchange <name>", description: "Exchange to use (pacifica, hyperliquid, lighter, aster)", default: "pacifica" },
             { flag: "--json", description: "Output as JSON for structured parsing" },
             { flag: "-n, --network <net>", description: "Network: mainnet or testnet", default: "mainnet" },
             { flag: "--dry-run", description: "Simulate without executing (for trade commands)" },
@@ -1032,7 +1080,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             account: {
                 description: "Account data (read-only)",
                 subcommands: {
-                    info: { usage: "perp account balance", description: "Balance, equity, margin, PnL" },
+                    info: { usage: "perp portfolio -e <exchange>", description: "Single-exchange balance, equity, margin, PnL" },
                     positions: { usage: "perp account positions", description: "Open positions" },
                     orders: { usage: "perp account orders", description: "Open/pending orders" },
                     history: { usage: "perp account history", description: "Order history" },
@@ -1192,7 +1240,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
             },
             portfolio: { usage: "perp portfolio", description: "Cross-exchange portfolio summary" },
             status: { usage: "perp portfolio", description: "Full account overview" },
-            health: { usage: "perp account balance --json", description: "Exchange connectivity check via balance fetch" },
+            health: { usage: "perp portfolio --health", description: "Exchange connectivity check" },
             settings: {
                 description: "CLI settings",
                 subcommands: {
@@ -1216,7 +1264,7 @@ server.resource("cli_schema", "perp://schema", { mimeType: "application/json", d
 // Trade execution tools (dry-run + confirm safety model)
 // ============================================================
 server.tool("trade_preview", "Preview a trade WITHOUT executing. Returns estimated fill price, fees, margin impact, and risk checks. ALWAYS call this before trade_execute and show the result to the user for confirmation.", {
-    exchange: z.string().describe("Exchange: pacifica, hyperliquid, or lighter"),
+    exchange: z.string().describe("Exchange: pacifica, hyperliquid, lighter, or aster"),
     symbol: z.string().describe("Trading symbol (e.g., BTC, ETH, SOL)"),
     side: z.enum(["buy", "sell"]).describe("Order side"),
     size: z.string().describe("Order size (base currency units, e.g., '0.1' for 0.1 BTC)"),
@@ -1293,7 +1341,7 @@ server.tool("trade_preview", "Preview a trade WITHOUT executing. Returns estimat
     }
 });
 server.tool("trade_execute", "Execute a trade. IMPORTANT: Always call trade_preview first and get explicit user confirmation before calling this tool. Supports market and limit orders.", {
-    exchange: z.string().describe("Exchange: pacifica, hyperliquid, or lighter"),
+    exchange: z.string().describe("Exchange: pacifica, hyperliquid, lighter, or aster"),
     symbol: z.string().describe("Trading symbol (e.g., BTC, ETH, SOL)"),
     side: z.enum(["buy", "sell"]).describe("Order side"),
     size: z.string().describe("Order size (base currency units)"),
@@ -1332,7 +1380,7 @@ server.tool("trade_execute", "Execute a trade. IMPORTANT: Always call trade_prev
     }
 });
 server.tool("trade_close", "Close an existing position. IMPORTANT: Call trade_preview first with the opposite side to show impact, then get user confirmation.", {
-    exchange: z.string().describe("Exchange: pacifica, hyperliquid, or lighter"),
+    exchange: z.string().describe("Exchange: pacifica, hyperliquid, lighter, or aster"),
     symbol: z.string().describe("Symbol to close (e.g., BTC, ETH)"),
 }, async ({ exchange, symbol }) => {
     try {
@@ -1370,7 +1418,7 @@ server.tool("get_funding_analysis", "Analyze funding income across exchanges —
     symbol: z.string().optional().describe("Filter by symbol"),
 }, async ({ period, exchange: exFilter, symbol: symFilter }) => {
     try {
-        const exchanges = exFilter ? [exFilter] : ["pacifica", "hyperliquid", "lighter"];
+        const exchanges = exFilter ? [exFilter] : ["pacifica", "hyperliquid", "lighter", "aster"];
         const periodMatch = period.match(/^(\d+)(d|w|m)$/);
         const sinceMs = periodMatch
             ? Date.now() - parseInt(periodMatch[1]) * ({ d: 86400000, w: 604800000, m: 2592000000 }[periodMatch[2]] ?? 86400000)
@@ -1440,7 +1488,7 @@ server.tool("get_pnl_analysis", "P&L analysis combining trading fees and funding
     exchange: z.string().optional().describe("Filter by exchange"),
 }, async ({ period, exchange: exFilter }) => {
     try {
-        const exchanges = exFilter ? [exFilter] : ["pacifica", "hyperliquid", "lighter"];
+        const exchanges = exFilter ? [exFilter] : ["pacifica", "hyperliquid", "lighter", "aster"];
         const periodMatch = period.match(/^(\d+)(d|w|m)$/);
         const sinceMs = periodMatch
             ? Date.now() - parseInt(periodMatch[1]) * ({ d: 86400000, w: 604800000, m: 2592000000 }[periodMatch[2]] ?? 86400000)
@@ -1554,7 +1602,7 @@ server.tool("get_arb_compare", "Compare active arbitrage positions side by side
 // ============================================================
 server.resource("market_prices", "market://prices", { mimeType: "application/json", description: "Live cross-exchange prices for all perpetual futures markets" }, async () => {
     const prices = {};
-    await Promise.allSettled(["pacifica", "hyperliquid", "lighter"].map(async (ex) => {
+    await Promise.allSettled(["pacifica", "hyperliquid", "lighter", "aster"].map(async (ex) => {
         try {
             const adapter = await getOrCreateAdapter(ex);
             const markets = await adapter.getMarkets();
@@ -1621,7 +1669,8 @@ server.prompt("trading-guide", "Step-by-step guide for trading with perp-cli via
 ## Supported Exchanges
 - **pacifica** (Solana) — SOL-based perpetual futures
 - **hyperliquid** (HyperEVM) — Low-fee perpetuals with HIP-3 DEXes
-- **lighter** (Ethereum) — Ethereum-based perpetual futures`,
+- **lighter** (Ethereum) — Ethereum-based perpetual futures
+- **aster** (BNB Chain) — BNB Chain perpetual futures`,
             },
         }],
 }));

package/dist/trade-validator.js

@@ -10,21 +10,20 @@ export async function validateTrade(adapter, params) {
     const checks = [];
     const warnings = [];
     const sym = params.symbol.toUpperCase();
-    // Fetch market data, balance, positions, orderbook in parallel.
+    // Fetch market list, balance, and positions in parallel.
+    // Defer the orderbook call until symbol membership is confirmed so invalid
+    // symbols return a structured symbol_valid failure instead of a venue error.
     // SSOT rule #2: errors must propagate, never silently substitute defaults.
     // getMarkets retains a tracked-error wrapper so the failed-load case surfaces
     // a structured symbol_valid check (not a generic exception).
     let marketsError = null;
-    const [markets, balance, positions, orderbook] = await Promise.all([
+    const [markets, balance, positions] = await Promise.all([
         adapter.getMarkets().catch((e) => {
             marketsError = e instanceof Error ? e.message : String(e);
             return [];
         }),
         adapter.getBalance(),
         adapter.getPositions(),
-        params.type !== "limit"
-            ? adapter.getOrderbook(sym)
-            : Promise.resolve({ bids: [], asks: [] }),
     ]);
     if (markets.length === 0 && marketsError) {
         checks.push({ check: "symbol_valid", passed: false, message: `Failed to load markets from ${adapter.name}: ${marketsError}` });
@@ -42,6 +41,9 @@ export async function validateTrade(adapter, params) {
         checks.push({ check: "symbol_valid", passed: false, message: `${sym} not found on ${adapter.name}` });
         return { valid: false, checks, warnings, timestamp: new Date().toISOString() };
     }
+    const orderbook = params.type !== "limit"
+        ? await adapter.getOrderbook(sym)
+        : { bids: [], asks: [] };
     const markPrice = Number(market.markPrice);
     if (params.type === "limit" && (params.price === undefined || !Number.isFinite(params.price))) {
         throw new Error(`Limit order requires explicit price (received ${params.price}); refusing silent mark-price substitution.`);

package/dist/utils.d.ts

@@ -17,6 +17,8 @@ export interface ApiResponse<T = unknown> {
         status?: number;
         retryable?: boolean;
         retryAfterMs?: number;
+        /** Actionable hint for automated callers (Codex v0.12.12 final QA #2). */
+        remediation?: string;
         details?: Record<string, unknown>;
     };
     meta?: {
@@ -33,9 +35,15 @@ export declare function jsonError(code: string, message: string, meta?: Partial<
     retryable?: boolean;
     retryAfterMs?: number;
     details?: Record<string, unknown>;
+    remediation?: string;
 }): ApiResponse<never>;
 /** Execute a command action with structured error handling.
  *  In JSON mode, errors are returned as JSON instead of crashing.
+ *
+ *  PerpError-typed throws are preserved end-to-end: their `code`,
+ *  `remediation`, and other StructuredError fields surface in the JSON
+ *  envelope's `error` block so machine consumers (agents / MCP / automation)
+ *  receive actionable hints. Codex v0.12.12 final QA #2.
  */
 export declare function withJsonErrors<T>(isJson: boolean, fn: () => Promise<T>, exchange?: string): Promise<T | undefined>;
 /**

package/dist/utils.js

@@ -194,6 +194,7 @@ export function jsonError(code, message, meta) {
             ...(meta?.status !== undefined ? { status: meta.status } : {}),
             ...(meta?.retryable !== undefined ? { retryable: meta.retryable } : {}),
             ...(meta?.retryAfterMs !== undefined ? { retryAfterMs: meta.retryAfterMs } : {}),
+            ...(meta?.remediation !== undefined ? { remediation: meta.remediation } : {}),
             ...(meta?.details ? { details: meta.details } : {}),
         },
         meta: { timestamp: new Date().toISOString(), ...meta },
@@ -201,6 +202,11 @@ export function jsonError(code, message, meta) {
 }
 /** Execute a command action with structured error handling.
  *  In JSON mode, errors are returned as JSON instead of crashing.
+ *
+ *  PerpError-typed throws are preserved end-to-end: their `code`,
+ *  `remediation`, and other StructuredError fields surface in the JSON
+ *  envelope's `error` block so machine consumers (agents / MCP / automation)
+ *  receive actionable hints. Codex v0.12.12 final QA #2.
  */
 export async function withJsonErrors(isJson, fn, exchange) {
     try {
@@ -213,10 +219,15 @@ export async function withJsonErrors(isJson, fn, exchange) {
                 status: classified.status,
                 retryable: classified.retryable,
                 retryAfterMs: classified.retryAfterMs,
+                remediation: classified.remediation,
+                details: classified.details,
             })));
         }
         else {
             console.error(chalk.red(`Error: ${classified.message}`));
+            if (classified.remediation) {
+                console.error(chalk.yellow(`Remediation: ${classified.remediation}`));
+            }
         }
         return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perp-cli",
-  "version": "0.12.12",
+  "version": "0.12.14",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster",
   "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.12.12"
+  version: "0.12.14"
 ---
 
 # perp-cli Agent Guide
@@ -41,7 +41,7 @@ Multi-DEX perpetual futures CLI + MCP server — Pacifica (Solana), Hyperliquid
 ## Install
 
 ```bash
-perp --version 2>/dev/null  # check if exists (must be >= 0.12.12)
+perp --version 2>/dev/null  # check if exists (must be >= 0.12.14)
 npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
 ```