perp-cli 0.12.9 → 0.12.11

package/dist/commands/manage.js

@@ -239,8 +239,7 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
     // Legacy `manage setup-api-key` removed in v0.12 (Phase 2d) — superseded by
     // the unified `wallet agent approve lighter` flow. The agent flow provides
     // 3-tier signer routing, expiry tracking, free-slot picking, and AgentMeta
-    // persistence. The auto-setup path in LighterAdapter.init() remains as the
-    // env-key fallback for users who haven't run the unified command yet.
+    // persistence.
     // ── Hyperliquid account abstraction mode ────────────────────────────────
     // Read side: HyperliquidAdapter._getAbstractionMode() (added v0.12.7).
     // Write side: HL `userSetAbstraction` action — master EVM EIP-712 signature.

package/dist/commands/wallet.js

@@ -1270,12 +1270,19 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .option("--policy <ids>", "Comma-separated policy IDs to enforce")
         .option("--expires <iso>", "Key expiry (ISO-8601)")
         .option("-p, --passphrase <pass>", "Vault passphrase", "")
-        .action(async (opts) => {
+        .action(async (opts, command) => {
         try {
             const o = loadOws();
             const walletIds = opts.wallets.split(",").map(s => s.trim());
             const policyIds = opts.policy ? opts.policy.split(",").map(s => s.trim()) : [];
-            const result = o.createApiKey(opts.name, walletIds, policyIds, opts.passphrase, opts.expires);
+            // optsWithGlobals() merges parent + subcommand options, so --passphrase
+            // works whether placed on `perp --passphrase X wallet key create` (parent)
+            // or `perp wallet key create --passphrase X` (subcommand). Without this
+            // merge, Commander v13 silently shadows the subcommand flag with the
+            // parent flag and opts.passphrase becomes the empty-string default.
+            const merged = command.optsWithGlobals();
+            const passphrase = merged.passphrase ?? opts.passphrase;
+            const result = o.createApiKey(opts.name, walletIds, policyIds, passphrase, opts.expires);
             if (isJson())
                 return printJson(jsonOk({ id: result.id, name: result.name, token: result.token, wallets: walletIds, policies: policyIds, expires: opts.expires ?? null }));
             console.log(chalk.green.bold("\n  OWS API Key Created\n"));

package/dist/config.js

@@ -74,15 +74,16 @@ export async function loadPrivateKey(exchange, pkOverride, walletName) {
         // settings module not available, skip
     }
     // 3. Exchange-specific env vars
-    // v0.12.4: Aster's ASTER_API_KEY entry is removed — the legacy HMAC
-    // signing path was retired in Plan v3.0. Aster onboarding is now via
-    // `perp wallet agent approve aster` (off-chain agent wallet); the runtime
-    // adapter pulls credentials from the agent store, not the env.
+    // v0.12.4 retired the legacy HMAC ASTER_API_KEY/SECRET path.
+    // v0.12.6 restored Aster as a normal EVM exchange in EXCHANGE_ENV_MAP
+    // (setup wizard / wallet show), but missed this map — leaving Tier 3
+    // env-PK loading broken. v0.12.10 restores ASTER_PRIVATE_KEY here so
+    // `tryLoadPrivateKey("aster")` finds the env value, mirroring HL/LT.
     const envMap = {
         pacifica: ["PACIFICA_PRIVATE_KEY", "pk"],
         hyperliquid: ["HYPERLIQUID_PRIVATE_KEY", "HL_PRIVATE_KEY"],
         lighter: ["LIGHTER_PRIVATE_KEY"],
-        aster: [],
+        aster: ["ASTER_PRIVATE_KEY"],
     };
     for (const envVar of envMap[exchange]) {
         if (process.env[envVar])

package/dist/exchanges/aster-typed-data.d.ts

@@ -25,6 +25,15 @@ export declare const ASTER_DOMAIN_B: {
     readonly version: "1";
     readonly verifyingContract: "0x0000000000000000000000000000000000000000";
 };
+/** Domain B (testnet): chainId=714 per Aster V3 testnet docs. */
+export declare const ASTER_DOMAIN_B_TESTNET: {
+    readonly chainId: 714;
+    readonly name: "AsterSignTransaction";
+    readonly version: "1";
+    readonly verifyingContract: "0x0000000000000000000000000000000000000000";
+};
+/** Returns the Domain B object for the requested network (testnet branches chainId). */
+export declare function getAsterDomainB(testnet: boolean): typeof ASTER_DOMAIN_B | typeof ASTER_DOMAIN_B_TESTNET;
 /** EIP-712 types for Domain B order signing — single msg string (URL-encoded query string). */
 export declare const ORDER_TYPES: {
     readonly Message: readonly [{
@@ -113,11 +122,15 @@ export declare function buildOrderQueryStringMsg(orderParams: Record<string, str
 /**
  * Build the EIP-712 typed-data payload for agent-signed order requests.
  *
- * Domain B (chainId=1666), primaryType="Message", single `msg` field containing
- * the URL-encoded query string produced by buildOrderQueryStringMsg.
+ * Domain B (chainId=1666 mainnet / 714 testnet), primaryType="Message",
+ * single `msg` field containing the URL-encoded query string produced by
+ * buildOrderQueryStringMsg.
+ *
+ * @param testnet When true, returns Domain B with chainId=714 per Aster V3
+ *                testnet docs. Defaults to false (mainnet).
  */
-export declare function buildOrderTypedData(orderParams: Record<string, string | number | boolean>): {
-    domain: typeof ASTER_DOMAIN_B;
+export declare function buildOrderTypedData(orderParams: Record<string, string | number | boolean>, testnet?: boolean): {
+    domain: typeof ASTER_DOMAIN_B | typeof ASTER_DOMAIN_B_TESTNET;
     types: typeof ORDER_TYPES;
     primaryType: "Message";
     message: {

package/dist/exchanges/aster-typed-data.js

@@ -24,6 +24,15 @@ export const ASTER_DOMAIN_B = {
     ...ASTER_DOMAIN_A,
     chainId: 1666,
 };
+/** Domain B (testnet): chainId=714 per Aster V3 testnet docs. */
+export const ASTER_DOMAIN_B_TESTNET = {
+    ...ASTER_DOMAIN_A,
+    chainId: 714,
+};
+/** Returns the Domain B object for the requested network (testnet branches chainId). */
+export function getAsterDomainB(testnet) {
+    return testnet ? ASTER_DOMAIN_B_TESTNET : ASTER_DOMAIN_B;
+}
 /** EIP-712 types for Domain B order signing — single msg string (URL-encoded query string). */
 export const ORDER_TYPES = {
     Message: [{ name: "msg", type: "string" }],
@@ -136,13 +145,17 @@ export function buildOrderQueryStringMsg(orderParams) {
 /**
  * Build the EIP-712 typed-data payload for agent-signed order requests.
  *
- * Domain B (chainId=1666), primaryType="Message", single `msg` field containing
- * the URL-encoded query string produced by buildOrderQueryStringMsg.
+ * Domain B (chainId=1666 mainnet / 714 testnet), primaryType="Message",
+ * single `msg` field containing the URL-encoded query string produced by
+ * buildOrderQueryStringMsg.
+ *
+ * @param testnet When true, returns Domain B with chainId=714 per Aster V3
+ *                testnet docs. Defaults to false (mainnet).
  */
-export function buildOrderTypedData(orderParams) {
+export function buildOrderTypedData(orderParams, testnet = false) {
     const msg = buildOrderQueryStringMsg(orderParams);
     return {
-        domain: ASTER_DOMAIN_B,
+        domain: getAsterDomainB(testnet),
         types: ORDER_TYPES,
         primaryType: "Message",
         message: { msg },

package/dist/exchanges/aster.d.ts

@@ -15,6 +15,14 @@ import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrd
 import type { EvmSigner } from "../signer/interface.js";
 import type { AgentMeta } from "../settings.js";
 import type { AgentSigningStrategy } from "../agent-wallet/signing-strategy.js";
+type ResolvedSigner = {
+    tier: "agent" | "master" | "pk";
+    signer: EvmSigner | AgentSigningStrategy;
+    /** EVM address that will appear in the `signer` field of Aster requests */
+    signerAddress: string;
+    /** EVM address of the owner/master — used as `user` field in Aster requests */
+    userAddress: string;
+};
 export declare class AsterAdapter implements ExchangeAdapter {
     readonly name = "aster";
     readonly chain = "bnb";
@@ -88,7 +96,13 @@ export declare class AsterAdapter implements ExchangeAdapter {
         assetId?: number;
         routeType?: number;
     }): Promise<unknown>;
-    private _resolveSigner;
+    /**
+     * Resolve the active signer per the three-tier policy.
+     *
+     * Exposed (leading underscore) for unit-test access only — do not call
+     * from production code outside this class.
+     */
+    _resolveSigner(): ResolvedSigner;
     private _nextNonce;
     /**
      * Build the canonical signed-request URL per Aster v3 spec.
@@ -102,24 +116,48 @@ 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.
+     *
      * `signatureChainId` is NOT a v3 parameter — it's an artifact of an older
      * scheme; including it breaks signature verification on every call.
+     *
+     * Exposed (with leading underscore) for unit-test access only — do not call
+     * from production code outside this class.
      */
-    private _buildSignedQueryString;
+    _buildSignedQueryString(params: Record<string, string | number | boolean>, resolved: ResolvedSigner): Promise<string>;
     /**
      * Sign and POST to a path using EIP-712 Domain B.
      */
     private _signedPostEip712;
     /**
      * Sign and GET from a path using EIP-712 Domain B.
+     *
+     * Unlike public GETs, signed GETs route through _handleAsterResponse so
+     * venue JSON error envelopes ({code, msg}) are not silently treated as
+     * success (SSOT Rule #2).
      */
     private _signedGetEip712;
     /**
      * Sign and DELETE from a path using EIP-712 Domain B.
      */
     private _signedDeleteEip712;
-    private _handleEip712Response;
-    /** Handle 429 rate limit with retry — used by GET/DELETE multi-attempt loops */
+    /**
+     * Unified response validator for ALL signed Aster requests.
+     *
+     * Validates BOTH HTTP status AND the venue JSON error envelope. Aster's
+     * API commonly returns HTTP 200 + `{code, msg: "Signature check failed"}`
+     * for signing or auth failures — checking only HTTP status would silently
+     * accept these as success and cause callers (e.g., getBalance) to cache
+     * zero balances or empty arrays. SSOT Rule #2: failures throw with
+     * remediation; never substitute a default.
+     *
+     * Used by signed POST/GET/DELETE. Public unsigned GETs use _handleResponse.
+     */
+    private _handleAsterResponse;
+    /** Handle 429 rate limit with retry — used by public unsigned GET multi-attempt loops */
     private _handleResponse;
     private _publicGet;
 }
+export {};

package/dist/exchanges/aster.js

@@ -501,6 +501,12 @@ export class AsterAdapter {
         throw new Error("Aster withdrawal requires the spot API (not available in futures mode). Use the Aster web UI to withdraw.");
     }
     // ── Private: signer resolution ────────────────────────────────────────────
+    /**
+     * Resolve the active signer per the three-tier policy.
+     *
+     * Exposed (leading underscore) for unit-test access only — do not call
+     * from production code outside this class.
+     */
     _resolveSigner() {
         // Tier 1: agent (when registered, not expired, --no-agent NOT set)
         if (!this._useNoAgent && this._agentSigner && this._agentMeta) {
@@ -522,12 +528,15 @@ export class AsterAdapter {
                 };
             }
         }
-        // Tier 2: OWS master
+        // 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
+        // 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 };
@@ -555,8 +564,15 @@ 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.
+     *
      * `signatureChainId` is NOT a v3 parameter — it's an artifact of an older
      * scheme; including it breaks signature verification on every call.
+     *
+     * Exposed (with leading underscore) for unit-test access only — do not call
+     * from production code outside this class.
      */
     async _buildSignedQueryString(params, resolved) {
         // Insertion order (matches Python reference: nonce, user, signer last).
@@ -566,7 +582,7 @@ export class AsterAdapter {
             user: resolved.userAddress,
             signer: resolved.signerAddress,
         };
-        const typed = buildOrderTypedData(fullParams);
+        const typed = buildOrderTypedData(fullParams, this._testnet);
         // Sign via the appropriate signer type
         const sigRaw = await resolved.signer.signTypedData(typed.domain, typed.types, typed.message);
         // Normalize: AgentSigningStrategy returns { signature, r, s, v }; EvmSigner returns string
@@ -586,21 +602,20 @@ export class AsterAdapter {
             headers: { "Content-Type": "application/x-www-form-urlencoded" },
             body: "",
         });
-        return this._handleEip712Response(res, "POST", path);
+        return this._handleAsterResponse(res, "POST", path);
     }
     /**
      * Sign and GET from a path using EIP-712 Domain B.
+     *
+     * Unlike public GETs, signed GETs route through _handleAsterResponse so
+     * venue JSON error envelopes ({code, msg}) are not silently treated as
+     * success (SSOT Rule #2).
      */
     async _signedGetEip712(path, params, resolved) {
         const qs = await this._buildSignedQueryString(params, resolved);
         const url = `${this._baseUrl}${path}?${qs}`;
-        for (let attempt = 0; attempt < 3; attempt++) {
-            const res = await fetch(url);
-            const result = await this._handleResponse(res, "GET", path, attempt);
-            if (result !== null)
-                return result;
-        }
-        throw new Error(`GET ${path} failed: max retries exceeded`);
+        const res = await fetch(url);
+        return this._handleAsterResponse(res, "GET", path);
     }
     /**
      * Sign and DELETE from a path using EIP-712 Domain B.
@@ -608,16 +623,23 @@ export class AsterAdapter {
     async _signedDeleteEip712(path, params, resolved) {
         const qs = await this._buildSignedQueryString(params, resolved);
         const url = `${this._baseUrl}${path}?${qs}`;
-        for (let attempt = 0; attempt < 3; attempt++) {
-            const res = await fetch(url, { method: "DELETE" });
-            const result = await this._handleResponse(res, "DELETE", path, attempt);
-            if (result !== null)
-                return result;
-        }
-        throw new Error(`DELETE ${path} failed: max retries exceeded`);
+        const res = await fetch(url, { method: "DELETE" });
+        return this._handleAsterResponse(res, "DELETE", path);
     }
     // ── Private: HTTP response handling ──────────────────────────────────────
-    async _handleEip712Response(res, method, path) {
+    /**
+     * Unified response validator for ALL signed Aster requests.
+     *
+     * Validates BOTH HTTP status AND the venue JSON error envelope. Aster's
+     * API commonly returns HTTP 200 + `{code, msg: "Signature check failed"}`
+     * for signing or auth failures — checking only HTTP status would silently
+     * accept these as success and cause callers (e.g., getBalance) to cache
+     * zero balances or empty arrays. SSOT Rule #2: failures throw with
+     * remediation; never substitute a default.
+     *
+     * Used by signed POST/GET/DELETE. Public unsigned GETs use _handleResponse.
+     */
+    async _handleAsterResponse(res, method, path) {
         if (res.status === 429) {
             const retryAfter = parseInt(res.headers.get("Retry-After") || "5", 10);
             await new Promise(r => setTimeout(r, Math.min(retryAfter * 1000, 30000)));
@@ -628,15 +650,28 @@ export class AsterAdapter {
             const s = classifyError(new Error(`${method} ${path} failed (${res.status}): ${text.slice(0, 200)}`), "aster");
             throw new PerpError(s.code, s.message, { exchange: s.exchange });
         }
-        const json = await res.json();
-        if (json.code !== undefined && json.code !== "000000" && json.code !== 200) {
-            const rawMsg = typeof json.msg === "string" ? json.msg : JSON.stringify(json);
-            const s = classifyError(new Error(rawMsg), "aster");
-            throw new PerpError(s.code, s.message, { exchange: s.exchange });
+        // Parse JSON, then validate venue error envelope. Aster success returns
+        // either an object whose `code` is "000000"/200 (or absent) or an array
+        // (e.g., GET /fapi/v3/openOrders, GET /fapi/v3/userTrades).
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new PerpError("EXCHANGE_ERROR", `${method} ${path}: malformed JSON: ${text.slice(0, 200)}`, { exchange: "aster" });
+        }
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            const json = parsed;
+            if (json.code !== undefined && json.code !== "000000" && json.code !== 200 && json.code !== 0) {
+                const rawMsg = typeof json.msg === "string" ? json.msg : JSON.stringify(json);
+                const s = classifyError(new Error(rawMsg), "aster");
+                throw new PerpError(s.code, s.message, { exchange: s.exchange });
+            }
         }
-        return json;
+        return parsed;
     }
-    /** Handle 429 rate limit with retry — used by GET/DELETE multi-attempt loops */
+    /** Handle 429 rate limit with retry — used by public unsigned GET multi-attempt loops */
     async _handleResponse(res, method, path, attempt = 0) {
         if (res.status === 429) {
             if (attempt >= 2)

package/dist/exchanges/hyperliquid.js

@@ -392,6 +392,12 @@ export class HyperliquidAdapter {
             // via `wallet manage account-mode unified`.
             if (raw === "default")
                 return "standard";
+            // "dexAbstraction" is HL's legacy fourth mode, slated for deprecation
+            // but still returned by the venue for some users. Per HL docs the spot
+            // pool acts as collateral (same accounting semantics as unified), so
+            // route through the unified branch rather than throwing.
+            if (raw === "dexAbstraction")
+                return "unified";
             throw new PerpError("INVALID_PARAMS", `UNKNOWN_ACCOUNT_MODE: HL returned unrecognized userAbstraction mode: ${JSON.stringify(raw)}`, { remediation: "Check app.hyperliquid.xyz Settings → Account Mode" });
         });
     }
@@ -424,6 +430,12 @@ export class HyperliquidAdapter {
         // - "standard": separate perp/spot accounting; perp clearinghouse is the
         //   only collateral source. Required mode for builder fee accrual.
         // HIP-3 dex accounts (this._dex) always use standard semantics.
+        //
+        // Portfolio-margin mode: per HL portfolio-margin docs, eligible collateral
+        // includes HYPE, BTC, USDH, USDC. We currently use USDC-only as a minimum
+        // viable baseline (mark-priced multi-asset accounting requires fetching
+        // spot mark prices and is deferred to a follow-up). Emit a stderr note so
+        // users see the breakdown when non-USDC collateral is present.
         const mode = await this._getAbstractionMode();
         if (mode === "unified" || mode === "portfolio") {
             const spotState = await this._getSpotClearinghouseState();
@@ -433,6 +445,22 @@ export class HyperliquidAdapter {
             const spotHold = Number(usdc?.hold ?? 0);
             equity = spotTotal;
             available = spotTotal - spotHold;
+            if (mode === "portfolio") {
+                const PORTFOLIO_COLLATERAL = ["HYPE", "BTC", "USDH"];
+                const nonUsdc = balances.filter((b) => {
+                    const coin = String(b.coin);
+                    if (coin.startsWith("USDC"))
+                        return false;
+                    if (Number(b.total ?? 0) <= 0)
+                        return false;
+                    return PORTFOLIO_COLLATERAL.some((c) => coin === c || coin.startsWith(`${c}-`));
+                });
+                if (nonUsdc.length > 0) {
+                    const summary = nonUsdc.map((b) => `${b.coin}=${b.total}`).join(", ");
+                    process.stderr.write(`[hl] portfolio mode: non-USDC collateral present but not counted in equity (${summary}). ` +
+                        `Equity reflects USDC only; full multi-asset accounting pending.\n`);
+                }
+            }
         }
         else {
             // mode === "standard"

package/dist/index.js

@@ -587,7 +587,7 @@ if (rawArgs.length === 0 || (!hasSubcommand && !rawArgs.includes("-h") && !rawAr
             const settings = loadSettings();
             const hasEnvKey = !!(process.env.PRIVATE_KEY || process.env.PACIFICA_PRIVATE_KEY ||
                 process.env.HL_PRIVATE_KEY || process.env.HYPERLIQUID_PRIVATE_KEY ||
-                process.env.LIGHTER_PRIVATE_KEY);
+                process.env.LIGHTER_PRIVATE_KEY || process.env.ASTER_PRIVATE_KEY);
             const hasOwsWallet = !!settings.owsActiveWallet;
             // ── ASCII banner ──
             const banner = [

package/package.json

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