perp-cli 0.12.17 → 0.14.1

package/dist/commands/agent.js

@@ -1,17 +1,39 @@
+import { Option } from "commander";
+import { networkOf } from "../cli-flags.js";
 import { createRequire } from "node:module";
 import { createInterface } from "node:readline/promises";
 import { stdin as input, stdout as output } from "node:process";
 import { printJson, jsonOk } from "../utils.js";
-import { PerpError } from "../errors.js";
+import { PerpError, classifyError } from "../errors.js";
 import chalk from "chalk";
 import bs58 from "bs58";
 import { loadSettings } from "../settings.js";
-import { getAgent, setAgent, deleteAgent, listAgents, acquireLock, releaseLock } from "../agent-wallet/store.js";
+import { getAgent, setAgent, deleteAgent, listAgents, acquireLock, releaseLock, getVenueAgent, getVenueAgentForNetwork, setVenueAgent, deleteVenueAgent, listVenueAgents, agentNetworkOf, recordedAgentNetworkOf, assertAgentNetwork, getAgentForNetwork, agentSourceOf, } from "../agent-wallet/store.js";
+import { getVenue, networkConfig, resolveVenueId } from "../exchanges/venue.js";
+import { listConfiguredAccountVenues } from "../config.js";
+import "../exchanges/venues/index.js";
+import { LIGHTER_RH_RESERVED_KEY_INDEXES } from "../exchanges/venues/lighter-family.js";
+import { HL_USER_SIGNED } from "../exchanges/venues/hyperliquid.js";
+import { unsupported } from "../exchanges/trading-v2.js";
 import { resolvePassphrase } from "../agent-wallet/passphrase.js";
 import { OwsEvmSigner } from "../signer/ows-evm.js";
 import { OwsSolanaSigner } from "../signer/ows-solana.js";
 import { loadOws } from "../signer/ows-loader.js";
-import { buildApproveAgentTypedData, buildDelAgentTypedData, buildApproveBuilderTypedData, } from "../exchanges/aster-typed-data.js";
+import { ASTER_DOMAIN_A, buildApproveAgentTypedData, buildDelAgentTypedData, } from "../exchanges/aster-typed-data.js";
+/**
+ * Subcommand `--passphrase <pp>`: still accepted (existing scripts) but deprecated like the root
+ * flag — hidden from help, and a stderr warning when it was given on the command line (it is
+ * visible in ps / shell history). Use with `.hook("preAction", warnDeprecatedPassphrase)`.
+ */
+export function deprecatedPassphraseOption(what = "Master OWS passphrase", flags = "--passphrase <pp>") {
+    return new Option(flags, `DEPRECATED (visible in ps / shell history) — ${what}; prefer OWS_PASSPHRASE env or stdin`).hideHelp();
+}
+export const ARGV_PASSPHRASE_WARNING = "[warn] --passphrase on the command line is DEPRECATED and visible in ps / shell history. Use the OWS_PASSPHRASE env var or pipe it on stdin.\n";
+/** preAction hook paired with deprecatedPassphraseOption(): warns once per command run. */
+export function warnDeprecatedPassphrase(cmd) {
+    if (cmd.getOptionValueSource("passphrase") === "cli")
+        process.stderr.write(ARGV_PASSPHRASE_WARNING);
+}
 /**
  * Emit a structured JSON error envelope to stdout and exit non-zero.
  * Stdout (not stderr) so machine consumers can read the envelope from a
@@ -19,12 +41,106 @@ import { buildApproveAgentTypedData, buildDelAgentTypedData, buildApproveBuilder
  */
 function reportErrorAndExit(err) {
     const ts = new Date().toISOString();
-    const envelope = err instanceof PerpError
-        ? { ok: false, error: { ...err.structured }, meta: { timestamp: ts } }
-        : { ok: false, error: { code: "UNKNOWN", message: err instanceof Error ? err.message : String(err) }, meta: { timestamp: ts } };
+    // Route through the central classifier so generic Errors thrown from
+    // dependencies (e.g. NAPI "decryption failed: aead::Error" from OWS vault
+    // unlock) get a meaningful code + remediation instead of a bare UNKNOWN.
+    // PerpError instances pass through unchanged via classifyError's first
+    // branch so explicitly typed errors keep their structured shape.
+    const envelope = { ok: false, error: classifyError(err), meta: { timestamp: ts } };
     process.stdout.write(JSON.stringify(envelope) + "\n");
     process.exit(1);
 }
+export function isLighterFamilyVenue(v) {
+    return getVenue(v).family === "lighter";
+}
+/** Validate an explicit Lighter-family API key slot: 4..254, minus venue-reserved indexes. */
+export function assertLighterSlot(venue, n) {
+    if (!Number.isInteger(n) || n < 4 || n > 254) {
+        throw new PerpError("INVALID_PARAMS", `--api-key-index must be an integer in [4, 254]; got ${n}`, {
+            remediation: "Slots 0-3 are reserved by the Lighter frontend. Use 4-254.",
+        });
+    }
+    if (venue === "lighter-rh" && LIGHTER_RH_RESERVED_KEY_INDEXES.includes(n)) {
+        throw new PerpError("INVALID_PARAMS", `Lighter RH API key index ${n} is reserved (${LIGHTER_RH_RESERVED_KEY_INDEXES.join(", ")})`, {
+            remediation: "Use an index in 4-254 other than 157.",
+        });
+    }
+}
+/** Read one line from a TTY without echo (raw mode). */
+export function promptHidden(question) {
+    return new Promise((resolve, reject) => {
+        const stdin = process.stdin;
+        process.stdout.write(question);
+        stdin.setRawMode(true);
+        stdin.resume();
+        stdin.setEncoding("utf8");
+        let buf = "";
+        const cleanup = () => {
+            stdin.off("data", onData);
+            stdin.setRawMode(false);
+            stdin.pause();
+        };
+        const onData = (chunk) => {
+            for (const c of chunk) {
+                if (c === "\r" || c === "\n") {
+                    cleanup();
+                    process.stdout.write("\n");
+                    resolve(buf);
+                    return;
+                }
+                if (c === "\u0003") {
+                    cleanup();
+                    reject(new PerpError("INVALID_PARAMS", "Cancelled"));
+                    return;
+                }
+                if (c === "\u007f" || c === "\b") {
+                    buf = buf.slice(0, -1);
+                    continue;
+                }
+                buf += c;
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+/** Read all of a piped (non-TTY) stdin. */
+function readPipedStdin() {
+    return new Promise((resolve, 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", () => resolve(chunks.join("")));
+        process.stdin.on("error", reject);
+    });
+}
+/**
+ * Ondo API key id + secret, from stdin only (design §10.4 — never flags).
+ * TTY: key id prompt, then hidden secret prompt. Piped: line 1 = key id, line 2 = secret.
+ */
+/** Lighter ChangePubKey settlement window when confirming a slot (docs example: 30 s, 1 s apart; kept under the 60 req/min budget). */
+const LIGHTER_SLOT_CONFIRM_TIMEOUT_MS = 30_000;
+const LIGHTER_SLOT_CONFIRM_POLL_MS = 3_000;
+async function readOndoKeyFromStdin() {
+    if (process.stdin.isTTY === true) {
+        const rl = createInterface({ input, output });
+        let keyId;
+        try {
+            keyId = (await rl.question("Ondo API key id (ondoKeyId_…): ")).trim();
+        }
+        finally {
+            rl.close();
+        }
+        const secret = (await promptHidden("Ondo API secret (hidden): ")).trim();
+        return { keyId, secret };
+    }
+    const lines = (await readPipedStdin()).split(/\r?\n/).map(l => l.trim()).filter(l => l.length > 0);
+    if (lines.length !== 2) {
+        throw new PerpError("INVALID_PARAMS", `Expected 2 lines on stdin (key id, secret); got ${lines.length}`, {
+            remediation: "printf '%s\\n%s\\n' \"$KEY_ID\" \"$SECRET\" | perp wallet agent approve ondo",
+        });
+    }
+    return { keyId: lines[0], secret: lines[1] };
+}
 const _require = createRequire(import.meta.url);
 const _pkg = _require("../../package.json");
 // ── Per-DEX verify implementations ───────────────────────────────────────
@@ -50,30 +166,34 @@ async function verifyAster(_opts) {
  * settings.agents.hyperliquid[name], asserts live response contains expected
  * agentEvmAddress. Mismatch → meta.warnings populated (non-fatal).
  */
-async function verifyHyperliquid(opts) {
-    const settings = loadSettings();
-    // Resolve master EVM address: flag > named agent's userEvmAddress > first registered agent
+async function verifyHyperliquid(network, opts) {
+    // The named agent must belong to the selected network; otherwise use the
+    // first agent registered on it (a mainnet agent is never checked on testnet).
+    const namedMeta = opts.agentName !== undefined ? getAgent("hyperliquid", opts.agentName) : null;
+    if (namedMeta !== null)
+        assertAgentNetwork("hyperliquid", namedMeta, network);
+    // Resolve master EVM address: flag > named agent's userEvmAddress > first agent on this network
+    // > the selected OWS master wallet's EVM account
     let masterAddress = opts.masterAddress;
     if (!masterAddress) {
-        const hlMap = settings.agents?.hyperliquid;
-        if (hlMap) {
-            if (opts.agentName && hlMap[opts.agentName]?.userEvmAddress) {
-                masterAddress = hlMap[opts.agentName].userEvmAddress;
-            }
-            else {
-                const first = Object.values(hlMap)[0];
-                if (first?.userEvmAddress)
-                    masterAddress = first.userEvmAddress;
-            }
-        }
+        const meta = namedMeta ?? getAgentForNetwork("hyperliquid", network);
+        if (meta?.userEvmAddress)
+            masterAddress = meta.userEvmAddress;
     }
     if (!masterAddress) {
-        throw new PerpError("INVALID_PARAMS", "Master EVM address required for Hyperliquid verify. Use --master-address.", {
-            remediation: "perp wallet agent verify hyperliquid --master-address 0xYOUR_ADDRESS",
+        // No local agent record (e.g. right after a revoke): the selected OWS master wallet
+        // (--master, else the active wallet) names the account. Reading its address needs no passphrase.
+        const masterName = opts.master ?? loadSettings().owsActiveWallet;
+        if (masterName)
+            masterAddress = OwsEvmSigner.create(masterName).getAddress();
+    }
+    if (!masterAddress) {
+        throw new PerpError("INVALID_PARAMS", "Master EVM address required for Hyperliquid verify: no local agent record and no OWS master wallet is selected. Use --master-address.", {
+            remediation: "perp wallet agent verify hyperliquid --master-address 0xYOUR_ADDRESS (or select the master wallet: --master <walletName>)",
         });
     }
     const user = masterAddress.toLowerCase();
-    const resp = await fetch("https://api.hyperliquid.xyz/info", {
+    const resp = await fetch(`${networkConfig(getVenue("hyperliquid"), network).restUrl}/info`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ type: "extraAgents", user }),
@@ -88,7 +208,7 @@ async function verifyHyperliquid(opts) {
     const warnings = [];
     // Cross-check: AC-28 — verify persisted agentEvmAddress matches live response
     if (opts.agentName) {
-        const agentMeta = settings.agents?.hyperliquid?.[opts.agentName];
+        const agentMeta = namedMeta;
         if (agentMeta?.agentEvmAddress) {
             const expected = agentMeta.agentEvmAddress.toLowerCase();
             const found = items.some((item) => typeof item === "object" &&
@@ -104,67 +224,103 @@ async function verifyHyperliquid(opts) {
     return { registered: items.length > 0, count: items.length, items, warnings: warnings.length > 0 ? warnings : undefined };
 }
 /**
- * Verify Pacifica agent registration.
+ * Verify Pacifica agent registration — POST /agent/list, master-signed.
  *
- * NOTE (v3.3 limitation): Cross-check semantics from AC-23 are inactive for
- * this DEX because settings.agents.pacifica type slot does not exist yet
- * (AgentsByExchange has only `aster?`). When Phase 2c extends AgentsByExchange
- * + AgentMeta with per-DEX fields (accountIndex, publicKey, etc.), the
- * cross-check branch below becomes live.
+ * Mirrors the official SDK `list_agent_wallets` (pacifica-fi/python-sdk
+ * rest/api_agent_keys_detailed.py): the signed message nests an EMPTY payload
+ * under `data` ({"data":{},"expiry_window":…,"timestamp":…,"type":"list_agent_wallets"}),
+ * and the request body is `{account, agent_wallet: null, signature, timestamp,
+ * expiry_window}` — no `type` field. The earlier `list_api_keys` →
+ * /account/api_keys shape signed a header without `data` and was rejected
+ * live with "signature does not match signer and canonical payload".
+ *
+ * When an agent record exists for this network (named, or the first one),
+ * `registered` reflects whether ITS agent pubkey is in the live list.
  */
-async function verifyPacifica(opts) {
+async function verifyPacifica(network, opts) {
     const settings = loadSettings();
     const masterName = opts.master ?? settings.owsActiveWallet;
     if (!masterName) {
-        throw new PerpError("INVALID_PARAMS", "Master wallet name required for Pacifica verify. Use --master.", {
-            remediation: "perp wallet agent verify pacifica --master <walletName> --passphrase $PP",
+        // Pacifica lists agent bindings only via a master-signed request (no agent-signed read exists).
+        throw new PerpError("NO_SIGNER_AVAILABLE", "Pacifica agent verify is signed by the master wallet, and none is configured on this computer", {
+            remediation: "Check the agent on the Pacifica website (API keys), or add the master wallet and run: perp wallet agent verify pacifica --master <walletName>",
         });
     }
+    const namedMeta = opts.agentName !== undefined ? getAgent("pacifica", opts.agentName) : null;
+    if (namedMeta !== null)
+        assertAgentNetwork("pacifica", namedMeta, network);
+    const expectedMeta = namedMeta ?? getAgentForNetwork("pacifica", network);
+    const expectedAgent = expectedMeta?.agentSolanaAddress ?? null;
     const passphrase = opts.passphrase ?? "";
     const solanaSigner = OwsSolanaSigner.create(masterName, passphrase);
     const account = solanaSigner.getPublicKeyBase58();
-    const timestamp = Date.now();
-    const expiryWindow = 5000;
-    const type = "list_api_keys";
-    // Canonical JSON: sort keys lexicographically, no whitespace
-    const signHeader = { expiry_window: expiryWindow, timestamp, type };
-    const canonicalJson = JSON.stringify(signHeader);
-    // Sign canonical JSON with Ed25519 (OWS Solana signer)
-    const msgBytes = new TextEncoder().encode(canonicalJson);
-    const sigBytes = await solanaSigner.signMessage(msgBytes);
-    // Base58-encode the signature
-    const sigBase58 = bs58.encode(sigBytes);
+    const { buildListAgentWalletsMessage } = await import("../exchanges/pacifica-typed-data.js");
+    const built = buildListAgentWalletsMessage();
+    const sigBytes = await solanaSigner.signMessage(new TextEncoder().encode(built.canonicalJson));
     const body = {
         account,
         agent_wallet: null,
-        signature: sigBase58,
-        timestamp,
-        expiry_window: expiryWindow,
-        type,
+        signature: bs58.encode(sigBytes),
+        timestamp: built.header.timestamp,
+        expiry_window: built.header.expiry_window,
     };
-    const resp = await fetch("https://api.pacifica.fi/api/v1/account/api_keys", {
+    const resp = await fetch(`${networkConfig(getVenue("pacifica"), network).restUrl}/agent/list`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
     });
     if (!resp.ok) {
-        const body = await resp.text().catch(() => "");
-        throw new PerpError("EXCHANGE_ERROR", `Pacifica verify failed: HTTP ${resp.status}: ${body.slice(0, 200)}`, {
+        const text = await resp.text().catch(() => "");
+        throw new PerpError("EXCHANGE_ERROR", `Pacifica verify failed: HTTP ${resp.status}: ${text.slice(0, 200)}`, {
             remediation: "Check master wallet name and passphrase. Run: perp wallet agent verify pacifica --master <name> --passphrase $PP",
         });
     }
-    const data = await resp.json();
-    const apiKeys = (data &&
-        typeof data === "object" &&
-        "data" in data &&
-        typeof data.data === "object" &&
-        data.data !== null &&
-        "api_keys" in data.data)
-        ? data.data.api_keys
-        : [];
-    const items = Array.isArray(apiKeys) ? apiKeys : [];
+    const json = await resp.json();
+    const items = parsePacAgentList(json);
+    const listed = items.map(pacAgentPubkeyOf);
+    const warnings = [];
+    if (expectedAgent !== null && expectedMeta !== null) {
+        const found = listed.includes(expectedAgent);
+        if (!found) {
+            warnings.push(`Agent "${expectedMeta.agentName}" (${expectedAgent}) is not bound to ${account} on Pacifica ${network}.`);
+        }
+        return { registered: found, count: items.length, items, warnings: warnings.length > 0 ? warnings : undefined };
+    }
     return { registered: items.length > 0, count: items.length, items };
 }
+/** Extract the agent list from a Pacifica /agent/list envelope; throws on an unrecognized shape. */
+export function parsePacAgentList(json) {
+    if (json !== null && typeof json === "object") {
+        const env = json;
+        if (env.success === false) {
+            throw new PerpError("EXCHANGE_ERROR", `Pacifica verify rejected: ${JSON.stringify(env.error ?? env).slice(0, 200)}`, {
+                remediation: "Check master wallet name and passphrase. Run: perp wallet agent verify pacifica --master <name>",
+            });
+        }
+        const data = env.data;
+        if (Array.isArray(data))
+            return data;
+        if (data !== null && typeof data === "object" && Array.isArray(data.agent_wallets)) {
+            return data.agent_wallets;
+        }
+    }
+    throw new PerpError("EXCHANGE_ERROR", `Pacifica /agent/list returned an unrecognized shape: ${JSON.stringify(json).slice(0, 200)}`, {
+        remediation: "Check the agent on the Pacifica website (API keys) and report the response shape.",
+    });
+}
+/** Agent pubkey of one /agent/list entry (a bare base58 string or an object carrying it). */
+function pacAgentPubkeyOf(item) {
+    if (typeof item === "string")
+        return item;
+    if (item !== null && typeof item === "object") {
+        const o = item;
+        for (const k of ["agent_wallet", "address", "public_key"]) {
+            if (typeof o[k] === "string")
+                return o[k];
+        }
+    }
+    return null;
+}
 /**
  * Verify Lighter agent registration.
  *
@@ -174,36 +330,31 @@ async function verifyPacifica(opts) {
  * + AgentMeta with per-DEX fields (accountIndex, publicKey, etc.), the
  * cross-check branch below becomes live.
  */
-async function verifyLighter(opts) {
-    const settings = loadSettings();
+async function verifyLighter(venue, network, opts) {
     const accountIndexStr = opts.accountIndex;
-    // Resolve accountIndex: flag > named agent > first registered agent
+    // Resolve accountIndex: flag > named agent > first agent on this network
+    const namedMeta = opts.agentName !== undefined ? getAgent(venue, opts.agentName) : null;
+    if (namedMeta !== null)
+        assertAgentNetwork(venue, namedMeta, network);
     let accountIndex;
     if (accountIndexStr !== undefined) {
         accountIndex = parseInt(accountIndexStr, 10);
     }
     else {
-        const ltMap = settings.agents?.lighter;
-        if (ltMap) {
-            if (opts.agentName && ltMap[opts.agentName]?.accountIndex !== undefined) {
-                accountIndex = ltMap[opts.agentName].accountIndex;
-            }
-            else {
-                const first = Object.values(ltMap)[0];
-                if (first?.accountIndex !== undefined)
-                    accountIndex = first.accountIndex;
-            }
-        }
+        const meta = namedMeta ?? getAgentForNetwork(venue, network);
+        if (meta?.accountIndex !== undefined)
+            accountIndex = meta.accountIndex;
     }
     if (accountIndex === undefined || isNaN(accountIndex)) {
-        throw new PerpError("INVALID_PARAMS", "Account index required for Lighter verify. Use --account-index.", {
-            remediation: "perp wallet agent verify lighter --account-index <n>",
+        throw new PerpError("INVALID_PARAMS", `Account index required for ${venue} verify. Use --account-index.`, {
+            remediation: `perp wallet agent verify ${venue} --account-index <n>`,
         });
     }
-    const resp = await fetch(`https://mainnet.zklighter.elliot.ai/api/v1/apikeys?account_index=${accountIndex}`, { method: "GET" });
+    const restUrl = networkConfig(getVenue(venue), network).restUrl;
+    const resp = await fetch(`${restUrl}/api/v1/apikeys?account_index=${accountIndex}`, { method: "GET" });
     if (!resp.ok) {
-        throw new PerpError("EXCHANGE_ERROR", `Lighter verify failed: HTTP ${resp.status}`, {
-            remediation: `Check account index. Run: perp wallet agent verify lighter --account-index ${accountIndex}`,
+        throw new PerpError("EXCHANGE_ERROR", `${venue} verify failed: HTTP ${resp.status}`, {
+            remediation: `Check account index. Run: perp wallet agent verify ${venue} --account-index ${accountIndex}`,
         });
     }
     const data = await resp.json();
@@ -216,11 +367,7 @@ async function verifyLighter(opts) {
     const warnings = [];
     // Cross-check if agentName provided
     if (opts.agentName) {
-        const ltAgents = settings.agents;
-        const ltMap = (ltAgents && typeof ltAgents === "object" && "lighter" in ltAgents)
-            ? ltAgents.lighter
-            : undefined;
-        const agentMeta = ltMap?.[opts.agentName];
+        const agentMeta = namedMeta;
         if (agentMeta?.publicKey) {
             const expected = agentMeta.publicKey;
             const found = items.some((item) => typeof item === "object" &&
@@ -228,12 +375,660 @@ async function verifyLighter(opts) {
                 "public_key" in item &&
                 item.public_key === expected);
             if (!found) {
-                warnings.push(`Agent "${opts.agentName}" (expected public_key ${agentMeta.publicKey}) not found in Lighter live response.`);
+                warnings.push(`Agent "${opts.agentName}" (expected public_key ${agentMeta.publicKey}) not found in ${venue} live response.`);
             }
         }
     }
     return { registered: items.length > 0, count: items.length, items, warnings: warnings.length > 0 ? warnings : undefined };
 }
+/** Ondo: authenticate GET /v1/account with the stored key (proves the key is live). */
+async function verifyOndo(network, opts) {
+    const meta = getVenueAgent("ondo", opts.agentName);
+    if (!meta) {
+        throw new PerpError("AGENT_NOT_REGISTERED", "No Ondo Perps API key registered", { remediation: "perp wallet agent approve ondo" });
+    }
+    const { loadOndoCredentials } = await import("../exchanges/ondo/agent.js");
+    const { OndoClient } = await import("../exchanges/ondo/client.js");
+    const def = getVenue("ondo");
+    const client = new OndoClient({
+        restUrl: networkConfig(def, network).restUrl,
+        network,
+        rateLimit: def.rateLimit,
+        credentials: loadOndoCredentials(meta.keyId),
+    });
+    const account = await client.get("/v1/account", null);
+    return { registered: true, count: 1, items: [{ agentName: meta.agentName, keyId: meta.keyId, accountID: account.accountID, accountState: account.accountState }] };
+}
+/** Arcus: GET /v1/apiKeys?address=<owner> and cross-check the stored key. */
+async function verifyArcus(network, opts) {
+    const meta = getVenueAgent("arcus", opts.agentName);
+    if (!meta) {
+        throw new PerpError("AGENT_NOT_REGISTERED", "No Arcus API key registered", { remediation: "perp wallet agent approve arcus --master <ows-wallet>" });
+    }
+    const { listArcusApiKeys } = await import("../exchanges/arcus/agent.js");
+    const keys = await listArcusApiKeys(network, meta.ownerAddress);
+    const warnings = [];
+    const hit = keys.find(k => k.apiKey.toLowerCase() === meta.apiKeyHex.toLowerCase());
+    if (!hit)
+        warnings.push(`Arcus key ${meta.apiKeyHex} ("${meta.agentName}") is not listed for ${meta.ownerAddress}`);
+    else if (hit.status !== "ACTIVE")
+        warnings.push(`Arcus key ${meta.apiKeyHex} status is ${hit.status}`);
+    return { registered: keys.length > 0, count: keys.length, items: keys, warnings: warnings.length > 0 ? warnings : undefined };
+}
+/**
+ * QFEX: a signed read as the bound account (GET /user/positions) and a Trade WebSocket
+ * authentication with that account. Read-only; nothing is cached from a denial.
+ */
+async function verifyQfex(network, opts) {
+    const meta = opts.agentName !== undefined ? getVenueAgent("qfex", opts.agentName) : getVenueAgentForNetwork("qfex", network);
+    if (!meta) {
+        throw new PerpError("AGENT_NOT_REGISTERED", `No QFEX API key imported for ${network}`, { remediation: `perp${network === "testnet" ? " -n testnet" : ""} wallet agent import qfex` });
+    }
+    if (meta.network !== network) {
+        throw new PerpError("AGENT_NOT_REGISTERED", `QFEX key "${meta.agentName}" was imported for ${meta.network}, not ${network}`, { remediation: `perp${meta.network === "testnet" ? " -n testnet" : ""} wallet agent verify qfex ${meta.agentName}` });
+    }
+    const { loadQfexCredentials } = await import("../exchanges/qfex/agent.js");
+    const { QfexClient } = await import("../exchanges/qfex/client.js");
+    const { QFEX_ENDPOINTS } = await import("../exchanges/venues/qfex.js");
+    const { QfexTradeSession, QFEX_TIMEOUTS, QFEX_IDLE_CLOSE_MS } = await import("../exchanges/qfex/ws-transport.js");
+    const credentials = loadQfexCredentials(meta.publicKey);
+    const ep = QFEX_ENDPOINTS[network];
+    const client = new QfexClient({ restUrl: ep.rest, bankerUrl: ep.banker, network, credentials, accountId: meta.accountId });
+    await client.get("/user/positions", null);
+    await new QfexTradeSession({
+        url: ep.tradeWs, network, credentials, accountId: meta.accountId, builderCode: null,
+        rateLimit: getVenue("qfex").rateLimit, timeouts: QFEX_TIMEOUTS, idleCloseMs: QFEX_IDLE_CLOSE_MS,
+    }).verifyAuth();
+    return {
+        registered: true, count: 1,
+        items: [{ agentName: meta.agentName, publicKey: meta.publicKey, accountId: meta.accountId, isPrimaryAccount: meta.isPrimaryAccount, network: meta.network, checks: "signed GET /user/positions as the account; Trade WebSocket authentication" }],
+    };
+}
+/**
+ * Confirmation of the account a QFEX key was resolved to (design §14.12 #9). In a terminal: a
+ * y/N prompt showing the UUID. Without one (piped stdin, --json): only an explicit --account-id
+ * that equals the resolved account counts — the resolved UUID is printed on stderr either way.
+ */
+export function confirmImportAccount(explicitAccountId, json) {
+    return async (binding) => {
+        const what = `QFEX account ${binding.accountId} (${binding.isPrimaryAccount ? "primary" : "subaccount"})`;
+        process.stderr.write(`  This key will trade ${what} — ${binding.method}\n`);
+        if (explicitAccountId !== null && explicitAccountId.toLowerCase() === binding.accountId)
+            return true;
+        if (json || process.stdin.isTTY !== true || process.stdout.isTTY !== true) {
+            throw new PerpError("INVALID_PARAMS", `QFEX import needs the account confirmed: the key resolves to ${what}`, {
+                remediation: `Re-run with that account named explicitly: perp wallet agent import qfex --account-id ${binding.accountId}`,
+            });
+        }
+        const { createInterface } = await import("node:readline/promises");
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        try {
+            const a = (await rl.question(`  Store the key for ${what}? [y/N]: `)).trim().toLowerCase();
+            return a === "y" || a === "yes";
+        }
+        finally {
+            rl.close();
+        }
+    };
+}
+/** Dispatch a verify to the venue-specific implementation. */
+async function verifyVenue(ex, network, opts) {
+    if (ex === "aster")
+        return verifyAster(opts);
+    if (ex === "hyperliquid")
+        return verifyHyperliquid(network, opts);
+    if (ex === "pacifica")
+        return verifyPacifica(network, opts);
+    if (isLighterFamilyVenue(ex))
+        return verifyLighter(ex, network, opts);
+    if (ex === "ondo")
+        return verifyOndo(network, opts);
+    if (ex === "arcus")
+        return verifyArcus(network, opts);
+    if (ex === "qfex")
+        return verifyQfex(network, opts);
+    throw new PerpError("NOT_IMPLEMENTED", `${ex} has no agents to verify`, {
+        remediation: "perp wallet agent verify <aster|hyperliquid|pacifica|lighter|lighter-rh|ondo|arcus|qfex> [agentName]",
+    });
+}
+/**
+ * Why agent `op` cannot run for `venue` on `network`; null when it can. Every
+ * other venue resolves endpoints / signing chain from the selected network
+ * (venue definition) — never a mainnet fallback.
+ *
+ * Aster testnet: approve uses POST /fapi/v3/registerAndApproveAgent, documented
+ * for testnet (asterdex/api-docs V3 aster-finance-futures-api-testnet.md,
+ * 2026-05-12). Revoke / rotate need the master-signed DelAgent (AsterChain,
+ * Domain A) flow, which the testnet docs do not document.
+ */
+export function agentApproveUnsupportedReason(venue, network, op) {
+    if (venue === "aster" && network === "testnet" && op !== "approve") {
+        return "the testnet API documents only registerAndApproveAgent — no agent delete / rotate flow";
+    }
+    return null;
+}
+/** Throws the uniform CAPABILITY_UNSUPPORTED error when agentApproveUnsupportedReason() is non-null. */
+export function assertAgentApproveSupported(venue, network, op) {
+    if (venue === "qfex") {
+        // Programmatic key creation needs a website session (SIWE + MFA) — not a CLI path.
+        throw unsupported("qfex", "agentApprove", "API keys are created (and revoked) on the QFEX website, behind 2FA", `Create the key in QFEX Developer Settings, then import it: perp${network === "testnet" ? " -n testnet" : ""} wallet agent import qfex`);
+    }
+    const reason = agentApproveUnsupportedReason(venue, network, op);
+    if (reason === null)
+        return;
+    throw unsupported(getVenue(venue).displayName, `agent ${op} on ${network}`, reason, "Revoke the testnet API agent at https://www.asterdex-testnet.com/en/api-wallet (Pro API), then approve a new one: perp -n testnet wallet agent approve aster");
+}
+/**
+ * Aster master-signed Domain A structs (ApproveAgent / DelAgent) carry an
+ * AsterChain field and are documented for mainnet only — refuse anything else.
+ */
+function assertAsterDomainAMainnet(network) {
+    if (network === "mainnet")
+        return;
+    throw unsupported("Aster", `master-signed agent operations on ${network}`, "the AsterChain-bearing approveAgent / DelAgent structs are documented for mainnet only", "On testnet use: perp -n testnet wallet agent approve aster (registerAndApproveAgent)");
+}
+/** Default agent name per venue and network (the `--agent-name` default of `wallet agent approve`). */
+export function defaultAgentName(venue, network) {
+    // Short suffix: Hyperliquid limits agent names to 16 characters ("perp-cli-hl-tn" = 14).
+    const suffix = network === "testnet" ? "-tn" : "";
+    switch (venue) {
+        case "aster": return `perp-cli-aster${suffix}`;
+        case "hyperliquid": return `perp-cli-hl${suffix}`;
+        case "pacifica": return `perp-cli-pac${suffix}`;
+        case "lighter": return `perp-cli-lt${suffix}`;
+        case "lighter-rh": return `perp-cli-lrh${suffix}`;
+        case "ondo": return `perp-cli-ondo${suffix}`;
+        case "arcus": return `perp-cli-arcus${suffix}`;
+        case "qfex": return `perp-cli-qfex${suffix}`;
+    }
+}
+/**
+ * Local OWS agent wallet name. Testnet agents get their own wallet so a
+ * testnet approve never collides with (or reuses) the mainnet agent key.
+ */
+function agentWalletNameFor(prefix, masterName, network) {
+    return network === "testnet" ? `agent-${prefix}-${masterName}-testnet` : `agent-${prefix}-${masterName}`;
+}
+/**
+ * The agent's OWS wallet name is fixed per venue + master + network, and OWS refuses a duplicate
+ * name. An existing wallet of that name is refused here, before anything is created or signed.
+ */
+function assertAgentWalletNameFree(venue, agentWalletName, network) {
+    if (!loadOws().listWallets().some((w) => w.name === agentWalletName))
+        return;
+    const net = network === "testnet" ? " -n testnet" : "";
+    const owner = listAgents(venue).find(a => a.meta.agentWalletName === agentWalletName);
+    if (owner !== undefined) {
+        throw new PerpError("INVALID_PARAMS", `${venue} agent "${owner.meta.agentName}" already exists (its OWS wallet "${agentWalletName}" is in use)`, {
+            exchange: venue,
+            remediation: `Replace it (revoke + new key): perp${net} wallet agent approve ${venue} --rotate, or perp${net} wallet agent rotate ${venue} ${owner.meta.agentName}`,
+        });
+    }
+    throw new PerpError("INVALID_PARAMS", `OWS wallet "${agentWalletName}" already exists but no ${venue} agent record uses it (left over from an interrupted approve)`, {
+        exchange: venue,
+        remediation: `If no ${venue} agent on the venue uses its key, delete it (ows wallet delete ${agentWalletName}) and re-run the approve`,
+    });
+}
+/** Refuse to overwrite a legacy-shaped agent record registered on another network. */
+function assertAgentNameFree(venue, agentName, network) {
+    const existing = getAgent(venue, agentName);
+    if (existing !== null && agentNetworkOf(venue, existing) !== network) {
+        throw new PerpError("INVALID_PARAMS", `${venue} agent "${agentName}" is already registered on ${agentNetworkOf(venue, existing)}`, {
+            remediation: `Choose another --agent-name for the ${network} agent (default: ${defaultAgentName(venue, network)})`,
+        });
+    }
+}
+/** Ondo / Arcus: refuse (even with --rotate) to replace a record registered on another network. */
+function assertVenueAgentNameFree(venue, agentName, network) {
+    const existing = getVenueAgent(venue, agentName);
+    if (existing !== null && existing.network !== network) {
+        throw new PerpError("INVALID_PARAMS", `${venue} agent "${agentName}" is already registered on ${existing.network}`, {
+            remediation: `Choose another --agent-name for the ${network} agent (default: ${defaultAgentName(venue, network)})`,
+        });
+    }
+}
+function parseExpiresInParam(expiresIn) {
+    try {
+        return parseExpiresIn(expiresIn);
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        throw new PerpError("INVALID_PARAMS", msg, { remediation: "Use: 30d, 90d, 180d, 1y, or ISO-8601 datetime" });
+    }
+}
+function requireMaster(master) {
+    const name = master ?? loadSettings().owsActiveWallet;
+    if (!name) {
+        // No master wallet on this computer: approving signs with the master, so it cannot run here.
+        throw new PerpError("NO_SIGNER_AVAILABLE", "Agent approval is signed by the master wallet, and none is configured on this computer (no --master, settings.owsActiveWallet empty)", {
+            remediation: "Create the agent / API key on the exchange website and import it: perp wallet agent import <venue> (hidden prompt / stdin). Or add the master wallet (perp wallet import --name <name>) and pass --master <name>.",
+        });
+    }
+    return name;
+}
+function requirePassphrase(passphrase) {
+    if (passphrase === null) {
+        throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
+            remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
+        });
+    }
+    return passphrase;
+}
+/**
+ * Register one agent wallet / API key on `venue`. Throws on any failure (the
+ * caller decides whether to exit or continue with other venues). Holds the
+ * per-venue lock for the duration of the venue round-trip.
+ */
+export async function approveVenueAgent(p) {
+    assertAgentApproveSupported(p.venue, p.network, "approve");
+    const agentName = p.agentName ?? defaultAgentName(p.venue, p.network);
+    // Ondo: HMAC key entered on stdin only (design §10.4)
+    if (p.venue === "ondo") {
+        assertVenueAgentNameFree("ondo", agentName, p.network);
+        if (getVenueAgent("ondo", agentName) && !p.rotate) {
+            throw new PerpError("INVALID_PARAMS", `Ondo agent "${agentName}" already exists`, {
+                remediation: "Pass --rotate to replace it, or choose another --agent-name",
+            });
+        }
+        const { approveOndoAgent } = await import("../exchanges/ondo/agent.js");
+        const { keyId, secret } = p.ondoKey ?? await readOndoKeyFromStdin();
+        const meta = await approveOndoAgent({ agentName, keyId, secret, network: p.network });
+        setVenueAgent("ondo", meta);
+        return { venue: "ondo", meta };
+    }
+    // Arcus: OWS Ed25519 agent + EIP-712 createApiKey (design §10.4)
+    if (p.venue === "arcus") {
+        const masterName = requireMaster(p.master);
+        assertVenueAgentNameFree("arcus", agentName, p.network);
+        if (getVenueAgent("arcus", agentName) && !p.rotate) {
+            throw new PerpError("INVALID_PARAMS", `Arcus agent "${agentName}" already exists`, {
+                remediation: "Pass --rotate to re-register it, or choose another --agent-name",
+            });
+        }
+        const expiresAt = parseExpiresIn(p.expiresIn);
+        const validDays = Math.ceil((expiresAt.getTime() - Date.now()) / 86_400_000);
+        const { approveArcusAgent } = await import("../exchanges/arcus/agent.js");
+        acquireLock("arcus");
+        try {
+            const meta = await approveArcusAgent({
+                agentName, masterOwsWallet: masterName, passphrase: p.passphrase, accountIndex: p.accountIndex, network: p.network, validDays,
+            });
+            setVenueAgent("arcus", meta);
+            return { venue: "arcus", meta };
+        }
+        finally {
+            releaseLock("arcus");
+        }
+    }
+    const expiresAt = parseExpiresInParam(p.expiresIn);
+    const masterName = requireMaster(p.master);
+    const expiresAtIso = expiresAt.toISOString();
+    const nowIso = new Date().toISOString();
+    assertAgentNameFree(p.venue, agentName, p.network);
+    // --rotate: the same path as `wallet agent rotate` (venue-confirmed revoke → delete the old
+    // local key → approve), for the OWS-stored agents (the fixed `agent-<dex>-<master>` wallet name
+    // would otherwise collide with the previous agent's) and the Lighter-family keystore agents.
+    // Without --rotate an existing agent of this name is never silently replaced.
+    if (p.venue === "pacifica" || p.venue === "hyperliquid" || p.venue === "aster" || isLighterFamilyVenue(p.venue)) {
+        if (!p.rotate) {
+            if (getAgent(p.venue, agentName) !== null) {
+                const net = p.network === "testnet" ? " -n testnet" : "";
+                throw new PerpError("INVALID_PARAMS", `${p.venue} agent "${agentName}" already exists on this computer`, {
+                    exchange: p.venue,
+                    remediation: `Replace it (revoke the old key, register a fresh one): perp${net} wallet agent approve ${p.venue} --rotate — or choose another --agent-name`,
+                });
+            }
+        }
+        else if (!isLighterFamilyVenue(p.venue) || getAgent(p.venue, agentName) !== null) {
+            return rotateVenueAgent({
+                exchange: p.venue, network: p.network, agentNameToRotate: agentName, master: p.master,
+                passphrase: async () => p.passphrase, expiresIn: p.expiresIn,
+                canPerp: p.canPerp, canSpot: p.canSpot, canWithdraw: p.canWithdraw, ipWhitelist: p.aster.ipWhitelist,
+            });
+        }
+    }
+    // Lighter family (lighter, lighter-rh): slot must be 4..254 minus venue-reserved
+    if (isLighterFamilyVenue(p.venue)) {
+        const ltVenue = p.venue;
+        if (p.apiKeyIndex !== null)
+            assertLighterSlot(ltVenue, p.apiKeyIndex);
+        const passphrase = requirePassphrase(p.passphrase);
+        acquireLock(ltVenue);
+        try {
+            const result = await runLtApproveFlow({
+                venue: ltVenue, network: p.network, masterName, passphrase, agentName, expiresAt, expiresAtIso, nowIso,
+                canPerp: p.canPerp, canSpot: p.canSpot, canWithdraw: p.canWithdraw,
+                apiKeyIndex: p.apiKeyIndex ?? undefined,
+                forceSlot: p.forceSlot,
+            });
+            return { venue: ltVenue, agentName, expiresAt: expiresAtIso, result };
+        }
+        finally {
+            releaseLock(ltVenue);
+        }
+    }
+    const passphrase = requirePassphrase(p.passphrase);
+    if (p.venue === "pacifica") {
+        acquireLock("pacifica");
+        try {
+            const result = await runPacApproveFlow({
+                network: p.network, masterName, passphrase, agentName, expiresAt, expiresAtIso, nowIso,
+                canPerp: p.canPerp, canSpot: p.canSpot, canWithdraw: p.canWithdraw,
+            });
+            return { venue: "pacifica", agentName, expiresAt: expiresAtIso, result };
+        }
+        finally {
+            releaseLock("pacifica");
+        }
+    }
+    if (p.venue === "hyperliquid") {
+        acquireLock("hyperliquid");
+        try {
+            const result = await runHlApproveFlow({
+                network: p.network, masterName, passphrase, agentName, expiresAt, expiresAtIso, nowIso,
+                canPerp: p.canPerp, canSpot: p.canSpot, canWithdraw: p.canWithdraw,
+            });
+            return { venue: "hyperliquid", agentName, expiresAt: expiresAtIso, result };
+        }
+        finally {
+            releaseLock("hyperliquid");
+        }
+    }
+    // Aster. Acquire the lock at the START of the flow (before any OWS resources
+    // are created) so that concurrent approves are fully serialized, not just
+    // the final settings write.
+    const nonceMicros = Date.now() * 1000 + (Math.floor(Math.random() * 1000));
+    acquireLock("aster");
+    try {
+        const result = await runApproveFlow({
+            network: p.network, masterName, passphrase, agentName, expiresAt,
+            expiredMs: expiresAt.getTime(), expiresAtIso, nonceMicros, nowIso,
+            canPerp: p.canPerp, canSpot: p.canSpot, canWithdraw: p.canWithdraw,
+            ipWhitelist: p.aster.ipWhitelist,
+        });
+        return { venue: "aster", agentName, expiresAt: expiresAtIso, result };
+    }
+    finally {
+        releaseLock("aster");
+    }
+}
+/**
+ * Loud warning for a QFEX key that has — or may have (it cannot be checked without acting) — the
+ * "Deposit and withdraw" permission. Such a key can withdraw with the key alone, and imported keys
+ * are stored with an empty passphrase (file permissions only). Not a block: a funding key is needed
+ * for a QFEX withdrawal. Shown at import and in `wallet agent list`. null = no warning.
+ */
+export function qfexWithdrawKeyWarning(meta) {
+    if (meta.permissions.depositWithdraw === false)
+        return null;
+    const has = meta.permissions.depositWithdraw === true ? "HAS" : "MAY HAVE (cannot be checked without withdrawing)";
+    return `QFEX key "${meta.agentName}" ${has} the "Deposit and withdraw" permission and is stored with an EMPTY passphrase (protected by file permissions only) — anyone who can read ~/.perp can withdraw with it. Delete it right after use: perp wallet agent revoke qfex ${meta.agentName} --local-only, and delete the key on the QFEX website.`;
+}
+/**
+ * Rotate an agent: venue-confirmed revoke of the existing agent (when one is recorded), delete
+ * its dead OWS wallet and local record, then approve a fresh agent under the same name. The single
+ * path of `wallet agent rotate` and `wallet agent approve --rotate`.
+ */
+export async function rotateVenueAgent(p) {
+    const { exchange, network, agentNameToRotate } = p;
+    const settings = loadSettings();
+    // Capture existing agent meta before revoke (for permission inheritance).
+    // It must belong to the selected network — rotate never crosses networks.
+    // The OWS agent wallet name derives from the master (one per venue + master + network), so
+    // under a NEW agent name the agent to replace is the record that owns that wallet.
+    const named = getAgent(exchange, agentNameToRotate);
+    if (named !== null)
+        assertAgentNetwork(exchange, named, network);
+    const walletOwner = () => {
+        if (isLighterFamilyVenue(exchange))
+            return null;
+        const master = p.master || settings.owsActiveWallet;
+        if (!master)
+            return null;
+        const walletName = agentWalletNameFor(exchange === "hyperliquid" ? "hl" : exchange === "pacifica" ? "pac" : "aster", master, network);
+        const owner = listAgents(exchange).find(a => a.meta.agentWalletName === walletName && agentNetworkOf(exchange, a.meta) === network);
+        return owner === undefined ? null : owner.meta;
+    };
+    const existing = named ?? walletOwner();
+    if (existing !== null && agentSourceOf(exchange, existing) === "imported") {
+        const net = network === "testnet" ? " -n testnet" : "";
+        throw new PerpError("INVALID_PARAMS", `${exchange} agent "${agentNameToRotate}" was imported from the exchange website — this CLI cannot rotate it (no master wallet signature)`, {
+            remediation: `Create a new key on the ${getVenue(exchange).displayName} website (and delete the old one there), then: perp${net} wallet agent import ${exchange} --agent-name ${agentNameToRotate} --replace`,
+        });
+    }
+    // The new agent is approved by the old agent's master unless --master says
+    // otherwise; resolved before the revoke so an unknown master changes nothing.
+    const masterName = p.master || existing?.masterWalletName || settings.owsActiveWallet;
+    if (!masterName) {
+        throw new PerpError("INVALID_PARAMS", `No master wallet for rotating ${exchange} agent "${agentNameToRotate}": no --master, no master on the agent record, and settings.owsActiveWallet is empty`, {
+            remediation: `Pass the master that registered it: perp wallet agent rotate ${exchange} ${agentNameToRotate} --master <ows-wallet>`,
+        });
+    }
+    // Resolve permissions BEFORE anything is revoked: explicit flags > old agent's trade
+    // permissions > defaults. With --no-can-perp/spot pattern, opts values are undefined when not
+    // passed. canWithdraw is NEVER inherited: only an explicit --can-withdraw grants it.
+    const permFlagsProvided = p.canPerp !== undefined || p.canSpot !== undefined;
+    let canPerp;
+    let canSpot;
+    if (permFlagsProvided) {
+        canPerp = p.canPerp ?? true;
+        canSpot = p.canSpot ?? false;
+    }
+    else if (existing?.permissions) {
+        // Preserve old agent's trade permissions when flags are absent
+        canPerp = existing.permissions.canPerpTrade;
+        canSpot = existing.permissions.canSpotTrade;
+    }
+    else {
+        canPerp = true;
+        canSpot = false;
+    }
+    const canWithdraw = p.canWithdraw === true;
+    // Aster: --can-withdraw without --ip-whitelist is refused here, before the passphrase is read
+    // and before the old agent is revoked (a later refusal would leave no agent at all).
+    if (exchange === "aster")
+        assertAsterWithdrawIpWhitelist(canWithdraw, p.ipWhitelist);
+    // Resolve passphrase (needed for both revoke and approve phases)
+    const passphrase = await p.passphrase();
+    if (passphrase === null) {
+        throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
+            remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
+        });
+    }
+    // Revoke the existing agent (if present) BEFORE approving the new one.
+    // Fail closed: if the venue does not confirm the revoke, abort with the
+    // old agent's local record (and keys) untouched and no new agent
+    // approved — the user keeps a working, recorded agent and can retry.
+    // The local record is deleted only after a confirmed revoke, so a later
+    // approve failure leaves no agent but nothing still authorized either.
+    if (existing) {
+        try {
+            if (exchange === "pacifica") {
+                // Pacifica master is a Solana keypair; can't reuse the EVM master signer.
+                const revokePacSigner = OwsSolanaSigner.create(existing.masterWalletName, passphrase);
+                await revokePacAgent(revokePacSigner, existing.agentSolanaAddress ?? null, network);
+            }
+            else if (isLighterFamilyVenue(exchange)) {
+                // LT rotate: kill the old slot (ChangePubKey to a throwaway key) and delete
+                // its keystore file before the new approve registers a fresh slot.
+                await revokeLtAgent(exchange, network, existing, passphrase);
+            }
+            else if (exchange === "hyperliquid") {
+                const revokeMs = OwsEvmSigner.create(existing.masterWalletName, passphrase);
+                await revokeHlAgent(revokeMs, network, existing.agentName, existing.agentEvmAddress);
+            }
+            else {
+                // Aster: DELETE /fapi/v3/agent — the response decides success.
+                const revokeMs = OwsEvmSigner.create(existing.masterWalletName, passphrase);
+                await assertAsterAgentDeleted(await deleteAsterAgent(revokeMs, existing.agentEvmAddress, network), existing.agentEvmAddress, `The old agent "${existing.agentName}" and its local record were kept and no new agent was approved. Retry the rotate, or delete the agent in the Aster UI and run: perp wallet agent revoke aster ${existing.agentName} --force`);
+            }
+        }
+        catch (revokeErr) {
+            if (revokeErr instanceof PerpError && (revokeErr.structured.code === "APPROVE_FAILED" || revokeErr.structured.code === "APPROVE_PARTIAL"))
+                throw revokeErr;
+            throw new PerpError("APPROVE_FAILED", `Rotate aborted: revoking the previous ${exchange} agent "${existing.agentName}" failed — it may still be authorized. ${revokeErr instanceof Error ? revokeErr.message : String(revokeErr)}`, {
+                exchange,
+                remediation: `The old agent and its local record were kept and no new agent was approved. Retry: perp wallet agent rotate ${exchange} ${existing.agentName}`,
+            });
+        }
+        if (existing.owsApiKeyId) {
+            try {
+                loadOws().revokeApiKey(existing.owsApiKeyId);
+            }
+            catch { /* best effort */ }
+        }
+        // Confirmed revoke → the old OWS agent wallet is dead; delete it so the approve
+        // below can create the same `agent-<dex>-<master>` name (OWS refuses duplicates).
+        if (!isLighterFamilyVenue(exchange))
+            deleteRevokedAgentWallet(exchange, existing);
+        deleteAgent(exchange, existing.agentName);
+    }
+    const expiresAt = parseExpiresIn(p.expiresIn);
+    const expiresAtIso = expiresAt.toISOString();
+    const nowIso = new Date().toISOString();
+    // Acquire lock and run the shared approve flow
+    acquireLock(exchange);
+    try {
+        if (exchange === "hyperliquid") {
+            const result = await runHlApproveFlow({
+                network,
+                masterName,
+                passphrase,
+                agentName: agentNameToRotate,
+                expiresAt,
+                expiresAtIso,
+                nowIso,
+                canPerp,
+                canSpot,
+                canWithdraw,
+            });
+            return { venue: "hyperliquid", agentName: agentNameToRotate, expiresAt: expiresAtIso, result };
+        }
+        else if (exchange === "pacifica") {
+            const result = await runPacApproveFlow({
+                network,
+                masterName,
+                passphrase,
+                agentName: agentNameToRotate,
+                expiresAt,
+                expiresAtIso,
+                nowIso,
+                canPerp,
+                canSpot,
+                canWithdraw,
+            });
+            return { venue: "pacifica", agentName: agentNameToRotate, expiresAt: expiresAtIso, result };
+        }
+        else if (isLighterFamilyVenue(exchange)) {
+            const result = await runLtApproveFlow({
+                venue: exchange,
+                network,
+                masterName,
+                passphrase,
+                agentName: agentNameToRotate,
+                expiresAt,
+                expiresAtIso,
+                nowIso,
+                canPerp,
+                canSpot,
+                canWithdraw,
+                // No apiKeyIndex override on rotate — picks next slot free locally and on-chain.
+                forceSlot: false,
+            });
+            return { venue: exchange, agentName: agentNameToRotate, expiresAt: expiresAtIso, result };
+        }
+        else {
+            const expiredMs = expiresAt.getTime();
+            const nonceMicros = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+            const result = await runApproveFlow({
+                network,
+                masterName,
+                passphrase,
+                agentName: agentNameToRotate,
+                expiresAt,
+                expiredMs,
+                expiresAtIso,
+                nonceMicros,
+                nowIso,
+                canPerp,
+                canSpot,
+                canWithdraw,
+                ipWhitelist: p.ipWhitelist,
+            });
+            return { venue: "aster", agentName: agentNameToRotate, expiresAt: expiresAtIso, result };
+        }
+    }
+    finally {
+        releaseLock(exchange);
+    }
+}
+/** Display identity of a rotated agent (EVM / Solana address, or the Lighter slot + public key). */
+function rotatedAgentAddressOf(o) {
+    if (o.venue === "hyperliquid" || o.venue === "aster")
+        return o.result.agentAddress;
+    if (o.venue === "pacifica")
+        return o.result.agentSolanaAddress;
+    return `slot=${o.result.apiKeyIndex} pubkey=${o.result.publicKey}`;
+}
+/** Live (read-only) registration check for `venue` — `wallet agent verify <venue>`. */
+export async function verifyVenueAgent(venue, network, opts) {
+    return verifyVenue(venue, network, { master: opts.master ?? undefined, passphrase: opts.passphrase });
+}
+/** Human-readable summary of a successful approve (no secrets — public ids/addresses only). */
+export function printApproveOutcome(outcome) {
+    switch (outcome.venue) {
+        case "ondo":
+            console.log(chalk.green.bold("\n  Ondo Perps API key registered!\n"));
+            console.log(`  Name:     ${chalk.cyan(outcome.meta.agentName)}`);
+            console.log(`  Key ID:   ${chalk.cyan(outcome.meta.keyId)}`);
+            console.log(`  Keystore: ${chalk.gray(outcome.meta.keystorePath)}`);
+            console.log();
+            return;
+        case "arcus":
+            console.log(chalk.green.bold("\n  Arcus API key registered!\n"));
+            console.log(`  Name:          ${chalk.cyan(outcome.meta.agentName)}`);
+            console.log(`  API Key:       ${chalk.cyan(outcome.meta.apiKeyHex)}`);
+            console.log(`  Owner:         ${chalk.cyan(outcome.meta.ownerAddress)}`);
+            console.log(`  Account Index: ${chalk.cyan(String(outcome.meta.accountIndex))}`);
+            console.log(`  Valid Until:   ${chalk.cyan(outcome.meta.validUntil)}`);
+            console.log();
+            return;
+        case "lighter":
+        case "lighter-rh":
+            console.log(chalk.green.bold(`\n  ${getVenue(outcome.venue).displayName} Agent approved successfully!\n`));
+            console.log(`  Name:           ${chalk.cyan(outcome.agentName)}`);
+            console.log(`  API Key Index:  ${chalk.cyan(String(outcome.result.apiKeyIndex))}`);
+            console.log(`  Public Key:     ${chalk.cyan(outcome.result.publicKey)}`);
+            console.log(`  Account Index:  ${chalk.cyan(String(outcome.result.accountIndex))}`);
+            console.log(`  Expires:        ${chalk.cyan(outcome.expiresAt)}`);
+            console.log();
+            return;
+        case "pacifica":
+            console.log(chalk.green.bold("\n  Pacifica Agent approved successfully!\n"));
+            console.log(`  Name:           ${chalk.cyan(outcome.agentName)}`);
+            console.log(`  Agent Address:  ${chalk.cyan(outcome.result.agentSolanaAddress)}`);
+            console.log(`  Master Address: ${chalk.cyan(outcome.result.userSolanaAddress)}`);
+            console.log(`  Expires:        ${chalk.cyan(outcome.expiresAt)}`);
+            console.log();
+            return;
+        case "hyperliquid":
+            console.log(chalk.green.bold("\n  Hyperliquid Agent approved successfully!\n"));
+            console.log(`  Name:          ${chalk.cyan(outcome.agentName)}`);
+            console.log(`  Agent Address: ${chalk.cyan(outcome.result.agentAddress)}`);
+            console.log(`  Expires:       ${chalk.cyan(outcome.expiresAt)}`);
+            console.log();
+            return;
+        case "aster":
+            console.log(chalk.green.bold("\n  Agent approved successfully!\n"));
+            console.log(`  Name:          ${chalk.cyan(outcome.agentName)}`);
+            console.log(`  Agent Address: ${chalk.cyan(outcome.result.agentAddress)}`);
+            console.log(`  Expires:       ${chalk.cyan(outcome.expiresAt)}`);
+            console.log(`  API Key ID:    ${chalk.gray(outcome.result.owsApiKeyId)}`);
+            console.log(`  Policy ID:     ${chalk.gray(outcome.result.policyId)}`);
+            console.log();
+            return;
+    }
+}
 /**
  * Register the per-DEX agent-wallet management subtree (`approve` /
  * `list` / `revoke` / `rotate` / `verify`) under the supplied parent
@@ -248,7 +1043,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
     // ── agent approve <exchange> ── register an agent wallet ──────────────────
     agent
         .command("approve <exchange>")
-        .description("Register an agent wallet for an exchange (Phase 2a/b/c/d: aster, hyperliquid, pacifica, lighter)")
+        .description("Register an agent wallet / API key for an exchange (aster, hyperliquid, pacifica, lighter, lighter-rh, ondo, arcus)")
         .option("--master <name>", "Master OWS wallet name")
         .option("--agent-name <name>", "Agent name (default: perp-cli-aster)")
         .option("--expires-in <duration>", "Expiry: 30d, 90d, 180d, 1y, or ISO-8601 datetime (default: 90d)")
@@ -259,12 +1054,14 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         .option("--can-withdraw", "Allow withdrawals (default: off)", false)
         .option("--no-withdraw", "Disallow withdrawals")
         .option("--rotate", "Allow re-approving an existing agent name")
-        .option("--passphrase <pp>", "Master OWS passphrase (fallback: OWS_PASSPHRASE env / stdin)")
-        .option("--builder <addr>", "Builder address for optional builder approval")
-        .option("--max-fee-rate <bps>", "Max fee rate bps (required with --builder)")
-        .option("--builder-name <name>", "Optional builder name")
-        .option("--ip-whitelist <list>", "Comma-separated IP whitelist (pass empty string to include empty)")
-        .option("--api-key-index <n>", "Lighter slot index (4-254). Default: next free slot.")
+        .addOption(deprecatedPassphraseOption()).hook("preAction", warnDeprecatedPassphrase)
+        .addOption(new Option("--builder <addr>", "Removed — use: perp wallet builder approve <venue>").hideHelp())
+        .addOption(new Option("--max-fee-rate <rate>", "Removed — use: perp wallet builder approve <venue>").hideHelp())
+        .addOption(new Option("--builder-name <name>", "Removed — use: perp wallet builder approve <venue>").hideHelp())
+        .option("--ip-whitelist <list>", "Aster IP whitelist, comma- or space-separated (required with --can-withdraw)")
+        .option("--api-key-index <n>", "Lighter / Lighter RH slot index (4-254; RH also excludes 157). Default: next slot free locally and on-chain.")
+        .option("--force", "Lighter / Lighter RH: overwrite an --api-key-index slot that already holds an on-chain key (kills whatever signs with it)")
+        .option("--account-index <n>", "Arcus subaccount the key is scoped to: 0-9, or 255 for all (trading needs 0-9)", "0")
         .option("--json", "Machine-readable output")
         .action(async (exchange, opts, command) => {
         const useJson = opts.json ?? isJson();
@@ -275,333 +1072,183 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         // was approve throwing PASSPHRASE_REQUIRED even with --passphrase set.
         const mergedOpts = command.optsWithGlobals();
         const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
-        // Normalize aliases
-        const exchangeNorm = exchange === "lt" ? "lighter"
-            : exchange === "hl" ? "hyperliquid"
-                : exchange === "pac" ? "pacifica"
-                    : exchange === "ast" ? "aster"
-                        : exchange;
-        // Phase 2d: Aster + HL + PAC + LT all implemented.
-        if (exchangeNorm !== "aster" &&
-            exchangeNorm !== "hyperliquid" &&
-            exchangeNorm !== "pacifica" &&
-            exchangeNorm !== "lighter") {
-            reportErrorAndExit(new PerpError("NOT_IMPLEMENTED", `${exchange} agent approve not implemented`, {
-                remediation: "Use one of: aster, hyperliquid, pacifica, lighter",
-            }));
-        }
-        // ── Lighter approve branch (Phase 2d) ───────────────────────────────
-        if (exchangeNorm === "lighter") {
-            const masterName = opts.master ?? loadSettings().owsActiveWallet;
-            const agentName = opts.agentName ?? "perp-cli-lt";
-            const expiresIn = opts.expiresIn ?? "90d";
-            let expiresAt;
-            try {
-                expiresAt = parseExpiresIn(expiresIn);
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                reportErrorAndExit(new PerpError("INVALID_PARAMS", msg, {
-                    remediation: "Use: 30d, 90d, 180d, 1y, or ISO-8601 datetime",
-                }));
-            }
-            if (!masterName) {
-                reportErrorAndExit(new PerpError("INVALID_PARAMS", "Master wallet name is required. Use --master or set owsActiveWallet in settings.", {
-                    remediation: "Run: perp setup or use --master <name>",
-                }));
-            }
-            // Slot validation: explicit value must be 4..254. Otherwise pick free slot.
-            let chosenSlot;
-            if (opts.apiKeyIndex !== undefined) {
-                const n = parseInt(opts.apiKeyIndex, 10);
-                if (!Number.isInteger(n) || n < 4 || n > 254) {
-                    reportErrorAndExit(new PerpError("INVALID_PARAMS", `--api-key-index must be an integer in [4, 254]; got ${opts.apiKeyIndex}`, {
-                        remediation: "Slots 0-3 are reserved by the Lighter frontend. Use 4-254.",
-                    }));
-                }
-                chosenSlot = n;
-            }
-            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
-            if (passphrase === null) {
-                reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
-                    remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
-                }));
-            }
-            try {
-                acquireLock("lighter");
-                try {
-                    const result = await runLtApproveFlow({
-                        masterName,
-                        passphrase: passphrase ?? "",
-                        agentName,
-                        expiresAt,
-                        expiresAtIso: expiresAt.toISOString(),
-                        nowIso: new Date().toISOString(),
-                        canPerp: opts.canPerp ?? true,
-                        canSpot: opts.canSpot ?? false,
-                        canWithdraw: opts.canWithdraw ?? false,
-                        apiKeyIndex: chosenSlot,
-                    });
-                    if (useJson) {
-                        printJson(jsonOk(result));
-                    }
-                    else {
-                        console.log(chalk.green.bold("\n  Lighter Agent approved successfully!\n"));
-                        console.log(`  Name:           ${chalk.cyan(agentName)}`);
-                        console.log(`  API Key Index:  ${chalk.cyan(String(result.apiKeyIndex))}`);
-                        console.log(`  Public Key:     ${chalk.cyan(result.publicKey)}`);
-                        console.log(`  Account Index:  ${chalk.cyan(String(result.accountIndex))}`);
-                        console.log(`  Expires:        ${chalk.cyan(expiresAt.toISOString())}`);
-                        console.log();
-                    }
-                }
-                finally {
-                    releaseLock("lighter");
-                }
-            }
-            catch (err) {
-                reportErrorAndExit(err);
-            }
-            return;
-        }
-        // ── Pacifica approve branch (Phase 2c) ──────────────────────────────
-        if (exchangeNorm === "pacifica") {
-            const masterName = opts.master ?? loadSettings().owsActiveWallet;
-            const agentName = opts.agentName ?? "perp-cli-pac";
-            const expiresIn = opts.expiresIn ?? "90d";
-            let expiresAt;
-            try {
-                expiresAt = parseExpiresIn(expiresIn);
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                reportErrorAndExit(new PerpError("INVALID_PARAMS", msg, {
-                    remediation: "Use: 30d, 90d, 180d, 1y, or ISO-8601 datetime",
-                }));
-            }
-            if (!masterName) {
-                reportErrorAndExit(new PerpError("INVALID_PARAMS", "Master wallet name is required. Use --master or set owsActiveWallet in settings.", {
-                    remediation: "Run: perp setup or use --master <name>",
-                }));
-            }
-            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
-            if (passphrase === null) {
-                reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
-                    remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
-                }));
-            }
-            try {
-                acquireLock("pacifica");
-                try {
-                    const result = await runPacApproveFlow({
-                        masterName,
-                        passphrase: passphrase ?? "",
-                        agentName,
-                        expiresAt,
-                        expiresAtIso: expiresAt.toISOString(),
-                        nowIso: new Date().toISOString(),
-                        canPerp: opts.canPerp ?? true,
-                        canSpot: opts.canSpot ?? false,
-                        canWithdraw: opts.canWithdraw ?? false,
-                    });
-                    if (useJson) {
-                        printJson(jsonOk(result));
-                    }
-                    else {
-                        console.log(chalk.green.bold("\n  Pacifica Agent approved successfully!\n"));
-                        console.log(`  Name:           ${chalk.cyan(agentName)}`);
-                        console.log(`  Agent Address:  ${chalk.cyan(result.agentSolanaAddress)}`);
-                        console.log(`  Master Address: ${chalk.cyan(result.userSolanaAddress)}`);
-                        console.log(`  Expires:        ${chalk.cyan(expiresAt.toISOString())}`);
-                        console.log();
-                    }
-                }
-                finally {
-                    releaseLock("pacifica");
-                }
-            }
-            catch (err) {
-                reportErrorAndExit(err);
-            }
-            return;
-        }
-        // ── Hyperliquid approve branch ──────────────────────────────────────
-        if (exchangeNorm === "hyperliquid") {
-            const masterName = opts.master ?? loadSettings().owsActiveWallet;
-            const agentName = opts.agentName ?? "perp-cli-hl";
-            const expiresIn = opts.expiresIn ?? "90d";
-            let expiresAt;
-            try {
-                expiresAt = parseExpiresIn(expiresIn);
-            }
-            catch (e) {
-                const msg = e instanceof Error ? e.message : String(e);
-                reportErrorAndExit(new PerpError("INVALID_PARAMS", msg, {
-                    remediation: "Use: 30d, 90d, 180d, 1y, or ISO-8601 datetime",
-                }));
-            }
-            if (!masterName) {
-                reportErrorAndExit(new PerpError("INVALID_PARAMS", "Master wallet name is required. Use --master or set owsActiveWallet in settings.", {
-                    remediation: "Run: perp setup or use --master <name>",
-                }));
-            }
-            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
-            if (passphrase === null) {
-                reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
-                    remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
-                }));
+        try {
+            if (opts.builder !== undefined || opts.maxFeeRate !== undefined || opts.builderName !== undefined) {
+                // Builder fees are opt-in and approved only for the builder configured in settings.
+                throw new PerpError("INVALID_PARAMS", "--builder / --max-fee-rate / --builder-name moved out of agent approve", {
+                    remediation: "Configure the builder (perp settings set builder.<venue> <address|code>,<feeBps>), then: perp wallet builder approve <venue>",
+                });
             }
-            try {
-                acquireLock("hyperliquid");
+            const network = networkOf(command);
+            // Normalize aliases (UNKNOWN_VENUE for anything unregistered)
+            const venue = resolveVenueId(exchange);
+            // Venues whose keys exist only as website-created imports (qfex) are refused before any prompt / passphrase read.
+            if (getVenue(venue).masterKeyKind === "none")
+                assertAgentApproveSupported(venue, network, "approve");
+            let master = opts.master ?? null;
+            let agentName = opts.agentName ?? null;
+            let expiresIn = opts.expiresIn ?? "90d";
+            let canPerp = opts.canPerp ?? true;
+            let canSpot = opts.canSpot ?? false;
+            let canWithdraw = opts.canWithdraw ?? false;
+            let passphrase = null;
+            // Aster wizard mode: enter only when no identity flags were given, stdin
+            // is a TTY and OWS_PASSPHRASE is unset.
+            const asterWizard = venue === "aster" &&
+                opts.master === undefined &&
+                opts.agentName === undefined &&
+                opts.expiresIn === undefined &&
+                process.stdin.isTTY === true &&
+                process.env["OWS_PASSPHRASE"] === undefined;
+            if (asterWizard) {
+                const rl = createInterface({ input, output });
                 try {
-                    const result = await runHlApproveFlow({
-                        masterName,
-                        passphrase: passphrase ?? "",
-                        agentName,
-                        expiresAt,
-                        expiresAtIso: expiresAt.toISOString(),
-                        nowIso: new Date().toISOString(),
-                        canPerp: opts.canPerp ?? true,
-                        canSpot: opts.canSpot ?? false,
-                        canWithdraw: opts.canWithdraw ?? false,
-                    });
-                    if (useJson) {
-                        printJson(jsonOk(result));
-                    }
-                    else {
-                        console.log(chalk.green.bold("\n  Hyperliquid Agent approved successfully!\n"));
-                        console.log(`  Name:          ${chalk.cyan(agentName)}`);
-                        console.log(`  Agent Address: ${chalk.cyan(result.agentAddress)}`);
-                        console.log(`  Expires:       ${chalk.cyan(expiresAt.toISOString())}`);
-                        console.log();
-                    }
+                    const settings = loadSettings();
+                    const defMaster = settings.owsActiveWallet || "main";
+                    const rawMaster = await rl.question(`Master wallet name [${defMaster}]: `);
+                    master = rawMaster.trim() || defMaster;
+                    const rawAgent = await rl.question(`Agent name [perp-cli-aster]: `);
+                    agentName = rawAgent.trim() || "perp-cli-aster";
+                    const rawExpiry = await rl.question(`Expires-in [90d]: `);
+                    expiresIn = rawExpiry.trim() || "90d";
+                    const rawPerp = await rl.question(`Can perp trade? [Y/n]: `);
+                    canPerp = rawPerp.trim().toLowerCase() !== "n";
+                    const rawSpot = await rl.question(`Can spot trade? [y/N]: `);
+                    canSpot = rawSpot.trim().toLowerCase() === "y";
+                    const rawWithdraw = await rl.question(`Can withdraw? [y/N]: `);
+                    canWithdraw = rawWithdraw.trim().toLowerCase() === "y";
+                    // Hidden passphrase prompt — readline doesn't support hidden natively;
+                    // we use muted output pattern compatible with node:readline/promises
+                    process.stdout.write("Master passphrase: ");
+                    const rawPp = await rl.question("");
+                    // Empty input = unencrypted vault wallet (historical wizard behavior).
+                    passphrase = rawPp.trim();
                 }
                 finally {
-                    releaseLock("hyperliquid");
+                    rl.close();
                 }
             }
-            catch (err) {
-                reportErrorAndExit(err);
-            }
-            return;
-        }
-        // Wizard mode: enter only when ALL THREE conditions hold
-        const wizardMode = opts.master === undefined &&
-            opts.agentName === undefined &&
-            opts.expiresIn === undefined &&
-            process.stdin.isTTY === true &&
-            process.env["OWS_PASSPHRASE"] === undefined;
-        let masterName;
-        let agentName;
-        let expiresIn;
-        let canPerp;
-        let canSpot;
-        let canWithdraw;
-        let passphrase;
-        if (wizardMode) {
-            const rl = createInterface({ input, output });
-            try {
-                const settings = loadSettings();
-                const defMaster = settings.owsActiveWallet || "main";
-                const rawMaster = await rl.question(`Master wallet name [${defMaster}]: `);
-                masterName = rawMaster.trim() || defMaster;
-                const rawAgent = await rl.question(`Agent name [perp-cli-aster]: `);
-                agentName = rawAgent.trim() || "perp-cli-aster";
-                const rawExpiry = await rl.question(`Expires-in [90d]: `);
-                expiresIn = rawExpiry.trim() || "90d";
-                const rawPerp = await rl.question(`Can perp trade? [Y/n]: `);
-                canPerp = rawPerp.trim().toLowerCase() !== "n";
-                const rawSpot = await rl.question(`Can spot trade? [y/N]: `);
-                canSpot = rawSpot.trim().toLowerCase() === "y";
-                const rawWithdraw = await rl.question(`Can withdraw? [y/N]: `);
-                canWithdraw = rawWithdraw.trim().toLowerCase() === "y";
-                // Hidden passphrase prompt — readline doesn't support hidden natively;
-                // we use muted output pattern compatible with node:readline/promises
-                process.stdout.write("Master passphrase: ");
-                const rawPp = await rl.question("");
-                passphrase = rawPp.trim() || null;
-            }
-            finally {
-                rl.close();
+            else if (venue !== "ondo") {
+                // Aster: --can-withdraw without --ip-whitelist is refused before any passphrase read.
+                if (venue === "aster")
+                    assertAsterWithdrawIpWhitelist(canWithdraw, opts.ipWhitelist);
+                // No master wallet on this computer → refuse before asking for a passphrase.
+                requireMaster(master);
+                // Ondo reads its key from stdin, so the passphrase resolver (which may
+                // consume a piped stdin) must not run for it.
+                passphrase = await resolvePassphrase({ flag: passphraseFlag });
             }
-        }
-        else {
-            masterName = opts.master ?? loadSettings().owsActiveWallet;
-            agentName = opts.agentName ?? "perp-cli-aster";
-            expiresIn = opts.expiresIn ?? "90d";
-            canPerp = opts.canPerp ?? true;
-            canSpot = opts.canSpot ?? false;
-            canWithdraw = opts.canWithdraw ?? false;
-            // 3-path passphrase resolver (non-TTY path)
-            passphrase = await resolvePassphrase({ flag: passphraseFlag });
-            if (passphrase === null) {
-                // TTY but non-wizard (some flags were supplied) — throw PASSPHRASE_REQUIRED
-                reportErrorAndExit(new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY or wizard skipped", {
-                    remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
-                }));
+            const outcome = await approveVenueAgent({
+                venue,
+                network,
+                master,
+                agentName,
+                expiresIn,
+                canPerp,
+                canSpot,
+                canWithdraw,
+                rotate: opts.rotate === true,
+                passphrase,
+                apiKeyIndex: opts.apiKeyIndex !== undefined ? Number(opts.apiKeyIndex) : null,
+                forceSlot: opts.force === true,
+                accountIndex: Number(opts.accountIndex),
+                aster: { ipWhitelist: opts.ipWhitelist },
+                ondoKey: null,
+            });
+            if (useJson) {
+                printJson(jsonOk("meta" in outcome ? outcome.meta : outcome.result));
+                return;
             }
+            printApproveOutcome(outcome);
         }
-        if (!masterName) {
-            reportErrorAndExit(new PerpError("INVALID_PARAMS", "Master wallet name is required. Use --master or set owsActiveWallet in settings.", {
-                remediation: "Run: perp setup or use --master <name>",
-            }));
-        }
-        // Parse expires-in
-        let expiresAt;
-        try {
-            expiresAt = parseExpiresIn(expiresIn);
+        catch (err) {
+            reportErrorAndExit(err);
         }
-        catch (e) {
-            const msg = e instanceof Error ? e.message : String(e);
-            reportErrorAndExit(new PerpError("INVALID_PARAMS", msg, {
-                remediation: "Use: 30d, 90d, 180d, 1y, or ISO-8601 datetime",
-            }));
-        }
-        const expiredMs = expiresAt.getTime();
-        const expiresAtIso = expiresAt.toISOString();
-        const nonceMicros = Date.now() * 1000 + (Math.floor(Math.random() * 1000));
-        const nowIso = new Date().toISOString();
-        const asterChain = "Mainnet";
+    });
+    // ── agent import <exchange> ── register a key created on the exchange website ──
+    // SSOT Rule #3: the key is read from a hidden prompt or stdin — never argv.
+    agent
+        .command("import <exchange> [key]")
+        .description("Import an agent wallet / API key created on the exchange WEBSITE (master wallet not needed on this computer; key via hidden prompt or stdin — never argv)")
+        .option("--master-address <address>", "Master / owner public address (aster, pacifica, arcus: required; hyperliquid, lighter: optional cross-check)")
+        .option("--account-index <n>", "Lighter / Lighter RH: account index (required). Arcus: subaccount the key is scoped to (optional cross-check)")
+        .option("--api-key-index <n>", "Lighter / Lighter RH: the key's API key slot (required)")
+        .option("--account-id <uuid>", "QFEX: the account the key trades (default: the primary account; required without a terminal — it is the confirmation)")
+        .option("--agent-name <name>", "Local name for the key (default: web-<venue>[-testnet])")
+        .option("--expires-in <duration>", "Expiry shown on the website (30d, 1y, ISO) — recorded when the venue does not report it")
+        .option("--replace", "Replace an existing imported key of the same name (its local copy is deleted)")
+        .addOption(new Option("--secret <secret>", "Refused — keys are never accepted on argv").hideHelp())
+        .option("--json", "Machine-readable output")
+        .addHelpText("after", `
+Input (never argv): a hidden prompt in a terminal, or stdin when piped —
+  one line with the private key; ondo: two lines (API key id, then secret);
+  qfex: two lines (API public key, then secret).
+
+Per venue:
+  hyperliquid  API wallet private key (More → API on the website). Verified: info userRole = agent of the master.
+  aster        API wallet (signer) private key + --master-address (user). Verified: signed GET /fapi/v3/balance.
+  pacifica     agent wallet private key + --master-address (account). NOT verifiable without the master (reported "unverified").
+  lighter      API key private key + --account-index + --api-key-index. Verified: slot holds a key and an auth token signed by the key is accepted.
+  lighter-rh   same as lighter.
+  arcus        API key private key (Ed25519) + --master-address (owner). Verified: GET /v1/apiKeys lists its public key ACTIVE.
+  ondo         API key id + secret. Verified: authenticated GET /v1/account.
+  qfex         API public key + secret [--account-id <uuid>]. Verified: signed reads as the account + Trade WebSocket
+               auth. The key is bound to ONE account UUID, which is shown and must be confirmed (y/N in a terminal;
+               piped: pass --account-id <uuid> equal to it). QFEX keys are created only on the website (2FA).
+
+The imported key trades. Deposits / withdrawals / transfers / referral / agent approvals need the
+master wallet: do them on the website, or add the master with 'perp wallet import'.
+The CLI cannot revoke an imported key: 'wallet agent revoke <venue> <name> --local-only' removes
+the local copy only — revoke it on the website.
+
+Examples:
+  perp -n testnet wallet agent import hyperliquid
+  pbpaste | perp wallet agent import aster --master-address 0xYOU
+  perp wallet agent import lighter --account-index 12345 --api-key-index 5
+  printf '%s\\n%s\\n' "$KEY_ID" "$SECRET" | perp wallet agent import ondo
+  printf '%s\\n%s\\n' "$PUBLIC_KEY" "$SECRET" | perp -n testnet wallet agent import qfex --account-id <uuid>`)
+        .action(async (exchange, argvKey, opts, command) => {
+        const useJson = opts.json ?? isJson();
         try {
-            // Step 1: Acquire lock at the START of the flow (before any OWS resources
-            // are created) so that concurrent approves are fully serialized, not just
-            // the final settings write.
-            acquireLock("aster");
-            try {
-                const result = await runApproveFlow({
-                    masterName,
-                    passphrase: passphrase ?? "",
-                    agentName,
-                    expiresAt,
-                    expiredMs,
-                    expiresAtIso,
-                    nonceMicros,
-                    nowIso,
-                    canPerp,
-                    canSpot,
-                    canWithdraw,
-                    asterChain,
-                    builder: opts.builder,
-                    maxFeeRate: opts.maxFeeRate,
-                    builderName: opts.builderName,
-                    ipWhitelist: opts.ipWhitelist,
+            // (-k / --private-key is a root option: the root preAction already rejects it.)
+            if (argvKey !== undefined || opts.secret !== undefined) {
+                throw new PerpError("INVALID_PARAMS", "Refusing a key on the command line: it is visible in shell history and the process list", {
+                    remediation: "Enter it at the hidden prompt (run in a terminal) or pipe it on stdin (e.g. pbpaste | perp wallet agent import <venue> ...). Clear the key from your shell history.",
                 });
-                if (useJson) {
-                    printJson(jsonOk(result));
-                }
-                else {
-                    console.log(chalk.green.bold("\n  Agent approved successfully!\n"));
-                    console.log(`  Name:          ${chalk.cyan(agentName)}`);
-                    console.log(`  Agent Address: ${chalk.cyan(result.agentAddress)}`);
-                    console.log(`  Expires:       ${chalk.cyan(expiresAtIso)}`);
-                    console.log(`  API Key ID:    ${chalk.gray(result.owsApiKeyId)}`);
-                    console.log(`  Policy ID:     ${chalk.gray(result.policyId)}`);
-                    console.log();
-                }
             }
-            finally {
-                releaseLock("aster");
+            const network = networkOf(command);
+            const venue = resolveVenueId(exchange);
+            const int = (flag, raw) => {
+                if (raw === undefined)
+                    return null;
+                const n = Number(raw);
+                if (!Number.isInteger(n) || n < 0)
+                    throw new PerpError("INVALID_PARAMS", `${flag} must be a non-negative integer (got "${raw}")`);
+                return n;
+            };
+            if (opts.accountId !== undefined && venue !== "qfex") {
+                throw new PerpError("INVALID_PARAMS", "--account-id applies to qfex only", { remediation: "Lighter / Arcus use --account-index" });
             }
+            const { importVenueAgent, readImportSecret, printImportOutcome } = await import("./agent-import.js");
+            const accountId = opts.accountId ?? null;
+            const params = {
+                venue,
+                network,
+                agentName: opts.agentName ?? null,
+                masterAddress: opts.masterAddress ?? null,
+                accountIndex: int("--account-index", opts.accountIndex),
+                apiKeyIndex: int("--api-key-index", opts.apiKeyIndex),
+                expiresIn: opts.expiresIn ?? null,
+                replace: opts.replace === true,
+                accountId,
+                confirmAccount: venue === "qfex" ? confirmImportAccount(accountId, useJson) : null,
+            };
+            const outcome = await importVenueAgent({ ...params, secret: await readImportSecret(venue) });
+            if (useJson) {
+                printJson(jsonOk(outcome));
+                return;
+            }
+            printImportOutcome(outcome);
         }
         catch (err) {
             reportErrorAndExit(err);
@@ -614,7 +1261,8 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         .option("--json", "Machine-readable output")
         .action((exchange, opts) => {
         const useJson = opts.json ?? isJson();
-        const all = listAgents(exchange);
+        const all = listAgents(exchange === undefined ? undefined : resolveVenueId(exchange))
+            .filter(({ exchange: ex }) => exchange === undefined || ex === resolveVenueId(exchange));
         const now = Date.now();
         const rows = all.map(({ exchange: ex, meta }) => {
             let status;
@@ -630,12 +1278,40 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
             return {
                 name: meta.agentName,
                 exchange: ex,
+                // null = untagged record whose network cannot be determined (shown as "unknown").
+                network: recordedAgentNetworkOf(ex, meta),
+                // "approved" = signed by a master wallet on this machine; "imported" = created on the website.
+                source: agentSourceOf(ex, meta),
                 evmAddress: meta.agentEvmAddress,
+                // "" = unknown (imported key whose venue does not report an expiry).
                 expiresAt: meta.expiresAt,
                 status,
-                permissions: meta.permissions,
+                // null = set on the exchange website, not known locally (imported keys).
+                permissions: agentSourceOf(ex, meta) === "imported" ? null : meta.permissions,
+                warning: null,
             };
         });
+        // Ondo / Arcus keys use venue-specific metas (no EVM agent address / permission set).
+        const venueFilter = exchange === undefined ? null : resolveVenueId(exchange);
+        for (const { exchange: ex, meta } of listVenueAgents()) {
+            if (venueFilter !== null && venueFilter !== ex)
+                continue;
+            const expiresAt = meta.kind === "arcus" ? meta.validUntil : null;
+            const status = expiresAt !== null && expiresAt !== "" && new Date(expiresAt).getTime() < now ? "expired" : "active";
+            rows.push({
+                name: meta.agentName,
+                exchange: ex,
+                network: meta.network,
+                source: agentSourceOf(ex, meta),
+                evmAddress: meta.kind === "arcus" ? meta.ownerAddress : "",
+                // Ondo keys carry no expiry; shown as "—".
+                expiresAt: expiresAt ?? "",
+                status,
+                // QFEX permissions are set on the website and cannot be read back → null (unknown).
+                permissions: meta.kind === "qfex" ? null : { canPerpTrade: true, canSpotTrade: false, canWithdraw: false },
+                warning: meta.kind === "qfex" ? qfexWithdrawKeyWarning(meta) : null,
+            });
+        }
         if (useJson) {
             printJson(jsonOk(rows));
             return;
@@ -645,8 +1321,8 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
             return;
         }
         console.log(chalk.cyan.bold("\n  Registered Agent Wallets\n"));
-        const header = ["NAME", "EXCHANGE", "EVM ADDR", "EXPIRES", "STATUS", "PERP", "SPOT", "WITHDRAW"];
-        const colWidths = [20, 10, 14, 26, 9, 6, 6, 10];
+        const header = ["NAME", "EXCHANGE", "NETWORK", "SOURCE", "EVM ADDR", "EXPIRES", "STATUS", "PERP", "SPOT", "WITHDRAW"];
+        const colWidths = [20, 10, 8, 8, 14, 26, 9, 6, 6, 10];
         console.log("  " + header.map((h, i) => chalk.bold(h.padEnd(colWidths[i]))).join("  "));
         console.log("  " + header.map((_, i) => "─".repeat(colWidths[i])).join("  "));
         for (const r of rows) {
@@ -655,30 +1331,137 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
             const cols = [
                 r.name.slice(0, 19),
                 r.exchange,
+                r.network ?? "unknown",
+                r.source,
                 addr,
-                new Date(r.expiresAt).toLocaleDateString(),
+                r.expiresAt ? new Date(r.expiresAt).toLocaleDateString() : r.source === "imported" ? "unknown" : "—",
                 statusColor(r.status),
-                r.permissions.canPerpTrade ? chalk.green("Y") : chalk.gray("N"),
-                r.permissions.canSpotTrade ? chalk.green("Y") : chalk.gray("N"),
-                r.permissions.canWithdraw ? chalk.green("Y") : chalk.gray("N"),
+                ...(r.permissions === null
+                    ? [chalk.gray("?"), chalk.gray("?"), chalk.gray("?")]
+                    : [
+                        r.permissions.canPerpTrade ? chalk.green("Y") : chalk.gray("N"),
+                        r.permissions.canSpotTrade ? chalk.green("Y") : chalk.gray("N"),
+                        r.permissions.canWithdraw === null ? chalk.gray("?") : r.permissions.canWithdraw ? chalk.green("Y") : chalk.gray("N"),
+                    ]),
             ];
             console.log("  " + cols.map((c, i) => String(c).padEnd(colWidths[i])).join("  "));
         }
+        if (rows.some(r => r.source === "imported")) {
+            console.log(chalk.gray("\n  imported = created on the exchange website; PERP/SPOT/WITHDRAW \"?\" = set on the website. The CLI cannot revoke these (revoke on the website)."));
+        }
+        for (const r of rows)
+            if (r.warning !== null)
+                console.log(chalk.red.bold(`\n  [WARNING] ${r.warning}`));
         console.log();
     });
     // ── agent revoke <exchange> <agentName> ─────────────────────────────────
     agent
         .command("revoke <exchange> <agentName>")
-        .description("Revoke an agent wallet registration")
-        .option("--force", "Skip Aster POST, only clear local state")
-        .option("--passphrase <pp>", "Master OWS passphrase")
+        .description("Revoke an agent wallet registration (imported keys: --local-only — revoke them on the website)")
+        .option("--force", "Skip the venue revoke call, only clear local state")
+        .option("--local-only", "Only remove the local record (and, for imported keys, the local key copy) — nothing is sent; the key stays authorized on the exchange")
+        .addOption(deprecatedPassphraseOption()).hook("preAction", warnDeprecatedPassphrase)
+        .option("--master <name>", "Master OWS wallet (Arcus revoke). Defaults to settings.owsActiveWallet")
         .option("--json", "Machine-readable output")
-        .action(async (exchange, agentName, opts, command) => {
+        .action(async (exchangeArg, agentName, opts, command) => {
         const useJson = opts.json ?? isJson();
+        let exchange;
+        let network;
+        const localOnly = opts.force === true || opts.localOnly === true;
+        try {
+            exchange = resolveVenueId(exchangeArg);
+            network = networkOf(command);
+            // An imported key is only ever removed locally, so it needs no venue support for revoke
+            // (e.g. an imported Aster testnet key).
+            const rec = exchange === "ondo" || exchange === "arcus" || exchange === "qfex" ? getVenueAgent(exchange, agentName) : getAgent(exchange, agentName);
+            // QFEX keys only exist as imports: a missing record is "already removed", never an approve-capability error.
+            if (exchange !== "qfex" && (rec === null || agentSourceOf(exchange, rec) !== "imported"))
+                assertAgentApproveSupported(exchange, network, "revoke");
+        }
+        catch (e) {
+            reportErrorAndExit(e);
+        }
         // optsWithGlobals(): see wallet agent approve for full rationale.
         const mergedOpts = command.optsWithGlobals();
         const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
         try {
+            // ── Ondo: the key stays valid on the venue — revoke it in the Ondo Perps UI ──
+            if (exchange === "ondo") {
+                const ondoMeta = getVenueAgent("ondo", agentName);
+                if (!ondoMeta) {
+                    if (useJson)
+                        printJson({ ok: true, data: { alreadyRevoked: true } });
+                    else
+                        console.log(`Agent "${agentName}" on ondo not found locally — already revoked.`);
+                    return;
+                }
+                const { revokeOndoAgentLocal } = await import("../exchanges/ondo/agent.js");
+                const keystoreRemoved = revokeOndoAgentLocal(ondoMeta.keyId);
+                deleteVenueAgent("ondo", agentName);
+                const note = "The key is still valid on Ondo Perps — delete it in the Ondo Perps UI (API Keys).";
+                if (useJson)
+                    printJson(jsonOk({ revoked: true, local: true, keystoreRemoved, note }));
+                else
+                    console.log(chalk.green(`Agent "${agentName}" on ondo removed locally.`) + chalk.yellow(`\n  ${note}`));
+                return;
+            }
+            // ── QFEX: local removal only — the key is revoked in QFEX Developer Settings (website, 2FA) ──
+            if (exchange === "qfex") {
+                const qfexMeta = getVenueAgent("qfex", agentName);
+                if (!qfexMeta) {
+                    if (useJson)
+                        printJson({ ok: true, data: { alreadyRevoked: true } });
+                    else
+                        console.log(`Agent "${agentName}" on qfex not found locally — already removed.`);
+                    return;
+                }
+                const { revokeQfexAgentLocal } = await import("../exchanges/qfex/agent.js");
+                const keystoreRemoved = revokeQfexAgentLocal(qfexMeta.publicKey);
+                deleteVenueAgent("qfex", agentName);
+                const note = "The key is still valid on QFEX — revoke it in QFEX Developer Settings (website) to invalidate it.";
+                if (useJson)
+                    printJson(jsonOk({ revoked: true, local: true, keystoreRemoved, note }));
+                else
+                    console.log(chalk.green(`Agent "${agentName}" on qfex removed locally.`) + chalk.yellow(`\n  ${note}`));
+                return;
+            }
+            // ── Arcus: EIP-712 RevokeApiKey signed by the master wallet ──
+            if (exchange === "arcus") {
+                const arcusMeta = getVenueAgent("arcus", agentName);
+                if (!arcusMeta) {
+                    if (useJson)
+                        printJson({ ok: true, data: { alreadyRevoked: true } });
+                    else
+                        console.log(`Agent "${agentName}" on arcus not found locally — already revoked.`);
+                    return;
+                }
+                if (arcusMeta.network !== network) {
+                    throw new PerpError("AGENT_NOT_REGISTERED", `Arcus API key "${agentName}" is registered on ${arcusMeta.network}, not ${network}`, {
+                        remediation: arcusMeta.network === "mainnet" ? "Run without -n testnet to revoke it" : "Run with -n testnet to revoke it",
+                    });
+                }
+                if (agentSourceOf("arcus", arcusMeta) === "imported") {
+                    await removeImportedLocally("arcus", network, arcusMeta, agentName, localOnly, useJson);
+                    return;
+                }
+                if (!localOnly) {
+                    const masterName = opts.master ?? loadSettings().owsActiveWallet;
+                    if (!masterName) {
+                        throw new PerpError("INVALID_PARAMS", "Master wallet name is required to revoke an Arcus key", {
+                            remediation: "Use --master <name>, or --force to clear local state only",
+                        });
+                    }
+                    const passphrase = await resolvePassphrase({ flag: passphraseFlag });
+                    const { revokeArcusAgent } = await import("../exchanges/arcus/agent.js");
+                    await revokeArcusAgent({ meta: arcusMeta, masterOwsWallet: masterName, passphrase, network });
+                }
+                deleteVenueAgent("arcus", agentName);
+                if (useJson)
+                    printJson(jsonOk({ revoked: true }));
+                else
+                    console.log(chalk.green(`Agent "${agentName}" on arcus revoked successfully.`));
+                return;
+            }
             // Step 1: Check local meta (idempotent — absent = already revoked)
             const meta = getAgent(exchange, agentName);
             if (!meta) {
@@ -691,7 +1474,13 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                 }
                 return;
             }
-            if (!opts.force) {
+            // A mainnet agent is never revoked (or locally forgotten) from a testnet run, and vice versa.
+            assertAgentNetwork(exchange, meta, network);
+            if (agentSourceOf(exchange, meta) === "imported") {
+                await removeImportedLocally(exchange, network, meta, agentName, localOnly, useJson);
+                return;
+            }
+            if (!localOnly) {
                 // Step 2: Resolve passphrase
                 const passphrase = await resolvePassphrase({ flag: passphraseFlag });
                 if (passphrase === null) {
@@ -700,69 +1489,37 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                     });
                 }
                 if (exchange === "hyperliquid") {
-                    // HL revoke: POST approveAgent with zero-address (best-effort, idempotent)
+                    // HL revoke: POST approveAgent with zero-address under the agent's name.
+                    // Rule #2: do NOT swallow — a failed/unknown revoke throws APPROVE_FAILED
+                    // before the local record is deleted (Step 6), like Pacifica / Aster.
                     const masterName = meta.masterWalletName;
                     const masterSigner = OwsEvmSigner.create(masterName, passphrase);
-                    try {
-                        await revokeHlAgent(masterSigner);
-                    }
-                    catch { /* best effort — HL revoke is idempotent */ }
+                    await revokeHlAgent(masterSigner, network, meta.agentName, meta.agentEvmAddress);
                 }
                 else if (exchange === "pacifica") {
-                    // PAC revoke: signed unbind_agent_wallet with the agent base58 address
+                    // PAC revoke: signed revoke_agent_wallet → POST /agent/revoke.
+                    // Rule #2: do NOT swallow. A refused revoke leaves the agent key
+                    // authorized to trade; suppressing it here would delete the local
+                    // record (Step 6) and leave the user believing the key is dead.
+                    // Mirrors the Aster branch below: fail, and offer --force for a
+                    // local-only cleanup.
                     const masterName = meta.masterWalletName;
                     const solanaSigner = OwsSolanaSigner.create(masterName, passphrase);
-                    try {
-                        await revokePacAgent(solanaSigner, meta.agentSolanaAddress ?? "");
-                    }
-                    catch { /* best effort — Pacifica revoke is idempotent */ }
+                    await revokePacAgent(solanaSigner, meta.agentSolanaAddress ?? null, network);
                 }
-                else if (exchange === "lighter" || exchange === "lt") {
-                    // LT revoke: Lighter has no on-chain revoke action; revoke is local-only.
-                    // Slots persist on the L2 server until overwritten by a fresh ChangePubKey
-                    // at the same index. revokeLtAgent is a no-op stub that exists for
-                    // symmetry with the other DEX revoke helpers.
-                    try {
-                        await revokeLtAgent();
-                    }
-                    catch { /* best effort — LT revoke is idempotent */ }
+                else if (isLighterFamilyVenue(exchange)) {
+                    // LT / LT-RH revoke: ChangePubKey the slot to a throwaway key (private half
+                    // discarded) — the old agent key stops working — then delete its keystore file.
+                    // Rule #2: a failed ChangePubKey throws before the local record is deleted.
+                    await revokeLtAgent(exchange, network, meta, passphrase);
+                }
+                else if (exchange !== "aster") {
+                    throw new PerpError("UNKNOWN_VENUE", `No revoke path for ${exchange}`);
                 }
                 else {
-                    // Aster revoke: Step 3: Build DelAgent EIP-712
-                    const masterName = meta.masterWalletName;
-                    const masterSigner = OwsEvmSigner.create(masterName, passphrase);
-                    const userEvmAddress = masterSigner.getAddress();
-                    const nonceMicros = Date.now() * 1000 + Math.floor(Math.random() * 1000);
-                    const delTypedData = buildDelAgentTypedData({
-                        user: userEvmAddress,
-                        agentAddress: meta.agentEvmAddress,
-                        nonceMicros,
-                        asterChain: "Mainnet",
-                    });
-                    const signature = await masterSigner.signTypedData(delTypedData.domain, delTypedData.types, delTypedData.message);
-                    // Step 4: POST DELETE /fapi/v3/agent
-                    const baseUrl = "https://fapi.asterdex.com";
-                    const qsEntries = [
-                        ["agentAddress", meta.agentEvmAddress],
-                        ["asterChain", "Mainnet"],
-                        ["user", userEvmAddress],
-                        ["nonce", String(nonceMicros)],
-                        ["signature", signature],
-                        ["signatureChainId", "56"],
-                    ];
-                    const qs = new URLSearchParams(Object.fromEntries(qsEntries));
-                    const revokeRes = await fetch(`${baseUrl}/fapi/v3/agent?${qs.toString()}`, {
-                        method: "DELETE",
-                        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                        body: "",
-                    });
-                    // Idempotent: 404 = already revoked server-side, treat as success
-                    if (!revokeRes.ok && revokeRes.status !== 404) {
-                        const errText = await revokeRes.text().catch(() => "");
-                        throw new PerpError("EXCHANGE_ERROR", `Aster agent delete failed (${revokeRes.status}): ${errText.slice(0, 200)}`, {
-                            remediation: "Use --force to skip Aster POST and only clear local state",
-                        });
-                    }
+                    // Aster revoke: signed DelAgent → DELETE /fapi/v3/agent
+                    const masterSigner = OwsEvmSigner.create(meta.masterWalletName, passphrase);
+                    await assertAsterAgentDeleted(await deleteAsterAgent(masterSigner, meta.agentEvmAddress, network), meta.agentEvmAddress, "Retry, or use --force to clear only the local record (the agent stays authorized on Aster until deleted in the Aster UI).");
                 }
             }
             // Step 5: Revoke OWS API key (Aster only — HL has no OWS key)
@@ -773,9 +1530,26 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                 }
                 catch { /* best effort */ }
             }
-            // Step 6: Delete local agent entry
+            // Step 5b: the venue confirmed the revoke — delete the now-dead OWS agent wallet, so a
+            // later approve/rotate can recreate `agent-<dex>-<master>` (OWS refuses duplicate names).
+            if (!localOnly && (exchange === "hyperliquid" || exchange === "pacifica" || exchange === "aster")) {
+                deleteRevokedAgentWallet(exchange, meta);
+            }
+            // Step 6: Delete local agent entry (--force: also the Lighter-family slot keystore file)
+            if (localOnly && isLighterFamilyVenue(exchange) && typeof meta.accountIndex === "number" && typeof meta.apiKeyIndex === "number") {
+                const { deleteLighterFamilyKey } = await import("../agent-wallet/lighter-keystore.js");
+                deleteLighterFamilyKey(exchange, network, meta.accountIndex, meta.apiKeyIndex);
+            }
             deleteAgent(exchange, agentName);
-            if (useJson) {
+            if (localOnly) {
+                // Local-only: nothing was sent, so the key is NOT revoked on the venue.
+                const note = `The agent key was NOT revoked on ${exchange} and may still be authorized — revoke it in the venue UI, or re-run without --force.`;
+                if (useJson)
+                    printJson(jsonOk({ revoked: false, localOnly: true, note }));
+                else
+                    console.log(chalk.yellow(`Agent "${agentName}" on ${exchange} removed locally only. ${note}`));
+            }
+            else if (useJson) {
                 printJson(jsonOk({ revoked: true }));
             }
             else {
@@ -790,220 +1564,58 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
     agent
         .command("rotate <exchange> [oldAgentName]")
         .description("Rotate an agent wallet: revoke existing, then approve with same name")
-        .option("--passphrase <pp>", "Master OWS passphrase")
-        .option("--master <name>", "Master OWS wallet name")
+        .addOption(deprecatedPassphraseOption()).hook("preAction", warnDeprecatedPassphrase)
+        .option("--master <name>", "Master OWS wallet name (default: the old agent's master, then settings.owsActiveWallet)")
         .option("--agent-name <name>", "Agent name to rotate (default: first registered agent)")
         .option("--expires-in <duration>", "New expiry (default: 90d)")
         .option("--can-perp", "Allow perp trading (default: inherit or on)")
         .option("--no-can-perp", "Disallow perp trading")
         .option("--can-spot", "Allow spot trading (default: inherit or off)")
         .option("--no-can-spot", "Disallow spot trading")
-        .option("--can-withdraw", "Allow withdrawals (default: inherit or off)")
-        .option("--no-can-withdraw", "Disallow withdrawals")
+        .option("--can-withdraw", "Allow withdrawals (default: off — never inherited from the old agent; Aster also needs --ip-whitelist)")
+        .option("--no-can-withdraw", "Disallow withdrawals (the default)")
+        .option("--ip-whitelist <list>", "Aster IP whitelist, comma- or space-separated (required with --can-withdraw)")
         .option("--json", "Machine-readable output")
-        .action(async (exchange, oldAgentNameArg, opts, command) => {
+        .action(async (exchangeArg, oldAgentNameArg, opts, command) => {
         const useJson = opts.json ?? isJson();
         // optsWithGlobals(): see wallet agent approve for full rationale.
         const mergedOpts = command.optsWithGlobals();
         const passphraseFlag = mergedOpts.passphrase ?? opts.passphrase;
         try {
-            // Determine which agent to rotate
-            const agentNameToRotate = oldAgentNameArg ?? opts.agentName ?? getAgent(exchange)?.agentName;
+            const exchange = resolveVenueId(exchangeArg);
+            if (exchange !== "aster" && exchange !== "hyperliquid" && exchange !== "pacifica" && !isLighterFamilyVenue(exchange)) {
+                throw new PerpError("NOT_IMPLEMENTED", `rotate is not supported for ${exchange}`, {
+                    remediation: `Run: perp wallet agent revoke ${exchange} <name>, then perp wallet agent approve ${exchange}`,
+                });
+            }
+            const network = networkOf(command);
+            // Determine which agent to rotate (default: first agent registered on this network)
+            const agentNameToRotate = oldAgentNameArg ?? opts.agentName ?? getAgentForNetwork(exchange, network)?.agentName;
+            const imported = agentNameToRotate !== undefined ? getAgent(exchange, agentNameToRotate) : null;
+            if (imported === null || agentSourceOf(exchange, imported) !== "imported")
+                assertAgentApproveSupported(exchange, network, "rotate");
             if (!agentNameToRotate) {
                 throw new PerpError("AGENT_NOT_REGISTERED", `No agent found for ${exchange}`, {
                     remediation: `Run: perp wallet agent approve ${exchange} to create one`,
                 });
             }
-            // Resolve passphrase early (needed for both revoke and approve phases)
-            const passphrase = await resolvePassphrase({ flag: passphraseFlag });
-            if (passphrase === null) {
-                throw new PerpError("PASSPHRASE_REQUIRED", "No passphrase provided and stdin is non-TTY", {
-                    remediation: "Provide passphrase via --passphrase flag, OWS_PASSPHRASE env var, or stdin pipe",
-                });
-            }
-            const settings = loadSettings();
-            const masterName = opts.master ?? settings.owsActiveWallet;
-            // Capture existing agent meta before revoke (for permission inheritance)
-            const existing = getAgent(exchange, agentNameToRotate);
-            // Resolve permissions: explicit flags > old agent's permissions > defaults.
-            // With --no-can-perp/spot/withdraw pattern, opts values are undefined when not passed.
-            const permFlagsProvided = opts.canPerp !== undefined || opts.canSpot !== undefined || opts.canWithdraw !== undefined;
-            let canPerp;
-            let canSpot;
-            let canWithdraw;
-            if (permFlagsProvided) {
-                canPerp = opts.canPerp ?? true;
-                canSpot = opts.canSpot ?? false;
-                canWithdraw = opts.canWithdraw ?? false;
-            }
-            else if (existing?.permissions) {
-                // Preserve old agent's permission set when flags are absent
-                canPerp = existing.permissions.canPerpTrade;
-                canSpot = existing.permissions.canSpotTrade;
-                canWithdraw = existing.permissions.canWithdraw;
+            const outcome = await rotateVenueAgent({
+                exchange, network, agentNameToRotate,
+                master: opts.master || null,
+                passphrase: () => resolvePassphrase({ flag: passphraseFlag }),
+                expiresIn: opts.expiresIn ?? "90d",
+                canPerp: opts.canPerp, canSpot: opts.canSpot, canWithdraw: opts.canWithdraw,
+                ipWhitelist: opts.ipWhitelist,
+            });
+            const rotatedAgentAddress = rotatedAgentAddressOf(outcome);
+            const expiresAtIso = outcome.expiresAt;
+            if (useJson) {
+                printJson(jsonOk({ rotated: true, agentName: agentNameToRotate, agentEvmAddress: rotatedAgentAddress, expiresAt: expiresAtIso }));
             }
             else {
-                canPerp = true;
-                canSpot = false;
-                canWithdraw = false;
-            }
-            // Revoke existing (if present) — best effort
-            if (existing) {
-                try {
-                    if (exchange === "pacifica") {
-                        // Pacifica master is a Solana keypair; can't reuse the EVM master signer.
-                        const revokePacSigner = OwsSolanaSigner.create(existing.masterWalletName, passphrase);
-                        await revokePacAgent(revokePacSigner, existing.agentSolanaAddress ?? "");
-                        if (existing.owsApiKeyId) {
-                            try {
-                                loadOws().revokeApiKey(existing.owsApiKeyId);
-                            }
-                            catch { /* best effort */ }
-                        }
-                        deleteAgent(exchange, agentNameToRotate);
-                        // Continue to the shared approve flow below.
-                        // (skip the remaining EVM-revoke branch via early continuation)
-                    }
-                    else if (exchange === "lighter" || exchange === "lt") {
-                        // LT rotate: no on-chain revoke; just clear local entry. The new
-                        // approve picks the next free slot, leaving the old slot orphaned
-                        // on the L2 server (it cannot be used again until overwritten via
-                        // a fresh ChangePubKey at that index — which the next approve does
-                        // implicitly when it picks max+1).
-                        await revokeLtAgent();
-                        if (existing.owsApiKeyId) {
-                            try {
-                                loadOws().revokeApiKey(existing.owsApiKeyId);
-                            }
-                            catch { /* best effort */ }
-                        }
-                        deleteAgent(exchange, agentNameToRotate);
-                        // Continue to the shared approve flow below.
-                    }
-                    else {
-                        const revokeMs = OwsEvmSigner.create(existing.masterWalletName, passphrase);
-                        if (exchange === "hyperliquid") {
-                            // HL: revoke via approveAgent with zero-address
-                            await revokeHlAgent(revokeMs);
-                        }
-                        else {
-                            // Aster: DELETE /fapi/v3/agent
-                            const userEvmAddress = revokeMs.getAddress();
-                            const nonceMicros = Date.now() * 1000 + Math.floor(Math.random() * 1000);
-                            const delTypedData = buildDelAgentTypedData({
-                                user: userEvmAddress,
-                                agentAddress: existing.agentEvmAddress,
-                                nonceMicros,
-                                asterChain: "Mainnet",
-                            });
-                            const sig = await revokeMs.signTypedData(delTypedData.domain, delTypedData.types, delTypedData.message);
-                            const baseUrl = "https://fapi.asterdex.com";
-                            const qs = new URLSearchParams(Object.fromEntries([
-                                ["agentAddress", existing.agentEvmAddress],
-                                ["asterChain", "Mainnet"],
-                                ["user", userEvmAddress],
-                                ["nonce", String(nonceMicros)],
-                                ["signature", sig],
-                                ["signatureChainId", "56"],
-                            ]));
-                            await fetch(`${baseUrl}/fapi/v3/agent?${qs.toString()}`, {
-                                method: "DELETE",
-                                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                                body: "",
-                            });
-                        }
-                        if (existing.owsApiKeyId) {
-                            try {
-                                loadOws().revokeApiKey(existing.owsApiKeyId);
-                            }
-                            catch { /* best effort */ }
-                        }
-                        deleteAgent(exchange, agentNameToRotate);
-                    }
-                }
-                catch { /* best effort on revoke — continue to approve */ }
-            }
-            const expiresIn = opts.expiresIn ?? "90d";
-            const expiresAt = parseExpiresIn(expiresIn);
-            const expiresAtIso = expiresAt.toISOString();
-            const nowIso = new Date().toISOString();
-            // Acquire lock and run the shared approve flow
-            acquireLock(exchange);
-            try {
-                let rotatedAgentAddress;
-                if (exchange === "hyperliquid") {
-                    const result = await runHlApproveFlow({
-                        masterName,
-                        passphrase,
-                        agentName: agentNameToRotate,
-                        expiresAt,
-                        expiresAtIso,
-                        nowIso,
-                        canPerp,
-                        canSpot,
-                        canWithdraw,
-                    });
-                    rotatedAgentAddress = result.agentAddress;
-                }
-                else if (exchange === "pacifica") {
-                    const result = await runPacApproveFlow({
-                        masterName,
-                        passphrase,
-                        agentName: agentNameToRotate,
-                        expiresAt,
-                        expiresAtIso,
-                        nowIso,
-                        canPerp,
-                        canSpot,
-                        canWithdraw,
-                    });
-                    rotatedAgentAddress = result.agentSolanaAddress;
-                }
-                else if (exchange === "lighter" || exchange === "lt") {
-                    const result = await runLtApproveFlow({
-                        masterName,
-                        passphrase,
-                        agentName: agentNameToRotate,
-                        expiresAt,
-                        expiresAtIso,
-                        nowIso,
-                        canPerp,
-                        canSpot,
-                        canWithdraw,
-                        // No apiKeyIndex override on rotate — picks next free slot.
-                    });
-                    rotatedAgentAddress = `slot=${result.apiKeyIndex} pubkey=${result.publicKey}`;
-                }
-                else {
-                    const expiredMs = expiresAt.getTime();
-                    const nonceMicros = Date.now() * 1000 + Math.floor(Math.random() * 1000);
-                    const result = await runApproveFlow({
-                        masterName,
-                        passphrase,
-                        agentName: agentNameToRotate,
-                        expiresAt,
-                        expiredMs,
-                        expiresAtIso,
-                        nonceMicros,
-                        nowIso,
-                        canPerp,
-                        canSpot,
-                        canWithdraw,
-                        asterChain: "Mainnet",
-                    });
-                    rotatedAgentAddress = result.agentAddress;
-                }
-                if (useJson) {
-                    printJson(jsonOk({ rotated: true, agentName: agentNameToRotate, agentEvmAddress: rotatedAgentAddress, expiresAt: expiresAtIso }));
-                }
-                else {
-                    console.log(chalk.green(`Agent "${agentNameToRotate}" on ${exchange} rotated successfully.`));
-                    console.log(`  New agent address: ${chalk.cyan(rotatedAgentAddress)}`);
-                    console.log(`  Expires: ${chalk.cyan(expiresAtIso)}`);
-                }
-            }
-            finally {
-                releaseLock(exchange);
+                console.log(chalk.green(`Agent "${agentNameToRotate}" on ${exchange} rotated successfully.`));
+                console.log(`  New agent address: ${chalk.cyan(rotatedAgentAddress)}`);
+                console.log(`  Expires: ${chalk.cyan(expiresAtIso)}`);
             }
         }
         catch (err) {
@@ -1017,7 +1629,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         .option("--master <name>", "Master OWS wallet name (Aster/PAC). Defaults to settings.owsActiveWallet")
         .option("--master-address <addr>", "Master EVM address (HL only)")
         .option("--account-index <n>", "Account index (Lighter only)")
-        .option("--passphrase <pp>", "Master OWS passphrase (Aster/PAC). Falls back to OWS_PASSPHRASE env.")
+        .addOption(deprecatedPassphraseOption()).hook("preAction", warnDeprecatedPassphrase)
         .option("--json", "Machine-readable output")
         .action(async (exchange, agentName, opts, command) => {
         const useJson = opts.json ?? isJson();
@@ -1035,13 +1647,16 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
             passphrase,
         };
         if (!exchange) {
-            // Aggregate mode: all 4 DEXs in parallel
-            const [asterResult, hlResult, pacResult, ltResult] = await Promise.allSettled([
-                verifyAster(verifyOpts),
-                verifyHyperliquid(verifyOpts),
-                verifyPacifica(verifyOpts),
-                verifyLighter(verifyOpts),
-            ]);
+            // Aggregate mode: every account venue with configured credentials, in parallel
+            let network;
+            try {
+                network = networkOf(command);
+            }
+            catch (err) {
+                reportErrorAndExit(err);
+            }
+            const venues = await listConfiguredAccountVenues();
+            const results = await Promise.allSettled(venues.map(v => verifyVenue(v, network, verifyOpts)));
             function slotResult(r) {
                 if (r.status === "fulfilled") {
                     const slot = { registered: r.value.registered, count: r.value.count, items: r.value.items };
@@ -1058,12 +1673,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                     },
                 };
             }
-            const data = {
-                aster: slotResult(asterResult),
-                hyperliquid: slotResult(hlResult),
-                pacifica: slotResult(pacResult),
-                lighter: slotResult(ltResult),
-            };
+            const data = Object.fromEntries(venues.map((v, i) => [v, slotResult(results[i])]));
             if (useJson) {
                 printJson({ ok: true, data, meta: { timestamp: ts } });
             }
@@ -1087,25 +1697,8 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         }
         // Single-DEX mode
         try {
-            let result;
-            const ex = exchange.toLowerCase();
-            if (ex === "aster") {
-                result = await verifyAster(verifyOpts);
-            }
-            else if (ex === "hyperliquid" || ex === "hl") {
-                result = await verifyHyperliquid(verifyOpts);
-            }
-            else if (ex === "pacifica" || ex === "pac") {
-                result = await verifyPacifica(verifyOpts);
-            }
-            else if (ex === "lighter" || ex === "lt") {
-                result = await verifyLighter(verifyOpts);
-            }
-            else {
-                throw new PerpError("INVALID_PARAMS", `Unknown exchange "${exchange}". Use: aster, hyperliquid, pacifica, lighter`, {
-                    remediation: "perp wallet agent verify <aster|hyperliquid|pacifica|lighter> [agentName]",
-                });
-            }
+            const ex = resolveVenueId(exchange);
+            const result = await verifyVenue(ex, networkOf(command), verifyOpts);
             if (useJson) {
                 printJson({
                     ok: true,
@@ -1130,7 +1723,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                             console.log(`  ${addr} | ${name} | ${exp} | ${cp.padEnd(7)} | ${cs.padEnd(7)} | ${cw}`);
                         }
                     }
-                    else if (ex === "hyperliquid" || ex === "hl") {
+                    else if (ex === "hyperliquid") {
                         console.log(chalk.dim("  address                    | validUntil  | name"));
                         for (const item of result.items) {
                             const i = item;
@@ -1140,7 +1733,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                             console.log(`  ${addr} | ${vu.padEnd(11)} | ${name}`);
                         }
                     }
-                    else if (ex === "lighter" || ex === "lt") {
+                    else if (isLighterFamilyVenue(ex)) {
                         console.log(chalk.dim("  api_key_index | public_key (truncated)  | nonce | transaction_time"));
                         for (const item of result.items) {
                             const i = item;
@@ -1151,7 +1744,7 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
                             console.log(`  ${idx.padEnd(13)} | ${pk.padEnd(23)} | ${nonce.padEnd(5)} | ${tt}`);
                         }
                     }
-                    else if (ex === "pacifica" || ex === "pac") {
+                    else if (ex === "pacifica") {
                         console.log(chalk.dim("  api_key (truncated)      | created_at"));
                         for (const item of result.items) {
                             const i = item;
@@ -1173,6 +1766,47 @@ export function registerWalletAgentCommands(walletCmd, isJson) {
         }
     });
 }
+/**
+ * Revoke for an IMPORTED key: the CLI holds no master wallet signature for it, so it never claims
+ * a venue revoke. Without --local-only → refused; with it → the local key copy and record are
+ * deleted and the user is told the key is still authorized on the exchange.
+ */
+async function removeImportedLocally(exchange, network, meta, agentName, localOnly, useJson) {
+    const where = `${getVenue(exchange).displayName} website`;
+    if (!localOnly) {
+        throw new PerpError("INVALID_PARAMS", `${exchange} agent "${agentName}" was imported from the exchange website — this CLI cannot revoke it (it has no master wallet signature for it)`, {
+            remediation: `Revoke / delete the key on the ${where}, then remove the local copy: perp${network === "testnet" ? " -n testnet" : ""} wallet agent revoke ${exchange} ${agentName} --local-only`,
+        });
+    }
+    const { deleteImportedAgentLocal } = await import("./agent-import.js");
+    const { keyRemoved } = await deleteImportedAgentLocal(exchange, network, meta);
+    const note = `The key is still authorized on the exchange — revoke it on the ${where}.`;
+    if (useJson)
+        printJson(jsonOk({ revoked: false, localOnly: true, keyRemoved, note }));
+    else
+        console.log(chalk.yellow(`Imported agent "${agentName}" on ${exchange} removed from this computer${keyRemoved ? " (local key deleted)" : ""}. ${note}`));
+}
+/**
+ * After a venue-CONFIRMED revoke, delete the agent's OWS wallet (its key can no longer trade).
+ * Absent wallet = nothing to do. A delete failure throws (Rule #2) with the exact cleanup step.
+ */
+function deleteRevokedAgentWallet(exchange, meta) {
+    const name = meta.agentWalletName;
+    if (!name)
+        return;
+    const ows = loadOws();
+    if (!ows.listWallets().some((w) => w.name === name))
+        return;
+    try {
+        ows.deleteWallet(name);
+    }
+    catch (e) {
+        throw new PerpError("APPROVE_PARTIAL", `${exchange} agent "${meta.agentName}" was revoked, but deleting its OWS wallet "${name}" failed: ${e instanceof Error ? e.message : String(e)}`, {
+            exchange,
+            remediation: `The key is revoked on ${exchange}. Delete the wallet manually (ows wallet delete ${name}), then re-run.`,
+        });
+    }
+}
 // ── Pre-venue rollback helpers ───────────────────────────────────────────────
 //
 // When `wallet agent approve <dex>` fails BEFORE the venue accepted the agent
@@ -1212,11 +1846,12 @@ function tryDeleteOrphanWallet(ows, walletName) {
  * (some users may need it for the venue UI).
  */
 function buildPreVenueRemediation(opts) {
-    const { cleanupOk, dex, masterName, agentAddress, hint } = opts;
-    const retry = `perp wallet agent approve ${dex} --master ${masterName}`;
+    const { cleanupOk, dex, network, masterName, agentAddress, hint } = opts;
+    const retry = `perp${network === "testnet" ? " -n testnet" : ""} wallet agent approve ${dex} --master ${masterName}`;
+    const walletName = agentWalletNameFor(dex === "hyperliquid" ? "hl" : dex === "pacifica" ? "pac" : "aster", masterName, network);
     const head = cleanupOk
         ? `Local agent wallet cleaned up. Deposit funds and retry: ${retry}`
-        : `Manual cleanup required — local agent wallet may still exist. Run: perp wallet remove agent-${dex === "hyperliquid" ? "hl" : dex === "pacifica" ? "pac" : "aster"}-${masterName}, then retry: ${retry}`;
+        : `Manual cleanup required — local agent wallet may still exist. Run: perp wallet remove ${walletName}, then retry: ${retry}`;
     const parts = [head];
     if (hint)
         parts.push(hint);
@@ -1230,8 +1865,20 @@ function buildPreVenueRemediation(opts) {
  * return true when called from within a locked context.
  */
 async function runApproveFlow(opts) {
-    const { masterName, passphrase, agentName, expiredMs, expiresAtIso, nonceMicros, nowIso, canPerp, canSpot, canWithdraw, asterChain, } = opts;
-    const baseUrl = "https://fapi.asterdex.com";
+    const { network, masterName, passphrase, agentName, expiredMs, expiresAtIso, nonceMicros, nowIso, canPerp, canSpot, canWithdraw, } = opts;
+    assertAgentApproveSupported("aster", network, "approve");
+    // Withdraw permission requires an IP whitelist on both networks (V3 docs: mandatory when
+    // canWithdraw is true) — refused before any OWS resource is created or anything is signed.
+    assertAsterWithdrawIpWhitelist(canWithdraw, opts.ipWhitelist);
+    if (network === "testnet") {
+        // Validate registerAndApproveAgent inputs before any OWS resource is created.
+        if (/[&=]/.test(agentName) || /[&=]/.test(opts.ipWhitelist ?? "")) {
+            throw new PerpError("INVALID_PARAMS", "Aster registerAndApproveAgent: agent name and IP whitelist must not contain '&' or '='", {
+                remediation: "Choose another --agent-name / --ip-whitelist",
+            });
+        }
+    }
+    const baseUrl = networkConfig(getVenue("aster"), network).restUrl;
     let owsApiKeyId;
     let owsPolicyId;
     let agentEvmAddress;
@@ -1241,7 +1888,8 @@ async function runApproveFlow(opts) {
     const userEvmAddress = masterSigner.getAddress();
     // Step 4: Generate agent OWS wallet
     const ows = loadOws();
-    agentWalletName = `agent-aster-${masterName}`;
+    agentWalletName = agentWalletNameFor("aster", masterName, network);
+    assertAgentWalletNameFree("aster", agentWalletName, network);
     const agentWallet = ows.createWallet(agentWalletName, passphrase);
     const agentEvmAccount = agentWallet.accounts.find((a) => a.chainId.startsWith("eip155:"));
     if (!agentEvmAccount) {
@@ -1266,110 +1914,23 @@ async function runApproveFlow(opts) {
     // Step 6: Build OWS API key — store only the id, never the token
     const apiKeyResult = ows.createApiKey(`api-aster-${agentName}`, [agentWallet.id], [policyId], passphrase, expiresAtIso);
     owsApiKeyId = apiKeyResult.id;
-    // Step 7 (Optional): Builder approval BEFORE approveAgent
-    if (opts.builder) {
-        if (!opts.maxFeeRate) {
-            throw new PerpError("INVALID_PARAMS", "--max-fee-rate is required when --builder is set", {
-                remediation: "Add --max-fee-rate <bps> to your command",
-            });
-        }
-        const builderTypedData = buildApproveBuilderTypedData({
-            builder: opts.builder,
-            maxFeeRate: opts.maxFeeRate,
-            builderName: opts.builderName,
-            user: userEvmAddress,
-            nonceMicros: nonceMicros - 1,
-            asterChain,
+    // Steps 8-11: sign + POST. Testnet uses the documented unauthenticated
+    // POST /fapi/v3/registerAndApproveAgent (asterdex/api-docs V3 testnet, 2026-05-12);
+    // the AsterChain-bearing Domain A approveAgent struct is documented for mainnet only.
+    // Mainnet keeps approveAgent: it is the live-verified path, and the docs describe
+    // registerAndApproveAgent as "equivalent to the standalone registration step followed
+    // by approveAgent" — an alternative, not a replacement.
+    const endpoint = network === "testnet" ? "registerAndApproveAgent" : "approveAgent";
+    const agentRes = network === "testnet"
+        ? await postAsterRegisterAndApproveAgent({
+            baseUrl, masterSigner, user: userEvmAddress, agentAddress: agentEvmAddress, agentName,
+            expiredMs, nonceMicros, canPerp, canSpot, canWithdraw, ipWhitelist: opts.ipWhitelist,
+        })
+        : await postAsterApproveAgent({
+            network, baseUrl, masterSigner, user: userEvmAddress, agentAddress: agentEvmAddress, agentName,
+            expiredMs, nonceMicros, canPerp, canSpot, canWithdraw, ipWhitelist: opts.ipWhitelist,
         });
-        const builderSig = await masterSigner.signTypedData(builderTypedData.domain, builderTypedData.types, builderTypedData.message);
-        const builderQsEntries = [
-            ["builder", opts.builder],
-            ["maxFeeRate", opts.maxFeeRate],
-            ...(opts.builderName !== undefined ? [["builderName", opts.builderName]] : []),
-            ["asterChain", asterChain],
-            ["user", userEvmAddress],
-            ["nonce", String(nonceMicros - 1)],
-            ["signature", builderSig],
-            ["signatureChainId", "56"],
-        ];
-        const builderRes = await fetch(`${baseUrl}/fapi/v3/approveBuilder?${new URLSearchParams(Object.fromEntries(builderQsEntries)).toString()}`, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: "",
-        });
-        if (!builderRes.ok) {
-            const errText = await builderRes.text().catch(() => "");
-            // Aster builder POST failed — pre-venue (no Aster agent registered yet).
-            // Rollback both: api key + orphan local OWS wallet.
-            if (owsApiKeyId) {
-                try {
-                    ows.revokeApiKey(owsApiKeyId);
-                }
-                catch { /* best effort */ }
-            }
-            tryDeleteOrphanWallet(ows, agentWalletName);
-            throw new PerpError("EXCHANGE_ERROR", `Aster approveBuilder failed (${builderRes.status}): ${errText.slice(0, 200)}`, {
-                remediation: "Check builder address and max-fee-rate parameters",
-            });
-        }
-        const builderResp = await builderRes.json();
-        const builderOk = builderResp.code === "000000" || builderResp.code === 200;
-        if (!builderOk) {
-            if (owsApiKeyId) {
-                try {
-                    ows.revokeApiKey(owsApiKeyId);
-                }
-                catch { /* best effort */ }
-            }
-            tryDeleteOrphanWallet(ows, agentWalletName);
-            const errMsg = builderResp.msg ?? builderResp.message ?? String(builderResp.code);
-            throw new PerpError("EXCHANGE_ERROR", `Aster approveBuilder failed: ${errMsg}`, {
-                remediation: "Check builder address and max-fee-rate parameters",
-            });
-        }
-    }
-    // Step 8: Build EIP-712 ApproveAgent payload
-    const approveTypedData = buildApproveAgentTypedData({
-        user: userEvmAddress,
-        agentAddress: agentEvmAddress,
-        agentName,
-        expiredMs,
-        canPerpTrade: canPerp,
-        canSpotTrade: canSpot,
-        canWithdraw,
-        ipWhitelist: opts.ipWhitelist,
-        builder: opts.builder,
-        maxFeeRate: opts.maxFeeRate,
-        builderName: opts.builderName,
-        nonceMicros,
-        asterChain,
-    });
-    // Step 9: Sign
-    const signature = await masterSigner.signTypedData(approveTypedData.domain, approveTypedData.types, approveTypedData.message);
-    // Step 10: Build query string
-    const qsEntries = [
-        ["agentName", agentName],
-        ["agentAddress", agentEvmAddress],
-    ];
-    if (opts.ipWhitelist !== undefined && opts.ipWhitelist !== null) {
-        qsEntries.push(["ipWhitelist", opts.ipWhitelist]);
-    }
-    qsEntries.push(["expired", String(expiredMs)], ["canSpotTrade", String(canSpot)], ["canPerpTrade", String(canPerp)], ["canWithdraw", String(canWithdraw)]);
-    if (opts.builder !== undefined && opts.builder !== null) {
-        qsEntries.push(["builder", opts.builder]);
-        qsEntries.push(["maxFeeRate", opts.maxFeeRate ?? ""]);
-        if (opts.builderName !== undefined) {
-            qsEntries.push(["builderName", opts.builderName]);
-        }
-    }
-    qsEntries.push(["asterChain", asterChain], ["user", userEvmAddress], ["nonce", String(nonceMicros)], ["signature", signature], ["signatureChainId", "56"]);
-    // Step 11: POST /fapi/v3/approveAgent
     let asterPostSucceeded = false;
-    const agentRes = await fetch(`${baseUrl}/fapi/v3/approveAgent?${new URLSearchParams(Object.fromEntries(qsEntries)).toString()}`, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: "",
-    });
     if (agentRes.ok) {
         const resp = await agentRes.json();
         if (resp.code === "000000" || resp.code === 200) {
@@ -1386,9 +1947,9 @@ async function runApproveFlow(opts) {
             }
             const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
             const errMsg = resp.msg ?? resp.message ?? String(resp.code);
-            throw new PerpError("APPROVE_PARTIAL", `Aster approveAgent failed: ${errMsg}`, {
+            throw new PerpError("APPROVE_PARTIAL", `Aster ${endpoint} failed: ${errMsg}`, {
                 remediation: buildPreVenueRemediation({
-                    cleanupOk, dex: "aster", masterName, agentAddress: agentEvmAddress,
+                    cleanupOk, dex: "aster", network, masterName, agentAddress: agentEvmAddress,
                 }),
             });
         }
@@ -1403,9 +1964,9 @@ async function runApproveFlow(opts) {
         }
         const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         const errText = await agentRes.text().catch(() => "");
-        throw new PerpError("APPROVE_PARTIAL", `Aster approveAgent failed (${agentRes.status}): ${errText.slice(0, 200)}`, {
+        throw new PerpError("APPROVE_PARTIAL", `Aster ${endpoint} failed (${agentRes.status}): ${errText.slice(0, 200)}`, {
             remediation: buildPreVenueRemediation({
-                cleanupOk, dex: "aster", masterName, agentAddress: agentEvmAddress,
+                cleanupOk, dex: "aster", network, masterName, agentAddress: agentEvmAddress,
             }),
         });
     }
@@ -1425,6 +1986,7 @@ async function runApproveFlow(opts) {
             permissions: { canPerpTrade: canPerp, canSpotTrade: canSpot, canWithdraw },
             asterApprovalNonce: String(nonceMicros),
             status: "active",
+            network,
         });
     }
     catch (persistErr) {
@@ -1435,27 +1997,7 @@ async function runApproveFlow(opts) {
         let revokeOk = false;
         // Attempt remote DELETE /fapi/v3/agent
         try {
-            const delNonce = Date.now() * 1000 + Math.floor(Math.random() * 1000);
-            const delTypedData = buildDelAgentTypedData({
-                user: userEvmAddress,
-                agentAddress: agentEvmAddress,
-                nonceMicros: delNonce,
-                asterChain,
-            });
-            const delSig = await masterSigner.signTypedData(delTypedData.domain, delTypedData.types, delTypedData.message);
-            const delQs = new URLSearchParams(Object.fromEntries([
-                ["agentAddress", agentEvmAddress],
-                ["asterChain", asterChain],
-                ["user", userEvmAddress],
-                ["nonce", String(delNonce)],
-                ["signature", delSig],
-                ["signatureChainId", "56"],
-            ]));
-            const delRes = await fetch(`${baseUrl}/fapi/v3/agent?${delQs.toString()}`, {
-                method: "DELETE",
-                headers: { "Content-Type": "application/x-www-form-urlencoded" },
-                body: "",
-            });
+            const delRes = await deleteAsterAgent(masterSigner, agentEvmAddress, network);
             deleteOk = delRes.ok || delRes.status === 404;
         }
         catch { /* best effort */ }
@@ -1496,6 +2038,7 @@ async function runApproveFlow(opts) {
                 permissions: { canPerpTrade: canPerp, canSpotTrade: canSpot, canWithdraw },
                 asterApprovalNonce: String(nonceMicros),
                 status: "partial",
+                network,
             });
         }
         catch { /* best effort — already in a bad state */ }
@@ -1513,12 +2056,147 @@ async function runApproveFlow(opts) {
         userEvmAddress,
     };
 }
+/** Mainnet: master-signed Domain A ApproveAgent → POST /fapi/v3/approveAgent. */
+async function postAsterApproveAgent(o) {
+    assertAsterDomainAMainnet(o.network);
+    const asterChain = asterChainOf(o.network);
+    const approveTypedData = buildApproveAgentTypedData({
+        user: o.user,
+        agentAddress: o.agentAddress,
+        agentName: o.agentName,
+        expiredMs: o.expiredMs,
+        canPerpTrade: o.canPerp,
+        canSpotTrade: o.canSpot,
+        canWithdraw: o.canWithdraw,
+        ipWhitelist: o.ipWhitelist,
+        nonceMicros: o.nonceMicros,
+        asterChain,
+    });
+    const signature = await o.masterSigner.signTypedData(approveTypedData.domain, approveTypedData.types, approveTypedData.message);
+    const qsEntries = [
+        ["agentName", o.agentName],
+        ["agentAddress", o.agentAddress],
+    ];
+    if (o.ipWhitelist !== undefined && o.ipWhitelist !== null) {
+        qsEntries.push(["ipWhitelist", o.ipWhitelist]);
+    }
+    qsEntries.push(["expired", String(o.expiredMs)], ["canSpotTrade", String(o.canSpot)], ["canPerpTrade", String(o.canPerp)], ["canWithdraw", String(o.canWithdraw)], ["asterChain", asterChain], ["user", o.user], ["nonce", String(o.nonceMicros)], ["signature", signature], ["signatureChainId", String(ASTER_DOMAIN_A.chainId)]);
+    return fetch(`${o.baseUrl}/fapi/v3/approveAgent?${new URLSearchParams(Object.fromEntries(qsEntries)).toString()}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: "",
+    });
+}
+/** Aster: an API wallet with withdraw permission must carry an IP whitelist (pre-flight, nothing signed). */
+export function assertAsterWithdrawIpWhitelist(canWithdraw, ipWhitelist) {
+    if (!canWithdraw || asterSpaceIpWhitelist(ipWhitelist) !== "")
+        return;
+    throw new PerpError("INVALID_PARAMS", "Aster requires an IP whitelist when an API wallet is granted the withdraw permission", {
+        remediation: "Pass --ip-whitelist \"<ip> <ip/cidr>\" together with --can-withdraw, or drop --can-withdraw",
+    });
+}
+/**
+ * Normalize the `--ip-whitelist` flag (comma- or space-separated) to the
+ * space-delimited form registerAndApproveAgent signs; "" when absent.
+ */
+export function asterSpaceIpWhitelist(raw) {
+    if (raw === undefined)
+        return "";
+    return raw.split(/[,\s]+/).filter(s => s.length > 0).join(" ");
+}
+/**
+ * Testnet: POST /fapi/v3/registerAndApproveAgent (unauthenticated; the master
+ * EVM wallet signs the literal param string as Message{msg}, domain chainId =
+ * signatureChainId = 56). Params are sent in the signed order plus `signature`.
+ */
+async function postAsterRegisterAndApproveAgent(o) {
+    const { buildRegisterAndApproveAgentTypedData, ASTER_REGISTER_AGENT_EVM_CHAIN_ID } = await import("../exchanges/aster-typed-data.js");
+    const td = buildRegisterAndApproveAgentTypedData({
+        user: o.user,
+        nonceMicros: o.nonceMicros,
+        agentName: o.agentName,
+        agentAddress: o.agentAddress,
+        expiredMs: o.expiredMs,
+        signatureChainId: ASTER_REGISTER_AGENT_EVM_CHAIN_ID,
+        canSpotTrade: o.canSpot,
+        canPerpTrade: o.canPerp,
+        canWithdraw: o.canWithdraw,
+        ipWhitelist: asterSpaceIpWhitelist(o.ipWhitelist),
+    });
+    const signature = await o.masterSigner.signTypedData(td.domain, td.types, td.message);
+    const qs = new URLSearchParams([...td.params, ["signature", signature]]);
+    return fetch(`${o.baseUrl}/fapi/v3/registerAndApproveAgent?${qs.toString()}`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: "",
+    });
+}
+/** Aster `AsterChain` field for the network (signed into Domain A messages and sent as a query param). */
+function asterChainOf(network) {
+    return network === "testnet" ? "Testnet" : "Mainnet";
+}
+/**
+ * Master-signed DelAgent → DELETE /fapi/v3/agent on the selected network's
+ * host. Returns the raw response; callers decide how to treat non-2xx.
+ */
+async function deleteAsterAgent(masterSigner, agentAddress, network) {
+    assertAgentApproveSupported("aster", network, "revoke");
+    assertAsterDomainAMainnet(network);
+    const userEvmAddress = masterSigner.getAddress();
+    const asterChain = asterChainOf(network);
+    const nonceMicros = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+    const delTypedData = buildDelAgentTypedData({ user: userEvmAddress, agentAddress, nonceMicros, asterChain });
+    const signature = await masterSigner.signTypedData(delTypedData.domain, delTypedData.types, delTypedData.message);
+    const qs = new URLSearchParams(Object.fromEntries([
+        ["agentAddress", agentAddress],
+        ["asterChain", asterChain],
+        ["user", userEvmAddress],
+        ["nonce", String(nonceMicros)],
+        ["signature", signature],
+        ["signatureChainId", String(ASTER_DOMAIN_A.chainId)],
+    ]));
+    return fetch(`${networkConfig(getVenue("aster"), network).restUrl}/fapi/v3/agent?${qs.toString()}`, {
+        method: "DELETE",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: "",
+    });
+}
+/**
+ * Decide an Aster DELETE /fapi/v3/agent response. 2xx = deleted; 404 = already
+ * gone server-side (idempotent). Anything else — or a 2xx JSON body carrying a
+ * negative Aster error `code` — throws APPROVE_FAILED: the agent may still be
+ * authorized, so the caller must keep its local record.
+ */
+async function assertAsterAgentDeleted(res, agentAddress, nextStep) {
+    if (res.status === 404)
+        return;
+    const text = await res.text();
+    const remediation = `The agent key may still be authorized to trade. ${nextStep} Agent: ${agentAddress}`;
+    if (!res.ok) {
+        throw new PerpError("APPROVE_FAILED", `Aster agent delete failed (${res.status}): ${text.slice(0, 200)}`, {
+            exchange: "aster",
+            remediation,
+        });
+    }
+    let body = null;
+    try {
+        body = JSON.parse(text);
+    }
+    catch { /* non-JSON 2xx body: the venue accepted it */ }
+    const code = body !== null && typeof body === "object" ? body.code : null;
+    if (typeof code === "number" && code < 0) {
+        throw new PerpError("APPROVE_FAILED", `Aster agent delete rejected: ${text.slice(0, 200)}`, {
+            exchange: "aster",
+            remediation,
+        });
+    }
+}
 /**
  * Parse an expires-in string to a Date.
  * Accepts: "30d", "90d", "180d", "1y", or any ISO-8601 datetime string.
  * Throws if malformed.
  */
-function parseExpiresIn(value) {
+export function parseExpiresIn(value) {
     const v = value.trim();
     // Match Nd (days) or Ny (years)
     const daysMatch = v.match(/^(\d+)d$/i);
@@ -1541,13 +2219,22 @@ function parseExpiresIn(value) {
     });
 }
 // ── Hyperliquid agent approve/revoke helpers (Phase 2b) ──────────────────────
-/** EIP-712 domain for HL user-signed actions (chainId 42161 = Arbitrum) */
-const HL_USER_SIGNED_DOMAIN = {
-    name: "HyperliquidSignTransaction",
-    version: "1",
-    chainId: 42161,
-    verifyingContract: "0x0000000000000000000000000000000000000000",
-};
+/**
+ * EIP-712 domain for HL user-signed actions on `network`. chainId must equal
+ * the action's signatureChainId (HL_USER_SIGNED in the venue definition).
+ */
+function hlUserSignedDomain(network) {
+    return {
+        name: "HyperliquidSignTransaction",
+        version: "1",
+        chainId: HL_USER_SIGNED[network].signatureChainId,
+        verifyingContract: "0x0000000000000000000000000000000000000000",
+    };
+}
+/** POST /exchange URL for `network` (venue definition restUrl). */
+function hlExchangeUrl(network) {
+    return `${networkConfig(getVenue("hyperliquid"), network).restUrl}/exchange`;
+}
 /** EIP-712 types for HyperliquidTransaction:ApproveAgent */
 const HL_APPROVE_AGENT_TYPES = {
     "HyperliquidTransaction:ApproveAgent": [
@@ -1557,6 +2244,8 @@ const HL_APPROVE_AGENT_TYPES = {
         { name: "nonce", type: "uint64" },
     ],
 };
+/** Hyperliquid approveAgent: "The expiration can be at most 180 days in the future" (exchange-endpoint docs). */
+const HL_AGENT_MAX_VALIDITY_MS = 180 * 86_400_000;
 /**
  * Core HL approve flow.
  * Caller MUST hold the "hyperliquid" lock before calling this function.
@@ -1565,24 +2254,52 @@ const HL_APPROVE_AGENT_TYPES = {
  *  1. Resolve master via OwsEvmSigner.create
  *  2. Generate agent OWS wallet (eip155-only, name `agent-hl-<masterName>`)
  *  3. Build HL approveAgent action + EIP-712 message
- *  4. Master signs EIP-712 (user-signed domain, chainId 42161)
- *  5. POST https://api.hyperliquid.xyz/exchange
+ *  4. Master signs EIP-712 (user-signed domain; hyperliquidChain + signatureChainId per network)
+ *  5. POST <network restUrl>/exchange
  *  6. On success: persist AgentMeta to settings.agents.hyperliquid[name]
  */
 async function runHlApproveFlow(opts) {
-    const { masterName, passphrase, agentName, expiresAtIso, nowIso, canPerp, canSpot, canWithdraw } = opts;
+    const { network, masterName, passphrase, agentName, expiresAt, expiresAtIso, nowIso, canPerp, canSpot, canWithdraw } = opts;
+    const { hyperliquidChain, signatureChainIdHex } = HL_USER_SIGNED[network];
+    // Hyperliquid rejects extra-agent names outside 1..16 characters; refuse before any wallet is created.
+    // The check covers the name itself: the venue docs state no length rule, and the documented
+    // expiry suffix below is by itself longer than 16 characters.
+    if (agentName.length < 1 || agentName.length > 16) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid agent name "${agentName}" must be 1-16 characters (got ${agentName.length})`, {
+            remediation: "Pass a shorter --agent-name",
+        });
+    }
+    if (agentName.includes("valid_until")) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid agent name "${agentName}" must not contain "valid_until" (the venue reads it as the expiry suffix)`, {
+            remediation: "Pass a different --agent-name; set the expiry with --expires-in",
+        });
+    }
+    // Docs (for-developers/api/exchange-endpoint, approveAgent → agentName): "A custom expiration can
+    // be set by appending `valid_until {timestamp}` after the name. The expiration can be at most
+    // 180 days in the future". The timestamp is sent in milliseconds, the unit of every other HL API
+    // timestamp (nonce; extraAgents `validUntil`). Without the suffix the venue applies its own
+    // expiry and the stored expiresAt would not be the venue's.
+    const validityMs = expiresAt.getTime() - Date.now();
+    if (!(validityMs > 0) || validityMs > HL_AGENT_MAX_VALIDITY_MS) {
+        throw new PerpError("INVALID_PARAMS", `Hyperliquid agent expiry ${expiresAtIso} must be in the future and at most 180 days away (venue limit)`, {
+            exchange: "hyperliquid",
+            remediation: "Pass --expires-in 180d or less (e.g. --expires-in 90d)",
+        });
+    }
+    const wireAgentName = `${agentName} valid_until ${expiresAt.getTime()}`;
     const { ethers } = await import("ethers");
     // Step 1: Resolve master signer
     const masterSigner = OwsEvmSigner.create(masterName, passphrase);
     const userEvmAddress = masterSigner.getAddress();
     // Step 2: Generate agent OWS wallet
     const ows = loadOws();
-    const agentWalletName = `agent-hl-${masterName}`;
+    const agentWalletName = agentWalletNameFor("hl", masterName, network);
     // HL agent wallet created with empty passphrase. This is intentional:
     // (1) Tier 1 hot-path must be prompt-free (P1 from agent_first_design.md).
     // (2) OWS provides at-rest encryption regardless of per-wallet passphrase.
     // (3) Agent blast-radius is limited (perp-only, no withdraw, no master ops).
     // At runtime, src/index.ts opens this wallet with "" matching the create-time empty.
+    assertAgentWalletNameFree("hyperliquid", agentWalletName, network);
     const agentWallet = ows.createWallet(agentWalletName, "");
     const agentEvmAccount = agentWallet.accounts.find((a) => a.chainId.startsWith("eip155:"));
     if (!agentEvmAccount) {
@@ -1594,29 +2311,36 @@ async function runHlApproveFlow(opts) {
     // Step 3: Build nonce (monotonic ms)
     const now = Date.now();
     const nonce = now;
-    const sigChainIdHex = "0xa4b1"; // 42161 hex
     const action = {
         type: "approveAgent",
-        hyperliquidChain: "Mainnet",
-        signatureChainId: sigChainIdHex,
+        hyperliquidChain,
+        signatureChainId: signatureChainIdHex,
         agentAddress: agentEvmAddress,
-        agentName,
+        agentName: wireAgentName,
         nonce,
     };
     // Step 4: Master signs EIP-712 (user-signed domain)
     const message = {
-        hyperliquidChain: "Mainnet",
+        hyperliquidChain,
         agentAddress: agentEvmAddress,
-        agentName,
+        agentName: wireAgentName,
         nonce,
     };
-    const sigRaw = await masterSigner.signTypedData(HL_USER_SIGNED_DOMAIN, HL_APPROVE_AGENT_TYPES, message);
+    let sigRaw;
+    try {
+        sigRaw = await masterSigner.signTypedData(hlUserSignedDomain(network), HL_APPROVE_AGENT_TYPES, message);
+    }
+    catch (e) {
+        // Nothing was sent: the fresh agent wallet is an orphan — remove it so a retry
+        // (e.g. after a wrong passphrase) does not hit "wallet name already exists".
+        tryDeleteOrphanWallet(ows, agentWalletName);
+        throw e;
+    }
     const parsed = ethers.Signature.from(sigRaw);
     const signature = { r: parsed.r, s: parsed.s, v: parsed.v };
     // Step 5: POST /exchange
-    const baseUrl = "https://api.hyperliquid.xyz";
     const payload = { action, nonce, signature, vaultAddress: null };
-    const agentRes = await fetch(`${baseUrl}/exchange`, {
+    const agentRes = await fetch(hlExchangeUrl(network), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(payload),
@@ -1634,18 +2358,27 @@ async function runHlApproveFlow(opts) {
         const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("EXCHANGE_ERROR", `HL exchange API parse error (${agentRes.status}): ${text.slice(0, 200)}`, {
             remediation: buildPreVenueRemediation({
-                cleanupOk, dex: "hyperliquid", masterName, agentAddress: agentEvmAddress,
+                cleanupOk, dex: "hyperliquid", network, masterName, agentAddress: agentEvmAddress,
                 hint: "Check Hyperliquid API status",
             }),
         });
     }
+    // Same acceptance rule as revokeHlAgent: only HTTP 2xx + status "ok" is a registered agent.
+    // Anything else but an explicit "err" is an UNKNOWN outcome: the agent may or may not be
+    // authorized, so the local agent wallet is kept (deleting it could orphan a live key).
+    if (!agentRes.ok || (resp?.status !== "ok" && resp?.status !== "err")) {
+        throw new PerpError("APPROVE_PARTIAL", `HL approveAgent outcome unknown (HTTP ${agentRes.status}): ${text.slice(0, 200)}`, {
+            exchange: "hyperliquid",
+            remediation: `Check the Hyperliquid UI (More → API) for agent ${agentEvmAddress}. If it is listed, re-run approve with --rotate; if not, delete the local OWS wallet "${agentWalletName}" and retry.`,
+        });
+    }
     if (resp?.status === "err") {
         // Pre-venue rejection — Hyperliquid did NOT register the agent. Roll
         // back the orphan local OWS wallet so retry can proceed cleanly.
         const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("APPROVE_PARTIAL", `HL approveAgent failed: ${typeof resp.response === "string" ? resp.response : JSON.stringify(resp)}`, {
             remediation: buildPreVenueRemediation({
-                cleanupOk, dex: "hyperliquid", masterName, agentAddress: agentEvmAddress,
+                cleanupOk, dex: "hyperliquid", network, masterName, agentAddress: agentEvmAddress,
             }),
         });
     }
@@ -1663,51 +2396,89 @@ async function runHlApproveFlow(opts) {
         permissions: { canPerpTrade: canPerp, canSpotTrade: canSpot, canWithdraw },
         asterApprovalNonce: String(nonce), // reused field: stores HL nonce for diagnostics
         status: "active",
+        network,
     });
     return { agentAddress: agentEvmAddress, agentName, expiresAt: expiresAtIso, userEvmAddress };
 }
 /**
  * Post a HL revoke action for the given agent.
- * Uses approveAgent with agentAddress set to the zero address (empty = revoke).
- * Per HL convention: sending approveAgent with an empty/zero agentAddress
- * clears the agent slot.
+ * Uses approveAgent with agentAddress set to the zero address under the
+ * agent's own name — HL keys agent slots by name (the unnamed slot is "").
+ *
+ * Rule #2: the venue must confirm with `{status:"ok"}`. Any other answer
+ * (HTTP error, `{status:"err"}`, unparseable body) throws APPROVE_FAILED —
+ * the agent key may still be authorized, so the caller must not forget it.
  */
-async function revokeHlAgent(masterSigner) {
+/** Hyperliquid's answer to a zero-address approveAgent for a named agent it no longer holds (pruned / expired). */
+const HL_AGENT_ALREADY_GONE = "Extra agent does not exist.";
+async function revokeHlAgent(masterSigner, network, agentName, agentAddress) {
     const { ethers } = await import("ethers");
+    const { hyperliquidChain, signatureChainIdHex } = HL_USER_SIGNED[network];
     const nonce = Date.now();
-    const sigChainIdHex = "0xa4b1";
     // Zero-address revoke: approveAgent with empty agentAddress (validUntil:0 convention)
     const revokeAddress = "0x0000000000000000000000000000000000000000";
     const action = {
         type: "approveAgent",
-        hyperliquidChain: "Mainnet",
-        signatureChainId: sigChainIdHex,
+        hyperliquidChain,
+        signatureChainId: signatureChainIdHex,
         agentAddress: revokeAddress,
-        agentName: "",
+        agentName,
         nonce,
     };
     const message = {
-        hyperliquidChain: "Mainnet",
+        hyperliquidChain,
         agentAddress: revokeAddress,
-        agentName: "",
+        agentName,
         nonce,
     };
-    const sigRaw = await masterSigner.signTypedData(HL_USER_SIGNED_DOMAIN, HL_APPROVE_AGENT_TYPES, message);
+    const sigRaw = await masterSigner.signTypedData(hlUserSignedDomain(network), HL_APPROVE_AGENT_TYPES, message);
     const parsed = ethers.Signature.from(sigRaw);
     const signature = { r: parsed.r, s: parsed.s, v: parsed.v };
     const payload = { action, nonce, signature, vaultAddress: null };
-    await fetch("https://api.hyperliquid.xyz/exchange", {
+    const res = await fetch(hlExchangeUrl(network), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(payload),
     });
-    // Revoke is best-effort — don't throw on HTTP errors
+    const text = await res.text();
+    const remediation = `The agent key may still be authorized to trade. Retry, or remove the API wallet in the Hyperliquid UI (More → API). Agent: ${agentAddress} ("${agentName}")`;
+    if (!res.ok) {
+        throw new PerpError("APPROVE_FAILED", `Hyperliquid revoke failed (${res.status}): ${text.slice(0, 200)}`, {
+            exchange: "hyperliquid",
+            remediation,
+        });
+    }
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        throw new PerpError("APPROVE_FAILED", `Hyperliquid revoke returned an unreadable response (${res.status}): ${text.slice(0, 200)}`, {
+            exchange: "hyperliquid",
+            remediation,
+        });
+    }
+    const status = body !== null && typeof body === "object" ? body.status : null;
+    // The venue no longer knows this agent — nothing is left to revoke. HL docs (for-developers/api/
+    // nonces-and-api-wallets, "API wallet pruning"): "API wallets and their associated nonce state may
+    // be pruned in the following cases: 1. The wallet is deregistered. … 2. The wallet expires.
+    // 3. The account that registered the agent no longer has funds." Only this exact venue answer
+    // (live mainnet 2026-10-05, on an expired agent) counts as "already gone".
+    if (status === "err" && body.response === HL_AGENT_ALREADY_GONE)
+        return;
+    if (status !== "ok") {
+        throw new PerpError("APPROVE_FAILED", `Hyperliquid revoke rejected: ${text.slice(0, 200)}`, {
+            exchange: "hyperliquid",
+            remediation,
+        });
+    }
 }
 // ── HL userSetAbstraction (account-mode write) helper ────────────────────────
 /** EIP-712 types for HyperliquidTransaction:UserSetAbstraction */
 const HL_USER_SET_ABSTRACTION_TYPES = {
     "HyperliquidTransaction:UserSetAbstraction": [
         { name: "hyperliquidChain", type: "string" },
+        { name: "user", type: "address" },
         { name: "abstraction", type: "string" },
         { name: "nonce", type: "uint64" },
     ],
@@ -1722,7 +2493,7 @@ const HL_ABSTRACTION_TO_WIRE = {
  * Send a Hyperliquid `userSetAbstraction` action.
  *
  * Reuses the same EIP-712 user-signed domain (`HyperliquidSignTransaction`,
- * chainId 42161) and `OwsEvmSigner.signTypedData` plumbing as
+ * per-network signatureChainId) and `OwsEvmSigner.signTypedData` plumbing as
  * `runHlApproveFlow`; the only differences are the type struct
  * (`UserSetAbstraction` vs `ApproveAgent`) and the action payload.
  *
@@ -1734,26 +2505,32 @@ export async function runHlSetAbstractionFlow(opts) {
     const { ethers } = await import("ethers");
     const masterSigner = OwsEvmSigner.create(masterName, passphrase);
     const userEvmAddress = masterSigner.getAddress();
-    const hyperliquidChain = (isTestnet ? "Testnet" : "Mainnet");
-    const sigChainIdHex = "0xa4b1"; // 42161 hex
+    const network = isTestnet ? "testnet" : "mainnet";
+    const { hyperliquidChain, signatureChainIdHex } = HL_USER_SIGNED[network];
     const abstraction = HL_ABSTRACTION_TO_WIRE[mode];
     const nonce = Date.now();
+    // Field set and order per hyperliquid-python-sdk USER_SET_ABSTRACTION_SIGN_TYPES
+    // (hyperliquidChain, user, abstraction, nonce); `user` is the lower-cased master address.
+    // Without `user` in the signed struct HL recovers a different signer (live testnet 2026-10-05:
+    // "Must deposit before performing actions. User: 0x5e33…").
+    const user = userEvmAddress.toLowerCase();
     const action = {
         type: "userSetAbstraction",
         hyperliquidChain,
-        signatureChainId: sigChainIdHex,
-        user: userEvmAddress,
+        signatureChainId: signatureChainIdHex,
+        user,
         abstraction,
         nonce,
     };
     const message = {
         hyperliquidChain,
+        user,
         abstraction,
         nonce,
     };
     let sigRaw;
     try {
-        sigRaw = await masterSigner.signTypedData(HL_USER_SIGNED_DOMAIN, HL_USER_SET_ABSTRACTION_TYPES, message);
+        sigRaw = await masterSigner.signTypedData(hlUserSignedDomain(network), HL_USER_SET_ABSTRACTION_TYPES, message);
     }
     catch (sigErr) {
         throw new PerpError("SIGNATURE_FAILED", `HL userSetAbstraction signing failed: ${sigErr instanceof Error ? sigErr.message : String(sigErr)}`, {
@@ -1762,9 +2539,8 @@ export async function runHlSetAbstractionFlow(opts) {
     }
     const parsed = ethers.Signature.from(sigRaw);
     const signature = { r: parsed.r, s: parsed.s, v: parsed.v };
-    const baseUrl = isTestnet ? "https://api.hyperliquid-testnet.xyz" : "https://api.hyperliquid.xyz";
     const payload = { action, nonce, signature, vaultAddress: null };
-    const res = await fetch(`${baseUrl}/exchange`, {
+    const res = await fetch(hlExchangeUrl(network), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(payload),
@@ -1801,14 +2577,14 @@ export async function runHlSetAbstractionFlow(opts) {
  *  1. Resolve master via OwsSolanaSigner.create
  *  2. Generate agent OWS wallet (`agent-pac-<masterName>`) with empty passphrase
  *  3. Build canonical bind_agent_wallet message + master Ed25519 signature
- *  4. POST https://api.pacifica.fi/api/v1/agent/bind
+ *  4. POST <network restUrl>/agent/bind (api.pacifica.fi / test-api.pacifica.fi)
  *  5. On success: persist AgentMeta to settings.agents.pacifica[name]
  *  6. On failure: rollback agent OWS wallet + emit APPROVE_PARTIAL/APPROVE_FAILED
  *
  * Off-chain auth — no on-chain transaction, no gas required.
  */
 async function runPacApproveFlow(opts) {
-    const { masterName, passphrase, agentName, expiresAtIso, nowIso, canPerp, canSpot, canWithdraw, } = opts;
+    const { network, masterName, passphrase, agentName, expiresAtIso, nowIso, canPerp, canSpot, canWithdraw, } = opts;
     const { buildBindAgentMessage } = await import("../exchanges/pacifica-typed-data.js");
     // Step 1: Resolve master Solana signer
     const masterSigner = OwsSolanaSigner.create(masterName, passphrase);
@@ -1816,7 +2592,8 @@ async function runPacApproveFlow(opts) {
     // Step 2: Generate agent OWS wallet (empty passphrase mirrors HL pattern;
     // the runtime opens with "" so the hot-path is prompt-free).
     const ows = loadOws();
-    const agentWalletName = `agent-pac-${masterName}`;
+    const agentWalletName = agentWalletNameFor("pac", masterName, network);
+    assertAgentWalletNameFree("pacifica", agentWalletName, network);
     const agentWallet = ows.createWallet(agentWalletName, "");
     const agentSolAccount = agentWallet.accounts.find((a) => a.chainId.startsWith("solana:"));
     if (!agentSolAccount) {
@@ -1851,7 +2628,7 @@ async function runPacApproveFlow(opts) {
     let pacPostSucceeded = false;
     let resp;
     try {
-        const httpRes = await fetch("https://api.pacifica.fi/api/v1/agent/bind", {
+        const httpRes = await fetch(`${networkConfig(getVenue("pacifica"), network).restUrl}/agent/bind`, {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body: JSON.stringify(requestBody),
@@ -1865,7 +2642,7 @@ async function runPacApproveFlow(opts) {
                 const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
                 throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet failed: ${errMsg}`, {
                     remediation: buildPreVenueRemediation({
-                        cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+                        cleanupOk, dex: "pacifica", network, masterName, agentAddress: agentSolanaAddress,
                     }),
                 });
             }
@@ -1877,7 +2654,7 @@ async function runPacApproveFlow(opts) {
             const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
             throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet failed (${httpRes.status}): ${errText.slice(0, 200)}`, {
                 remediation: buildPreVenueRemediation({
-                    cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+                    cleanupOk, dex: "pacifica", network, masterName, agentAddress: agentSolanaAddress,
                 }),
             });
         }
@@ -1889,7 +2666,7 @@ async function runPacApproveFlow(opts) {
         const cleanupOk = tryDeleteOrphanWallet(ows, agentWalletName);
         throw new PerpError("APPROVE_PARTIAL", `Pacifica bind_agent_wallet network error: ${httpErr instanceof Error ? httpErr.message : String(httpErr)}`, {
             remediation: buildPreVenueRemediation({
-                cleanupOk, dex: "pacifica", masterName, agentAddress: agentSolanaAddress,
+                cleanupOk, dex: "pacifica", network, masterName, agentAddress: agentSolanaAddress,
             }),
         });
     }
@@ -1913,6 +2690,7 @@ async function runPacApproveFlow(opts) {
             permissions: { canPerpTrade: canPerp, canSpotTrade: canSpot, canWithdraw },
             asterApprovalNonce: String(bind.header.timestamp),
             status: "active",
+            network,
         });
     }
     catch (persistErr) {
@@ -1920,7 +2698,7 @@ async function runPacApproveFlow(opts) {
         // Best-effort revoke + APPROVE_PARTIAL.
         if (pacPostSucceeded) {
             try {
-                await revokePacAgent(masterSigner, agentSolanaAddress);
+                await revokePacAgent(masterSigner, agentSolanaAddress, network);
             }
             catch { /* best effort */ }
         }
@@ -1936,54 +2714,91 @@ async function runPacApproveFlow(opts) {
     };
 }
 /**
- * Revoke a Pacifica agent wallet (best-effort, idempotent).
- * Sends signed unbind_agent_wallet to /api/v1/agent/bind. Pacifica accepts
- * either a specific agent base58 or an empty string (revoke all) — we pass
- * the specific agent address when available.
+ * Revoke a Pacifica agent wallet.
+ *
+ * Endpoint + operation type follow the official Pacifica SDK
+ * (`rest/api_agent_keys_detailed.py`): `revoke_agent_wallet` → POST
+ * /agent/revoke. A missing agent address is refused (it must never widen into
+ * `revoke_all_agent_wallets`, which would also kill agents this CLI does not own).
+ *
+ * Rule #2: this THROWS on a rejected revoke. It previously POSTed an
+ * `unbind_agent_wallet` type to /agent/bind — neither of which Pacifica
+ * exposes — and discarded the response entirely, so a refused revoke was
+ * reported to the user as success while the agent key stayed authorized to
+ * trade. Callers that genuinely want best-effort must catch explicitly.
  */
-async function revokePacAgent(masterSigner, agentSolanaAddress) {
-    const { buildUnbindAgentMessage } = await import("../exchanges/pacifica-typed-data.js");
+export async function revokePacAgent(masterSigner, agentSolanaAddress, network) {
+    if (agentSolanaAddress === null || agentSolanaAddress.length === 0) {
+        throw new PerpError("AGENT_NOT_REGISTERED", "Pacifica agent record has no agent address — refusing to send a revoke (it would revoke ALL agents)", {
+            exchange: "pacifica",
+            remediation: "Revoke the agent in the Pacifica UI, then clear the local record: perp wallet agent revoke pacifica <name> --force",
+        });
+    }
+    const { buildRevokeAgentMessage } = await import("../exchanges/pacifica-typed-data.js");
     const userSolanaAddress = masterSigner.getPublicKeyBase58();
-    const unbind = buildUnbindAgentMessage({
-        account: userSolanaAddress,
-        agentWallet: agentSolanaAddress,
-    });
-    const msgBytes = new TextEncoder().encode(unbind.canonicalJson);
+    const built = buildRevokeAgentMessage({ account: userSolanaAddress, agentWallet: agentSolanaAddress });
+    const path = "/agent/revoke";
+    const msgBytes = new TextEncoder().encode(built.canonicalJson);
     const sigBytes = await masterSigner.signMessage(msgBytes);
     const signature = bs58.encode(sigBytes);
     const requestBody = {
         account: userSolanaAddress,
         signature,
-        timestamp: unbind.header.timestamp,
-        expiry_window: unbind.header.expiry_window,
-        type: unbind.header.type,
-        ...unbind.payload,
+        timestamp: built.header.timestamp,
+        expiry_window: built.header.expiry_window,
+        type: built.header.type,
+        ...built.payload,
     };
-    // FIXME(2c-spike): unverified endpoint — Pacifica may expose a separate
-    // `/api/v1/agent/unbind` or accept unbind via the same /agent/bind. We POST
-    // to /agent/bind because the action type discriminates server-side per the
-    // signing convention. Confirm against live mainnet.
-    await fetch("https://api.pacifica.fi/api/v1/agent/bind", {
+    const res = await fetch(`${networkConfig(getVenue("pacifica"), network).restUrl}${path}`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(requestBody),
     });
-    // Revoke is best-effort — don't throw on HTTP errors
+    const text = await res.text().catch(() => "");
+    if (!res.ok) {
+        throw new PerpError("APPROVE_FAILED", `Pacifica revoke failed (${res.status}): ${text.slice(0, 200)}`, {
+            exchange: "pacifica",
+            remediation: `The agent key may still be authorized to trade. Retry, or revoke it from the Pacifica UI. Agent: ${agentSolanaAddress}`,
+        });
+    }
+    // Pacifica wraps REST results in `{ success, error, data }` — a 200 with
+    // success:false is still a refusal, so check the envelope, not just the code.
+    try {
+        const parsed = JSON.parse(text);
+        if (parsed && parsed.success === false) {
+            throw new PerpError("APPROVE_FAILED", `Pacifica revoke rejected: ${JSON.stringify(parsed.error ?? parsed)}`, {
+                exchange: "pacifica",
+                remediation: `The agent key may still be authorized to trade. Retry, or revoke it from the Pacifica UI. Agent: ${agentSolanaAddress}`,
+            });
+        }
+    }
+    catch (e) {
+        if (e instanceof PerpError)
+            throw e;
+        // Non-JSON 2xx body: the venue accepted it. Nothing to assert.
+    }
+}
+/** A slot is occupied on-chain when /apikeys lists a non-empty, non-zero public key for it. */
+function isLtSlotKeyOccupied(publicKey) {
+    return !/^(0x)?0*$/.test(publicKey.trim());
 }
 /**
- * Pick the next free Lighter slot in [4, 254].
+ * Pick the first free Lighter slot in [5, 254].
  *
- * Strategy: scan settings.agents.lighter; pick `max(usedSlots) + 1` capped to
- * 254. If none used, default to 4. If 4 itself is used (env-driven auto-setup
- * default), advance to next.
+ * A slot is used when any local agent record (any network — conservative) holds it,
+ * when the venue reserves it, or when the account's on-chain key list shows a key on
+ * it (`onChainOccupied`) — an auto pick must never overwrite a key some other client
+ * (web app, another machine) is using.
  */
-function pickNextFreeLtSlot(settings) {
-    const ltMap = settings.agents?.lighter ?? {};
-    const used = new Set();
+export function pickNextFreeLtSlot(settings, venue, onChainOccupied) {
+    const ltMap = settings.agents?.[venue] ?? {};
+    const used = new Set(venue === "lighter-rh" ? LIGHTER_RH_RESERVED_KEY_INDEXES : []);
     for (const meta of Object.values(ltMap)) {
         if (typeof meta.apiKeyIndex === "number")
             used.add(meta.apiKeyIndex);
     }
+    for (const slot of onChainOccupied)
+        used.add(slot);
     // Slot 4 is the default Lighter env-key auto-setup index — treat as used so
     // agent-managed slots don't collide with the env-driven legacy path.
     used.add(4);
@@ -1991,8 +2806,8 @@ function pickNextFreeLtSlot(settings) {
         if (!used.has(i))
             return i;
     }
-    throw new PerpError("INVALID_PARAMS", "All Lighter slots [4, 254] are in use", {
-        remediation: "Revoke an existing agent: perp wallet agent revoke lighter <name>",
+    throw new PerpError("INVALID_PARAMS", "All Lighter slots [4, 254] are in use (locally or on-chain)", {
+        remediation: `Revoke an existing agent: perp wallet agent revoke ${venue} <name>`,
     });
 }
 /**
@@ -2015,38 +2830,60 @@ function pickNextFreeLtSlot(settings) {
  * Off-chain auth — no on-chain BNB/ETH gas required.
  */
 async function runLtApproveFlow(opts) {
-    const { masterName, passphrase, agentName, expiresAtIso, nowIso, canPerp, canSpot, canWithdraw, apiKeyIndex: explicitSlot, } = opts;
+    const { venue, network, masterName, passphrase, agentName, expiresAtIso, nowIso, canPerp, canSpot, canWithdraw, apiKeyIndex: explicitSlot, forceSlot, } = opts;
+    const venueName = getVenue(venue).displayName;
     const { LighterAdapter } = await import("../exchanges/lighter.js");
     // Step 1: Resolve master EVM signer (Lighter L1 ChangePubKey is EVM EIP-712 + EIP-191).
     const masterSigner = OwsEvmSigner.create(masterName, passphrase);
     const userEvmAddress = masterSigner.getAddress();
-    // Step 2: Pick slot.
-    const settings = loadSettings();
-    let chosenSlot;
     if (explicitSlot !== undefined) {
         // Validate range (defensive — caller should have already checked, but the
         // helper is also used from rotate where no validation runs upstream).
-        if (!Number.isInteger(explicitSlot) || explicitSlot < 4 || explicitSlot > 254) {
-            throw new PerpError("INVALID_PARAMS", `apiKeyIndex must be an integer in [4, 254]; got ${explicitSlot}`, {
-                remediation: "Slots 0-3 are reserved by the Lighter frontend.",
-            });
-        }
-        chosenSlot = explicitSlot;
-    }
-    else {
-        chosenSlot = pickNextFreeLtSlot(settings);
+        assertLighterSlot(venue, explicitSlot);
     }
-    // Step 3: Spin up a LighterAdapter bound to the master EVM signer.
+    // Step 2: Spin up a LighterAdapter bound to the master EVM signer.
     // Constructor takes evmKey (empty since we'll inject signer); init() resolves
     // accountIndex from the L1 EVM address via REST.
-    const adapter = new LighterAdapter("", false);
+    const adapter = LighterAdapter.forVenue(venue, "", network === "testnet");
     adapter.setSigner(masterSigner);
     await adapter.init();
     if (adapter.accountIndex < 0) {
-        throw new PerpError("INVALID_PARAMS", `No Lighter account found for master EVM address ${userEvmAddress}`, {
-            remediation: "Deposit USDC to the master address on Lighter to create an account, then retry.",
+        throw new PerpError("INVALID_PARAMS", `No ${venueName} account found for master EVM address ${userEvmAddress}`, {
+            remediation: `Deposit ${adapter.collateralSymbol} to the master address on ${venueName} to create an account, then retry.`,
         });
     }
+    // Step 3: Pick the slot against the account's LIVE key list. Overwriting an occupied slot
+    // silently kills whatever client (web app, another machine, another agent) signs with it.
+    const onChain = await adapter.listApiKeys();
+    const onChainOccupied = new Set(onChain.filter((k) => isLtSlotKeyOccupied(k.publicKey)).map((k) => k.apiKeyIndex));
+    let chosenSlot;
+    if (explicitSlot !== undefined) {
+        chosenSlot = explicitSlot;
+        const localHolder = listAgents(venue).find(({ meta }) => meta.accountIndex === adapter.accountIndex && meta.apiKeyIndex === chosenSlot && agentNetworkOf(venue, meta) === network);
+        if (localHolder) {
+            throw new PerpError("INVALID_PARAMS", `${venueName} slot ${chosenSlot} on account ${adapter.accountIndex} is held by local ${network} agent "${localHolder.meta.agentName}"`, {
+                remediation: `Rotate it (perp${network === "testnet" ? " -n testnet" : ""} wallet agent rotate ${venue} ${localHolder.meta.agentName}), or pick another --api-key-index`,
+            });
+        }
+        if (onChainOccupied.has(chosenSlot) && !forceSlot) {
+            throw new PerpError("INVALID_PARAMS", `${venueName} slot ${chosenSlot} on account ${adapter.accountIndex} already holds an on-chain API key — approving would overwrite it and break whatever signs with it`, {
+                remediation: `Omit --api-key-index to auto-pick a free slot, or pass --force to deliberately overwrite slot ${chosenSlot}`,
+            });
+        }
+    }
+    else {
+        chosenSlot = pickNextFreeLtSlot(loadSettings(), venue, onChainOccupied);
+    }
+    // Before any venue write: account indexes are per-network and pre-tagging keystore files are keyed
+    // by accountIndex + slot only (migrated to the network-tagged path on first load), so refuse to
+    // reuse another network's account+slot.
+    for (const { meta } of listAgents(venue)) {
+        if (meta.accountIndex === adapter.accountIndex && meta.apiKeyIndex === chosenSlot && agentNetworkOf(venue, meta) !== network) {
+            throw new PerpError("INVALID_PARAMS", `${venueName} keystore slot ${adapter.accountIndex}-${chosenSlot} already holds ${agentNetworkOf(venue, meta)} agent "${meta.agentName}"`, {
+                remediation: `Pick another slot: perp${network === "testnet" ? " -n testnet" : ""} wallet agent approve ${venue} --api-key-index <4-254>`,
+            });
+        }
+    }
     // Step 4: Generate keypair + ChangePubKey via existing production infra.
     // setupApiKey already does:
     //   - generateAPIKey() (WASM)
@@ -2061,7 +2898,7 @@ async function runLtApproveFlow(opts) {
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
-        throw new PerpError("APPROVE_PARTIAL", `Lighter ChangePubKey failed: ${msg}`, {
+        throw new PerpError("APPROVE_PARTIAL", `${venueName} ChangePubKey failed: ${msg}`, {
             remediation: `Slot ${chosenSlot} for cleanup: this slot may be partially registered on the L2 server. Retry with a different --api-key-index, or rotate.`,
         });
     }
@@ -2074,13 +2911,23 @@ async function runLtApproveFlow(opts) {
     // (file mode 0600 + obfuscation, NOT cryptographic strength against a local
     // attacker). `accountIndex` and `apiKeyIndex` already live in
     // settings.agents.lighter[name], so they don't need to be duplicated in env.
-    const agentWalletName = `agent-lt-${masterName}`;
+    const agentWalletName = venue === "lighter" ? `agent-lt-${masterName}` : `agent-${venue}-${masterName}`;
     void agentWalletName; // wallet bookkeeping only — not used to derive the L2 key
-    const { saveLighterKey } = await import("../agent-wallet/lighter-keystore.js");
-    saveLighterKey(adapter.accountIndex, chosenSlot, registered.privateKey, "");
+    const { saveLighterFamilyKey } = await import("../agent-wallet/lighter-keystore.js");
+    try {
+        saveLighterFamilyKey(venue, network, adapter.accountIndex, chosenSlot, registered.privateKey, "");
+    }
+    catch (saveErr) {
+        // The slot already holds the new key on-chain, but its private half could not be stored —
+        // the slot is unusable from this machine until it is re-registered.
+        throw new PerpError("APPROVE_PARTIAL", `${venueName} ChangePubKey succeeded on slot ${chosenSlot} (account ${adapter.accountIndex}) but saving its key to the keystore failed: ${saveErr instanceof Error ? saveErr.message : String(saveErr)}`, {
+            exchange: venue,
+            remediation: `Slot ${chosenSlot} now holds a key whose private half was not saved. Fix the keystore directory (permissions / disk space under ~/.perp), then re-register the slot: perp${network === "testnet" ? " -n testnet" : ""} wallet agent approve ${venue} --api-key-index ${chosenSlot} --force`,
+        });
+    }
     // Step 6: Persist
     try {
-        setAgent("lighter", {
+        setAgent(venue, {
             agentName,
             agentWalletName,
             // Lighter agent's identity on the L2 is publicKey + apiKeyIndex.
@@ -2100,11 +2947,12 @@ async function runLtApproveFlow(opts) {
             permissions: { canPerpTrade: canPerp, canSpotTrade: canSpot, canWithdraw },
             asterApprovalNonce: String(Date.now()), // reused field: not used by LT
             status: "active",
+            network,
         });
     }
     catch (persistErr) {
-        throw new PerpError("APPROVE_PARTIAL", `Lighter ChangePubKey succeeded but persist failed: ${persistErr instanceof Error ? persistErr.message : String(persistErr)}`, {
-            remediation: `Lighter slot ${chosenSlot} is registered on the L2 server. Manually update settings.agents.lighter or re-run: perp wallet agent approve lighter --api-key-index <other slot>.`,
+        throw new PerpError("APPROVE_PARTIAL", `${venueName} ChangePubKey succeeded but persist failed: ${persistErr instanceof Error ? persistErr.message : String(persistErr)}`, {
+            remediation: `${venueName} slot ${chosenSlot} is registered on the L2 server. Manually update settings.agents.${venue} or re-run: perp wallet agent approve ${venue} --api-key-index <other slot>.`,
         });
     }
     return {
@@ -2117,15 +2965,70 @@ async function runLtApproveFlow(opts) {
     };
 }
 /**
- * Revoke a Lighter agent (local-only, idempotent).
- *
- * Lighter's L2 has no on-chain revoke action — slots persist on the server
- * until overwritten by a fresh ChangePubKey at the same index. This helper
- * is a no-op stub that exists for symmetry with the other DEX revoke helpers
- * (revokeHlAgent, revokePacAgent) so the dispatch reads consistently. Caller
- * is responsible for `deleteAgent("lighter", name)` to clear local state.
+ * Revoke a Lighter-family agent: Lighter has no "remove key" tx, so the slot's public key
+ * is replaced (master-signed ChangePubKey) by a freshly generated throwaway key whose private
+ * half is discarded — the old agent key can no longer sign. Then the slot keystore file is
+ * deleted. Throws APPROVE_FAILED (nothing deleted locally) when the ChangePubKey is not accepted.
  */
-async function revokeLtAgent() {
-    // No-op. See AC-35: Lighter revoke is local-only.
-    return;
+async function revokeLtAgent(venue, network, meta, passphrase) {
+    const venueName = getVenue(venue).displayName;
+    if (typeof meta.accountIndex !== "number" || typeof meta.apiKeyIndex !== "number") {
+        throw new PerpError("AGENT_NOT_REGISTERED", `${venueName} agent "${meta.agentName}" has no accountIndex/apiKeyIndex — cannot locate its slot`, {
+            remediation: `Revoke the key in the ${venueName} web app (API keys), then: perp wallet agent revoke ${venue} ${meta.agentName} --force`,
+        });
+    }
+    const { LighterAdapter } = await import("../exchanges/lighter.js");
+    const adapter = LighterAdapter.forVenue(venue, "", network === "testnet");
+    adapter.setSigner(OwsEvmSigner.create(meta.masterWalletName, passphrase));
+    await adapter.init();
+    if (adapter.accountIndex !== meta.accountIndex) {
+        throw new PerpError("APPROVE_FAILED", `${venueName} master account ${adapter.accountIndex} does not own agent "${meta.agentName}" (account ${meta.accountIndex})`, {
+            remediation: `Run with the master wallet that registered it (--master / settings.owsActiveWallet), or revoke it in the ${venueName} web app`,
+        });
+    }
+    let throwawayPublicKey;
+    try {
+        // Throwaway key: the returned private key is intentionally dropped (never persisted or logged).
+        throwawayPublicKey = (await adapter.setupApiKey(meta.apiKeyIndex)).publicKey;
+    }
+    catch (e) {
+        throw new PerpError("APPROVE_FAILED", `${venueName} revoke failed: ChangePubKey on slot ${meta.apiKeyIndex} was not accepted — ${e instanceof Error ? e.message : String(e)}`, {
+            exchange: venue,
+            remediation: `The agent key may still be authorized. Retry, or revoke it in the ${venueName} web app. Slot: ${meta.apiKeyIndex}`,
+        });
+    }
+    // sendTx acceptance is not settlement: re-read the slot and require its public key to be the
+    // throwaway one before deleting the local key (otherwise the old key may still be live and the
+    // user would lose the only local copy of a still-authorized key's record).
+    const norm = (k) => k.trim().replace(/^0x/i, "").toLowerCase();
+    // Docs (apidocs.lighter.xyz "Create accounts programmatically"): "`code: 200` only means the API
+    // accepted the transaction. It still has to execute before the key can sign orders, so poll
+    // apikeys until it returns your public key" — their example polls every 1 s for 30 s. Live
+    // (lighter-rh mainnet 2026-10-05) the slot showed the new key a few seconds after the send.
+    let slotKey;
+    try {
+        const deadline = Date.now() + LIGHTER_SLOT_CONFIRM_TIMEOUT_MS;
+        for (;;) {
+            const keys = await adapter.listApiKeys();
+            const entry = keys.find((k) => k.apiKeyIndex === meta.apiKeyIndex);
+            slotKey = entry ? entry.publicKey : null;
+            if ((slotKey !== null && norm(slotKey) === norm(throwawayPublicKey)) || Date.now() + LIGHTER_SLOT_CONFIRM_POLL_MS > deadline)
+                break;
+            await new Promise((r) => setTimeout(r, LIGHTER_SLOT_CONFIRM_POLL_MS));
+        }
+    }
+    catch (e) {
+        throw new PerpError("APPROVE_PARTIAL", `${venueName} revoke sent ChangePubKey for slot ${meta.apiKeyIndex}, but re-reading the slot failed: ${e instanceof Error ? e.message : String(e)}`, {
+            exchange: venue,
+            remediation: `Local key kept. Check the slot: perp${network === "testnet" ? " -n testnet" : ""} wallet agent verify ${venue} --agent-name ${meta.agentName}; once the slot shows a different key, re-run the revoke.`,
+        });
+    }
+    if (slotKey === null || norm(slotKey) !== norm(throwawayPublicKey) || (meta.publicKey !== undefined && norm(slotKey) === norm(meta.publicKey))) {
+        throw new PerpError("APPROVE_PARTIAL", `${venueName} revoke sent ChangePubKey for slot ${meta.apiKeyIndex}, but the slot does not show the replacement key yet (current: ${slotKey === null ? "none" : slotKey.slice(0, 20) + "…"})`, {
+            exchange: venue,
+            remediation: `Local key kept — the old agent key may still be authorized. Wait a few seconds and re-run: perp${network === "testnet" ? " -n testnet" : ""} wallet agent revoke ${venue} ${meta.agentName}`,
+        });
+    }
+    const { deleteLighterFamilyKey } = await import("../agent-wallet/lighter-keystore.js");
+    deleteLighterFamilyKey(venue, network, meta.accountIndex, meta.apiKeyIndex);
 }