perp-cli 0.12.11 → 0.12.13

package/dist/commands/alerts.js

@@ -271,7 +271,7 @@ export function registerAlertCommands(program, isJson) {
             // Pass through env vars for keys
             // L2 agent key + indices now live in ~/.perp keystore + settings.agents (SSOT Rule #3),
             // not env. Only Tier 3 master PKs need passthrough.
-            const envKeys = ["LIGHTER_PRIVATE_KEY", "HL_PRIVATE_KEY", "PACIFICA_PRIVATE_KEY", "PRIVATE_KEY"];
+            const envKeys = ["LIGHTER_PRIVATE_KEY", "HL_PRIVATE_KEY", "PACIFICA_PRIVATE_KEY", "ASTER_PRIVATE_KEY", "PRIVATE_KEY"];
             const envStr = envKeys.filter(k => process.env[k]).map(k => `${k}='${process.env[k]}'`).join(" ");
             const cmd = `${envStr} ${nodeCmd} ${cliPath} ${args}`;
             execSync(`tmux new-session -d -s ${session} '${cmd.replace(/'/g, "'\\''")}'`);

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

@@ -1,10 +1,17 @@
 /**
- * Aster DEX adapter — EIP-712 three-tier signer routing (v3.2).
+ * Aster DEX adapter — EIP-712 agent-only signer routing (v3.3).
  *
- * Signer priority:
- *   Tier 1 — Agent OWS wallet  (registered + not expired + no --no-agent)
- *   Tier 2 — OWS master wallet (--ows / owsActiveWallet)
- *   Tier 3 — PK direct         (--private-key / PRIVATE_KEY / ASTER_PRIVATE_KEY)
+ * Signer policy:
+ *   Tier 1 — Agent OWS wallet  (registered + not expired + no --no-agent) — REQUIRED
+ *   Tier 2 — OWS master        — NOT_SUPPORTED (venue rejects master self-signing)
+ *   Tier 3 — PK direct         — NOT_SUPPORTED (venue rejects master self-signing)
+ *
+ * Aster V3 spec requires `signer` to be a registered API_WALLET (agent). The
+ * master wallet is never a valid signer — venue returns
+ * `code:-1000 msg:"Signature check failed"` when user==signer==master, even
+ * though the EIP-712 envelope is well-formed. Master/PK signers are still
+ * accepted via setMasterSigner/setPkSigner (used during approveAgent flow),
+ * but signed read/trade requests must use Tier 1.
  *
  * HMAC paths fully removed (see Step 3 plan — all Binance-compat HMAC code deleted).
  *
@@ -116,9 +123,9 @@ export declare class AsterAdapter implements ExchangeAdapter {
      * signed dict and the URL query string must be byte-identical except for
      * the appended signature.
      *
-     * Both `user` and `signer` are ALWAYS emitted as distinct query fields,
-     * even when the values are identical (Tier 2/3 self-signing case where
-     * master signs for itself). Aster's authority server checks both fields.
+     * Both `user` and `signer` are ALWAYS emitted as distinct query fields.
+     * In production (Tier 1 only), `user` is the master and `signer` is the
+     * registered agent address. Aster's authority server checks both fields.
      *
      * `signatureChainId` is NOT a v3 parameter — it's an artifact of an older
      * scheme; including it breaks signature verification on every call.
@@ -137,12 +144,24 @@ export declare class AsterAdapter implements ExchangeAdapter {
      * Unlike public GETs, signed GETs route through _handleAsterResponse so
      * venue JSON error envelopes ({code, msg}) are not silently treated as
      * success (SSOT Rule #2).
+     *
+     * Retries up to 3 attempts with exponential backoff (2s/4s/8s) on HTTP 429
+     * rate-limit. Each retry rebuilds a fresh signed query string (new nonce
+     * + signature) — Aster reuses recent nonces strictly, so reusing a stale
+     * one would itself be rejected. Non-429 venue errors throw immediately.
      */
     private _signedGetEip712;
     /**
      * Sign and DELETE from a path using EIP-712 Domain B.
+     * Same retry behavior as _signedGetEip712.
      */
     private _signedDeleteEip712;
+    /** 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

@@ -1,10 +1,17 @@
 /**
- * Aster DEX adapter — EIP-712 three-tier signer routing (v3.2).
+ * Aster DEX adapter — EIP-712 agent-only signer routing (v3.3).
  *
- * Signer priority:
- *   Tier 1 — Agent OWS wallet  (registered + not expired + no --no-agent)
- *   Tier 2 — OWS master wallet (--ows / owsActiveWallet)
- *   Tier 3 — PK direct         (--private-key / PRIVATE_KEY / ASTER_PRIVATE_KEY)
+ * Signer policy:
+ *   Tier 1 — Agent OWS wallet  (registered + not expired + no --no-agent) — REQUIRED
+ *   Tier 2 — OWS master        — NOT_SUPPORTED (venue rejects master self-signing)
+ *   Tier 3 — PK direct         — NOT_SUPPORTED (venue rejects master self-signing)
+ *
+ * Aster V3 spec requires `signer` to be a registered API_WALLET (agent). The
+ * master wallet is never a valid signer — venue returns
+ * `code:-1000 msg:"Signature check failed"` when user==signer==master, even
+ * though the EIP-712 envelope is well-formed. Master/PK signers are still
+ * accepted via setMasterSigner/setPkSigner (used during approveAgent flow),
+ * but signed read/trade requests must use Tier 1.
  *
  * HMAC paths fully removed (see Step 3 plan — all Binance-compat HMAC code deleted).
  *
@@ -528,18 +535,19 @@ export class AsterAdapter {
                 };
             }
         }
-        // Tier 2: OWS master — master self-signs, so user==signer per V3 spec.
-        // The query string MUST still emit `user=` AND `signer=` as distinct
-        // fields even when the values are identical (Aster authority verifies
-        // both keys); see _buildSignedQueryString.
-        if (this._masterSigner) {
-            const addr = this._masterSigner.getAddress();
-            return { tier: "master", signer: this._masterSigner, signerAddress: addr, userAddress: addr };
-        }
-        // Tier 3: PK direct — same self-signing model as Tier 2.
-        if (this._pkSigner) {
-            const addr = this._pkSigner.getAddress();
-            return { tier: "pk", signer: this._pkSigner, signerAddress: addr, userAddress: addr };
+        // Tier 2/3: master self-signing is not supported by the venue. Per Aster
+        // V3 spec the `signer` field MUST be a registered API_WALLET (agent);
+        // sending `user==signer==master` is rejected with
+        // `code:-1000 msg:"Signature check failed"` even though the EIP-712
+        // envelope is well-formed. SSOT Rule #2: throw with remediation rather
+        // than silently dispatching a request the venue will reject.
+        //
+        // Reference: HypurrQuant_FE AsterPerpAdapter.ts throws if agent isn't
+        // configured; never attempts master self-signing.
+        if (this._masterSigner || this._pkSigner) {
+            throw new PerpError("NOT_IMPLEMENTED", "Aster requires a registered agent — master self-signing is not supported by venue", {
+                remediation: "perp wallet agent approve aster --master <wallet>",
+            });
         }
         // No signer at any tier
         throw new PerpError("NO_SIGNER_AVAILABLE", "No signing path configured for Aster", {
@@ -564,9 +572,9 @@ export class AsterAdapter {
      * signed dict and the URL query string must be byte-identical except for
      * the appended signature.
      *
-     * Both `user` and `signer` are ALWAYS emitted as distinct query fields,
-     * even when the values are identical (Tier 2/3 self-signing case where
-     * master signs for itself). Aster's authority server checks both fields.
+     * Both `user` and `signer` are ALWAYS emitted as distinct query fields.
+     * In production (Tier 1 only), `user` is the master and `signer` is the
+     * registered agent address. Aster's authority server checks both fields.
      *
      * `signatureChainId` is NOT a v3 parameter — it's an artifact of an older
      * scheme; including it breaks signature verification on every call.
@@ -610,21 +618,57 @@ export class AsterAdapter {
      * Unlike public GETs, signed GETs route through _handleAsterResponse so
      * venue JSON error envelopes ({code, msg}) are not silently treated as
      * success (SSOT Rule #2).
+     *
+     * Retries up to 3 attempts with exponential backoff (2s/4s/8s) on HTTP 429
+     * rate-limit. Each retry rebuilds a fresh signed query string (new nonce
+     * + signature) — Aster reuses recent nonces strictly, so reusing a stale
+     * one would itself be rejected. Non-429 venue errors throw immediately.
      */
     async _signedGetEip712(path, params, resolved) {
-        const qs = await this._buildSignedQueryString(params, resolved);
-        const url = `${this._baseUrl}${path}?${qs}`;
-        const res = await fetch(url);
-        return this._handleAsterResponse(res, "GET", path);
+        return this._signedRequestWithRetry("GET", path, params, resolved);
     }
     /**
      * Sign and DELETE from a path using EIP-712 Domain B.
+     * Same retry behavior as _signedGetEip712.
      */
     async _signedDeleteEip712(path, params, resolved) {
-        const qs = await this._buildSignedQueryString(params, resolved);
-        const url = `${this._baseUrl}${path}?${qs}`;
-        const res = await fetch(url, { method: "DELETE" });
-        return this._handleAsterResponse(res, "DELETE", path);
+        return this._signedRequestWithRetry("DELETE", path, params, resolved);
+    }
+    /** 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 = 4;
+        let lastErr;
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+            // Rebuild signed query string with fresh nonce on each attempt.
+            const qs = await this._buildSignedQueryString(params, resolved);
+            const url = `${this._baseUrl}${path}?${qs}`;
+            const res = await fetch(url, method === "DELETE" ? { method: "DELETE" } : undefined);
+            // 429 → backoff + retry. All other paths (including non-429 venue
+            // errors wrapped in HTTP 200 with code≠0) throw immediately via
+            // _handleAsterResponse — no silent fallback (Rule #2).
+            if (res.status === 429 && attempt < MAX_ATTEMPTS - 1) {
+                const backoffMs = 2000 * Math.pow(2, attempt); // 2s, 4s, 8s
+                await new Promise((r) => setTimeout(r, backoffMs));
+                continue;
+            }
+            try {
+                return await this._handleAsterResponse(res, method, path);
+            }
+            catch (e) {
+                lastErr = e;
+                if (res.status === 429 && attempt < MAX_ATTEMPTS - 1) {
+                    const backoffMs = 2000 * Math.pow(2, attempt);
+                    await new Promise((r) => setTimeout(r, backoffMs));
+                    continue;
+                }
+                throw e;
+            }
+        }
+        throw lastErr;
     }
     // ── Private: HTTP response handling ──────────────────────────────────────
     /**

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" });
@@ -503,7 +538,7 @@ server.tool("suggest_command", "Given a natural language trading goal, suggest t
         }
         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>";
@@ -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) }] };
     }
@@ -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 {

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.11",
+  "version": "0.12.13",
   "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.11"
+  version: "0.12.13"
 ---
 
 # 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.11)
+perp --version 2>/dev/null  # check if exists (must be >= 0.12.13)
 npm install -g perp-cli@latest 2>/dev/null || npx -y perp-cli@latest --json --version
 ```