perp-cli 0.12.15 → 0.14.0

package/dist/commands/jobs.d.ts

@@ -1,2 +1,3 @@
 import { Command } from "commander";
-export declare function registerBackgroundCommands(program: Command, isJson: () => boolean): void;
+import type { ExchangeAdapter } from "../exchanges/index.js";
+export declare function registerBackgroundCommands(program: Command, isJson: () => boolean, getAdapterFor?: (venue: string) => Promise<ExchangeAdapter>): void;

package/dist/commands/jobs.js

@@ -1,9 +1,32 @@
-import { listJobs, stopJob, removeJob, loadJob, logFile } from "../jobs.js";
-import { printJson, jsonOk } from "../utils.js";
+import { listJobs, stopJob, removeJob, loadJob, logFile, assertTmuxSessionName, JOB_STOP_TIMEOUT_MS } from "../jobs.js";
+import { printJson, jsonOk, symbolMatch } from "../utils.js";
+import { PerpError } from "../errors.js";
 import chalk from "chalk";
 import { existsSync, readFileSync } from "node:fs";
-import { execSync } from "node:child_process";
-export function registerBackgroundCommands(program, isJson) {
+import { execFileSync } from "node:child_process";
+import { scrubSecretEnv } from "../secret-env.js";
+/**
+ * What a stopped job left on its venue(s): open orders and positions on its symbol (every symbol
+ * when the job has none). One entry per venue; a failed read is reported, never "nothing left".
+ */
+async function leftoversOf(job, getAdapterFor) {
+    const sym = typeof job.params.symbol === "string" && job.params.symbol !== "ALL" ? job.params.symbol.toUpperCase() : null;
+    const venues = job.exchange === "multi" ? [] : job.exchange.split(/[+,]/).map(v => v.trim()).filter(Boolean);
+    const out = [];
+    for (const venue of venues) {
+        try {
+            const a = await getAdapterFor(venue);
+            const [orders, positions] = await Promise.all([a.getOpenOrders(), a.getPositions()]);
+            const mine = (xs) => sym === null ? xs : xs.filter(x => symbolMatch(x.symbol, sym));
+            out.push({ venue, orders: mine(orders), positions: mine(positions).filter(p => Number(p.size) !== 0), error: null });
+        }
+        catch (e) {
+            out.push({ venue, orders: [], positions: [], error: e instanceof Error ? e.message : String(e) });
+        }
+    }
+    return out;
+}
+export function registerBackgroundCommands(program, isJson, getAdapterFor) {
     const jobs = program.command("background").description("Background process supervisor (tmux sessions for strategies, alerts, etc.)");
     jobs
         .command("list", { isDefault: true })
@@ -41,23 +64,60 @@ export function registerBackgroundCommands(program, isJson) {
     });
     jobs
         .command("stop <id>")
-        .description("Stop a running job")
-        .action((id) => {
+        .description("Stop a running job gracefully: SIGINT (the job cancels its orders / saves state), wait up to --timeout, only then kill; reports what is left on the venue")
+        .option("--timeout <sec>", "Seconds to wait for the job's own cleanup before killing it", String(JOB_STOP_TIMEOUT_MS / 1000))
+        .action(async (id, opts) => {
         const job = loadJob(id);
         if (!job) {
             console.log(chalk.red(`\n  Job ${id} not found.\n`));
             return;
         }
-        stopJob(id);
+        const timeoutSec = Number(opts.timeout);
+        if (!(timeoutSec > 0))
+            throw new PerpError("INVALID_PARAMS", `--timeout must be a positive number of seconds (got ${opts.timeout})`);
+        if (!isJson())
+            console.log(chalk.gray(`\n  Stopping job ${id} (SIGINT, waiting up to ${timeoutSec}s for its cleanup)...`));
+        const r = await stopJob(id, timeoutSec * 1000);
+        if (r === null)
+            return;
+        const log = logFile(id);
+        const tail = existsSync(log) ? readFileSync(log, "utf-8").split("\n").filter(l => l.trim() !== "").slice(-12) : [];
+        const left = getAdapterFor !== undefined ? await leftoversOf(job, getAdapterFor) : [];
+        const leftCount = left.reduce((n, v) => n + v.orders.length + v.positions.length, 0);
         if (isJson())
-            return printJson(jsonOk({ id, status: "stopped" }));
-        console.log(chalk.green(`\n  Job ${id} stopped.\n`));
+            return printJson(jsonOk({ id, status: "stopped", stop: r, leftovers: left, logTail: tail }));
+        if (r.outcome === "forced")
+            console.log(chalk.red.bold(`  Job ${id} was FORCE-KILLED: ${r.note}. Its own cleanup (cancel orders / save state) did NOT run.`));
+        else if (r.outcome === "graceful")
+            console.log(chalk.green(`  Job ${id} exited after SIGINT (${(r.waitedMs / 1000).toFixed(1)}s).`));
+        else
+            console.log(chalk.gray(`  Job ${id} was not running.`));
+        if (tail.length > 0) {
+            console.log(chalk.gray("  Last log lines:"));
+            for (const l of tail)
+                console.log(chalk.gray(`    ${l}`));
+        }
+        for (const v of left) {
+            if (v.error !== null) {
+                console.log(chalk.yellow(`  ${v.venue}: could not read what is left (${v.error}) — check: perp -e ${v.venue} account orders / account positions`));
+                continue;
+            }
+            for (const o of v.orders)
+                console.log(chalk.yellow(`  LEFT OPEN on ${v.venue}: order ${o.side} ${o.size} ${o.symbol} @ ${o.price} (${o.orderId}) — cancel: perp -e ${v.venue} trade cancel ${o.symbol} ${o.orderId}`));
+            for (const p of v.positions)
+                console.log(chalk.yellow(`  LEFT OPEN on ${v.venue}: position ${p.side} ${p.size.replace(/^-/, "")} ${p.symbol} — close: perp -e ${v.venue} trade close ${p.symbol}`));
+        }
+        if (left.length > 0 && leftCount === 0 && left.every(v => v.error === null))
+            console.log(chalk.green(`  Nothing left open on ${left.map(v => v.venue).join(", ")}${typeof job.params.symbol === "string" ? ` for ${job.params.symbol}` : ""}.`));
+        if (job.exchange === "multi")
+            console.log(chalk.gray("  Multi-venue job: check every venue: perp arb status"));
+        console.log();
     });
     jobs
         .command("logs <id>")
         .description("Show logs for a job")
         .option("-f, --follow", "Follow log output (tail -f)")
-        .option("-n, --lines <n>", "Number of lines to show", "50")
+        .option("--lines <n>", "Number of lines to show", "50")
         .action((id, opts) => {
         const log = logFile(id);
         if (!existsSync(log)) {
@@ -69,13 +129,13 @@ export function registerBackgroundCommands(program, isJson) {
             const job = loadJob(id);
             if (job?.status === "running") {
                 try {
-                    execSync(`tmux attach-session -t ${job.tmuxSession}`, { stdio: "inherit" });
+                    execFileSync("tmux", ["attach-session", "-t", assertTmuxSessionName(job.tmuxSession)], { stdio: "inherit", env: scrubSecretEnv(process.env) });
                     return;
                 }
                 catch { /* fall through to tail */ }
             }
             try {
-                execSync(`tail -f ${log}`, { stdio: "inherit" });
+                execFileSync("tail", ["-f", log], { stdio: "inherit", env: scrubSecretEnv(process.env) });
             }
             catch { /* ctrl-c */ }
         }
@@ -89,15 +149,17 @@ export function registerBackgroundCommands(program, isJson) {
     });
     jobs
         .command("remove <id>")
-        .description("Remove a job entry and its logs")
-        .action((id) => {
+        .description("Remove a job entry and its logs (a running job is stopped gracefully first)")
+        .action(async (id) => {
         const job = loadJob(id);
         if (!job) {
             console.log(chalk.red(`\n  Job ${id} not found.\n`));
             return;
         }
         if (job.status === "running") {
-            stopJob(id);
+            const r = await stopJob(id);
+            if (r?.outcome === "forced" && !isJson())
+                console.log(chalk.red(`  Job ${id} was force-killed (${r.note}); its cleanup did not run — check its venue for open orders / positions.`));
         }
         removeJob(id);
         if (isJson())

package/dist/commands/manage.js

@@ -1,13 +1,18 @@
-import { printJson, jsonOk, jsonError } from "../utils.js";
+import { isDryRun, networkOf, supportsDryRun } from "../cli-flags.js";
+import { printJson, jsonOk, jsonError, withJsonErrors } from "../utils.js";
 import chalk from "chalk";
 import { hasPacificaSdk } from "../exchanges/capabilities.js";
-import { PerpError } from "../errors.js";
-import { loadSettings } from "../settings.js";
+import { PerpError, classifyError, parsePositiveDecimal } from "../errors.js";
+import { unsupported } from "../exchanges/trading-v2.js";
+import { loadSettings, saveSettings } from "../settings.js";
 import { resolvePassphrase } from "../agent-wallet/passphrase.js";
 import { runHlSetAbstractionFlow } from "./agent.js";
-import { HyperliquidAdapter } from "../exchanges/hyperliquid.js";
+import { HyperliquidAdapter, hlAbstractionCachePrefix } from "../exchanges/hyperliquid.js";
+import { invalidateCache } from "../cache.js";
+import { LighterAdapter } from "../exchanges/lighter.js";
+import { resolveVenueId } from "../exchanges/venue.js";
 export function registerWalletManageCommands(parent, getAdapter, isJson, getPacificaAdapter) {
-    const manage = parent.command("manage").description("Exchange account settings (margin, subaccount, API keys, builder, account-mode) — Pacifica + Lighter + Hyperliquid");
+    const manage = parent.command("manage").description("Exchange account settings (margin, subaccount, API keys, builder-owner tools, account-mode) — Pacifica + Lighter + Hyperliquid");
     // Ensure adapter is initialized before accessing PacificaAdapter
     async function pac() {
         const adapter = await getAdapter();
@@ -45,15 +50,15 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
     withdrawCmd._hidden = true;
     // Subaccounts
     const sub = manage.command("sub").description("Subaccount management");
+    // Gated. Docs (rest-api/subaccounts/create-subaccount): "Both the main account and subaccount
+    // must sign to establish the relationship." perp-cli has no keypair source for the subaccount
+    // signature, so the request cannot be built.
     sub
         .command("create <name>")
-        .description("Create a subaccount")
-        .action(async (name) => {
-        const a = await pac();
-        const result = await a.sdk.createSubaccount(name, a.publicKey, a.signer);
-        if (isJson())
-            return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  Subaccount "${name}" created.\n`));
+        .description("Create a subaccount (not supported: the subaccount wallet must co-sign — use the Pacifica web app)")
+        .action(async (_name) => {
+        await pac();
+        throw unsupported("Pacifica", "subaccountCreate", "creating a subaccount needs a signature from the subaccount wallet as well as the main account, and perp-cli only holds the main account signer", "Create the subaccount in the Pacifica web app, then use: perp wallet manage sub list / sub transfer");
     });
     sub
         .command("list")
@@ -67,10 +72,17 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
     });
     sub
         .command("transfer <from> <to> <amount>")
-        .description("Transfer funds between accounts")
+        .description("Transfer USDC between a main account and its subaccounts (<from> must be the signing account)")
         .action(async (from, to, amount) => {
         const a = await pac();
-        const result = await a.sdk.transferFunds({ from_account: from, to_account: to, amount }, a.publicKey, a.signer);
+        // Docs (subaccount-fund-transfer): the sender is the signing "account"; there is no from field.
+        if (from !== a.publicKey) {
+            throw new PerpError("INVALID_PARAMS", `Pacifica transfers are sent by the signing account (${a.publicKey}); <from> was ${from}`, {
+                exchange: "pacifica",
+                remediation: "Pass the active account as <from>, or run the command with the sender's wallet",
+            });
+        }
+        const result = await a.sdk.transferFunds({ to_account: to, amount: parsePositiveDecimal(amount, "transfer amount") }, a.publicKey, a.signer);
         if (isJson())
             return printJson(jsonOk(result));
         console.log(chalk.green(`\n  Transferred $${amount}.\n`));
@@ -81,77 +93,48 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
     // and OWS at-rest encryption. See `wallet agent approve pacifica --help`.
     // Lake (liquidity vaults)
     const lake = manage.command("lake").description("Lake (liquidity vault) management");
+    // Field names per docs.pacifica.fi rest-api/vaults (create-vault / deposit-to-vault / withdraw-from-vault).
     lake
-        .command("create <symbol> <amount>")
-        .description("Create a new lake")
-        .action(async (symbol, amount) => {
+        .command("create")
+        .description("Create a new vault (lake)")
+        .option("--manager <address>", "Manager address (omit to create a fresh vault with no manager)")
+        .option("--nickname <name>", "Display name for the vault")
+        .option("--initial-deposit <amount>", "Seed deposit in USDC from the creator")
+        .action(async (opts) => {
         const a = await pac();
-        const result = await a.sdk.createLake({ symbol: symbol.toUpperCase(), amount }, a.publicKey, a.signer);
+        const result = await a.sdk.createLake({
+            manager: opts.manager === undefined ? null : opts.manager,
+            nickname: opts.nickname === undefined ? null : opts.nickname,
+            initial_deposit: opts.initialDeposit === undefined ? null : parsePositiveDecimal(opts.initialDeposit, "--initial-deposit"),
+        }, a.publicKey, a.signer);
         if (isJson())
             return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  Lake created for ${symbol.toUpperCase()} with $${amount}.\n`));
+        console.log(chalk.green(`\n  Vault created.\n`));
+        console.log(JSON.stringify(result, null, 2));
     });
     lake
-        .command("deposit <lakeId> <amount>")
-        .description("Deposit to a lake")
-        .action(async (lakeId, amount) => {
+        .command("deposit <lake> <amount>")
+        .description("Deposit USDC into a vault (<lake> = vault address)")
+        .action(async (lakeAddress, amount) => {
         const a = await pac();
-        const result = await a.sdk.depositToLake({ lake_id: lakeId, amount }, a.publicKey, a.signer);
+        const result = await a.sdk.depositToLake({ lake: lakeAddress, amount: parsePositiveDecimal(amount, "deposit amount") }, a.publicKey, a.signer);
         if (isJson())
             return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  Deposited $${amount} to lake ${lakeId}.\n`));
+        console.log(chalk.green(`\n  Deposited $${amount} to vault ${lakeAddress}.\n`));
     });
     lake
-        .command("withdraw <lakeId> <amount>")
-        .description("Withdraw from a lake")
-        .action(async (lakeId, amount) => {
-        const a = await pac();
-        const result = await a.sdk.withdrawFromLake({ lake_id: lakeId, amount }, a.publicKey, a.signer);
-        if (isJson())
-            return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  Withdrew $${amount} from lake ${lakeId}.\n`));
-    });
-    // Builder Codes
-    const builder = manage.command("builder").description("Builder code management (Pacifica)");
-    builder
-        .command("approve <code> <maxFeeRate>")
-        .description("Approve a builder code (e.g. approve MYCODE 0.001)")
-        .action(async (code, maxFeeRate) => {
+        .command("withdraw <lake> <shares>")
+        .description("Redeem vault shares (<lake> = vault address, <shares> = number of shares, not USDC)")
+        .action(async (lakeAddress, shares) => {
         const a = await pac();
-        const result = await a.sdk.approveBuilderCode({ builder_code: code, max_fee_rate: maxFeeRate }, a.publicKey, a.signer);
+        const result = await a.sdk.withdrawFromLake({ lake: lakeAddress, shares: parsePositiveDecimal(shares, "shares") }, a.publicKey, a.signer);
         if (isJson())
             return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  Builder code "${code}" approved (max fee: ${maxFeeRate}).\n`));
-    });
-    builder
-        .command("revoke <code>")
-        .description("Revoke a builder code")
-        .action(async (code) => {
-        const a = await pac();
-        const result = await a.sdk.revokeBuilderCode({ builder_code: code }, a.publicKey, a.signer);
-        if (isJson())
-            return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  Builder code "${code}" revoked.\n`));
-    });
-    builder
-        .command("list")
-        .description("List approved builder codes")
-        .action(async () => {
-        const a = await pac();
-        const result = await a.sdk.getBuilderApprovals(a.publicKey);
-        if (isJson())
-            return printJson(jsonOk(result));
-        const approvals = result;
-        if (!Array.isArray(approvals) || approvals.length === 0) {
-            console.log(chalk.gray("\n  No builder codes approved.\n"));
-            return;
-        }
-        console.log(chalk.cyan.bold("\n  Approved Builder Codes\n"));
-        for (const b of approvals) {
-            console.log(`  ${chalk.white(b.builder_code.padEnd(16))} max_fee: ${b.max_fee_rate}  ${chalk.gray(b.description || "")}`);
-        }
-        console.log();
+        console.log(chalk.green(`\n  Redeemed ${shares} shares from vault ${lakeAddress}.\n`));
     });
+    // Pacifica builder-OWNER tools. A user's builder approval / revoke / status is
+    // `perp wallet builder approve|revoke|status <venue>` (settings builder.<venue>).
+    const builder = manage.command("builder").description("Pacifica builder-owner tools (overview, trades, leaderboard, update-fee). Approve / revoke / status: perp wallet builder");
     builder
         .command("overview")
         .description("Show your builder code overview (if you are a builder)")
@@ -193,7 +176,7 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
         console.log(chalk.green(`\n  Builder code "${code}" fee rate updated to ${feeRate}.\n`));
     });
     // Referral
-    const referral = manage.command("referral").description("Referral code management (Pacifica)");
+    const referral = manage.command("referral").description("Referral codes (Pacifica claim; Hyperliquid/Lighter explicit set)");
     referral
         .command("claim <code>")
         .description("Claim a referral code")
@@ -204,17 +187,74 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
             return printJson(jsonOk(result));
         console.log(chalk.green(`\n  Referral code "${code}" claimed!\n`));
     });
+    // Explicit referral apply (HL / Lighter). Never done on adapter creation: this
+    // signs and sends one referral action with the active signer. Supports --dry-run.
+    supportsDryRun(referral
+        .command("set [code]")
+        .description("Hyperliquid / Lighter: sign + send a one-time referral action (default code: settings referralCodes.<venue>; supports --dry-run)")
+        .action(async (codeArg, _opts, cmd) => {
+        await withJsonErrors(isJson(), async () => {
+            const venue = resolveVenueId(String(cmd.optsWithGlobals().exchange));
+            if (venue !== "hyperliquid" && venue !== "lighter") {
+                throw new PerpError("CAPABILITY_UNSUPPORTED", `referral set supports hyperliquid and lighter (got ${venue})`, {
+                    remediation: "Run with -e hyperliquid or -e lighter (Pacifica: perp -e pacifica wallet manage referral claim <code>)",
+                });
+            }
+            const code = codeArg ?? loadSettings().referralCodes[venue];
+            if (!code) {
+                throw new PerpError("INVALID_PARAMS", `No ${venue} referral code given and settings referralCodes.${venue} is empty`, {
+                    remediation: `Pass a code: perp -e ${venue} wallet manage referral set <code>`,
+                });
+            }
+            const network = networkOf(cmd);
+            const plan = { venue, network, code, action: venue === "hyperliquid" ? "setReferrer" : "referral/use" };
+            if (isDryRun(cmd)) {
+                if (isJson())
+                    return printJson(jsonOk({ dryRun: true, sent: false, ...plan }));
+                console.log(chalk.yellow(`\n  [dry-run] Would sign + send ${plan.action} with code "${code}" on ${venue} (${network}). Nothing sent.\n`));
+                return;
+            }
+            // The referral is the account owner's action — never signed with an imported agent / API key.
+            const { cliCredentialOptsFrom, requireMasterWallet } = await import("../config.js");
+            await requireMasterWallet(venue, cliCredentialOptsFrom(cmd.optsWithGlobals()), `${venue} referral set`);
+            const adapter = await getAdapter();
+            let result;
+            if (venue === "hyperliquid") {
+                if (!(adapter instanceof HyperliquidAdapter))
+                    throw new Error("hyperliquid venue did not produce a HyperliquidAdapter");
+                result = await adapter.setReferrer(code);
+            }
+            else {
+                if (!(adapter instanceof LighterAdapter))
+                    throw new Error("lighter venue did not produce a LighterAdapter");
+                if (adapter.isReadOnly) {
+                    throw new PerpError("NO_SIGNER_AVAILABLE", "Lighter referral needs a signer (agent API key)", {
+                        remediation: "Register one first: perp wallet agent approve lighter",
+                    });
+                }
+                result = await adapter.useReferralCode(code);
+            }
+            const s = loadSettings();
+            s.referralApplied[venue] = true;
+            saveSettings(s);
+            if (isJson())
+                return printJson(jsonOk({ sent: true, ...plan, result }));
+            console.log(chalk.green(`\n  ${venue} referral code "${code}" applied.\n`));
+        });
+    }));
     // API Keys
     const apikey = manage.command("apikey").description("API key management");
     apikey
-        .command("create <name> <maxFeeRate>")
-        .description("Create an API key")
-        .action(async (name, maxFeeRate) => {
+        .command("create")
+        .description("Create an API Config Key (rate-limit key; up to 5 per account)")
+        .action(async () => {
         const a = await pac();
-        const result = await a.sdk.createApiKey(name, maxFeeRate, a.publicKey, a.signer);
+        // Docs (api/rate-limits/api-config-keys): no name / fee-rate field — the signed payload is empty.
+        const result = await a.sdk.createApiKey(a.publicKey, a.signer);
         if (isJson())
             return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  API key "${name}" created.\n`));
+        console.log(chalk.green(`\n  API Config Key created.\n`));
+        console.log(JSON.stringify(result, null, 2));
     });
     apikey
         .command("list")
@@ -258,7 +298,7 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
         // Merge parent + subcommand opts so --passphrase works on either side.
         const mergedOpts = command.optsWithGlobals();
         const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
-        const network = mergedOpts.network ?? "mainnet";
+        const network = networkOf(command);
         const isTestnet = network === "testnet";
         // ── Show branch (no positional arg) ─────────────────────────────────
         if (!mode) {
@@ -285,7 +325,8 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
                     });
                 }
                 adapter.setAddress(evmAccount.address);
-                const current = await adapter._getAbstractionMode();
+                // The command that reports the mode never answers from the disk cache.
+                const current = await adapter._getAbstractionMode({ fresh: true });
                 if (useJson) {
                     return printJson(jsonOk({ mode: current, master: masterName, address: evmAccount.address, network: isTestnet ? "testnet" : "mainnet" }));
                 }
@@ -298,9 +339,7 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
             }
             catch (err) {
                 if (useJson) {
-                    const e = err instanceof PerpError
-                        ? err.structured
-                        : { code: "UNKNOWN", message: err instanceof Error ? err.message : String(err) };
+                    const e = classifyError(err);
                     console.error(JSON.stringify(jsonError(e.code, e.message)));
                     process.exit(1);
                 }
@@ -345,7 +384,7 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
                 const evmAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155:"));
                 if (evmAccount) {
                     readAdapter.setAddress(evmAccount.address);
-                    prevMode = await readAdapter._getAbstractionMode();
+                    prevMode = await readAdapter._getAbstractionMode({ fresh: true });
                 }
             }
             catch {
@@ -354,12 +393,20 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
                 // informational metadata — its absence does NOT mask the write.
                 prevMode = null;
             }
-            const result = await runHlSetAbstractionFlow({
-                masterName,
-                passphrase: passphrase ?? "",
-                mode: newMode,
-                isTestnet,
-            });
+            // The cached mode (HL_ABSTRACTION_TTL_MS) is dropped whatever the outcome: a sent action
+            // whose answer was lost may have changed the mode.
+            let result;
+            try {
+                result = await runHlSetAbstractionFlow({
+                    masterName,
+                    passphrase: passphrase ?? "",
+                    mode: newMode,
+                    isTestnet,
+                });
+            }
+            finally {
+                invalidateCache(hlAbstractionCachePrefix(network));
+            }
             if (useJson) {
                 return printJson(jsonOk({
                     mode: result.mode,
@@ -380,9 +427,7 @@ export function registerWalletManageCommands(parent, getAdapter, isJson, getPaci
         }
         catch (err) {
             if (useJson) {
-                const e = err instanceof PerpError
-                    ? err.structured
-                    : { code: "UNKNOWN", message: err instanceof Error ? err.message : String(err) };
+                const e = classifyError(err);
                 console.error(JSON.stringify(jsonError(e.code, e.message)));
                 process.exit(1);
             }

package/dist/commands/market.d.ts

@@ -1,3 +1,6 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
-export declare function registerMarketCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, getAdapterForExchange?: (exchange: string) => Promise<ExchangeAdapter>): void;
+import "../exchanges/venues/index.js";
+export declare function registerMarketCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, getAdapterForExchange?: (exchange: string) => Promise<ExchangeAdapter>, 
+/** Credentialed adapter of the selected venue — for market data the venue serves only to an authenticated account. */
+getAccountAdapter?: () => Promise<ExchangeAdapter>): void;

package/dist/commands/market.js

@@ -1,8 +1,17 @@
 import { makeTable, formatUsd, formatPercent, printJson, jsonOk, jsonError, withJsonErrors } from "../utils.js";
 import chalk from "chalk";
-import { hasPacificaSdk, isDexCapable } from "../exchanges/capabilities.js";
-const EXCHANGES = ["pacifica", "hyperliquid", "lighter", "aster"];
-export function registerMarketCommands(program, getAdapter, isJson, getAdapterForExchange) {
+import { PerpError } from "../errors.js";
+import { midDecimal } from "../exchanges/precision.js";
+import { hasPacificaSdk, isDexCapable, klinesNeedAuth } from "../exchanges/capabilities.js";
+import { listVenuesWithRole } from "../exchanges/venue.js";
+import "../exchanges/venues/index.js";
+/** Venues with an adapter (market-data-only venues have none — see `perp arb scan`). */
+const EXCHANGES = listVenuesWithRole("account").map(v => v.id);
+/** null = venue does not publish the value → "-" (never rendered as $0). */
+const usdOrDash = (v) => (v === null ? chalk.gray("-") : `$${formatUsd(v)}`);
+export function registerMarketCommands(program, getAdapter, isJson, getAdapterForExchange, 
+/** Credentialed adapter of the selected venue — for market data the venue serves only to an authenticated account. */
+getAccountAdapter) {
     const market = program.command("market").description("Market data commands");
     market
         .command("list")
@@ -14,10 +23,10 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
         const marketRow = (m) => [
             chalk.white.bold(m.symbol),
             `$${formatUsd(m.markPrice)}`,
-            `$${formatUsd(m.indexPrice)}`,
+            usdOrDash(m.indexPrice),
             m.fundingRate != null ? formatPercent(m.fundingRate) : chalk.gray("N/A"),
-            `$${formatUsd(m.volume24h)}`,
-            `$${formatUsd(m.openInterest)}`,
+            usdOrDash(m.volume24h),
+            usdOrDash(m.openInterest),
             String(m.maxLeverage) + "x",
         ];
         // Multi-exchange mode
@@ -97,7 +106,7 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
         const priceRow = (m) => [
             chalk.white.bold(m.symbol),
             `$${formatUsd(m.markPrice)}`,
-            `$${formatUsd(m.indexPrice)}`,
+            usdOrDash(m.indexPrice),
             m.fundingRate != null ? formatPercent(m.fundingRate) : chalk.gray("N/A"),
         ];
         if (!explicitExchange && getAdapterForExchange) {
@@ -169,10 +178,10 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
             return printJson(jsonOk(m));
         console.log(chalk.cyan.bold(`\n  ${m.symbol} on ${adapter.name}\n`));
         console.log(`  Mark Price:     $${formatUsd(m.markPrice)}`);
-        console.log(`  Index Price:    $${formatUsd(m.indexPrice)}`);
+        console.log(`  Index Price:    ${usdOrDash(m.indexPrice)}`);
         console.log(`  Funding Rate:   ${m.fundingRate != null ? formatPercent(m.fundingRate) : chalk.gray("N/A")}`);
-        console.log(`  24h Volume:     $${formatUsd(m.volume24h)}`);
-        console.log(`  Open Interest:  $${formatUsd(m.openInterest)}`);
+        console.log(`  24h Volume:     ${usdOrDash(m.volume24h)}`);
+        console.log(`  Open Interest:  ${usdOrDash(m.openInterest)}`);
         console.log(`  Max Leverage:   ${m.maxLeverage}x`);
         console.log();
     });
@@ -279,17 +288,19 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
         .description("Get mid price for a single symbol (fast)")
         .action(async (symbol) => {
         const sym = symbol.toUpperCase();
-        try {
+        // withJsonErrors: every failure (incl. an empty book) is an error envelope AND exit code 1.
+        await withJsonErrors(isJson(), async () => {
             const adapter = await getAdapter();
-            // Try orderbook mid (best bid + best ask) / 2
+            // Orderbook mid (best bid + best ask) / 2
             const book = await adapter.getOrderbook(sym);
             const bestBid = book.bids[0]?.[0];
             const bestAsk = book.asks[0]?.[0];
             if (!bestBid && !bestAsk) {
-                if (isJson())
-                    return printJson(jsonError("SYMBOL_NOT_FOUND", `No orderbook data for ${sym}`));
-                console.log(chalk.red(`\n  No orderbook data for ${sym}.\n`));
-                return;
+                // The market exists (getOrderbook resolved it) but nobody quotes it: no price, not "unknown symbol".
+                throw new PerpError("PRICE_STALE", `${sym} orderbook on ${adapter.name} is empty (no bids and no asks) — no mid price`, {
+                    exchange: adapter.name,
+                    remediation: `The market has no liquidity right now; check: perp -e ${adapter.name} market book ${sym}, or pick a market with a two-sided book`,
+                });
             }
             const bid = Number(bestBid ?? 0);
             const ask = Number(bestAsk ?? 0);
@@ -298,7 +309,8 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
             if (isJson())
                 return printJson(jsonOk({
                     symbol: sym,
-                    mid: mid.toString(),
+                    // Exact decimal mid of the two quoted strings (float (bid + ask) / 2 prints artifacts).
+                    mid: bestBid && bestAsk ? midDecimal(bestBid, bestAsk) : mid.toString(),
                     bid: bestBid ?? null,
                     ask: bestAsk ?? null,
                     spread: spread.toFixed(6),
@@ -311,19 +323,7 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
                 console.log(`  Ask:    $${formatUsd(bestAsk)}`);
             console.log(`  Spread: ${spread.toFixed(4)}%`);
             console.log();
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (isJson()) {
-                const { classifyError } = await import("../errors.js");
-                const classified = classifyError(err);
-                return printJson(jsonError(classified.code, classified.message, {
-                    status: classified.status,
-                    retryable: classified.retryable,
-                }));
-            }
-            console.error(chalk.red(`Error: ${msg}`));
-        }
+        });
     });
     market
         .command("kline <symbol> <interval>")
@@ -331,7 +331,9 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
         .option("--start <ts>", "Start time (unix ms)")
         .option("--end <ts>", "End time (unix ms)")
         .action(async (symbol, interval, opts) => {
-        const adapter = await getAdapter();
+        const publicAdapter = await getAdapter();
+        // A venue whose candles endpoint is authenticated (Ondo) is read with the registered key.
+        const adapter = getAccountAdapter !== undefined && klinesNeedAuth(publicAdapter) ? await getAccountAdapter() : publicAdapter;
         const now = Date.now();
         const startTime = opts.start ? parseInt(opts.start) : now - 24 * 60 * 60 * 1000;
         const endTime = opts.end ? parseInt(opts.end) : now;
@@ -362,8 +364,9 @@ export function registerMarketCommands(program, getAdapter, isJson, getAdapterFo
             const adapter = await getAdapter();
             if (!(isDexCapable(adapter))) {
                 if (isJson())
-                    return printJson(jsonError("INVALID_EXCHANGE", "HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid."));
+                    return printJson(jsonError("INVALID_PARAMS", "HIP-3 dexes are only available on Hyperliquid.", { remediation: "Re-run with -e hyperliquid." }));
                 console.error(chalk.red("\n  HIP-3 dexes are only available on Hyperliquid. Use -e hyperliquid.\n"));
+                process.exitCode = 1;
                 return;
             }
             const dexes = await adapter.listDeployedDexes();

package/dist/commands/outcome.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `perp outcome` — Hyperliquid Outcome markets (HIP-4).
+ *
+ * Currently HL-only. Asset class is fully collateralized binary/range
+ * contracts, quoted per outcome (outcomeMeta quoteToken, e.g. USDC). No leverage, no liquidation. Settlement is
+ * dated per-outcome.
+ */
+import { Command } from "commander";
+import type { ExchangeAdapter } from "../exchanges/index.js";
+export declare function registerOutcomeCommands(program: Command, getAdapterForExchange: (exchange: string) => Promise<ExchangeAdapter>, isJson: () => boolean): void;