perp-cli 0.11.0 → 0.12.0

package/dist/commands/wallet.js

@@ -1,13 +1,51 @@
 import chalk from "chalk";
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from "fs";
 import { resolve } from "path";
-import { createRequire } from "node:module";
 import { formatUsd, makeTable, printJson, jsonOk } from "../utils.js";
 import { EXCHANGE_ENV_MAP, validateKey, loadEnvFile, setEnvVar, ENV_FILE } from "./init.js";
 import { loadSettings, saveSettings } from "../settings.js";
-const _require = createRequire(import.meta.url);
-function loadOws() {
-    return _require("@open-wallet-standard/core");
+import { registerWalletAgentCommands } from "./agent.js";
+import { registerWalletManageCommands } from "./manage.js";
+import { loadOws } from "../signer/ows-loader.js";
+// ── OWS CLI subprocess helper (used by backup/restore/rotate) ──
+//
+// The wallet command tree exposes three different "agent" sub-namespaces;
+// they are intentionally separate because they answer three different
+// questions:
+//
+//   * `wallet agent approve <ex> ...`  — DEX-side agent registration. Sends
+//     EIP-712 approveAgent (or equivalent) to the exchange so the agent
+//     wallet can post orders on behalf of the master. State lives partly on
+//     the DEX (their auth list) and partly in `~/.perp/settings.json` under
+//     `agents.<exchange>.<name>`.
+//
+//   * `wallet key create / list / revoke`  — OWS-side API key. A vault
+//     access token (`ows_key_…`) that lets an off-host agent process invoke
+//     OWS signing primitives without holding the master passphrase. Pure
+//     OWS construct, no DEX traffic.
+//
+//   * `wallet policy create / list / show / delete`  — OWS-side guardrail.
+//     A policy attached to an OWS API key that bounds what the agent can
+//     sign (chain allowlist, per-tx USD cap, daily withdraw cap, etc.).
+//     Also pure OWS, evaluated locally before any signature is produced.
+//
+// Future maintainers: do NOT collapse these. They protect different layers.
+async function runOwsCli(args, timeout = 30000) {
+    const { resolve: pathResolve } = await import("path");
+    const { existsSync: fsExists } = await import("fs");
+    const { spawnSync } = await import("child_process");
+    const owsBin = [
+        pathResolve(process.env.HOME || "~", ".ows", "bin", "ows"),
+        "/usr/local/bin/ows",
+    ].find(p => fsExists(p));
+    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}` };
+    const proc = spawnSync(owsBin, args, { encoding: "utf-8", timeout, env: owsEnv });
+    if (proc.error)
+        throw new Error(`OWS CLI failed: ${proc.error.message}`);
+    return { stdout: (proc.stdout || "").trim(), stderr: (proc.stderr || "").trim() };
 }
 const PERP_DIR = resolve(process.env.HOME || "~", ".perp");
 const WALLETS_FILE = resolve(PERP_DIR, "wallets.json");
@@ -278,7 +316,7 @@ async function _legacyImport(chain, privateKey, name, isJson) {
     }
 }
 // ── Commands ──────────────────────────────────────────────────
-export function registerWalletCommands(program, isJson) {
+export function registerWalletCommands(program, isJson, getAdapter, getPacificaAdapter) {
     const wallet = program.command("wallet").description("Wallet management & on-chain balances");
     // ── generate (OWS — creates multi-chain wallet in encrypted vault) ──
     wallet
@@ -343,26 +381,123 @@ export function registerWalletCommands(program, isJson) {
         }
     });
     // ── import (OWS by default — imports key into encrypted vault) ──
+    //
+    // 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.
     wallet
-        .command("import <privateKey>")
-        .description("Import a private key into OWS encrypted vault")
+        .command("import [privateKey]")
+        .description("Import a private key into OWS encrypted vault (use --evm/--solana to import both curves at once)")
         .option("--name <name>", "Wallet alias name", "imported")
-        .option("--chain <chain>", "Key type: evm (default) or solana", "evm")
+        .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>", "OWS vault encryption passphrase (default: empty / OWS_PASSPHRASE env)")
         .option("--legacy <chain>", "Legacy mode: import to wallets.json (solana or evm)")
         .action(async (privateKey, opts) => {
-        // Legacy mode
+        // 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));
+            }
+            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));
+            }
+            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 (precedence: --passphrase > OWS_PASSPHRASE env > "")
+            const pp = opts.passphrase
+                ?? (("OWS_PASSPHRASE" in process.env) ? (process.env["OWS_PASSPHRASE"] ?? "") : "");
             let w;
             if (opts.mnemonic) {
-                w = ows.importWalletMnemonic(opts.name, privateKey);
+                w = ows.importWalletMnemonic(opts.name, privateKey, pp);
+            }
+            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));
+            }
+            else if (opts.evm) {
+                // Single EVM via flag — same as positional + --chain evm
+                w = ows.importWalletPrivateKey(opts.name, opts.evm, pp, undefined, "evm");
+            }
+            else if (opts.solana) {
+                // Single Solana via flag — same as positional + --chain solana
+                w = ows.importWalletPrivateKey(opts.name, normalizeSolana(opts.solana), pp, undefined, "solana");
             }
             else {
-                w = ows.importWalletPrivateKey(opts.name, privateKey, "", undefined, opts.chain);
+                const keyArg = opts.chain === "solana" ? normalizeSolana(privateKey) : privateKey;
+                w = ows.importWalletPrivateKey(opts.name, keyArg, pp, undefined, opts.chain);
             }
             // Set as active wallet if none set
             const { loadSettings: ls, saveSettings: ss } = await import("../settings.js");
@@ -493,24 +628,21 @@ export function registerWalletCommands(program, isJson) {
                 await adapter.init();
                 const apiKeyIndex = 4;
                 const { privateKey: apiKey } = await adapter.setupApiKey(apiKeyIndex);
-                setEnvVar("LIGHTER_API_KEY", apiKey);
-                setEnvVar("LIGHTER_ACCOUNT_INDEX", String(adapter.accountIndex));
-                setEnvVar("LIGHTER_API_KEY_INDEX", String(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 };
             }
             catch (e) {
                 lighterApiSetup = { error: e instanceof Error ? e.message : String(e) };
             }
         }
-        const settings = loadSettings();
-        const referralHint = !settings.referrals
-            ? { referrals: false, hint: "Optional: 'perp settings referrals on' to support perp-cli development (no extra fees — exchange rebates only)" }
-            : undefined;
         if (isJson())
             return printJson(jsonOk({
                 exchange: resolved, address, envFile: ENV_FILE, default: !!opts.default,
                 ...(resolved === "lighter" && { lighterApiKey: lighterApiSetup }),
-                ...(referralHint && { referralHint }),
             }));
         console.log(chalk.green(`\n  ${resolved} configured.`));
         console.log(`  Address:  ${chalk.green(address)}`);
@@ -523,13 +655,9 @@ export function registerWalletCommands(program, isJson) {
             }
             else {
                 console.log(chalk.yellow(`  API Key:  setup failed — ${lighterApiSetup.error}`));
-                console.log(chalk.gray(`  You can retry: perp -e lighter manage setup-api-key`));
+                console.log(chalk.gray(`  You can retry: perp wallet agent approve lighter`));
             }
         }
-        if (!settings.referrals) {
-            console.log(chalk.gray(`  Optional: ${chalk.cyan("perp settings referrals on")} to support perp-cli development`));
-            console.log(chalk.gray(`  (no extra fees — exchange rebates only)`));
-        }
         console.log();
     });
     // ── show (show configured exchanges with public addresses) ──
@@ -554,14 +682,41 @@ export function registerWalletCommands(program, isJson) {
             const { valid, address } = await validateKey(entry.chain, entry.key);
             results.push({ name: entry.name, address: valid ? address : "(invalid key)", source: entry.source });
         }
+        // SSOT Rule #3: surface OWS active wallet's publicAddresses so agents and
+        // commands like `wallet agent verify` can read the master EVM/Solana
+        // addresses without relying on env-derived keys.
+        const settings = loadSettings();
+        const activeOwsName = settings.owsActiveWallet;
+        let owsActive = null;
+        if (activeOwsName) {
+            try {
+                const w = loadOws().getWallet(activeOwsName);
+                const evm = w.accounts.find(a => a.chainId.startsWith("eip155:"))?.address ?? null;
+                const sol = w.accounts.find(a => a.chainId.startsWith("solana:"))?.address ?? null;
+                owsActive = { name: activeOwsName, evmAddress: evm, solanaAddress: sol };
+            }
+            catch {
+                // OWS unavailable or wallet missing — leave owsActive null. SSOT Rule #2:
+                // no fallback to env-derived addresses for the OWS slot.
+                owsActive = { name: activeOwsName, evmAddress: null, solanaAddress: null };
+            }
+        }
         if (isJson()) {
             const data = results.map((r) => ({ exchange: r.name, address: r.address, source: r.source }));
-            return printJson(jsonOk({ envFile: ENV_FILE, exchanges: data }));
+            return printJson(jsonOk({ envFile: ENV_FILE, owsActive, exchanges: data }));
         }
         console.log(chalk.cyan.bold("\n  Configured Wallets\n"));
-        if (results.length === 0) {
+        if (owsActive) {
+            console.log(`  ${chalk.cyan("OWS Active".padEnd(14))} ${chalk.white.bold(owsActive.name)}`);
+            if (owsActive.evmAddress)
+                console.log(`  ${chalk.cyan("  EVM".padEnd(14))} ${chalk.green(owsActive.evmAddress)}`);
+            if (owsActive.solanaAddress)
+                console.log(`  ${chalk.cyan("  Solana".padEnd(14))} ${chalk.green(owsActive.solanaAddress)}`);
+            console.log();
+        }
+        if (results.length === 0 && !owsActive) {
             console.log(chalk.gray("  No keys configured."));
-            console.log(chalk.gray(`  Run ${chalk.cyan("perp setup")} or ${chalk.cyan("perp wallet set <exchange> <key>")}\n`));
+            console.log(chalk.gray(`  Run ${chalk.cyan("perp setup")} or ${chalk.cyan("perp wallet generate")}\n`));
             return;
         }
         for (const { name, address, source } of results) {
@@ -717,7 +872,33 @@ export function registerWalletCommands(program, isJson) {
         if (name) {
             entry = store.wallets[name];
             if (!entry) {
-                console.error(chalk.red(`\n  Wallet "${name}" not found.\n`));
+                // Try OWS vault before failing — balance only needs address + chain type
+                try {
+                    const { loadOws } = await import("../signer/ows-loader.js");
+                    const ows = loadOws();
+                    const owsWallet = ows.getWallet(name);
+                    const evmAccount = owsWallet.accounts.find((a) => a.chainId.startsWith("eip155:"));
+                    const solAccount = owsWallet.accounts.find((a) => a.chainId.startsWith("solana:"));
+                    const account = evmAccount ?? solAccount;
+                    if (account) {
+                        entry = {
+                            name,
+                            type: evmAccount ? "evm" : "solana",
+                            address: account.address,
+                            privateKey: "", // OWS wallet — PK stays encrypted in vault
+                            createdAt: new Date().toISOString(),
+                        };
+                    }
+                }
+                catch { /* not in OWS either */ }
+            }
+            if (!entry) {
+                if (isJson()) {
+                    printJson({ ok: false, error: { code: "KEY_NOT_FOUND", message: `Wallet "${name}" not found in OWS vault or legacy store.` }, meta: { timestamp: new Date().toISOString() } });
+                }
+                else {
+                    console.error(chalk.red(`\n  Wallet "${name}" not found.\n`));
+                }
                 process.exit(1);
             }
         }
@@ -898,4 +1079,551 @@ export function registerWalletCommands(program, isJson) {
             console.log();
         }
     });
+    // ── Policy Engine (OWS) ──────────────────────────────────────────────
+    // OWS-side guardrail: rules an agent API key must satisfy at sign time.
+    const policyCmd = wallet.command("policy").description("Policy engine — guardrails for agent signing");
+    policyCmd
+        .command("create")
+        .description("Create a signing policy")
+        .requiredOption("--id <id>", "Unique policy ID")
+        .requiredOption("--name <name>", "Human-readable policy name")
+        .option("--chains <chains>", "Comma-separated allowed CAIP-2 chain IDs")
+        .option("--expires <iso>", "Policy expiry (ISO-8601 timestamp)")
+        .option("--executable <path>", "Path to custom policy executable")
+        .option("--perp-defaults", "Auto-configure with perp-cli guardrail (DEX contracts + spending limits)")
+        .option("--max-tx-usd <amount>", "Max per-transaction USD", "1000")
+        .option("--max-daily-usd <amount>", "Max daily spending USD", "5000")
+        .option("--max-withdraw-usd <amount>", "Max per-withdrawal USD", "500")
+        .option("--max-daily-withdraw-usd <amount>", "Max daily withdrawal USD", "2000")
+        .option("--block-approve", "Block approve() and transferFrom() calls")
+        .action(async (opts) => {
+        try {
+            const o = loadOws();
+            const rules = [];
+            if (opts.perpDefaults) {
+                const { ALLOWED_CHAINS } = await import("../guardrail/contracts.js");
+                rules.push({ type: "allowed_chains", chain_ids: ALLOWED_CHAINS });
+            }
+            else if (opts.chains) {
+                rules.push({ type: "allowed_chains", chain_ids: opts.chains.split(",").map(s => s.trim()) });
+            }
+            if (opts.expires) {
+                rules.push({ type: "expires_at", timestamp: opts.expires });
+            }
+            let executablePath = opts.executable;
+            let config;
+            if (opts.perpDefaults) {
+                const { resolve: pathResolve } = await import("path");
+                try {
+                    const { createRequire: cr } = await import("node:module");
+                    const req = cr(import.meta.url);
+                    executablePath = pathResolve(req.resolve("perp-cli/dist/guardrail/perp-guardrail.js"));
+                }
+                catch {
+                    executablePath = pathResolve(process.cwd(), "node_modules/.bin/perp-guardrail");
+                }
+                config = {
+                    max_tx_usd: parseInt(opts.maxTxUsd || "1000"),
+                    max_daily_usd: parseInt(opts.maxDailyUsd || "5000"),
+                    max_withdraw_usd: parseInt(opts.maxWithdrawUsd || "500"),
+                    max_daily_withdraw_usd: parseInt(opts.maxDailyWithdrawUsd || "2000"),
+                    ...(opts.blockApprove ? { block_selectors: ["0x095ea7b3", "0x23b872dd"] } : {}),
+                };
+            }
+            const policyDef = {
+                id: opts.id, name: opts.name, version: 1, created_at: new Date().toISOString(),
+                rules, executable: executablePath || null, config: config || null, action: "deny",
+            };
+            o.createPolicy(JSON.stringify(policyDef));
+            if (isJson())
+                return printJson(jsonOk(policyDef));
+            console.log(chalk.green(`\n  Policy "${opts.name}" created (${opts.id})`));
+            if (opts.chains || opts.perpDefaults) {
+                const chainRule = rules.find(r => r.type === "allowed_chains");
+                if (chainRule)
+                    console.log(`  Chains:     ${chalk.cyan(chainRule.chain_ids.length + " chains")}`);
+            }
+            if (opts.expires)
+                console.log(`  Expires:    ${chalk.yellow(opts.expires)}`);
+            if (executablePath)
+                console.log(`  Executable: ${chalk.gray(executablePath)}`);
+            if (config)
+                console.log(`  Limits:     ${chalk.cyan(`$${config.max_tx_usd}/tx, $${config.max_daily_usd}/day`)}`);
+            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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    policyCmd
+        .command("list")
+        .description("List all policies")
+        .action(async () => {
+        try {
+            const o = loadOws();
+            const policies = o.listPolicies();
+            if (isJson())
+                return printJson(jsonOk({ policies }));
+            if (policies.length === 0) {
+                console.log(chalk.gray("\n  No policies defined.\n"));
+                return;
+            }
+            console.log(chalk.cyan.bold("\n  OWS Policies\n"));
+            const rows = policies.map(p => {
+                const ruleTypes = p.rules.map(r => r.type).join(", ");
+                return [chalk.white.bold(p.id), p.name, chalk.cyan(ruleTypes), chalk.gray(p.created_at?.split("T")[0] ?? "-")];
+            });
+            console.log(makeTable(["ID", "Name", "Rules", "Created"], rows));
+            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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    policyCmd
+        .command("show <id>")
+        .description("Show policy details")
+        .action(async (id) => {
+        try {
+            const o = loadOws();
+            const p = o.getPolicy(id);
+            if (isJson())
+                return printJson(jsonOk(p));
+            console.log(chalk.cyan.bold(`\n  Policy: ${id}\n`));
+            console.log(JSON.stringify(p, null, 2));
+            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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    policyCmd
+        .command("delete <id>")
+        .description("Delete a policy")
+        .action(async (id) => {
+        try {
+            const o = loadOws();
+            o.deletePolicy(id);
+            if (isJson())
+                return printJson(jsonOk({ deleted: id }));
+            console.log(chalk.yellow(`\n  Policy "${id}" deleted.\n`));
+        }
+        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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    // ── API Keys (OWS) ──────────────────────────────────────────────────
+    // OWS-side scoped agent access tokens. NOT to be confused with
+    // `wallet agent` (DEX-side delegation) — see comment near runOwsCli.
+    const keyCmd = wallet.command("key").description("API key management — scoped agent access tokens");
+    keyCmd
+        .command("create")
+        .description("Create an API key for policy-gated agent signing")
+        .requiredOption("--name <name>", "Key name (e.g. trading-bot)")
+        .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", "")
+        .action(async (opts) => {
+        try {
+            const o = loadOws();
+            const walletIds = opts.wallets.split(",").map(s => s.trim());
+            const policyIds = opts.policy ? opts.policy.split(",").map(s => s.trim()) : [];
+            const result = o.createApiKey(opts.name, walletIds, policyIds, opts.passphrase, opts.expires);
+            if (isJson())
+                return printJson(jsonOk({ id: result.id, name: result.name, token: result.token, wallets: walletIds, policies: policyIds, expires: opts.expires ?? null }));
+            console.log(chalk.green.bold("\n  OWS API Key Created\n"));
+            console.log(`  Name:     ${chalk.white.bold(result.name)}`);
+            console.log(`  ID:       ${chalk.gray(result.id)}`);
+            console.log(`  Wallets:  ${chalk.cyan(walletIds.join(", "))}`);
+            if (policyIds.length)
+                console.log(`  Policies: ${chalk.cyan(policyIds.join(", "))}`);
+            if (opts.expires)
+                console.log(`  Expires:  ${chalk.yellow(opts.expires)}`);
+            console.log();
+            console.log(`  Token: ${chalk.yellow.bold(result.token)}`);
+            console.log(chalk.red("\n  Save this token — it will not be shown again!\n"));
+            console.log(chalk.gray("  Usage: perp --ows <wallet> --ows-key <token> -e hl trade ..."));
+            console.log(chalk.gray("     or: OWS_API_KEY=<token> perp --ows <wallet> -e hl trade ...\n"));
+        }
+        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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    keyCmd
+        .command("list")
+        .description("List all API keys (tokens are never displayed)")
+        .action(async () => {
+        try {
+            const o = loadOws();
+            const keys = o.listApiKeys();
+            if (isJson())
+                return printJson(jsonOk({ keys }));
+            if (keys.length === 0) {
+                console.log(chalk.gray("\n  No API keys found.\n"));
+                return;
+            }
+            console.log(chalk.cyan.bold("\n  OWS API Keys\n"));
+            const rows = keys.map(k => [
+                chalk.white.bold(k.name), chalk.gray(k.id), chalk.gray(k.created_at?.split("T")[0] ?? "-"),
+            ]);
+            console.log(makeTable(["Name", "ID", "Created"], rows));
+            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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    keyCmd
+        .command("revoke <id>")
+        .description("Revoke an API key (token becomes permanently invalid)")
+        .action(async (id) => {
+        try {
+            const o = loadOws();
+            o.revokeApiKey(id);
+            if (isJson())
+                return printJson(jsonOk({ revoked: id }));
+            console.log(chalk.yellow(`\n  API key "${id}" revoked.\n`));
+        }
+        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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    // ── deposit (OWS-backed MoonPay on-ramp) ─────────────────────────────
+    wallet
+        .command("deposit <walletName>")
+        .description("Create multi-chain deposit via MoonPay (auto-converts to USDC)")
+        .option("-c, --chain <chain>", "Target chain for USDC delivery")
+        .option("--for <exchange>", "Target exchange (auto-selects chain: hl→arbitrum, pac→solana, lt→ethereum)")
+        .action(async (walletName, opts) => {
+        try {
+            // Resolve chain from exchange if specified
+            const exchangeChainMap = {
+                hyperliquid: "arbitrum", hl: "arbitrum",
+                pacifica: "solana", pac: "solana",
+                lighter: "ethereum", lt: "ethereum",
+            };
+            const forExchange = opts.for;
+            const chain = opts.chain || (forExchange ? exchangeChainMap[forExchange.toLowerCase()] : undefined) || "base";
+            // Verify wallet exists first
+            const o = loadOws();
+            o.getWallet(walletName);
+            // Find OWS CLI binary
+            const { resolve: pathResolve } = await import("path");
+            const { existsSync: fsExists } = await import("fs");
+            const owsBin = [
+                pathResolve(process.env.HOME || "~", ".ows", "bin", "ows"),
+                "/usr/local/bin/ows",
+            ].find(p => fsExists(p));
+            if (!owsBin) {
+                throw new Error("OWS CLI not found. Install: curl -fsSL https://docs.openwallet.sh/install.sh | bash");
+            }
+            // 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}` };
+            try {
+                const { spawnSync } = await import("child_process");
+                const proc = spawnSync(owsBin, ["fund", "deposit", "--wallet", walletName, "--chain", chain], {
+                    encoding: "utf-8", timeout: 30000, env: owsEnv,
+                });
+                const stderrOutput = proc.stderr || "";
+                const combined = stderrOutput + "\n" + (proc.stdout || "");
+                // Parse deposit addresses
+                const addresses = {};
+                for (const line of combined.split("\n")) {
+                    const match = line.match(/^\s+(bitcoin|ethereum|solana|tron)\s+(\S+)/);
+                    if (match)
+                        addresses[match[1]] = match[2];
+                }
+                const urlMatch = combined.match(/(https:\/\/moonpay\S+)/);
+                const depositUrl = urlMatch?.[1] ?? null;
+                // Find our wallet's target address
+                const w = o.getWallet(walletName);
+                const evmAddr = w.accounts.find((a) => a.chainId.startsWith("eip155:"))?.address ?? "";
+                if (isJson()) {
+                    return printJson(jsonOk({
+                        wallet: walletName,
+                        chain,
+                        exchange: forExchange || null,
+                        targetAddress: evmAddr,
+                        depositAddresses: addresses,
+                        depositUrl,
+                        note: `Send any crypto to the deposit addresses. Funds auto-convert to USDC and deliver to ${evmAddr} on ${chain}.`,
+                    }));
+                }
+                // Pass through the human-readable output
+                if (stderrOutput.trim()) {
+                    console.log();
+                    console.log(stderrOutput.trim());
+                }
+                if (depositUrl)
+                    console.log(`\n${depositUrl}`);
+                console.log();
+                return;
+            }
+            catch (spawnErr) {
+                throw new Error(`OWS CLI deposit failed: ${spawnErr instanceof Error ? spawnErr.message : String(spawnErr)}`);
+            }
+        }
+        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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    // ── Setup Wizard (one-click vault + policy + agent key) ──────────────
+    wallet
+        .command("setup")
+        .description("One-click setup: create wallet + guardrail policy + agent API key")
+        .option("-n, --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")
+        .action(async (opts) => {
+        try {
+            const o = loadOws();
+            // Step 1: Create or reuse wallet
+            let w;
+            let walletCreated = false;
+            try {
+                w = o.getWallet(opts.name);
+                if (!isJson())
+                    console.log(chalk.gray(`\n  Wallet "${opts.name}" already exists. Using it.`));
+            }
+            catch {
+                w = o.createWallet(opts.name, "", 12);
+                walletCreated = true;
+                const settings = loadSettings();
+                if (!settings.owsActiveWallet) {
+                    settings.owsActiveWallet = opts.name;
+                    saveSettings(settings);
+                }
+            }
+            const evmAddr = w.accounts.find((a) => a.chainId.startsWith("eip155:"))?.address ?? "-";
+            const solAddr = w.accounts.find((a) => a.chainId.startsWith("solana:"))?.address ?? "-";
+            if (!isJson() && walletCreated) {
+                console.log(chalk.green.bold(`\n  1. Wallet Created: ${opts.name}`));
+                console.log(`     EVM:    ${chalk.green(evmAddr)}`);
+                console.log(`     Solana: ${chalk.green(solAddr)}`);
+            }
+            // Step 2: Create guardrail policy
+            const policyId = `perp-guardrail-${opts.name}`;
+            const { ALLOWED_CHAINS } = await import("../guardrail/contracts.js");
+            const { resolve: pathResolve } = await import("path");
+            let executablePath;
+            try {
+                const { createRequire: cr } = await import("node:module");
+                const req = cr(import.meta.url);
+                executablePath = pathResolve(req.resolve("perp-cli/dist/guardrail/perp-guardrail.js"));
+            }
+            catch {
+                executablePath = pathResolve(process.cwd(), "node_modules/.bin/perp-guardrail");
+            }
+            const policyDef = {
+                id: policyId, name: `perp-cli guardrail (${opts.name})`, version: 1,
+                created_at: new Date().toISOString(),
+                rules: [{ type: "allowed_chains", chain_ids: ALLOWED_CHAINS }],
+                executable: executablePath,
+                config: {
+                    max_tx_usd: parseInt(opts.maxTxUsd),
+                    max_daily_usd: parseInt(opts.maxDailyUsd),
+                    max_withdraw_usd: Math.round(parseInt(opts.maxTxUsd) / 2),
+                    max_daily_withdraw_usd: Math.round(parseInt(opts.maxDailyUsd) / 2.5),
+                    block_selectors: ["0x095ea7b3", "0x23b872dd"],
+                },
+                action: "deny",
+            };
+            try {
+                o.deletePolicy(policyId);
+            }
+            catch { /* doesn't exist yet */ }
+            o.createPolicy(JSON.stringify(policyDef));
+            if (!isJson()) {
+                console.log(chalk.green.bold(`\n  2. Guardrail Policy Created: ${policyId}`));
+                console.log(`     Limits: ${chalk.cyan(`$${opts.maxTxUsd}/tx, $${opts.maxDailyUsd}/day`)}`);
+                console.log(`     Chains: ${chalk.cyan(`${ALLOWED_CHAINS.length} chains (all perp-cli exchanges)`)}`);
+            }
+            // Step 3: Create API key
+            let token;
+            let keyId;
+            if (!opts.skipKey) {
+                const keyName = `${opts.name}-agent`;
+                const result = o.createApiKey(keyName, [opts.name], [policyId], "", undefined);
+                token = result.token;
+                keyId = result.id;
+                if (!isJson()) {
+                    console.log(chalk.green.bold(`\n  3. Agent API Key Created: ${keyName}`));
+                    console.log(`     ID: ${chalk.gray(keyId)}`);
+                }
+            }
+            if (isJson()) {
+                return printJson(jsonOk({
+                    wallet: { name: opts.name, evm: evmAddr, solana: solAddr, created: walletCreated },
+                    policy: { id: policyId, maxTxUsd: parseInt(opts.maxTxUsd), maxDailyUsd: parseInt(opts.maxDailyUsd) },
+                    apiKey: token ? { id: keyId, token } : null,
+                }));
+            }
+            console.log(chalk.cyan.bold("\n  ─── Setup Complete ───\n"));
+            if (token) {
+                console.log(`  ${chalk.yellow.bold("Agent Token:")} ${chalk.yellow(token)}`);
+                console.log(chalk.red("  Save this token — it will not be shown again!\n"));
+                console.log(chalk.white.bold("  Usage:\n"));
+                console.log(chalk.gray("  # Owner mode (no policy limits):"));
+                console.log(`  ${chalk.cyan(`perp --ows ${opts.name} -e hl trade buy ETH 0.1`)}\n`);
+                console.log(chalk.gray("  # Agent mode (policy enforced):"));
+                console.log(`  ${chalk.cyan(`perp --ows ${opts.name} --ows-key ${token.slice(0, 16)}... -e hl trade buy ETH 0.1`)}\n`);
+            }
+            console.log(chalk.gray("  Fund your wallet before trading:"));
+            console.log(`  ${chalk.cyan(`perp wallet deposit ${opts.name} --for hl`)}   ${chalk.gray("(Hyperliquid → Arbitrum USDC)")}`);
+            console.log(`  ${chalk.cyan(`perp wallet deposit ${opts.name} --for pac`)}  ${chalk.gray("(Pacifica → Solana USDC)")}`);
+            console.log(`  ${chalk.cyan(`perp wallet deposit ${opts.name} --for lt`)}   ${chalk.gray("(Lighter → Ethereum USDC)")}\n`);
+        }
+        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  OWS setup error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    // ── Backup / Restore (encrypted vault archive) ────────────────────────
+    wallet
+        .command("backup")
+        .description("Backup entire OWS vault (encrypted archive)")
+        .option("-o, --output <path>", "Output file path", `ows-backup-${new Date().toISOString().split("T")[0]}.tar.gz.enc`)
+        .action(async (opts) => {
+        try {
+            const { stdout, stderr } = await runOwsCli(["backup", "--output", opts.output]);
+            if (isJson())
+                return printJson(jsonOk({ backup: opts.output, output: stderr || stdout }));
+            if (stderr)
+                console.log("\n" + stderr);
+            if (stdout)
+                console.log(stdout);
+            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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    wallet
+        .command("restore <file>")
+        .description("Restore OWS vault from encrypted backup")
+        .action(async (file) => {
+        try {
+            const { stdout, stderr } = await runOwsCli(["restore", "--input", file]);
+            if (isJson())
+                return printJson(jsonOk({ restored: file, output: stderr || stdout }));
+            if (stderr)
+                console.log("\n" + stderr);
+            if (stdout)
+                console.log(stdout);
+            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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    // ── Key rotation (create new wallet + transfer assets) ───────────────
+    wallet
+        .command("rotate")
+        .description("Rotate wallet keys (create new wallet + transfer assets)")
+        .requiredOption("--from <name>", "Source wallet name")
+        .requiredOption("--to <name>", "Target wallet name (created if not exists)")
+        .option("--chain <chain>", "Chain to rotate on", "evm")
+        .action(async (opts) => {
+        try {
+            const chainMap = { evm: "eip155:1", arbitrum: "eip155:42161", base: "eip155:8453", solana: "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp" };
+            const chainArg = chainMap[opts.chain] || opts.chain;
+            const { stdout, stderr } = await runOwsCli(["wallet", "rotate", "--from", opts.from, "--to", opts.to, "--chain", chainArg], 120000);
+            if (isJson())
+                return printJson(jsonOk({ from: opts.from, to: opts.to, chain: chainArg, output: stderr || stdout }));
+            if (stderr)
+                console.log("\n" + stderr);
+            if (stdout)
+                console.log(stdout);
+            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  OWS error: ${msg}\n`));
+            process.exit(1);
+        }
+    });
+    // ── Agent (DEX-side delegation) ──────────────────────────────────────
+    // 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);
+    // ── 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.
+    // Skipped when adapter wiring isn't supplied (test programs may register
+    // wallet without adapters).
+    if (getAdapter && getPacificaAdapter) {
+        registerWalletManageCommands(wallet, getAdapter, isJson, getPacificaAdapter);
+    }
 }