perp-cli 0.12.15 → 0.14.0

package/dist/trade-validator.d.ts

@@ -37,3 +37,25 @@ export interface TradeCheckParams {
  * Runs multiple checks in parallel where possible.
  */
 export declare function validateTrade(adapter: ExchangeAdapter, params: TradeCheckParams): Promise<TradeValidation>;
+/**
+ * Hard pre-trade risk gate for manual order commands.
+ *
+ * Unlike validateTrade (which is advisory — used by `trade check` and the MCP
+ * preview), this is meant to run immediately before submitting a real order.
+ * It throws RISK_VIOLATION when the order would breach the locally configured
+ * limits (maxPositionUsd / maxTotalExposureUsd / maxPositions, plus any active
+ * critical violation that suspends trading). reduce-only and --force orders are
+ * exempt, so position-reducing and intentional-override flows are never blocked.
+ *
+ * Leverage is only checked when the caller passes an explicit value; the bare
+ * buy/sell/market/limit commands carry no leverage argument, so the gate there
+ * enforces notional/exposure rather than per-order leverage.
+ */
+export declare function enforceOrderRisk(adapter: ExchangeAdapter, p: {
+    symbol: string;
+    size: number;
+    price?: number;
+    leverage?: number;
+    reduceOnly?: boolean;
+    force?: boolean;
+}): Promise<void>;

package/dist/trade-validator.js

@@ -1,7 +1,9 @@
+import { maxLeverageForNotional } from "./exchanges/interface.js";
 import { symbolMatch } from "./utils.js";
 import { DEFAULT_TAKER_FEE } from "./constants.js";
+import { PerpError } from "./errors.js";
+import { resolveAdapterSlippage } from "./exchanges/slippage.js";
 // Use centralized DEFAULT_TAKER_FEE from constants.ts (0.035%)
-const DEFAULT_MAX_SLIPPAGE = 0.005; // 0.5%
 /**
  * Validate a trade before execution.
  * Runs multiple checks in parallel where possible.
@@ -10,6 +12,8 @@ export async function validateTrade(adapter, params) {
     const checks = [];
     const warnings = [];
     const sym = params.symbol.toUpperCase();
+    // Liquidity threshold = the bound a market order on this venue would carry (design §13.10 #14).
+    const maxSlippage = resolveAdapterSlippage(adapter, null).bps / 10_000;
     // Fetch market list, balance, and positions in parallel.
     // Defer the orderbook call until symbol membership is confirmed so invalid
     // symbols return a structured symbol_valid failure instead of a venue error.
@@ -29,11 +33,8 @@ export async function validateTrade(adapter, params) {
         checks.push({ check: "symbol_valid", passed: false, message: `Failed to load markets from ${adapter.name}: ${marketsError}` });
         return { valid: false, checks, warnings, timestamp: new Date().toISOString() };
     }
-    // 1. Symbol validity (handle BTC vs BTC-PERP suffix variants)
-    const market = markets.find(m => {
-        const ms = m.symbol.toUpperCase();
-        return ms === sym || ms === `${sym}-PERP` || ms.replace(/-PERP$/, "") === sym;
-    });
+    // 1. Symbol validity (BTC vs BTC-PERP; a HIP-3 dex adapter lists "xyz:NVDA" for "NVDA")
+    const market = markets.find(m => symbolMatch(m.symbol, sym));
     if (market) {
         checks.push({ check: "symbol_valid", passed: true, message: `${sym} found on ${adapter.name}`, details: { maxLeverage: market.maxLeverage } });
     }
@@ -45,6 +46,13 @@ export async function validateTrade(adapter, params) {
         ? await adapter.getOrderbook(sym)
         : { bids: [], asks: [] };
     const markPrice = Number(market.markPrice);
+    // Rule #2: NaN slipped past the previous `markPrice <= 0` check because
+    // NaN comparisons are always false. Reject explicit non-finite values
+    // upfront so downstream NaN propagation (notional, marginRequired,
+    // slippage, deviation) is impossible.
+    if (Number.isNaN(markPrice) || markPrice === Infinity || markPrice === -Infinity) {
+        throw new PerpError("EXCHANGE_ERROR", `${adapter.name} returned non-finite markPrice for ${sym}: ${market.markPrice}`, { exchange: adapter.name });
+    }
     if (params.type === "limit" && (params.price === undefined || !Number.isFinite(params.price))) {
         throw new Error(`Limit order requires explicit price (received ${params.price}); refusing silent mark-price substitution.`);
     }
@@ -56,13 +64,25 @@ export async function validateTrade(adapter, params) {
     if (params.leverage !== undefined && (!Number.isFinite(params.leverage) || params.leverage <= 0)) {
         throw new Error(`Leverage must be a positive number (received ${params.leverage}).`);
     }
-    const leverage = params.leverage ?? market.maxLeverage;
+    // `market.maxLeverage` is the TOP tier. Venues that publish notional-tiered
+    // caps (Hyperliquid: 36 of 233 symbols, e.g. BTC 40x but 20x above $150M)
+    // reject an order sized past a threshold even though the flat value allows it,
+    // so resolve the cap AT THIS ORDER'S NOTIONAL.
+    const effectiveMax = maxLeverageForNotional(market, notional);
+    const leverage = params.leverage ?? effectiveMax;
     if (!Number.isFinite(leverage) || leverage <= 0) {
         throw new Error(`No usable leverage for ${sym} (resolved=${leverage}); supply params.leverage explicitly.`);
     }
     const marginRequired = notional / leverage;
     // 2. Balance check
     const available = Number(balance.available);
+    // Rule #2: a NaN `available` would silently take the "insufficient
+    // balance" branch on the negative comparison and *also* render
+    // misleading "$NaN available" in the user-visible message. Throw
+    // instead so the trade flow surfaces a real venue/parsing failure.
+    if (!Number.isFinite(available)) {
+        throw new PerpError("EXCHANGE_ERROR", `${adapter.name} returned non-finite balance.available: ${balance.available}`, { exchange: adapter.name });
+    }
     if (params.reduceOnly) {
         // reduce-only doesn't need margin
         checks.push({ check: "balance_sufficient", passed: true, message: "Reduce-only order, no margin needed" });
@@ -96,15 +116,25 @@ export async function validateTrade(adapter, params) {
         let availableLiquidity = 0;
         let worstPrice = 0;
         for (const [px, sz] of book) {
-            availableLiquidity += Number(px) * Number(sz);
-            worstPrice = Number(px);
+            const pxN = Number(px);
+            const szN = Number(sz);
+            // Rule #2: a NaN level would silently inflate `availableLiquidity`
+            // to NaN, the `>= notional` comparison would be false, and the
+            // outer branch would emit a "Insufficient liquidity: $NaN" message.
+            // Reject the level explicitly so a malformed orderbook can't
+            // fabricate a passing or failing liquidity check.
+            if (!Number.isFinite(pxN) || !Number.isFinite(szN) || pxN <= 0 || szN < 0) {
+                throw new PerpError("EXCHANGE_ERROR", `${adapter.name} orderbook level has non-finite or non-positive value for ${sym}: px=${px} sz=${sz}`, { exchange: adapter.name });
+            }
+            availableLiquidity += pxN * szN;
+            worstPrice = pxN;
             if (availableLiquidity >= notional)
                 break;
         }
         if (availableLiquidity >= notional) {
             const slippage = markPrice > 0 ? Math.abs(worstPrice - markPrice) / markPrice : 0;
-            if (slippage > DEFAULT_MAX_SLIPPAGE) {
-                checks.push({ check: "liquidity_ok", passed: false, message: `Slippage ${(slippage * 100).toFixed(2)}% exceeds ${(DEFAULT_MAX_SLIPPAGE * 100).toFixed(1)}% threshold`, details: { slippagePct: slippage * 100, worstPrice, liquidityUsd: availableLiquidity } });
+            if (slippage > maxSlippage) {
+                checks.push({ check: "liquidity_ok", passed: false, message: `Slippage ${(slippage * 100).toFixed(2)}% exceeds the ${(maxSlippage * 100).toFixed(2)}% market-order slippage bound`, details: { slippagePct: slippage * 100, worstPrice, liquidityUsd: availableLiquidity } });
             }
             else {
                 checks.push({ check: "liquidity_ok", passed: true, message: `Sufficient liquidity ($${availableLiquidity.toFixed(0)}), slippage ~${(slippage * 100).toFixed(3)}%`, details: { slippagePct: slippage * 100, liquidityUsd: availableLiquidity } });
@@ -121,7 +151,11 @@ export async function validateTrade(adapter, params) {
     try {
         const { assessRisk, preTradeCheck } = await import("./risk.js");
         const assessment = assessRisk([{ exchange: adapter.name, balance }], positions.map(p => ({ exchange: adapter.name, position: p })));
-        const riskResult = preTradeCheck(assessment, notional, leverage);
+        // The leverage limit is checked only for a leverage the caller STATED (--leverage), exactly
+        // like enforceOrderRisk. Without one, `leverage` above is the market MAXIMUM (used for the
+        // margin estimate only) — not what the account trades at: checking it failed every order on
+        // a 50x market against a 20x limit while the account was set to 5x.
+        const riskResult = preTradeCheck(assessment, notional, params.leverage ?? 0);
         if (riskResult.allowed) {
             checks.push({ check: "risk_limits", passed: true, message: "Within risk limits" });
         }
@@ -143,6 +177,11 @@ export async function validateTrade(adapter, params) {
         const pos = positions.find(p => symbolMatch(p.symbol, sym));
         if (pos) {
             const posSize = parseFloat(pos.size);
+            // Rule #2: NaN posSize would make `params.size > posSize` always
+            // false, silently passing the reduce-only size check.
+            if (!Number.isFinite(posSize)) {
+                throw new PerpError("EXCHANGE_ERROR", `${adapter.name} returned non-finite position size for ${sym}: ${pos.size}`, { exchange: adapter.name });
+            }
             if (params.size > posSize) {
                 checks.push({ check: "position_exists", passed: false, message: `Reduce size ${params.size} exceeds position ${posSize}`, details: { positionSize: posSize, reduceSize: params.size } });
             }
@@ -158,8 +197,13 @@ export async function validateTrade(adapter, params) {
     const fee = notional * DEFAULT_TAKER_FEE;
     const estimatedSlippage = params.type === "limit" ? 0 : notional * 0.001;
     const valid = checks.every(c => c.passed);
-    if (leverage > market.maxLeverage) {
-        warnings.push(`Requested leverage ${leverage}x exceeds max ${market.maxLeverage}x`);
+    if (leverage > effectiveMax) {
+        // Compare against the tier that applies at this notional, not the headline
+        // cap — otherwise the check is tautological whenever leverage defaulted FROM
+        // maxLeverage, and it never fires for the tiered case it exists to catch.
+        warnings.push(effectiveMax < market.maxLeverage
+            ? `Requested leverage ${leverage}x exceeds ${effectiveMax}x, the cap for this $${notional.toFixed(0)} notional (headline max ${market.maxLeverage}x applies below the tier threshold)`
+            : `Requested leverage ${leverage}x exceeds max ${market.maxLeverage}x`);
     }
     return {
         valid,
@@ -174,9 +218,69 @@ export async function validateTrade(adapter, params) {
         marketInfo: {
             symbol: sym,
             markPrice,
-            fundingRate: Number(market.fundingRate),
+            // Rule #2: NaN funding rate must not propagate to envelope output;
+            // surface the missing-data state via warnings rather than emitting
+            // `fundingRate: NaN` to agents that JSON.parse the response.
+            fundingRate: (() => {
+                const fr = Number(market.fundingRate);
+                if (!Number.isFinite(fr)) {
+                    warnings.push(`Funding rate unavailable for ${sym} on ${adapter.name} (received ${market.fundingRate})`);
+                    return 0;
+                }
+                return fr;
+            })(),
             maxLeverage: market.maxLeverage,
         },
         timestamp: new Date().toISOString(),
     };
 }
+/**
+ * Hard pre-trade risk gate for manual order commands.
+ *
+ * Unlike validateTrade (which is advisory — used by `trade check` and the MCP
+ * preview), this is meant to run immediately before submitting a real order.
+ * It throws RISK_VIOLATION when the order would breach the locally configured
+ * limits (maxPositionUsd / maxTotalExposureUsd / maxPositions, plus any active
+ * critical violation that suspends trading). reduce-only and --force orders are
+ * exempt, so position-reducing and intentional-override flows are never blocked.
+ *
+ * Leverage is only checked when the caller passes an explicit value; the bare
+ * buy/sell/market/limit commands carry no leverage argument, so the gate there
+ * enforces notional/exposure rather than per-order leverage.
+ */
+export async function enforceOrderRisk(adapter, p) {
+    if (p.reduceOnly || p.force)
+        return;
+    const { loadRiskLimits, assessRisk, preTradeCheck } = await import("./risk.js");
+    const limits = loadRiskLimits();
+    // Resolve notional: limit orders carry a price; market orders need markPrice.
+    let price = p.price;
+    if (price == null || !Number.isFinite(price)) {
+        const markets = await adapter.getMarkets();
+        const m = markets.find((mk) => symbolMatch(mk.symbol, p.symbol));
+        if (!m) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `${p.symbol} not found on ${adapter.name}`, { exchange: adapter.name });
+        }
+        price = Number(m.markPrice);
+    }
+    // SSOT rule #2: if the notional cannot be computed we cannot enforce the
+    // limit — fail closed (the caller may pass --force) rather than wave it
+    // through with a silent zero notional that bypasses the position cap.
+    if (!Number.isFinite(price) || price <= 0) {
+        throw new PerpError("PRICE_STALE", `Cannot resolve a mark price for ${p.symbol} on ${adapter.name} to check risk limits`, {
+            exchange: adapter.name,
+            remediation: "Retry, or pass --force to skip the local risk check.",
+        });
+    }
+    const notional = Math.abs(p.size * price);
+    const [balance, positions] = await Promise.all([adapter.getBalance(), adapter.getPositions()]);
+    const assessment = assessRisk([{ exchange: adapter.name, balance }], positions.map((pos) => ({ exchange: adapter.name, position: pos })), limits);
+    const check = preTradeCheck(assessment, notional, p.leverage ?? 0);
+    if (!check.allowed) {
+        throw new PerpError("RISK_VIOLATION", check.reason ?? "Order blocked by local risk limits", {
+            exchange: adapter.name,
+            remediation: "Adjust limits with `perp risk set ...`, reduce the order size, or pass --force to override.",
+            details: { symbol: p.symbol, notional },
+        });
+    }
+}

package/dist/utils/numeric.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Coerce a venue payload value to a finite number — or throw.
+ *
+ * Shared across all 4 exchange adapters (Lighter / Hyperliquid / Aster /
+ * Pacifica) to enforce Rule #2 ("no fallback") on venue-returned strings
+ * and numbers. Previously each adapter inlined `Number(x ?? 0)` which
+ * silently coerced NaN / Infinity / non-numeric strings to 0, masking
+ * stale-cache / partial-response corruption as legitimate "$0 balance".
+ *
+ * Rules:
+ *  - `undefined` / `null` → returns `defaultValue` (default 0). Venues
+ *    legitimately omit a field for an empty account or zero position;
+ *    that is "no data, treat as zero", not a parsing failure.
+ *  - empty string `""` → throws. Strict policy (qa/2026-05-16): an
+ *    empty string is indistinguishable from a stale-cache partial
+ *    response, so `Number("") === 0` would land back in the same
+ *    silent-substitution hole. A truly absent field must surface as
+ *    `undefined`/`null` at the adapter layer, not `""`.
+ *  - finite number / parseable numeric string → returned as-is.
+ *  - NaN / ±Infinity / non-numeric string → throws `EXCHANGE_ERROR`
+ *    tagged with `exchange` so triage can attribute the failure to the
+ *    exact venue endpoint.
+ *
+ * @param value Raw payload value (untyped — venues lie about SDK types).
+ * @param fieldName Field path for the error message (e.g.
+ *   `"available_balance"`, `"position.unrealized_pnl"`).
+ * @param exchange Exchange tag for the PerpError details payload
+ *   (`hyperliquid` / `pacifica` / `aster` / `lighter`).
+ * @param opts.defaultValue Value returned for null/undefined. Default `0`.
+ */
+export declare function parseFiniteVenueNumber(value: unknown, fieldName: string, exchange: string, opts?: {
+    defaultValue?: number;
+}): number;
+/**
+ * A rate the venue sends as a JSON NUMBER, as a plain decimal string without float noise:
+ * rounded to 15 significant digits (a double's exact precision) and written without exponent.
+ * Lighter /funding-rates sends e.g. `"rate":0.00009599999999999999` → "0.000096";
+ * -0.000047999999999999994 → "-0.000048"; 1.2e-7 → "0.00000012". A rate the venue sends as a
+ * STRING is passed through verbatim by callers, never through this. Non-finite → EXCHANGE_ERROR.
+ */
+export declare function venueRateString(value: number, what?: string): string;
+/**
+ * A required venue rate field as a decimal string: a JSON number → venueRateString (no float
+ * noise); a numeric string → verbatim. Missing / non-numeric → EXCHANGE_ERROR (never "0").
+ */
+export declare function venueRateField(value: unknown, fieldName: string, exchange: string): string;

package/dist/utils/numeric.js

@@ -0,0 +1,79 @@
+import { PerpError } from "../errors.js";
+/**
+ * Coerce a venue payload value to a finite number — or throw.
+ *
+ * Shared across all 4 exchange adapters (Lighter / Hyperliquid / Aster /
+ * Pacifica) to enforce Rule #2 ("no fallback") on venue-returned strings
+ * and numbers. Previously each adapter inlined `Number(x ?? 0)` which
+ * silently coerced NaN / Infinity / non-numeric strings to 0, masking
+ * stale-cache / partial-response corruption as legitimate "$0 balance".
+ *
+ * Rules:
+ *  - `undefined` / `null` → returns `defaultValue` (default 0). Venues
+ *    legitimately omit a field for an empty account or zero position;
+ *    that is "no data, treat as zero", not a parsing failure.
+ *  - empty string `""` → throws. Strict policy (qa/2026-05-16): an
+ *    empty string is indistinguishable from a stale-cache partial
+ *    response, so `Number("") === 0` would land back in the same
+ *    silent-substitution hole. A truly absent field must surface as
+ *    `undefined`/`null` at the adapter layer, not `""`.
+ *  - finite number / parseable numeric string → returned as-is.
+ *  - NaN / ±Infinity / non-numeric string → throws `EXCHANGE_ERROR`
+ *    tagged with `exchange` so triage can attribute the failure to the
+ *    exact venue endpoint.
+ *
+ * @param value Raw payload value (untyped — venues lie about SDK types).
+ * @param fieldName Field path for the error message (e.g.
+ *   `"available_balance"`, `"position.unrealized_pnl"`).
+ * @param exchange Exchange tag for the PerpError details payload
+ *   (`hyperliquid` / `pacifica` / `aster` / `lighter`).
+ * @param opts.defaultValue Value returned for null/undefined. Default `0`.
+ */
+export function parseFiniteVenueNumber(value, fieldName, exchange, opts = {}) {
+    const defaultValue = opts.defaultValue ?? 0;
+    if (value === undefined || value === null)
+        return defaultValue;
+    if (value === "") {
+        throw new PerpError("EXCHANGE_ERROR", `${exchange} response field \`${fieldName}\` is an empty string (use null for missing data)`, { exchange });
+    }
+    const n = typeof value === "number" ? value : Number(value);
+    if (!Number.isFinite(n)) {
+        throw new PerpError("EXCHANGE_ERROR", `${exchange} response field \`${fieldName}\` is not a finite number: ${JSON.stringify(value)}`, { exchange });
+    }
+    return n;
+}
+/** Significant digits kept when a venue rate arrives as a JSON number (IEEE-754 double: 15 are exact). */
+const RATE_SIG_DIGITS = 15;
+/**
+ * A rate the venue sends as a JSON NUMBER, as a plain decimal string without float noise:
+ * rounded to 15 significant digits (a double's exact precision) and written without exponent.
+ * Lighter /funding-rates sends e.g. `"rate":0.00009599999999999999` → "0.000096";
+ * -0.000047999999999999994 → "-0.000048"; 1.2e-7 → "0.00000012". A rate the venue sends as a
+ * STRING is passed through verbatim by callers, never through this. Non-finite → EXCHANGE_ERROR.
+ */
+export function venueRateString(value, what = "rate") {
+    if (!Number.isFinite(value))
+        throw new PerpError("EXCHANGE_ERROR", `${what} is not a finite number (${value})`);
+    if (value === 0)
+        return "0";
+    const [mant, expS] = value.toExponential(RATE_SIG_DIGITS - 1).split("e");
+    const digits = mant.replace("-", "").replace(".", "").replace(/0+$/, "");
+    const point = Number(expS) + 1; // value = 0.<digits> × 10^point
+    const sign = value < 0 ? "-" : "";
+    if (point <= 0)
+        return `${sign}0.${"0".repeat(-point)}${digits}`;
+    if (point >= digits.length)
+        return `${sign}${digits}${"0".repeat(point - digits.length)}`;
+    return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+/**
+ * A required venue rate field as a decimal string: a JSON number → venueRateString (no float
+ * noise); a numeric string → verbatim. Missing / non-numeric → EXCHANGE_ERROR (never "0").
+ */
+export function venueRateField(value, fieldName, exchange) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return venueRateString(value, `${exchange} ${fieldName}`);
+    if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value)))
+        return value;
+    throw new PerpError("EXCHANGE_ERROR", `${exchange} ${fieldName}: not a numeric rate (${JSON.stringify(value)})`, { exchange });
+}

package/dist/utils.d.ts

@@ -1,3 +1,4 @@
+import type { OrderResult } from "./exchanges/venue-types.js";
 export declare function symbolMatch(candidate: string, target: string): boolean;
 export declare function formatUsd(value: string | number): string;
 export declare function formatPnl(value: string | number): string;
@@ -46,6 +47,24 @@ export declare function jsonError(code: string, message: string, meta?: Partial<
  *  receive actionable hints. Codex v0.12.12 final QA #2.
  */
 export declare function withJsonErrors<T>(isJson: boolean, fn: () => Promise<T>, exchange?: string): Promise<T | undefined>;
+/**
+ * Central CLI error printer. JSON: the structured envelope incl. details and
+ * remediation. Human: the uniform "not supported" line for CAPABILITY_UNSUPPORTED
+ * (design §13.6) — `✗ <Venue>: <feature> not supported — <reason>. Alternative: <remediation>` —
+ * otherwise `Error: <message>` plus the remediation.
+ */
+export declare function printCliError(err: unknown, isJson: boolean, exchange?: string): void;
+/**
+ * JSON payload of an order result (design §13.7): the uniform OrderResult (+ execution)
+ * with the venue's raw response duplicated under `legacy` for one release.
+ */
+export declare function orderResultJson(r: OrderResult & {
+    remediation?: string | null;
+}, extra?: Record<string, unknown>): Record<string, unknown>;
+/** Human lines for an order result — one format for every venue (design §13.7). */
+export declare function formatOrderResult(r: OrderResult & {
+    remediation?: string | null;
+}): string[];
 /**
  * Log each rejected outcome from Promise.allSettled to stderr with a
  * per-source label. SSOT rule #2 helper: turn a quiet rejection inside a

package/dist/utils.js

@@ -2,9 +2,19 @@ import Table from "cli-table3";
 import chalk from "chalk";
 import { classifyError } from "./errors.js";
 export function symbolMatch(candidate, target) {
-    const c = candidate.toUpperCase();
-    const t = target.toUpperCase();
-    return c === t || c === `${t}-PERP` || c.replace(/-PERP$/, "") === t;
+    // Symmetric match: strip a trailing -PERP from BOTH sides before comparing.
+    // Callers pass (venueSymbol, userInput); the venue may report "BTC" or
+    // "BTC-PERP" and the user may type either form, so matching must not depend
+    // on which side carries the suffix.
+    const strip = (s) => s.toUpperCase().replace(/-PERP$/, "");
+    const c = strip(candidate);
+    const t = strip(target);
+    if (c === t)
+        return true;
+    // A HIP-3 dex-scoped adapter reports "xyz:NVDA" while the user (with --dex xyz) types "NVDA".
+    // One-way only: a dex-prefixed user input never matches a bare venue symbol.
+    const colon = c.indexOf(":");
+    return colon > 0 && !t.includes(":") && c.slice(colon + 1) === t;
 }
 export function formatUsd(value) {
     const num = Number(value);
@@ -136,6 +146,10 @@ function downsample(values, targetLen) {
 // ── JSON Output ──
 const _isNdjson = () => process.argv.includes("--ndjson");
 export function printJson(data) {
+    // An error envelope always means a non-zero exit (scripts / agents key on the exit code too):
+    // commands that print `jsonError(...)` and return would otherwise exit 0 with ok:false.
+    if (data !== null && typeof data === "object" && data.ok === false)
+        process.exitCode = 1;
     // Sanitize all string values in output
     let output = sanitizeValue(data);
     // Apply --fields filter
@@ -213,25 +227,88 @@ export async function withJsonErrors(isJson, fn, exchange) {
         return await fn();
     }
     catch (err) {
-        const classified = classifyError(err, exchange);
-        if (isJson) {
-            console.log(JSON.stringify(jsonError(classified.code, classified.message, {
-                status: classified.status,
-                retryable: classified.retryable,
-                retryAfterMs: classified.retryAfterMs,
-                remediation: classified.remediation,
-                details: classified.details,
-            })));
-        }
-        else {
-            console.error(chalk.red(`Error: ${classified.message}`));
-            if (classified.remediation) {
-                console.error(chalk.yellow(`Remediation: ${classified.remediation}`));
-            }
-        }
+        printCliError(err, isJson, exchange);
+        process.exitCode = 1; // printed, not swallowed: the command still exits non-zero
         return undefined;
     }
 }
+/**
+ * Central CLI error printer. JSON: the structured envelope incl. details and
+ * remediation. Human: the uniform "not supported" line for CAPABILITY_UNSUPPORTED
+ * (design §13.6) — `✗ <Venue>: <feature> not supported — <reason>. Alternative: <remediation>` —
+ * otherwise `Error: <message>` plus the remediation.
+ */
+export function printCliError(err, isJson, exchange) {
+    const classified = classifyError(err, exchange);
+    if (isJson) {
+        console.log(JSON.stringify(jsonError(classified.code, classified.message, {
+            status: classified.status,
+            retryable: classified.retryable,
+            retryAfterMs: classified.retryAfterMs,
+            remediation: classified.remediation,
+            details: classified.details,
+        })));
+        return;
+    }
+    const d = classified.details;
+    if (classified.code === "CAPABILITY_UNSUPPORTED" && d && typeof d.venue === "string" && typeof d.feature === "string" && typeof d.reason === "string") {
+        const alt = classified.remediation !== undefined ? ` Alternative: ${classified.remediation}` : "";
+        console.error(chalk.red(`✗ ${d.venue}: ${d.feature} not supported — ${d.reason}.`) + chalk.yellow(alt));
+        return;
+    }
+    console.error(chalk.red(`Error: ${classified.message}`));
+    if (classified.remediation) {
+        console.error(chalk.yellow(`Remediation: ${classified.remediation}`));
+    }
+}
+/**
+ * JSON payload of an order result (design §13.7): the uniform OrderResult (+ execution)
+ * with the venue's raw response duplicated under `legacy` for one release.
+ */
+export function orderResultJson(r, extra) {
+    return { ...r, ...extra, legacy: r.venueRaw };
+}
+/** Human lines for an order result — one format for every venue (design §13.7). */
+export function formatOrderResult(r) {
+    const lines = [];
+    const statusColor = r.status === "filled" ? chalk.green
+        : r.status === "rejected" || r.status === "cancelled" ? chalk.red
+            : r.status === "partiallyFilled" ? chalk.yellow : chalk.white;
+    const fill = `filled ${r.filledSize ?? "unknown"}${r.avgPrice !== null ? ` @ ${r.avgPrice}` : ""}`;
+    lines.push(`  Status:     ${statusColor(r.status)} (${r.finality === "final" ? "final" : chalk.yellow("pending")}) — ${fill}`);
+    const ids = [];
+    if (r.orderId !== null)
+        ids.push(`order ${r.orderId}`);
+    if (r.clientOrderId !== null)
+        ids.push(`client id ${r.clientOrderId}`);
+    if (ids.length > 0)
+        lines.push(`  Order:      ${ids.join(" · ")}`);
+    const e = r.execution;
+    const exec = [e.method];
+    if (e.slippageBps !== null)
+        exec.push(`slippage ${Math.round(e.slippageBps * 100) / 100} bps${e.slippageSource !== null ? ` (${e.slippageSource})` : ""}`);
+    if (e.protectionPrice !== null)
+        exec.push(`protection ${e.protectionPrice}${e.referencePrice !== null ? ` (ref ${e.referencePrice})` : ""}`);
+    else if (e.referencePrice !== null)
+        exec.push(`ref ${e.referencePrice}`);
+    lines.push(`  Execution:  ${exec.join(" · ")}`);
+    if (e.tifRequested !== null || e.tifSent !== null) {
+        const tif = e.tifRequested !== null && e.tifSent !== null && e.tifRequested !== e.tifSent
+            ? `${e.tifRequested} → ${e.tifSent}` : (e.tifSent ?? e.tifRequested);
+        lines.push(`  TIF:        ${tif}${e.expiresAt !== null ? ` (expires ${new Date(e.expiresAt).toISOString()})` : ""}`);
+    }
+    if (e.builderFee !== null) {
+        const approved = e.builderFee.approvedMaxBps === null ? "" : `, approved max ${e.builderFee.approvedMaxBps} bps`;
+        const fee = e.builderFee.feeKind === "share" ? "fee share (you pay the normal fee, nothing extra)"
+            : e.builderFee.feeKind === "max" ? `up to ${e.builderFee.feeBps} bps (builder's own rate applies${approved})` : `${e.builderFee.feeBps} bps`;
+        lines.push(`  Builder:    ${fee} → ${e.builderFee.identity}`);
+    }
+    for (const n of e.notes)
+        lines.push(chalk.gray(`  Note:       ${n}`));
+    if (r.remediation !== undefined && r.remediation !== null)
+        lines.push(chalk.yellow(`  ${r.remediation}`));
+    return lines;
+}
 /**
  * Log each rejected outcome from Promise.allSettled to stderr with a
  * per-source label. SSOT rule #2 helper: turn a quiet rejection inside a

package/dist/withdraw-gate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Withdraw gate for venues whose withdrawals are authorized by an API key alone — no owner
+ * signature (settings.withdraw.<venue>; today: qfex). Design §14.12 #8.
+ *
+ * Before such a withdrawal is sent it must pass, locally:
+ *   1. a gate is configured at all (absent → refused);
+ *   2. the destination is on the allowlist;
+ *   3. amount ≤ maxPerTx;
+ *   4. today's total (UTC day, from this machine's ledger) + amount ≤ maxPerDay.
+ * The adapter enforces it inside withdraw(), so no caller can skip it.
+ *
+ * What it is NOT: a defence against key theft. Someone holding the key file does not use this
+ * CLI. That defence is a trading key WITHOUT the withdraw permission (a separate key for
+ * funding). The gate limits mistakes and misdirected automation: its allowlist can only be
+ * changed with an interactive terminal confirmation (confirmWithdrawGateChange), never under
+ * --json, a pipe, the MCP server or a job.
+ *
+ * Ledger: ~/.perp/withdraw-ledger.json — amounts and addresses only (no secrets, Rule #3).
+ * An attempt is recorded BEFORE it is sent and removed only on a definite refusal, so an
+ * unknown outcome counts against the day.
+ */
+import type { WithdrawGate, WithdrawGateVenue } from "./settings.js";
+export interface WithdrawLedgerEntry {
+    id: string;
+    venue: string;
+    network: string;
+    /** USDC, as sent. */
+    amount: string;
+    to: string;
+    /** ISO timestamp of the attempt. */
+    at: string;
+}
+/** Sum of the amounts attempted for venue + network on the UTC day of `nowMs`. */
+export declare function withdrawnOnDay(venue: string, network: string, nowMs: number): number;
+/**
+ * Throws POLICY_DENIED unless the withdrawal passes `gate`. Nothing is sent before this returns.
+ * `gate` null = settings.withdraw.<venue> is not configured.
+ */
+export declare function assertWithdrawAllowed(venue: WithdrawGateVenue, network: string, amount: string, to: string, gate: WithdrawGate | null, nowMs: number): void;
+/** Record an attempt (call BEFORE sending). Returns its id for forgetWithdrawAttempt. */
+export declare function recordWithdrawAttempt(venue: string, network: string, amount: string, to: string, nowMs: number): string;
+/** Remove an attempt the venue DEFINITELY refused (nothing left the account). */
+export declare function forgetWithdrawAttempt(id: string): void;
+/**
+ * Confirmation for creating or changing settings.withdraw.<venue>. Only an interactive
+ * terminal can confirm: --json, a non-TTY stdin/stdout (pipes, the MCP server, jobs) are
+ * refused, and there is no --yes.
+ */
+export declare function confirmWithdrawGateChange(venue: string, gate: WithdrawGate, json: boolean): Promise<void>;