perp-cli 0.12.17 → 0.14.0

package/dist/commands/settings.js

@@ -1,7 +1,76 @@
+import { unsupported } from "../exchanges/trading-v2.js";
 import chalk from "chalk";
 import { printJson, jsonOk, withJsonErrors } from "../utils.js";
-import { loadSettings, saveSettings } from "../settings.js";
+import { loadSettings, saveSettings, SHIPPED_DEFAULT_SLIPPAGE_BPS } from "../settings.js";
 import { ENV_FILE, loadEnvFile, setEnvVar, EXCHANGE_ENV_MAP, validateKey } from "./init.js";
+import { getVenue, resolveVenueId } from "../exchanges/venue.js";
+import "../exchanges/venues/index.js";
+import { maxDefaultSlippageBps, parseSlippageSettingBps } from "../exchanges/slippage.js";
+import { PerpError } from "../errors.js";
+import { isSecretEnvName } from "../secret-env.js";
+import { BUILDER_FEE_CAPABILITIES, parseBuilderEntry, requireBuilderCapability } from "../exchanges/builder-fee.js";
+import { validateDebridgeAffiliate, validateWithdrawGate, WITHDRAW_GATE_VENUES } from "../settings.js";
+import { confirmWithdrawGateChange } from "../withdraw-gate.js";
+const invalidParam = (problem) => new PerpError("INVALID_PARAMS", problem, {
+    remediation: "perp settings set builder.<venue> <address|code>,<feeBps> (e.g. builder.hyperliquid 0xabc…,1)",
+});
+/** `builder.<venue>` value "<address|code>,<feeBps>" → validated settings entry. */
+function builderEntryOf(key, value) {
+    const venue = getVenue(key.slice("builder.".length)).id;
+    const cap = requireBuilderCapability(venue);
+    if (cap.feeKind === "share") {
+        // Fee share (QFEX): the code only — there is no user-paid fee to configure.
+        const entry = { code: value.trim() };
+        parseBuilderEntry(venue, entry, problem => new PerpError("INVALID_PARAMS", problem, {
+            remediation: `perp settings set builder.${venue} <uuid> (the builder code only — ${venue} builder codes share the venue fee; no feeBps)`,
+        }));
+        return { venue, entry };
+    }
+    const parts = value.split(",");
+    if (parts.length !== 2)
+        throw invalidParam(`${key} value must be "<${cap.identity}>,<feeBps>" (got "${value}")`);
+    const fee = Number(parts[1].trim());
+    const entry = { [cap.identity]: parts[0].trim(), feeBps: parts[1].trim() === "" ? NaN : fee };
+    parseBuilderEntry(venue, entry, invalidParam); // strict: identity format, fee > 0, ≤ venue cap, venue increment
+    return { venue, entry };
+}
+/**
+ * L5: a builder.<venue> value charges the USER on every perp order, so setting one needs an
+ * explicit y/N (or --yes) that shows the fee. Non-interactive / --json without --yes is refused.
+ */
+async function confirmBuilderSetting(venue, entry, yes, json) {
+    if (yes)
+        return;
+    const cap = requireBuilderCapability(getVenue(venue).id);
+    const fee = `${cap.feeKind === "max" ? "up to " : ""}${String(entry.feeBps)} bps`;
+    const share = cap.feeKind === "share";
+    const what = share
+        ? `builder.${venue} = ${String(entry.code)}: your ${venue} fills are attributed to ${String(entry.code)}; you pay the normal fee (the venue shares part of it with the builder — no extra charge; attached to the trading connection from the next order)`
+        : `builder.${venue} = ${String(entry[cap.identity])} charges ${fee} on YOUR ${venue} perp orders (paid by you, to the builder${cap.approval === "none" ? "; no venue approval step — attached from the next order" : ""})`;
+    if (json || process.stdin.isTTY !== true) {
+        throw new PerpError("INVALID_PARAMS", `Setting a builder ${share ? "code" : "fee"} needs explicit confirmation: ${what}`, {
+            remediation: `Re-run with --yes to confirm: perp settings set builder.${venue} ${share ? "<uuid>" : `<${cap.identity}>,<feeBps>`} --yes`,
+        });
+    }
+    const { createInterface } = await import("node:readline/promises");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const a = (await rl.question(`  ${what}. Save? [y/N]: `)).trim().toLowerCase();
+        if (a !== "y" && a !== "yes")
+            throw new PerpError("INVALID_PARAMS", `builder.${venue} not set — cancelled, nothing was saved`);
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Parse `slippageBps.<venue>` → venue id (aliases accepted). Throws UNKNOWN_VENUE. */
+function slippageVenueOf(key) {
+    const venue = getVenue(key.slice("slippageBps.".length));
+    if (venue.capabilities === null) {
+        throw unsupported(venue.displayName, "trading", "no trading API, so slippageBps does not apply", "Set slippageBps only for trading venues");
+    }
+    return venue.id;
+}
 // Resolve exchange alias → env var key
 function resolveEnvKey(nameOrKey) {
     // Direct env var name
@@ -30,15 +99,36 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
         .action(async () => {
         await withJsonErrors(isJson(), async () => {
             const s = loadSettings();
+            const defaultSlippageShipped = s.defaultSlippageBps === SHIPPED_DEFAULT_SLIPPAGE_BPS;
             if (isJson())
-                return printJson(jsonOk(s));
+                return printJson(jsonOk({ ...s, defaultSlippageBpsSource: defaultSlippageShipped ? "shipped default" : "user" }));
             console.log(chalk.cyan.bold("\n  CLI Settings\n"));
             console.log(`  Default Exchange: ${s.defaultExchange ? chalk.cyan(s.defaultExchange) : chalk.gray("pacifica (built-in)")}`);
-            console.log(`  Referrals:        ${chalk.green("MANDATORY (always on)")}`);
-            console.log(chalk.white.bold("\n  Referral Codes:"));
-            console.log(`    Pacifica:      ${s.referralCodes.pacifica || chalk.gray("(none)")}`);
+            console.log(chalk.white.bold("\n  Referral Codes (bound only by an explicit `wallet manage referral set`):"));
             console.log(`    Hyperliquid:   ${s.referralCodes.hyperliquid || chalk.gray("(none)")}`);
             console.log(`    Lighter:       ${s.referralCodes.lighter || chalk.gray("(none)")}`);
+            console.log(chalk.white.bold("\n  Builder fees (off unless set; attached only after venue approval):"));
+            const builderEntries = Object.entries(s.builder);
+            if (builderEntries.length === 0)
+                console.log(chalk.gray("    (none — no builder fee is attached on any venue)"));
+            for (const [v, e] of builderEntries) {
+                const id = "address" in e ? e.address : e.code;
+                const fee = "feeBps" in e ? `${e.feeBps} bps` : "fee share (you pay the normal fee)";
+                console.log(`    ${v.padEnd(14)} ${id}  ${fee}${BUILDER_FEE_CAPABILITIES[v]?.feeKind === "max" ? " (max)" : ""}`);
+            }
+            console.log(chalk.white.bold("\n  Withdraw gate (qfex: API-key withdrawals; hyperliquid: withdraw / transfer to a non-owner address; off unless set):"));
+            const gates = Object.entries(s.withdraw);
+            if (gates.length === 0)
+                console.log(chalk.gray(`    (none — gated withdrawals on ${WITHDRAW_GATE_VENUES.join(", ")} are refused; Hyperliquid to the owner's own address is always allowed)`));
+            for (const [v, g] of gates)
+                console.log(`    ${v.padEnd(14)} max ${g.maxPerTx}/tx, ${g.maxPerDay}/day → ${g.allowlist.join(", ")}`);
+            const aff = s.bridge.debridgeAffiliate;
+            console.log(`  deBridge affiliate: ${aff === null ? chalk.gray("(none)") : `referral ${aff.referralCode ?? "-"} · fee ${aff.feePercent === null ? "none" : `${aff.feePercent}% → ${aff.feeRecipient}`}`}`);
+            console.log(chalk.white.bold("\n  Slippage bound (bps) — market / close / trigger orders:"));
+            console.log(`    ${"default".padEnd(14)} ${s.defaultSlippageBps}${defaultSlippageShipped ? chalk.gray(" (shipped default)") : ""}`);
+            for (const [v, bps] of Object.entries(s.slippageBps))
+                console.log(`    ${v.padEnd(14)} ${bps}`);
+            console.log(chalk.gray("    precedence: --slippage-bps → slippageBps.<venue> → default"));
             console.log(chalk.white.bold("\n  Fee Tiers:"));
             for (const [ex, fee] of Object.entries(s.fees)) {
                 const tPct = (fee.taker * 100).toFixed(4);
@@ -48,10 +138,9 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
             console.log(chalk.gray(`\n  Config: ~/.perp/settings.json\n`));
         });
     });
-    // Note: `settings referrals on/off` removed in v0.12 — referral codes are
-    // now mandatory (SSOT-aligned with Pacifica's always-on builder code).
-    // To reset applied flags (force re-send on next connection):
-    //   perp settings set referralApplied.hyperliquid false   (and same for lighter)
+    // HL / Lighter referral codes are applied only by the explicit
+    // `perp -e <hyperliquid|lighter> wallet manage referral set [code]` (never on
+    // adapter creation). referralCodes.<venue> is that command's default code.
     // ── settings fees ──
     // Bare `settings fees` shows current tiers (same as `settings fees show`).
     const showFees = async () => {
@@ -79,16 +168,18 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
         .action(showFees);
     fees
         .command("sync")
-        .description("Fetch fee tiers from exchange APIs and save")
-        .option("--exchange <name>", "Sync only a specific exchange")
-        .action(async (opts) => {
+        .description("Fetch fee tiers from exchange APIs and save (-e <exchange> to sync only one)")
+        .action(async () => {
         await withJsonErrors(isJson(), async () => {
+            // -e/--exchange is the root option: read it there only when it was passed on the command
+            // line (never the root's default venue — no flag means "all").
+            const only = program.getOptionValueSource("exchange") === "cli" ? String(program.opts().exchange) : undefined;
             if (!getAdapterForExchange) {
                 console.error(chalk.red("  Fee sync requires exchange adapters. Set up keys first with `perp setup`."));
                 return;
             }
             const s = loadSettings();
-            const exchanges = opts.exchange ? [opts.exchange.toLowerCase()] : ["hyperliquid", "pacifica", "lighter"];
+            const exchanges = only !== undefined ? [only.toLowerCase()] : ["hyperliquid", "pacifica", "lighter"];
             const results = {};
             for (const ex of exchanges) {
                 try {
@@ -186,16 +277,55 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
         .description("Set a specific setting")
         .argument("<key>", "Setting key (e.g. referralCodes.hyperliquid)")
         .argument("<value>", "Setting value")
-        .action(async (key, value) => {
+        .option("--yes", "Confirm a builder.<venue> fee without the y/N prompt")
+        .action(async (key, value, opts) => {
         await withJsonErrors(isJson(), async () => {
             const s = loadSettings();
             if (key === "default-exchange" || key === "defaultExchange") {
-                const valid = ["pacifica", "hyperliquid", "lighter"];
-                if (!valid.includes(value.toLowerCase())) {
-                    console.error(chalk.red(`  Invalid exchange: ${value}. Use: ${valid.join(", ")}`));
-                    return;
+                s.defaultExchange = resolveVenueId(value);
+            }
+            else if (key === "defaultSlippageBps") {
+                s.defaultSlippageBps = parseSlippageSettingBps(key, value, maxDefaultSlippageBps());
+            }
+            else if (key.startsWith("slippageBps.")) {
+                const venue = slippageVenueOf(key);
+                s.slippageBps[venue] = parseSlippageSettingBps(key, value, getVenue(venue).maxSlippageBps);
+            }
+            else if (key.startsWith("builder.")) {
+                const { venue, entry } = builderEntryOf(key, value);
+                await confirmBuilderSetting(venue, entry, opts.yes === true, isJson());
+                s.builder[venue] = entry;
+            }
+            else if (key.startsWith("withdraw.")) {
+                // settings.withdraw.<venue> = "<address[+address…]>,<maxPerTx>,<maxPerDay>". Changing the
+                // allowlist / limits needs an interactive terminal confirmation — no --yes, never --json.
+                const venue = getVenue(key.slice("withdraw.".length)).id;
+                const parts = value.split(",");
+                if (parts.length !== 3) {
+                    throw new PerpError("INVALID_PARAMS", `${key} value must be "<address[+address…]>,<maxPerTx>,<maxPerDay>" (got "${value}")`, {
+                        remediation: `e.g. perp settings set withdraw.${venue} 0xYourWallet,100,500`,
+                    });
                 }
-                s.defaultExchange = value.toLowerCase();
+                const num = (raw) => (raw.trim() === "" ? NaN : Number(raw.trim()));
+                const gate = validateWithdrawGate(venue, {
+                    allowlist: parts[0].split("+").map(a => a.trim()).filter(a => a !== ""), maxPerTx: num(parts[1]), maxPerDay: num(parts[2]),
+                }, problem => new PerpError("INVALID_PARAMS", problem));
+                await confirmWithdrawGateChange(venue, gate, isJson());
+                s.withdraw[venue] = gate;
+            }
+            else if (key === "bridge.debridgeAffiliate.referralCode" || key === "bridge.debridgeAffiliate.fee") {
+                const cur = s.bridge.debridgeAffiliate ?? { referralCode: null, feePercent: null, feeRecipient: null };
+                let next;
+                if (key.endsWith(".referralCode")) {
+                    next = { ...cur, referralCode: value };
+                }
+                else {
+                    const parts = value.split(",");
+                    if (parts.length !== 2)
+                        throw invalidParam(`${key} value must be "<percent>,<recipient>" (got "${value}")`);
+                    next = { ...cur, feePercent: parts[0].trim() === "" ? NaN : Number(parts[0].trim()), feeRecipient: parts[1].trim() };
+                }
+                s.bridge.debridgeAffiliate = validateDebridgeAffiliate(next, invalidParam);
             }
             else if (key.startsWith("referralCodes.")) {
                 const exchange = key.split(".")[1];
@@ -208,7 +338,7 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
                 }
             }
             else if (key.startsWith("referralApplied.")) {
-                // Force re-apply: `set referralApplied.hyperliquid false`
+                // Bookkeeping only (set by `wallet manage referral set`).
                 const exchange = key.split(".")[1];
                 if (exchange in s.referralApplied) {
                     s.referralApplied[exchange] = value === "true" || value === "on";
@@ -220,13 +350,88 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
             }
             else {
                 console.error(chalk.red(`  Unknown key: ${key}`));
-                console.log(chalk.gray("  Valid keys: default-exchange, referralCodes.{pacifica,hyperliquid,lighter}, referralApplied.{hyperliquid,lighter}\n"));
+                console.log(chalk.gray("  Valid keys: default-exchange, referralCodes.{hyperliquid,lighter}, referralApplied.{hyperliquid,lighter}, defaultSlippageBps, slippageBps.<venue>, builder.<venue>, withdraw.<venue>, bridge.debridgeAffiliate.{referralCode,fee}\n"));
                 return;
             }
             saveSettings(s);
             if (isJson())
                 return printJson(jsonOk({ key, value }));
             console.log(chalk.green(`\n  ${key} = ${value}\n`));
+            if (key.startsWith("builder.")) {
+                const venue = getVenue(key.slice("builder.".length)).id;
+                const cap = requireBuilderCapability(venue);
+                if (cap.feeKind === "share") {
+                    console.log(chalk.yellow(`  Your ${venue} fills are attributed to this builder code; you pay the normal fee (no extra charge).`));
+                    console.log(chalk.gray(`  Attribution cannot be confirmed from the trader side. Disable per command with --no-builder; remove with: perp settings unset builder.${venue}\n`));
+                    return;
+                }
+                console.log(chalk.yellow(`  This adds a builder fee to YOUR ${venue} perp orders (paid by you, to the builder).`));
+                console.log(chalk.gray(cap.approval === "master"
+                    ? `  Nothing is attached until the venue approval is confirmed: perp wallet builder approve ${venue}\n  Disable per command with --no-builder; remove with: perp settings unset builder.${venue}\n`
+                    : `  ${venue} needs no approval — the fee is attached from the next order.\n  Disable per command with --no-builder; remove with: perp settings unset builder.${venue}\n`));
+            }
+        });
+    });
+    // ── settings unset ──
+    settings
+        .command("unset")
+        .description("Remove a setting (slippageBps.<venue>, builder.<venue>, withdraw.<venue>, bridge.debridgeAffiliate; defaultSlippageBps restores the shipped default)")
+        .argument("<key>", "Setting key (e.g. slippageBps.ondo)")
+        .action(async (key) => {
+        await withJsonErrors(isJson(), async () => {
+            if (key === "defaultSlippageBps") {
+                const s = loadSettings();
+                s.defaultSlippageBps = SHIPPED_DEFAULT_SLIPPAGE_BPS;
+                saveSettings(s);
+                if (isJson())
+                    return printJson(jsonOk({ key, value: SHIPPED_DEFAULT_SLIPPAGE_BPS, source: "shipped default" }));
+                console.log(chalk.green(`\n  defaultSlippageBps = ${SHIPPED_DEFAULT_SLIPPAGE_BPS} (shipped default)\n`));
+                return;
+            }
+            if (key.startsWith("builder.")) {
+                const venue = getVenue(key.slice("builder.".length)).id;
+                const s = loadSettings();
+                const existed = s.builder[venue] !== undefined;
+                delete s.builder[venue];
+                saveSettings(s);
+                if (isJson())
+                    return printJson(jsonOk({ key: `builder.${venue}`, removed: existed }));
+                console.log(existed ? chalk.green(`\n  builder.${venue} removed — no builder fee is attached on ${venue}\n`) : chalk.gray(`\n  builder.${venue} was not set\n`));
+                return;
+            }
+            if (key.startsWith("withdraw.")) {
+                // Removing the gate turns API-key withdrawals OFF for that venue — no confirmation needed.
+                const venue = getVenue(key.slice("withdraw.".length)).id;
+                const s = loadSettings();
+                const existed = s.withdraw[venue] !== undefined;
+                delete s.withdraw[venue];
+                saveSettings(s);
+                if (isJson())
+                    return printJson(jsonOk({ key: `withdraw.${venue}`, removed: existed }));
+                console.log(existed ? chalk.green(`\n  withdraw.${venue} removed — withdrawals on ${venue} are refused until it is set again\n`) : chalk.gray(`\n  withdraw.${venue} was not set\n`));
+                return;
+            }
+            if (key === "bridge.debridgeAffiliate") {
+                const s = loadSettings();
+                const existed = s.bridge.debridgeAffiliate !== null;
+                s.bridge.debridgeAffiliate = null;
+                saveSettings(s);
+                if (isJson())
+                    return printJson(jsonOk({ key, removed: existed }));
+                console.log(existed ? chalk.green(`\n  ${key} removed\n`) : chalk.gray(`\n  ${key} was not set\n`));
+                return;
+            }
+            if (!key.startsWith("slippageBps.")) {
+                throw new PerpError("INVALID_PARAMS", `Cannot unset "${key}"`, { remediation: "Unsettable keys: defaultSlippageBps, slippageBps.<venue>, builder.<venue>, withdraw.<venue>, bridge.debridgeAffiliate" });
+            }
+            const venue = slippageVenueOf(key);
+            const s = loadSettings();
+            const existed = s.slippageBps[venue] !== undefined;
+            delete s.slippageBps[venue];
+            saveSettings(s);
+            if (isJson())
+                return printJson(jsonOk({ key: `slippageBps.${venue}`, removed: existed }));
+            console.log(existed ? chalk.green(`\n  slippageBps.${venue} removed\n`) : chalk.gray(`\n  slippageBps.${venue} was not set\n`));
         });
     });
     // ── settings env ──
@@ -261,7 +466,7 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
         console.log(chalk.cyan.bold("\n  perp-cli Configuration\n"));
         console.log(`  File: ${chalk.gray(ENV_FILE)}\n`);
         if (results.length === 0) {
-            console.log(chalk.gray("  No keys configured. Run 'perp setup' or 'perp settings env set <exchange> <key>'\n"));
+            console.log(chalk.gray("  No legacy keys in ~/.perp/.env. Import keys into the OWS vault: 'perp wallet set <exchange>'\n"));
             return;
         }
         for (const { name, address, source } of results) {
@@ -269,41 +474,29 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
         }
         console.log();
     });
-    // ── settings env set <exchange|key> <value> ──
+    // ── settings env set <name> <value> ──
+    // Non-secret values only (e.g. LIGHTER_REFERRAL_CODE). SSOT Rule #3: key material is never
+    // written to ~/.perp/.env nor accepted on argv — exchange keys go to the OWS vault.
     env
         .command("set <name> <value>")
-        .description("Set a key (exchange name or env var name)")
+        .description("Set a non-secret env value in ~/.perp/.env (private keys are refused: use 'perp wallet set <exchange>')")
         .action(async (name, value) => {
-        const resolved = resolveEnvKey(name);
-        if (resolved) {
-            // Validate the key
-            const { valid, address } = await validateKey(resolved.chain, value);
-            if (!valid) {
-                if (isJson()) {
-                    const { jsonError } = await import("../utils.js");
-                    return printJson(jsonError("INVALID_PARAMS", `Invalid ${resolved.chain} private key`));
-                }
-                console.error(chalk.red(`\n  Invalid ${resolved.chain} private key.\n`));
-                process.exit(1);
+        await withJsonErrors(isJson(), async () => {
+            const resolved = resolveEnvKey(name);
+            if (resolved !== null || isSecretEnvName(name)) {
+                throw new PerpError("INVALID_PARAMS", `Refusing to write ${resolved?.envKey ?? name} to ~/.perp/.env: key material is never stored in plaintext or accepted on the command line`, {
+                    remediation: resolved !== null
+                        ? "Import the key into the OWS vault: perp wallet set <exchange> (hidden prompt or stdin). Clear the key from your shell history."
+                        : "Secrets live in the OWS vault (perp wallet set / perp wallet import) or agent keystores (perp wallet agent approve <venue>). Clear the value from your shell history.",
+                });
             }
-            const normalized = resolved.chain === "evm"
-                ? (value.startsWith("0x") ? value : `0x${value}`)
-                : value;
-            setEnvVar(resolved.envKey, normalized);
-            if (isJson())
-                return printJson(jsonOk({ key: resolved.envKey, address, file: ENV_FILE }));
-            console.log(chalk.green(`\n  ${resolved.envKey} set.`));
-            console.log(`  Address: ${chalk.gray(address)}`);
-            console.log(`  File:    ${chalk.gray("~/.perp/.env")}\n`);
-        }
-        else {
-            // Raw env var (e.g. LIGHTER_REFERRAL_CODE, custom vars)
+            // Raw non-secret env var (e.g. LIGHTER_REFERRAL_CODE, custom vars)
             setEnvVar(name, value);
             if (isJson())
                 return printJson(jsonOk({ key: name, file: ENV_FILE }));
             console.log(chalk.green(`\n  ${name} set.`));
             console.log(`  File: ${chalk.gray("~/.perp/.env")}\n`);
-        }
+        });
     });
     // ── settings env remove <name> ──
     env
@@ -323,12 +516,14 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
         }
         delete env[envKey];
         // Rewrite file
-        const { writeFileSync } = await import("fs");
+        // Atomic write with an explicit 0600 (writeFileSync's mode only applies when creating the file:
+        // a rewrite would keep looser permissions of an existing .env).
+        const { writeKeystoreAtomic } = await import("../agent-wallet/venue-keystore.js");
         const lines = ["# perp-cli configuration", "# Generated by 'perp setup' — edit freely", ""];
         for (const [k, v] of Object.entries(env))
             lines.push(`${k}=${v}`);
         lines.push("");
-        writeFileSync(ENV_FILE, lines.join("\n"), { mode: 0o600 });
+        writeKeystoreAtomic(ENV_FILE, lines.join("\n"));
         if (isJson())
             return printJson(jsonOk({ removed: envKey }));
         console.log(chalk.yellow(`\n  ${envKey} removed from ~/.perp/.env\n`));
@@ -351,7 +546,7 @@ export function registerSettingsCommands(program, isJson, getAdapterForExchange)
         console.log(chalk.yellow("\n  'perp env' is deprecated. Use 'perp settings env' instead.\n"));
         console.log(chalk.gray("  Examples:"));
         console.log(chalk.gray("    perp settings env show"));
-        console.log(chalk.gray("    perp settings env set <exchange> <key>"));
+        console.log(chalk.gray("    perp settings env set <name> <value>   (non-secret values only)"));
         console.log(chalk.gray("    perp settings env remove <name>"));
         console.log(chalk.gray("    perp settings env path\n"));
     });

package/dist/commands/trade.d.ts

@@ -1,3 +1,53 @@
 import { Command } from "commander";
 import type { ExchangeAdapter } from "../exchanges/index.js";
+import { PerpError } from "../errors.js";
+import "../exchanges/venues/index.js";
+import { type CancelResult } from "../exchanges/venue-types.js";
+/**
+ * A cancel with anything not proven cancelled (failed, or pending / still listed open after the
+ * verifying re-list) → ORDER_PARTIAL carrying the whole result (non-zero exit, also in --json);
+ * all failed (none cancelled, none pending) → ORDER_REJECTED (definitely nothing cancelled).
+ */
+export declare function cancelIncompleteError(r: CancelResult, scope: string): PerpError | null;
+/**
+ * Sizes of scaled levels on the venue lot grid: the total is floored to `step`, each level is
+ * floor(total × pct / 100) lots and the LAST level takes the remainder — so every level is a
+ * multiple of the lot and the levels sum to the floored total. An off-lot level is refused by the
+ * venue (Pacifica 422 "Limit order amount 0.00205 is not a multiple of lot size"; Lighter 21706
+ * "invalid order base or quote amount" for 0.01475 TSLA at 4 size decimals). A level of zero lots
+ * → SIZE_TOO_SMALL.
+ */
+export declare function scaleLevelSizes(total: string, pcts: readonly number[], step: string): string[];
+/**
+ * Refuse (SIZE_TOO_SMALL, nothing sent) a scaled order with a level under the venue's published
+ * minimum order size / notional (VenueMarket.minSize / minNotional; null = none published on this
+ * data path → not checked). Reduce-only levels are held to it too: no venue's docs state an
+ * exemption (Pacifica market-info: `min_order_size` "Minimum order size (denominated in USD)",
+ * no exception listed).
+ */
+export declare function requireScaleLevelMinimums(venue: string, symbol: string, levels: ReadonlyArray<{
+    price: string;
+    size: string;
+}>, min: {
+    minSize: string | null;
+    minNotional: string | null;
+}): void;
+/** Outcome of one scaled level: placed, definitely refused, unknown (may exist), or never sent. */
+export interface ScaleLevelOutcome {
+    price: string;
+    size: string;
+    pct: number;
+    outcome: "placed" | "rejected" | "unknown" | "notSent";
+    result: Record<string, unknown> | {
+        error: string;
+    };
+}
+/**
+ * The failure a scaled order reports unless every level was placed: any unknown outcome →
+ * ORDER_PENDING; every level definitely refused → ORDER_REJECTED; otherwise ORDER_PARTIAL.
+ * details list the placed / failed / unknown / not-sent levels.
+ */
+export declare function scaleIncompleteError(venue: string, what: string, levels: readonly ScaleLevelOutcome[]): PerpError | null;
+/** One-arg `trade cancel <x>`: true when x is an order id (numeric, UUID or 0x-hex), never a symbol. */
+export declare function looksLikeOrderId(x: string): boolean;
 export declare function registerTradeCommands(program: Command, getAdapter: () => Promise<ExchangeAdapter>, isJson: () => boolean, isDryRun?: () => boolean, getAdapterForExchange?: (exchange: string) => Promise<ExchangeAdapter>): void;