perp-cli 0.12.17 → 0.14.1

package/dist/commands/wallet.js

@@ -1,11 +1,18 @@
+import { Option } from "commander";
+import { evmOnchainBalances, solanaOnchainBalances, stableTotal } from "../onchain-balances.js";
+import { PerpError } from "../errors.js";
 import chalk from "chalk";
-import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
+import bs58 from "bs58";
+import { existsSync, mkdirSync, readFileSync } from "fs";
+import { writeKeystoreAtomic } from "../agent-wallet/venue-keystore.js";
 import { resolve } from "path";
-import { formatUsd, makeTable, printJson, jsonOk } from "../utils.js";
-import { EXCHANGE_ENV_MAP, validateKey, loadEnvFile, setEnvVar, ENV_FILE } from "./init.js";
+import { formatUsd, makeTable, printJson, jsonOk, withJsonErrors } from "../utils.js";
+import { EXCHANGE_ENV_MAP, validateKey, loadEnvFile, ENV_FILE } from "./init.js";
+import { scrubSecretEnv } from "../secret-env.js";
 import { loadSettings, saveSettings } from "../settings.js";
-import { registerWalletAgentCommands } from "./agent.js";
+import { deprecatedPassphraseOption, registerWalletAgentCommands, warnDeprecatedPassphrase } from "./agent.js";
 import { registerWalletManageCommands } from "./manage.js";
+import { registerWalletBuilderCommands } from "./builder.js";
 import { loadOws } from "../signer/ows-loader.js";
 // ── OWS CLI subprocess helper (used by backup/restore/rotate) ──
 //
@@ -41,7 +48,8 @@ async function runOwsCli(args, timeout = 30000) {
     if (!owsBin) {
         throw new Error("OWS CLI not found. Install: curl -fsSL https://docs.openwallet.sh/install.sh | bash");
     }
-    const owsEnv = { ...process.env, PATH: `${pathResolve(process.env.HOME || "~", ".ows", "bin")}:${process.env.PATH}` };
+    // The OWS CLI child never receives key material (SSOT Rule #3): secret env vars are stripped.
+    const owsEnv = { ...scrubSecretEnv(process.env), PATH: `${pathResolve(process.env.HOME || "~", ".ows", "bin")}:${process.env.PATH}` };
     const proc = spawnSync(owsBin, args, { encoding: "utf-8", timeout, env: owsEnv });
     if (proc.error)
         throw new Error(`OWS CLI failed: ${proc.error.message}`);
@@ -66,7 +74,8 @@ function loadStore() {
 }
 function saveStore(store) {
     ensurePerpDir();
-    writeFileSync(WALLETS_FILE, JSON.stringify(store, null, 2), { mode: 0o600 });
+    // Atomic, explicit 0600 (writeFileSync's mode is ignored when the file already exists).
+    writeKeystoreAtomic(WALLETS_FILE, JSON.stringify(store, null, 2));
 }
 /** Exported for smart landing page in index.ts */
 export function getWalletSetupStatus() {
@@ -90,80 +99,60 @@ export function getWalletKeyByName(name) {
     const store = loadStore();
     return store.wallets[name]?.privateKey ?? null;
 }
+/** SOL + USDC / USDT on Solana (devnet: USDP). */
 async function getSolanaBalances(address, isTestnet) {
-    const { Connection, PublicKey } = await import("@solana/web3.js");
-    const rpcUrl = isTestnet
-        ? "https://api.devnet.solana.com"
-        : "https://api.mainnet-beta.solana.com";
-    const connection = new Connection(rpcUrl);
-    const pubkey = new PublicKey(address);
-    const balances = [];
-    const solLamports = await connection.getBalance(pubkey);
-    const solBalance = solLamports / 1e9;
-    balances.push({ token: "SOL", balance: solBalance.toFixed(6), usdValue: "" });
-    const usdcMint = isTestnet
-        ? "USDPqRbLidFGufty2s3oizmDEKdqx7ePTqzDMbf5ZKM"
-        : "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
-    try {
-        const tokenAccounts = await connection.getParsedTokenAccountsByOwner(pubkey, {
-            mint: new PublicKey(usdcMint),
-        });
-        let usdcBalance = 0;
-        for (const { account } of tokenAccounts.value) {
-            const parsed = account.data.parsed?.info;
-            if (parsed)
-                usdcBalance += Number(parsed.tokenAmount?.uiAmount ?? 0);
-        }
-        balances.push({
-            token: isTestnet ? "USDP" : "USDC",
-            balance: usdcBalance.toFixed(2),
-            usdValue: `$${formatUsd(usdcBalance)}`,
-        });
-    }
-    catch {
-        balances.push({ token: isTestnet ? "USDP" : "USDC", balance: "0.00", usdValue: "$0.00" });
-    }
-    try {
-        const res = await fetch("https://api.coingecko.com/api/v3/simple/price?ids=solana&vs_currencies=usd");
-        const json = (await res.json());
-        balances[0].usdValue = `$${formatUsd(solBalance * (json.solana?.usd ?? 0))}`;
-    }
-    catch {
-        balances[0].usdValue = "-";
-    }
-    return balances;
+    return solanaOnchainBalances(address, isTestnet);
 }
-async function getEvmBalances(address, isTestnet) {
-    const { ethers } = await import("ethers");
-    const rpcUrl = isTestnet
-        ? "https://sepolia-rollup.arbitrum.io/rpc"
-        : "https://arb1.arbitrum.io/rpc";
-    const provider = new ethers.JsonRpcProvider(rpcUrl);
-    const balances = [];
-    const ethBal = await provider.getBalance(address);
-    const ethBalance = Number(ethers.formatEther(ethBal));
-    balances.push({ token: "ETH", balance: ethBalance.toFixed(6), usdValue: "" });
-    const usdcAddr = isTestnet
-        ? "0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d"
-        : "0xaf88d065e77c8cC2239327C5EDb3A432268e5831";
-    try {
-        const usdc = new ethers.Contract(usdcAddr, ["function balanceOf(address) view returns (uint256)"], provider);
-        const rawBal = await usdc.balanceOf(address);
-        const usdcBalance = Number(ethers.formatUnits(rawBal, 6));
-        balances.push({ token: "USDC", balance: usdcBalance.toFixed(2), usdValue: `$${formatUsd(usdcBalance)}` });
-    }
-    catch {
-        balances.push({ token: "USDC", balance: "0.00", usdValue: "$0.00" });
-    }
-    try {
-        const res = await fetch("https://api.coingecko.com/api/v3/simple/price?ids=ethereum&vs_currencies=usd");
-        const json = (await res.json());
-        balances[0].usdValue = `$${formatUsd(ethBalance * (json.ethereum?.usd ?? 0))}`;
+/** Gas token + USDC / USDT (USDG on Robinhood Chain) on every EVM chain perp-cli uses; `only` limits the chains. */
+async function getEvmBalances(address, isTestnet, only) {
+    return evmOnchainBalances(address, isTestnet, only);
+}
+/** Human table: non-zero balances and failed reads (JSON keeps every row), then the stablecoin total. */
+function balanceTable(balances) {
+    const shown = balances.filter(b => b.error !== null || Number(b.balance) !== 0);
+    const rows = shown.map((b) => [
+        b.chain,
+        chalk.white.bold(b.token),
+        b.balance === null ? chalk.red("read failed") : b.balance,
+        b.usdValue === null ? chalk.gray("-") : `$${formatUsd(b.usdValue)}`,
+    ]);
+    const total = stableTotal(balances);
+    rows.push([chalk.gray("total"), chalk.white.bold("stablecoins"), "", `$${formatUsd(total.usd)}${total.errors.length > 0 ? chalk.red(" (some reads failed)") : ""}`]);
+    return makeTable(["Chain", "Token", "Balance", "USD Value"], rows);
+}
+async function balanceEntry(label, vm, address, testnet) {
+    const balances = vm === "solana" ? await getSolanaBalances(address, testnet) : await getEvmBalances(address, testnet);
+    const total = stableTotal(balances);
+    return { ...label, chain: vm, address, balances, stableUsd: total.usd, errors: total.errors };
+}
+/** Reads each distinct address once (several venues often share one key), in order. */
+async function balanceEntries(items, testnet) {
+    const seen = new Map();
+    const out = [];
+    for (const it of items) {
+        const key = `${it.vm}:${it.address.toLowerCase()}`;
+        const prev = seen.get(key);
+        if (prev !== undefined) {
+            if (it.label.exchange !== undefined)
+                prev.exchange = prev.exchange === undefined ? it.label.exchange : `${prev.exchange},${it.label.exchange}`;
+            continue;
+        }
+        const entry = await balanceEntry(it.label, it.vm, it.address, testnet);
+        seen.set(key, entry);
+        out.push(entry);
     }
-    catch {
-        balances[0].usdValue = "-";
+    return out;
+}
+/** Exactly one JSON document (an array of entries), or one table per entry. */
+function printBalanceEntries(entries, json) {
+    if (json)
+        return printJson(jsonOk(entries));
+    for (const e of entries) {
+        const who = [e.wallet, e.exchange].filter(x => x !== undefined).join(" / ");
+        console.log(chalk.cyan.bold(`\n  ${who} (${e.chain} ${e.address.slice(0, 8)}...)`));
+        console.log(balanceTable(e.balances));
     }
-    return balances;
+    console.log();
 }
 // ── Derive address from private key ──────────────────────────
 async function deriveSolanaAddress(key) {
@@ -182,141 +171,114 @@ async function deriveEvmAddress(key) {
     const pk = key.startsWith("0x") ? key : `0x${key}`;
     return new ethers.Wallet(pk).address;
 }
-// ── Legacy helpers ───────────────────────────────────────────
-async function _legacyGenerate(chain, name, isJson) {
-    if (chain === "solana") {
-        const { Keypair } = await import("@solana/web3.js");
-        const bs58 = (await import("bs58")).default;
-        const keypair = Keypair.generate();
-        const address = keypair.publicKey.toBase58();
-        const privkey = bs58.encode(keypair.secretKey);
-        const walletName = name || "default-sol";
-        const store = loadStore();
-        if (store.wallets[walletName]) {
-            console.error(chalk.red(`\n  Wallet "${walletName}" already exists.\n`));
-            process.exit(1);
-        }
-        store.wallets[walletName] = { name: walletName, type: "solana", address, privateKey: privkey, createdAt: new Date().toISOString() };
-        if (!store.active.pacifica)
-            store.active.pacifica = walletName;
-        saveStore(store);
-        setEnvVar("PACIFICA_PRIVATE_KEY", privkey);
-        if (isJson())
-            return printJson(jsonOk({ name: walletName, type: "solana", address, legacy: true }));
-        console.log(chalk.yellow.bold("\n  [Legacy] Solana Wallet Generated\n"));
-        console.log(`  Name:    ${chalk.white.bold(walletName)}`);
-        console.log(`  Address: ${chalk.green(address)}`);
-        console.log(chalk.gray(`  Saved:   ~/.perp/.env + wallets.json (unencrypted)`));
-        console.log(chalk.yellow(`\n  Consider: ${chalk.cyan("perp wallet migrate")} to move to OWS vault\n`));
+/** `--legacy` (raw keys written to ~/.perp/.env + wallets.json) was removed — SSOT Rule #3. */
+function legacyWriteRemoved(cmd) {
+    return new PerpError("INVALID_PARAMS", `wallet ${cmd} --legacy was removed: it wrote raw private keys to ~/.perp/.env and wallets.json`, {
+        remediation: cmd === "generate"
+            ? "Run: perp wallet generate [name] (OWS encrypted vault). Existing ~/.perp/.env keys keep working; move them with perp wallet set <exchange>"
+            : "Run: perp wallet import --name <name> [--chain evm|solana|dual] (key via hidden prompt or stdin) or perp wallet set <exchange>",
+    });
+}
+/**
+ * Solana key normalization: OWS SDK expects 32-byte hex secret. Phantom
+ * exports base58 (88 chars, 64-byte keypair = secret + public). Auto-detect
+ * base58/JSON-array/hex and normalize to 32-byte hex secret.
+ */
+export function normalizeSolanaKey(input) {
+    const s = input.trim();
+    // Already hex (with optional 0x prefix)
+    const hexNoPrefix = s.startsWith("0x") ? s.slice(2) : s;
+    if (/^[0-9a-fA-F]{64}$/.test(hexNoPrefix))
+        return hexNoPrefix;
+    if (/^[0-9a-fA-F]{128}$/.test(hexNoPrefix)) {
+        return hexNoPrefix.slice(0, 64); // 64-byte keypair → first 32 bytes secret
     }
-    else if (chain === "evm") {
-        const { ethers } = await import("ethers");
-        const w = ethers.Wallet.createRandom();
-        const walletName = name || "default-evm";
-        const store = loadStore();
-        if (store.wallets[walletName]) {
-            console.error(chalk.red(`\n  Wallet "${walletName}" already exists.\n`));
-            process.exit(1);
+    // JSON byte array
+    if (s.startsWith("[")) {
+        let arr;
+        try {
+            arr = JSON.parse(s);
         }
-        store.wallets[walletName] = { name: walletName, type: "evm", address: w.address, privateKey: w.privateKey, createdAt: new Date().toISOString() };
-        if (!store.active.hyperliquid)
-            store.active.hyperliquid = walletName;
-        if (!store.active.lighter)
-            store.active.lighter = walletName;
-        saveStore(store);
-        setEnvVar("HL_PRIVATE_KEY", w.privateKey);
-        setEnvVar("LIGHTER_PRIVATE_KEY", w.privateKey);
-        if (isJson())
-            return printJson(jsonOk({ name: walletName, type: "evm", address: w.address, legacy: true }));
-        console.log(chalk.yellow.bold("\n  [Legacy] EVM Wallet Generated\n"));
-        console.log(`  Name:    ${chalk.white.bold(walletName)}`);
-        console.log(`  Address: ${chalk.green(w.address)}`);
-        console.log(chalk.gray(`  Saved:   ~/.perp/.env + wallets.json (unencrypted)`));
-        console.log(chalk.yellow(`\n  Consider: ${chalk.cyan("perp wallet migrate")} to move to OWS vault\n`));
+        catch {
+            // Never surface the parser message: V8 echoes the input (the secret) in it.
+            throw new Error("Invalid Solana JSON byte array (not valid JSON)");
+        }
+        if (arr.length === 64)
+            return Buffer.from(arr.slice(0, 32)).toString("hex");
+        if (arr.length === 32)
+            return Buffer.from(arr).toString("hex");
+        throw new Error(`Invalid Solana JSON byte array length: ${arr.length} (expected 32 or 64)`);
     }
-    else {
-        console.error(chalk.red(`\n  Unknown chain: ${chain}. Use: solana or evm\n`));
-        process.exit(1);
+    // base58 (Phantom export — typically 87-88 chars for 64-byte keypair)
+    try {
+        const decoded = bs58.decode(s);
+        if (decoded.length === 64)
+            return Buffer.from(decoded.slice(0, 32)).toString("hex");
+        if (decoded.length === 32)
+            return Buffer.from(decoded).toString("hex");
+        throw new Error(`Invalid Solana base58 byte length: ${decoded.length} (expected 32 or 64)`);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Invalid Solana key — expected hex (64 chars), base58 (Phantom export), or JSON byte array. Inner: ${msg}`);
     }
 }
-async function _legacyImport(chain, privateKey, name, isJson) {
-    if (chain === "solana") {
-        const { Keypair } = await import("@solana/web3.js");
-        const bs58 = (await import("bs58")).default;
-        let address, normalizedKey;
-        try {
-            try {
-                const bytes = bs58.decode(privateKey);
-                const kp = Keypair.fromSecretKey(bytes);
-                address = kp.publicKey.toBase58();
-                normalizedKey = bs58.encode(kp.secretKey);
-            }
-            catch {
-                const arr = JSON.parse(privateKey);
-                const kp = Keypair.fromSecretKey(Uint8Array.from(arr));
-                address = kp.publicKey.toBase58();
-                normalizedKey = bs58.encode(kp.secretKey);
-            }
-        }
-        catch {
-            console.error(chalk.red("\n  Invalid Solana private key.\n"));
-            process.exit(1);
-            return;
-        }
-        const store = loadStore();
-        if (store.wallets[name]) {
-            console.error(chalk.red(`\n  Wallet "${name}" already exists.\n`));
-            process.exit(1);
-        }
-        store.wallets[name] = { name, type: "solana", address, privateKey: normalizedKey, createdAt: new Date().toISOString() };
-        if (!store.active.pacifica)
-            store.active.pacifica = name;
-        saveStore(store);
-        setEnvVar("PACIFICA_PRIVATE_KEY", normalizedKey);
-        if (isJson())
-            return printJson(jsonOk({ name, type: "solana", address, legacy: true }));
-        console.log(chalk.yellow.bold("\n  [Legacy] Solana Key Imported\n"));
-        console.log(`  Name:    ${chalk.white.bold(name)}`);
-        console.log(`  Address: ${chalk.green(address)}\n`);
+/**
+ * Import key material into the OWS vault as wallet `name` — the single import
+ * path shared by `wallet import` and `perp setup`. Never logs key material.
+ */
+/**
+ * Strip secret material from an error message before it is shown/logged: the exact secret
+ * strings plus any long hex / base58 / byte-array run (keys never reach output — Rule #3).
+ */
+export function redactSecrets(message, secrets) {
+    let out = message;
+    for (const sec of secrets) {
+        const t = sec.trim();
+        for (const v of [t, t.replace(/^0x/i, "")])
+            if (v.length >= 8)
+                out = out.split(v).join("[redacted]");
     }
-    else if (chain === "evm") {
-        const { ethers } = await import("ethers");
-        const pk = privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`;
-        let address;
-        try {
-            address = new ethers.Wallet(pk).address;
-        }
-        catch {
-            console.error(chalk.red("\n  Invalid EVM private key.\n"));
-            process.exit(1);
-            return;
-        }
-        const store = loadStore();
-        if (store.wallets[name]) {
-            console.error(chalk.red(`\n  Wallet "${name}" already exists.\n`));
-            process.exit(1);
-        }
-        store.wallets[name] = { name, type: "evm", address, privateKey: pk, createdAt: new Date().toISOString() };
-        if (!store.active.hyperliquid)
-            store.active.hyperliquid = name;
-        if (!store.active.lighter)
-            store.active.lighter = name;
-        saveStore(store);
-        setEnvVar("HL_PRIVATE_KEY", pk);
-        setEnvVar("LIGHTER_PRIVATE_KEY", pk);
-        if (isJson())
-            return printJson(jsonOk({ name, type: "evm", address, legacy: true }));
-        console.log(chalk.yellow.bold("\n  [Legacy] EVM Key Imported\n"));
-        console.log(`  Name:    ${chalk.white.bold(name)}`);
-        console.log(`  Address: ${chalk.green(address)}\n`);
+    return out
+        .replace(/(0x)?[0-9a-fA-F]{32,}/g, "[redacted]")
+        .replace(/[1-9A-HJ-NP-Za-km-z]{40,}/g, "[redacted]")
+        .replace(/\[\s*\d{1,3}(\s*,\s*\d{1,3}){7,}[^\]]*\]?/g, "[redacted]");
+}
+/** Read all of a piped (non-TTY) stdin. */
+function readAllStdin() {
+    return new Promise((resolveRead, reject) => {
+        const chunks = [];
+        process.stdin.setEncoding("utf-8");
+        process.stdin.on("data", (c) => chunks.push(typeof c === "string" ? c : c.toString("utf-8")));
+        process.stdin.on("end", () => resolveRead(chunks.join("")));
+        process.stdin.on("error", reject);
+    });
+}
+export async function importOwsWallet(name, passphrase, input) {
+    const secrets = input.kind === "mnemonic" ? [input.mnemonic] : input.kind === "dual" ? [input.evm, input.solana] : [input.key];
+    try {
+        return importOwsWalletRaw(name, passphrase, input);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new PerpError("INVALID_PARAMS", `Import failed: ${redactSecrets(msg, secrets)}`, {
+            remediation: "Check the key / mnemonic format and retry (the input is never echoed)",
+        });
     }
-    else {
-        console.error(chalk.red(`\n  Unknown chain: ${chain}. Use: solana or evm\n`));
-        process.exit(1);
+}
+function importOwsWalletRaw(name, passphrase, input) {
+    const ows = loadOws();
+    if (input.kind === "mnemonic")
+        return ows.importWalletMnemonic(name, input.mnemonic, passphrase);
+    if (input.kind === "dual") {
+        // Dual-curve: both explicit keys (OWS 1.3+ API — both must be present)
+        return ows.importWalletPrivateKey(name, "", // ignored when both secp256k1Key and ed25519Key are provided
+        passphrase, undefined, undefined, input.evm, normalizeSolanaKey(input.solana));
     }
+    const key = input.chain === "solana" ? normalizeSolanaKey(input.key) : input.key;
+    return ows.importWalletPrivateKey(name, key, passphrase, undefined, input.chain);
 }
-// ── Commands ──────────────────────────────────────────────────
-export function registerWalletCommands(program, isJson, getAdapter, getPacificaAdapter) {
+export function registerWalletCommands(program, isJson, getAdapter, getPacificaAdapter, getAdapterForExchange) {
     const wallet = program.command("wallet").description("Wallet management & on-chain balances");
     // ── generate (OWS — creates multi-chain wallet in encrypted vault) ──
     wallet
@@ -324,12 +286,12 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .description("Generate a new wallet (OWS encrypted vault, multi-chain)")
         .option("--words <count>", "Mnemonic word count (12 or 24)", "12")
         .option("--show-mnemonic", "Display the mnemonic phrase (CAUTION)")
-        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
-        .option("--legacy <chain>", "Legacy mode: generate solana or evm key (unencrypted)")
+        .addOption(deprecatedPassphraseOption()).hook("preAction", warnDeprecatedPassphrase)
+        .addOption(new Option("--legacy <chain>", "Removed — refused (raw keys are never written to ~/.perp/.env)").hideHelp())
         .action(async (name, opts, command) => {
-        // Legacy mode for backward compat
-        if (opts.legacy) {
-            return _legacyGenerate(opts.legacy, name, isJson);
+        if (opts.legacy !== undefined) {
+            await withJsonErrors(isJson(), async () => { throw legacyWriteRemoved("generate"); });
+            return;
         }
         const walletName = name || "default";
         try {
@@ -399,128 +361,73 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
     // Solana key normalization: OWS SDK expects 32-byte hex secret. Phantom
     // exports base58 (88 chars, 64-byte keypair = secret + public). Auto-detect
     // base58/JSON-array/hex and normalize to 32-byte hex secret.
+    // SSOT Rule #3: keys are never accepted on argv (shell history / process list) —
+    // hidden TTY prompt or stdin pipe only, matching `wallet set`.
     wallet
         .command("import [privateKey]")
-        .description("Import a private key into OWS encrypted vault (use --evm/--solana to import both curves at once)")
+        .description("Import a private key or mnemonic into the OWS encrypted vault (key via hidden prompt or stdin — never argv)")
         .option("--name <name>", "Wallet alias name", "imported")
-        .option("--chain <chain>", "Key type for positional <privateKey>: evm (default) or solana", "evm")
-        .option("--evm <hex>", "EVM (secp256k1) private key — use with --solana to import both curves")
-        .option("--solana <key>", "Solana (ed25519) private key — accepts hex (64), base58 (Phantom export), or JSON byte array. Use with --evm to import both curves")
-        .option("--mnemonic", "Import as mnemonic phrase instead of private key")
-        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
-        .option("--legacy <chain>", "Legacy mode: import to wallets.json (solana or evm)")
-        .action(async (privateKey, opts, command) => {
-        // Legacy mode (positional only)
-        if (opts.legacy) {
-            if (!privateKey) {
-                const msg = "--legacy mode requires a positional <privateKey>";
-                if (isJson()) {
-                    const { jsonError } = await import("../utils.js");
-                    return printJson(jsonError("OWS_ERROR", msg));
-                }
-                console.error(chalk.red(`\n  Error: ${msg}\n`));
-                process.exit(1);
-            }
-            return _legacyImport(opts.legacy, privateKey, opts.name, isJson);
-        }
-        // Validation: input mode is exactly one of (positional | --evm/--solana flags | mnemonic)
-        const hasPositional = !!privateKey;
-        const hasFlagKeys = !!(opts.evm || opts.solana);
-        if (!hasPositional && !hasFlagKeys) {
-            const msg = "Provide a <privateKey> argument OR --evm/--solana flag(s)";
-            if (isJson()) {
-                const { jsonError } = await import("../utils.js");
-                return printJson(jsonError("OWS_ERROR", msg));
-            }
-            console.error(chalk.red(`\n  Error: ${msg}\n`));
-            process.exit(1);
-        }
-        if (hasPositional && hasFlagKeys) {
-            const msg = "Cannot mix positional <privateKey> with --evm/--solana flags. Use one input style.";
-            if (isJson()) {
-                const { jsonError } = await import("../utils.js");
-                return printJson(jsonError("OWS_ERROR", msg));
+        .option("--chain <chain>", "Key type: evm (default), solana, or dual (EVM + Solana keys: two prompts, or two stdin lines EVM first)", "evm")
+        .option("--mnemonic", "Import a mnemonic phrase instead of a private key")
+        .addOption(deprecatedPassphraseOption()).hook("preAction", warnDeprecatedPassphrase)
+        .addOption(new Option("--evm <hex>", "Removed — refused (key on argv); use --chain evm|dual").hideHelp())
+        .addOption(new Option("--solana <key>", "Removed — refused (key on argv); use --chain solana|dual").hideHelp())
+        .addOption(new Option("--legacy <chain>", "Removed — refused (raw keys are never written to ~/.perp/.env)").hideHelp())
+        .action(async (argvKey, opts, command) => {
+        await withJsonErrors(isJson(), async () => {
+            if (opts.legacy !== undefined)
+                throw legacyWriteRemoved("import");
+            if (argvKey !== undefined || opts.evm !== undefined || opts.solana !== undefined) {
+                throw new PerpError("INVALID_PARAMS", "Refusing a private key / mnemonic on the command line: it is visible in shell history and the process list", {
+                    remediation: "Enter it at the hidden prompt (perp wallet import --name <name> [--chain evm|solana|dual] [--mnemonic]) or pipe it on stdin (e.g. pbpaste | OWS_PASSPHRASE=... perp wallet import --name <name>). Clear the key from your shell history.",
+                });
             }
-            console.error(chalk.red(`\n  Error: ${msg}\n`));
-            process.exit(1);
-        }
-        if (opts.mnemonic && hasFlagKeys) {
-            const msg = "--mnemonic cannot be combined with --evm/--solana";
-            if (isJson()) {
-                const { jsonError } = await import("../utils.js");
-                return printJson(jsonError("OWS_ERROR", msg));
+            const chain = opts.chain;
+            if (chain !== "evm" && chain !== "solana" && chain !== "dual") {
+                throw new PerpError("INVALID_PARAMS", `Unknown --chain "${chain}"`, { remediation: "Use --chain evm, solana, or dual" });
             }
-            console.error(chalk.red(`\n  Error: ${msg}\n`));
-            process.exit(1);
-        }
-        try {
-            const ows = loadOws();
-            // Auto-normalize Solana keys: accept hex / base58 (Phantom) / JSON byte array
-            const bs58 = (await import("bs58")).default;
-            const normalizeSolana = (input) => {
-                const s = input.trim();
-                // Already hex (with optional 0x prefix)
-                const hexNoPrefix = s.startsWith("0x") ? s.slice(2) : s;
-                if (/^[0-9a-fA-F]{64}$/.test(hexNoPrefix))
-                    return hexNoPrefix;
-                if (/^[0-9a-fA-F]{128}$/.test(hexNoPrefix)) {
-                    return hexNoPrefix.slice(0, 64); // 64-byte keypair → first 32 bytes secret
-                }
-                // JSON byte array
-                if (s.startsWith("[")) {
-                    const arr = JSON.parse(s);
-                    if (arr.length === 64)
-                        return Buffer.from(arr.slice(0, 32)).toString("hex");
-                    if (arr.length === 32)
-                        return Buffer.from(arr).toString("hex");
-                    throw new Error(`Invalid Solana JSON byte array length: ${arr.length} (expected 32 or 64)`);
-                }
-                // base58 (Phantom export — typically 87-88 chars for 64-byte keypair)
-                try {
-                    const decoded = bs58.decode(s);
-                    if (decoded.length === 64)
-                        return Buffer.from(decoded.slice(0, 32)).toString("hex");
-                    if (decoded.length === 32)
-                        return Buffer.from(decoded).toString("hex");
-                    throw new Error(`Invalid Solana base58 byte length: ${decoded.length} (expected 32 or 64)`);
-                }
-                catch (err) {
-                    const msg = err instanceof Error ? err.message : String(err);
-                    throw new Error(`Invalid Solana key — expected hex (64 chars), base58 (Phantom export), or JSON byte array. Inner: ${msg}`);
-                }
-            };
-            // Resolve vault passphrase via the standard 3-path resolver (--passphrase
-            // > OWS_PASSPHRASE env > stdin pipe). When stdin is a TTY and nothing was
-            // provided, the resolver returns null; fall back to "" to preserve the
-            // historical "no passphrase" default for interactive use.
-            //
-            // optsWithGlobals() merges parent + subcommand options — see the
-            // wallet generate action for context. Without it, the parent program's
-            // --passphrase shadows the subcommand's same-named flag.
-            const merged = command.optsWithGlobals();
-            const { resolvePassphrase } = await import("../agent-wallet/passphrase.js");
-            const pp = (await resolvePassphrase({ flag: merged.passphrase ?? opts.passphrase })) ?? "";
-            let w;
-            if (opts.mnemonic) {
-                w = ows.importWalletMnemonic(opts.name, privateKey, pp);
+            if (opts.mnemonic && chain !== "evm") {
+                throw new PerpError("INVALID_PARAMS", "--mnemonic derives every chain itself and cannot be combined with --chain solana|dual", {
+                    remediation: "Drop --chain: perp wallet import --mnemonic --name <name>",
+                });
             }
-            else if (opts.evm && opts.solana) {
-                // Dual-curve: both explicit keys (OWS 1.3+ API — both must be present)
-                w = ows.importWalletPrivateKey(opts.name, "", // ignored when both secp256k1Key and ed25519Key are provided
-                pp, undefined, undefined, opts.evm, normalizeSolana(opts.solana));
+            const { promptHidden } = await import("./agent.js");
+            const piped = process.stdin.isTTY !== true;
+            const labels = opts.mnemonic ? ["mnemonic phrase"] : chain === "dual" ? ["EVM private key", "Solana private key"] : [`${chain === "evm" ? "EVM" : "Solana"} private key`];
+            let secrets;
+            if (piped) {
+                const lines = (await readAllStdin()).split(/\r?\n/).map(l => l.trim()).filter(l => l.length > 0);
+                secrets = opts.mnemonic ? [lines.join(" ")] : lines;
             }
-            else if (opts.evm) {
-                // Single EVM via flag — same as positional + --chain evm
-                w = ows.importWalletPrivateKey(opts.name, opts.evm, pp, undefined, "evm");
+            else {
+                secrets = [];
+                for (const label of labels)
+                    secrets.push((await promptHidden(`${label} (hidden): `)).trim());
             }
-            else if (opts.solana) {
-                // Single Solana via flag — same as positional + --chain solana
-                w = ows.importWalletPrivateKey(opts.name, normalizeSolana(opts.solana), pp, undefined, "solana");
+            if (secrets.length !== labels.length || secrets.some(x => x.length === 0)) {
+                throw new PerpError("INVALID_PARAMS", `Expected ${labels.join(" + ")} on stdin / at the prompt (${labels.length === 2 ? "two lines, EVM first" : "one line"}); received ${secrets.filter(x => x.length > 0).length}`, {
+                    remediation: "Enter it at the hidden prompt, or pipe it: pbpaste | OWS_PASSPHRASE=... perp wallet import --name <name>",
+                });
             }
+            // Vault passphrase: --passphrase > OWS_PASSPHRASE > hidden prompt. Piped stdin
+            // carries the key, so a non-interactive run must name the passphrase explicitly.
+            // optsWithGlobals(): the root program's --passphrase shadows the subcommand's.
+            const flagPp = command.optsWithGlobals().passphrase;
+            let pp;
+            if (flagPp !== undefined)
+                pp = flagPp;
+            else if ("OWS_PASSPHRASE" in process.env)
+                pp = process.env.OWS_PASSPHRASE ?? "";
+            else if (!piped)
+                pp = await promptHidden("OWS vault passphrase (hidden, empty = none): ");
             else {
-                const keyArg = opts.chain === "solana" ? normalizeSolana(privateKey) : privateKey;
-                w = ows.importWalletPrivateKey(opts.name, keyArg, pp, undefined, opts.chain);
+                throw new PerpError("PASSPHRASE_REQUIRED", "stdin carries the key, so the vault passphrase must come from OWS_PASSPHRASE or --passphrase", {
+                    remediation: `pbpaste | OWS_PASSPHRASE="$PP" perp wallet import --name ${opts.name}  (use OWS_PASSPHRASE= for an unencrypted vault wallet)`,
+                });
             }
+            const w = await importOwsWallet(opts.name, pp, opts.mnemonic ? { kind: "mnemonic", mnemonic: secrets[0] }
+                : chain === "dual" ? { kind: "dual", evm: secrets[0], solana: secrets[1] }
+                    : { kind: "single", key: secrets[0], chain });
             // Set as active wallet if none set
             const { loadSettings: ls, saveSettings: ss } = await import("../settings.js");
             const settings = ls();
@@ -545,16 +452,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
                 console.log(chalk.cyan(`  Active: yes (used by all exchanges)`));
             }
             console.log();
-        }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            if (isJson()) {
-                const { jsonError } = await import("../utils.js");
-                return printJson(jsonError("OWS_ERROR", msg));
-            }
-            console.error(chalk.red(`\n  Error: ${msg}\n`));
-            process.exit(1);
-        }
+        });
     });
     // ── use (set active wallet — OWS first, legacy fallback) ──
     wallet
@@ -590,7 +488,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         if (!entry) {
             console.error(chalk.red(`\n  Wallet "${name}" not found in OWS vault or legacy store.\n`));
             console.error(chalk.gray(`  Create: perp wallet generate ${name}`));
-            console.error(chalk.gray(`  Import: perp wallet import <key> -n ${name}\n`));
+            console.error(chalk.gray(`  Import: perp wallet import --name ${name}  (hidden prompt / stdin)\n`));
             process.exit(1);
         }
         const exchanges = entry.type === "solana" ? ["pacifica"] : ["hyperliquid", "lighter"];
@@ -604,83 +502,92 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         console.log(chalk.gray(`  Address: ${entry.address}`));
         console.log(chalk.yellow(`  Note: consider migrating to OWS: perp wallet migrate\n`));
     });
-    // ── set (configure exchange key → ~/.perp/.env) ──
+    // ── set (import an exchange key into the OWS vault → active wallet) ──
+    //
+    // SSOT Rule #3: the key goes into the encrypted OWS vault, never ~/.perp/.env,
+    // and never via argv (shell history / process list). Input: hidden TTY prompt,
+    // or stdin pipe. Keys already in a legacy ~/.perp/.env keep working (read path unchanged).
     wallet
-        .command("set <exchange> <key>")
-        .description("Set private key for an exchange")
+        .command("set <exchange> [key]")
+        .description("Import an exchange private key into the OWS vault and make it the active wallet (key via hidden prompt or stdin — never argv)")
+        .option("--name <name>", "OWS wallet name (default: the exchange id, e.g. hyperliquid)")
         .option("--default", "Also set as default exchange")
-        .action(async (exchange, key, opts) => {
-        // Resolve alias (hl → hyperliquid, pac → pacifica, lt → lighter, ast → aster)
-        const aliases = { hl: "hyperliquid", pac: "pacifica", lt: "lighter", ast: "aster" };
-        const resolved = aliases[exchange.toLowerCase()] || exchange.toLowerCase();
-        const info = EXCHANGE_ENV_MAP[resolved];
-        if (!info) {
-            if (isJson()) {
-                const { jsonError } = await import("../utils.js");
-                return printJson(jsonError("INVALID_PARAMS", `Unknown exchange: ${exchange}. Use: pacifica, hyperliquid, lighter, aster (or hl, pac, lt, ast).`));
-            }
-            console.error(chalk.red(`\n  Unknown exchange: ${exchange}`));
-            console.error(chalk.gray(`  Use: pacifica, hyperliquid, lighter, aster (or hl, pac, lt, ast).\n`));
-            process.exit(1);
-        }
-        const { valid, address } = await validateKey(info.chain, key);
-        if (!valid) {
-            if (isJson()) {
-                const { jsonError } = await import("../utils.js");
-                return printJson(jsonError("INVALID_PARAMS", `Invalid ${info.chain} private key`));
+        .action(async (exchange, argvKey, opts, command) => {
+        await withJsonErrors(isJson(), async () => {
+            if (argvKey !== undefined) {
+                throw new PerpError("INVALID_PARAMS", "Refusing a private key on the command line: it is visible in shell history and the process list", {
+                    remediation: `Enter it at the hidden prompt (perp wallet set ${exchange}) or pipe it on stdin (e.g. pbpaste | OWS_PASSPHRASE=... perp wallet set ${exchange}). Clear the key from your shell history.`,
+                });
             }
-            console.error(chalk.red(`\n  Invalid ${info.chain} private key.\n`));
-            process.exit(1);
-        }
-        const normalized = info.chain === "evm"
-            ? (key.startsWith("0x") ? key : `0x${key}`)
-            : key;
-        setEnvVar(info.envKey, normalized);
-        if (opts.default) {
-            const settings = loadSettings();
-            settings.defaultExchange = resolved;
-            saveSettings(settings);
-        }
-        // Auto-setup Lighter API key if setting lighter PK
-        let lighterApiSetup = {};
-        if (resolved === "lighter") {
-            try {
-                const { LighterAdapter } = await import("../exchanges/lighter.js");
-                const adapter = new LighterAdapter(normalized);
-                await adapter.init();
-                const apiKeyIndex = 4;
-                const { privateKey: apiKey } = await adapter.setupApiKey(apiKeyIndex);
-                // SSOT Rule #3: persist L2 key in encrypted keystore.
-                // accountIndex/apiKeyIndex live in settings.agents.lighter and don't
-                // need env duplication.
-                const { saveLighterKey } = await import("../agent-wallet/lighter-keystore.js");
-                saveLighterKey(adapter.accountIndex, apiKeyIndex, apiKey, "");
-                lighterApiSetup = { apiKey, accountIndex: adapter.accountIndex };
+            // Resolve alias (hl → hyperliquid, pac → pacifica, lt → lighter, ast → aster)
+            const aliases = { hl: "hyperliquid", pac: "pacifica", lt: "lighter", ast: "aster" };
+            const resolved = aliases[exchange.toLowerCase()] || exchange.toLowerCase();
+            const info = EXCHANGE_ENV_MAP[resolved];
+            if (!info) {
+                throw new PerpError("INVALID_PARAMS", `Unknown exchange: ${exchange}`, {
+                    remediation: "Use: pacifica, hyperliquid, lighter, aster (or hl, pac, lt, ast). Lighter RH / Ondo / Arcus use: perp wallet agent approve <lighter-rh|ondo|arcus>; QFEX: perp wallet agent import qfex.",
+                });
             }
-            catch (e) {
-                lighterApiSetup = { error: e instanceof Error ? e.message : String(e) };
+            const { promptHidden } = await import("./agent.js");
+            const piped = process.stdin.isTTY !== true;
+            const key = (piped ? await readAllStdin() : await promptHidden(`${resolved} private key (hidden): `)).trim();
+            if (!key) {
+                throw new PerpError("INVALID_PARAMS", "No private key received", {
+                    remediation: `Enter it at the hidden prompt, or pipe it: pbpaste | perp wallet set ${exchange}`,
+                });
             }
-        }
-        if (isJson())
-            return printJson(jsonOk({
-                exchange: resolved, address, envFile: ENV_FILE, default: !!opts.default,
-                ...(resolved === "lighter" && { lighterApiKey: lighterApiSetup }),
-            }));
-        console.log(chalk.green(`\n  ${resolved} configured.`));
-        console.log(`  Address:  ${chalk.green(address)}`);
-        console.log(`  Saved to: ${chalk.gray("~/.perp/.env")}`);
-        if (opts.default)
-            console.log(`  Default:  ${chalk.cyan(resolved)}`);
-        if (resolved === "lighter") {
-            if (lighterApiSetup.apiKey) {
-                console.log(chalk.green(`  API Key:  auto-registered (index: ${lighterApiSetup.accountIndex})`));
+            const { valid, address } = await validateKey(info.chain, key);
+            if (!valid) {
+                throw new PerpError("INVALID_PARAMS", `Invalid ${info.chain} private key`, {
+                    remediation: info.chain === "evm" ? "Expected 32-byte hex (0x-prefixed or not)" : "Expected a Solana secret key (base58, hex, or JSON byte array)",
+                });
             }
+            // Vault passphrase: --passphrase > OWS_PASSPHRASE > hidden prompt. Piped stdin
+            // carries the key, so a non-interactive run must name the passphrase explicitly.
+            const flagPp = command.optsWithGlobals().passphrase;
+            let passphrase;
+            if (flagPp !== undefined)
+                passphrase = flagPp;
+            else if ("OWS_PASSPHRASE" in process.env)
+                passphrase = process.env.OWS_PASSPHRASE ?? "";
+            else if (!piped)
+                passphrase = await promptHidden("OWS vault passphrase (hidden, empty = none): ");
             else {
-                console.log(chalk.yellow(`  API Key:  setup failed — ${lighterApiSetup.error}`));
-                console.log(chalk.gray(`  You can retry: perp wallet agent approve lighter`));
+                throw new PerpError("PASSPHRASE_REQUIRED", "stdin carries the key, so the vault passphrase must come from OWS_PASSPHRASE or --passphrase", {
+                    remediation: `pbpaste | OWS_PASSPHRASE="$PP" perp wallet set ${exchange}  (use OWS_PASSPHRASE= for an unencrypted vault wallet)`,
+                });
             }
-        }
-        console.log();
+            const name = opts.name ?? resolved;
+            const w = await importOwsWallet(name, passphrase, {
+                kind: "single",
+                key: info.chain === "evm" && !key.startsWith("0x") ? `0x${key}` : key,
+                chain: info.chain,
+            });
+            const settings = loadSettings();
+            const previousActiveWallet = settings.owsActiveWallet || null;
+            settings.owsActiveWallet = name;
+            if (opts.default)
+                settings.defaultExchange = resolved;
+            saveSettings(settings);
+            // No implicit Lighter API-key registration here (it signed a mainnet ChangePubKey on slot 4
+            // and echoed the L2 key): trading needs an explicit `perp wallet agent approve lighter`.
+            const lighterNextStep = "perp wallet agent approve lighter";
+            if (isJson())
+                return printJson(jsonOk({
+                    exchange: resolved, address, owsWallet: w.name, activeWallet: name, previousActiveWallet, default: !!opts.default,
+                    ...(resolved === "lighter" && { lighterApiKey: { registered: false, nextStep: lighterNextStep } }),
+                }));
+            console.log(chalk.green(`\n  ${resolved} key imported into the OWS vault.`));
+            console.log(`  Address:  ${chalk.green(address)}`);
+            console.log(`  Wallet:   ${chalk.white.bold(w.name)} ${chalk.gray("(encrypted in ~/.ows/)")}`);
+            console.log(`  Active:   ${chalk.cyan(name)} (used by all exchanges)${previousActiveWallet && previousActiveWallet !== name ? chalk.yellow(` — was ${previousActiveWallet}; switch back: perp wallet use ${previousActiveWallet}`) : ""}`);
+            if (opts.default)
+                console.log(`  Default:  ${chalk.cyan(resolved)}`);
+            if (resolved === "lighter") {
+                console.log(chalk.yellow(`  API Key:  not registered — to trade, run: ${lighterNextStep}`));
+            }
+            console.log();
+        });
     });
     // ── show (show configured exchanges with public addresses) ──
     wallet
@@ -766,13 +673,17 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         if (isJson()) {
             return printJson(jsonOk({
                 ows: { wallets: owsWallets, active: activeOwsWallet },
-                legacy: { wallets: store.wallets, active: store.active },
+                // Public fields only — wallets.json entries hold raw private keys (never printed).
+                legacy: {
+                    wallets: Object.fromEntries(Object.entries(store.wallets).map(([k, w]) => [k, { name: w.name, type: w.type, address: w.address, createdAt: w.createdAt }])),
+                    active: store.active,
+                },
             }));
         }
         if (owsWallets.length === 0 && legacyEntries.length === 0) {
             console.log(chalk.gray("\n  No wallets found."));
             console.log(chalk.gray(`  Create: ${chalk.cyan("perp wallet generate [name]")}`));
-            console.log(chalk.gray(`  Import: ${chalk.cyan("perp wallet import <key>")}\n`));
+            console.log(chalk.gray(`  Import: ${chalk.cyan("perp wallet import --name <name>")}\n`));
             return;
         }
         if (owsWallets.length > 0) {
@@ -886,7 +797,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
     // ── balance (by wallet name) ──
     wallet
         .command("balance [name]")
-        .description("Check on-chain balance for a saved wallet (or active wallet)")
+        .description("On-chain balances for a saved wallet (or the active one): gas token + USDC / USDT on Arbitrum, Ethereum, Base, BNB Chain, Robinhood Chain (USDG) and Solana")
         .option("--testnet", "Use testnet", false)
         .action(async (name, opts) => {
         const store = loadStore();
@@ -929,8 +840,35 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
             const activeEntries = Object.entries(store.active)
                 .map(([ex, wn]) => ({ exchange: ex, ...store.wallets[wn] }))
                 .filter((e) => e.address);
-            // Fallback to .env-based wallets when no named wallets are active
+            // OWS-aware path: vault-based setups have no legacy `active` mapping
+            // (it's empty by design — owsActiveWallet replaces per-exchange
+            // active wallets). Fetch on-chain balances for both EVM and Solana
+            // accounts of the active OWS vault BEFORE falling through to the
+            // legacy .env path.
             if (activeEntries.length === 0) {
+                const settings = loadSettings();
+                if (settings.owsActiveWallet) {
+                    // Only loading the OWS vault may fall through to the env path; balance reads report
+                    // their own per-token errors and any other failure propagates.
+                    let owsAccounts = null;
+                    try {
+                        const { loadOws } = await import("../signer/ows-loader.js");
+                        owsAccounts = loadOws().getWallet(settings.owsActiveWallet).accounts;
+                    }
+                    catch {
+                        owsAccounts = null; // OWS module unavailable or vault missing — use the env path below
+                    }
+                    if (owsAccounts !== null) {
+                        const results = [];
+                        for (const acct of owsAccounts) {
+                            const vm = acct.chainId.startsWith("solana:") ? "solana" : acct.chainId.startsWith("eip155:") ? "evm" : null;
+                            if (vm === null)
+                                continue;
+                            results.push(await balanceEntry({ wallet: settings.owsActiveWallet }, vm, acct.address, opts.testnet));
+                        }
+                        return printBalanceEntries(results, isJson());
+                    }
+                }
                 const stored = loadEnvFile();
                 const envEntries = [];
                 for (const [exchange, info] of Object.entries(EXCHANGE_ENV_MAP)) {
@@ -945,61 +883,20 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
                 }
                 if (envEntries.length === 0) {
                     if (isJson()) {
-                        printJson({ ok: false, error: { code: "INVALID_PARAMS", message: "No wallets configured. Run 'perp setup' or 'perp wallet set <exchange> <key>'." }, meta: { timestamp: new Date().toISOString() } });
+                        printJson({ ok: false, error: { code: "INVALID_PARAMS", message: "No wallets configured. Run 'perp setup' or 'perp wallet set <exchange>'." }, meta: { timestamp: new Date().toISOString() } });
                     }
                     else {
-                        console.error(chalk.gray("\n  No wallets configured. Run 'perp setup' or 'perp wallet set <exchange> <key>'.\n"));
+                        console.error(chalk.gray("\n  No wallets configured. Run 'perp setup' or 'perp wallet set <exchange>'.\n"));
                     }
                     process.exit(1);
                 }
-                for (const we of envEntries) {
-                    if (!isJson())
-                        console.log(chalk.cyan.bold(`\n  ${we.exchange} (${we.address.slice(0, 8)}...)`));
-                    const balances = we.chain === "solana"
-                        ? await getSolanaBalances(we.address, opts.testnet)
-                        : await getEvmBalances(we.address, opts.testnet);
-                    if (isJson()) {
-                        printJson(jsonOk({ exchange: we.exchange, address: we.address, balances }));
-                        continue;
-                    }
-                    const rows = balances.map((b) => [
-                        chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-"),
-                    ]);
-                    console.log(makeTable(["Token", "Balance", "USD Value"], rows));
-                }
-                console.log();
-                return;
-            }
-            for (const ae of activeEntries) {
-                if (!isJson())
-                    console.log(chalk.cyan.bold(`\n  ${ae.name} (${ae.exchange})`));
-                const balances = ae.type === "solana"
-                    ? await getSolanaBalances(ae.address, opts.testnet)
-                    : await getEvmBalances(ae.address, opts.testnet);
-                if (isJson()) {
-                    printJson(jsonOk({ wallet: ae.name, exchange: ae.exchange, balances }));
-                    continue;
-                }
-                const rows = balances.map((b) => [
-                    chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-"),
-                ]);
-                console.log(makeTable(["Token", "Balance", "USD Value"], rows));
+                return printBalanceEntries(await balanceEntries(envEntries.map(we => ({ label: { exchange: we.exchange }, vm: we.chain, address: we.address })), opts.testnet), isJson());
             }
-            console.log();
-            return;
+            return printBalanceEntries(await balanceEntries(activeEntries.map(ae => ({
+                label: { wallet: ae.name, exchange: ae.exchange }, vm: ae.type === "solana" ? "solana" : "evm", address: ae.address,
+            })), opts.testnet), isJson());
         }
-        if (!isJson())
-            console.log(chalk.cyan(`\n  Fetching balance for "${entry.name}" (${entry.address.slice(0, 8)}...)\n`));
-        const balances = entry.type === "solana"
-            ? await getSolanaBalances(entry.address, opts.testnet)
-            : await getEvmBalances(entry.address, opts.testnet);
-        if (isJson())
-            return printJson(jsonOk({ wallet: entry.name, balances }));
-        const rows = balances.map((b) => [
-            chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-"),
-        ]);
-        console.log(makeTable(["Token", "Balance", "USD Value"], rows));
-        console.log();
+        return printBalanceEntries([await balanceEntry({ wallet: entry.name }, entry.type === "solana" ? "solana" : "evm", entry.address, opts.testnet)], isJson());
     });
     // ── direct address balance (kept for convenience) ──
     wallet
@@ -1012,8 +909,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         const balances = await getSolanaBalances(address, opts.testnet);
         if (isJson())
             return printJson(jsonOk(balances));
-        const rows = balances.map((b) => [chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-")]);
-        console.log(makeTable(["Token", "Balance", "USD Value"], rows));
+        console.log(balanceTable(balances));
         console.log(chalk.gray(`\n  Network: ${opts.testnet ? "Devnet" : "Mainnet"}\n`));
     });
     wallet
@@ -1023,11 +919,10 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .action(async (address, opts) => {
         if (!isJson())
             console.log(chalk.cyan(`\n  Fetching Arbitrum balances for ${address.slice(0, 8)}...${address.slice(-4)}\n`));
-        const balances = await getEvmBalances(address, opts.testnet);
+        const balances = await getEvmBalances(address, opts.testnet, [opts.testnet ? "arbitrum-sepolia" : "arbitrum"]);
         if (isJson())
             return printJson(jsonOk(balances));
-        const rows = balances.map((b) => [chalk.white.bold(b.token), b.balance, b.usdValue || chalk.gray("-")]);
-        console.log(makeTable(["Token", "Balance", "USD Value"], rows));
+        console.log(balanceTable(balances));
         console.log(chalk.gray(`\n  Network: Arbitrum ${opts.testnet ? "Sepolia" : "One"}\n`));
     });
     // ── migrate (legacy → OWS) ──
@@ -1071,7 +966,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
                 results.push({ name: entry.name, status: "migrated" });
             }
             catch (e) {
-                results.push({ name: entry.name, status: "failed", error: e instanceof Error ? e.message : String(e) });
+                results.push({ name: entry.name, status: "failed", error: redactSecrets(e instanceof Error ? e.message : String(e), [entry.privateKey]) });
             }
         }
         // Set first migrated wallet as active if none set
@@ -1269,7 +1164,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
         .requiredOption("--wallets <names>", "Comma-separated OWS wallet names")
         .option("--policy <ids>", "Comma-separated policy IDs to enforce")
         .option("--expires <iso>", "Key expiry (ISO-8601)")
-        .option("-p, --passphrase <pass>", "Vault passphrase", "")
+        .addOption(deprecatedPassphraseOption("Vault passphrase", "-p, --passphrase <pass>").default("")).hook("preAction", warnDeprecatedPassphrase)
         .action(async (opts, command) => {
         try {
             const o = loadOws();
@@ -1391,7 +1286,8 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
             }
             // Call OWS CLI subprocess for native MoonPay deposit
             // OWS CLI writes addresses to stderr, URL to stdout
-            const owsEnv = { ...process.env, PATH: `${pathResolve(process.env.HOME || "~", ".ows", "bin")}:${process.env.PATH}` };
+            // The OWS CLI child never receives key material (SSOT Rule #3): secret env vars are stripped.
+            const owsEnv = { ...scrubSecretEnv(process.env), PATH: `${pathResolve(process.env.HOME || "~", ".ows", "bin")}:${process.env.PATH}` };
             try {
                 const { spawnSync } = await import("child_process");
                 const proc = spawnSync(owsBin, ["fund", "deposit", "--wallet", walletName, "--chain", chain], {
@@ -1450,7 +1346,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
     wallet
         .command("setup")
         .description("One-click setup: create wallet + guardrail policy + agent API key")
-        .option("-n, --name <name>", "Wallet name", "perp-trading")
+        .option("--name <name>", "Wallet name", "perp-trading")
         .option("--max-tx-usd <amount>", "Max per-transaction USD", "1000")
         .option("--max-daily-usd <amount>", "Max daily spending USD", "5000")
         .option("--skip-key", "Skip API key creation")
@@ -1647,6 +1543,8 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
     // NOTE: Distinct from `wallet key` (OWS API token) and `wallet policy`
     // (OWS guardrail). See runOwsCli comment above for the three-way split.
     registerWalletAgentCommands(wallet, isJson);
+    // ── Builder fees (off by default; settings builder.<venue>) ──
+    registerWalletBuilderCommands(wallet, isJson, getAdapterForExchange ?? null);
     // ── Manage (per-DEX exchange settings — Pacifica + Lighter) ──────────
     // Absorbed from former top-level `perp manage`. Holds exchange-specific
     // settings: margin mode, subaccount, lake, builder/referral, API keys.