perp-cli 0.9.8 → 0.12.0

package/dist/signer/ows-evm.js

@@ -0,0 +1,86 @@
+import { loadOws } from "./ows-loader.js";
+/**
+ * EVM signer backed by Open Wallet Standard.
+ * Keys never leave the OWS encrypted vault.
+ */
+export class OwsEvmSigner {
+    _address;
+    _walletName;
+    _passphrase;
+    constructor(walletName, address, passphrase) {
+        this._walletName = walletName;
+        this._address = address;
+        this._passphrase = passphrase;
+    }
+    static create(walletName, passphrase = "") {
+        const ows = loadOws();
+        const wallet = ows.getWallet(walletName);
+        const evmAccount = wallet.accounts.find((a) => a.chainId.startsWith("eip155:"));
+        if (!evmAccount) {
+            throw new Error(`OWS wallet "${walletName}" has no EVM account`);
+        }
+        return new OwsEvmSigner(walletName, evmAccount.address, passphrase);
+    }
+    getAddress() {
+        return this._address;
+    }
+    async signTypedData(domain, types, value) {
+        const ows = loadOws();
+        // Build EIP-712 structure expected by OWS
+        const typedData = JSON.stringify({
+            types: {
+                EIP712Domain: Object.keys(domain).map((key) => ({
+                    name: key,
+                    type: inferEip712DomainType(key),
+                })),
+                ...types,
+            },
+            primaryType: Object.keys(types)[0],
+            domain,
+            message: value,
+        });
+        const result = ows.signTypedData(this._walletName, "ethereum", typedData, this._passphrase);
+        return canonicalizeOwsSignature(result);
+    }
+    async signMessage(message) {
+        const ows = loadOws();
+        const msgStr = typeof message === "string"
+            ? message
+            : Buffer.from(message).toString("hex");
+        const encoding = typeof message === "string" ? "utf8" : "hex";
+        const result = ows.signMessage(this._walletName, "ethereum", msgStr, this._passphrase, encoding);
+        return canonicalizeOwsSignature(result);
+    }
+}
+/**
+ * Normalize OWS signature output to canonical 65-byte hex (0x-prefixed).
+ *
+ * OWS may return the signature in two shapes depending on version:
+ *   (A) 65-byte hex with v already embedded — use as-is
+ *   (B) 64-byte hex (r+s only) + separate recoveryId — append v
+ *
+ * For shape B, recoveryId may be either canonical (27/28) or raw (0/1).
+ * If raw, add 27 to canonicalize.
+ */
+export function canonicalizeOwsSignature(result) {
+    const sigHex = result.signature.startsWith("0x") ? result.signature.slice(2) : result.signature;
+    if (sigHex.length === 130) {
+        // Already 65-byte sig with embedded v — trust OWS
+        return `0x${sigHex}`;
+    }
+    if (sigHex.length !== 128) {
+        throw new Error(`Unexpected OWS signature length: ${sigHex.length} hex chars (expected 128 or 130)`);
+    }
+    // 64-byte r+s — append v from recoveryId
+    const rid = result.recoveryId ?? 0;
+    const v = rid >= 27 ? rid : rid + 27; // accept canonical or raw recoveryId
+    return `0x${sigHex}${v.toString(16).padStart(2, "0")}`;
+}
+function inferEip712DomainType(key) {
+    switch (key) {
+        case "chainId": return "uint256";
+        case "verifyingContract": return "address";
+        case "salt": return "bytes32";
+        default: return "string";
+    }
+}

package/dist/signer/ows-loader.d.ts

@@ -0,0 +1,2 @@
+/** Lazy-load the OWS native module (NAPI binding, requires CJS require). */
+export declare function loadOws(): typeof import("@open-wallet-standard/core");

package/dist/signer/ows-loader.js

@@ -0,0 +1,6 @@
+import { createRequire } from "node:module";
+const _require = createRequire(import.meta.url);
+/** Lazy-load the OWS native module (NAPI binding, requires CJS require). */
+export function loadOws() {
+    return _require("@open-wallet-standard/core");
+}

package/dist/signer/ows-solana.d.ts

@@ -0,0 +1,25 @@
+import type { SolanaSigner } from "./interface.js";
+/**
+ * Solana signer backed by Open Wallet Standard.
+ * Keys never leave the OWS encrypted vault.
+ */
+export declare class OwsSolanaSigner implements SolanaSigner {
+    private _address;
+    private _walletName;
+    private _passphrase;
+    private constructor();
+    static create(walletName: string, passphrase?: string): OwsSolanaSigner;
+    getPublicKeyBase58(): string;
+    signMessage(message: Uint8Array): Promise<Uint8Array>;
+    signTransaction(tx: {
+        sign(keypair: unknown): void;
+    }): void;
+    partialSignTransaction(tx: {
+        partialSign(keypair: unknown): void;
+    }): void;
+    /**
+     * Sign raw Solana transaction bytes via OWS.
+     * The caller is responsible for serializing/deserializing the transaction.
+     */
+    signTransactionBytes(txBytes: Uint8Array): Uint8Array;
+}

package/dist/signer/ows-solana.js

@@ -0,0 +1,56 @@
+import { loadOws } from "./ows-loader.js";
+/**
+ * Solana signer backed by Open Wallet Standard.
+ * Keys never leave the OWS encrypted vault.
+ */
+export class OwsSolanaSigner {
+    _address;
+    _walletName;
+    _passphrase;
+    constructor(walletName, address, passphrase) {
+        this._walletName = walletName;
+        this._address = address;
+        this._passphrase = passphrase;
+    }
+    static create(walletName, passphrase = "") {
+        const ows = loadOws();
+        const wallet = ows.getWallet(walletName);
+        const solAccount = wallet.accounts.find((a) => a.chainId.startsWith("solana:"));
+        if (!solAccount) {
+            throw new Error(`OWS wallet "${walletName}" has no Solana account`);
+        }
+        return new OwsSolanaSigner(walletName, solAccount.address, passphrase);
+    }
+    getPublicKeyBase58() {
+        return this._address;
+    }
+    async signMessage(message) {
+        const ows = loadOws();
+        const msgHex = Buffer.from(message).toString("hex");
+        const result = ows.signMessage(this._walletName, "solana", msgHex, this._passphrase, "hex");
+        // Convert hex signature to Uint8Array
+        const sigHex = result.signature.startsWith("0x") ? result.signature.slice(2) : result.signature;
+        return Uint8Array.from(Buffer.from(sigHex, "hex"));
+    }
+    signTransaction(tx) {
+        // OWS doesn't expose raw keypairs. For Solana transactions that require
+        // a keypair, we serialize -> sign via OWS -> inject signature back.
+        throw new Error("OWS signer does not support in-place tx.sign(). " +
+            "Use signTransactionBytes() or the deposit relayer instead.");
+    }
+    partialSignTransaction(tx) {
+        throw new Error("OWS signer does not support in-place tx.partialSign(). " +
+            "Use signTransactionBytes() or the deposit relayer instead.");
+    }
+    /**
+     * Sign raw Solana transaction bytes via OWS.
+     * The caller is responsible for serializing/deserializing the transaction.
+     */
+    signTransactionBytes(txBytes) {
+        const ows = loadOws();
+        const txHex = Buffer.from(txBytes).toString("hex");
+        const result = ows.signTransaction(this._walletName, "solana", txHex, this._passphrase);
+        const sigHex = result.signature.startsWith("0x") ? result.signature.slice(2) : result.signature;
+        return Uint8Array.from(Buffer.from(sigHex, "hex"));
+    }
+}

package/dist/smart-order.d.ts

@@ -16,13 +16,19 @@
  * - Saves 5-50+ bps vs raw market orders on thin books
  * - Predictable execution price
  *
- * Fallback: if the IOC limit fails, falls back to market order.
+ * SSOT rule #2: silent fallback is forbidden. The opt-in `fallback: true` flag
+ * is preserved for callers that explicitly want best-effort market substitution
+ * after IOC reject, but the DEFAULT is `false` — failure must surface as a
+ * thrown error, never a silent market sweep.
  */
 import type { ExchangeAdapter } from "./exchanges/index.js";
 export interface SmartOrderOpts {
     /** Extra ticks of tolerance beyond best price. Default: 1 */
     tickTolerance?: number;
-    /** Fall back to market order if IOC limit fails. Default: true */
+    /**
+     * Opt-in: fall back to market order if IOC limit fails.
+     * SSOT rule #2 default: `false` — failure throws unless caller explicitly opts in.
+     */
     fallback?: boolean;
     /** Reduce only flag for closing positions. Default: false */
     reduceOnly?: boolean;

package/dist/smart-order.js

@@ -16,7 +16,10 @@
  * - Saves 5-50+ bps vs raw market orders on thin books
  * - Predictable execution price
  *
- * Fallback: if the IOC limit fails, falls back to market order.
+ * SSOT rule #2: silent fallback is forbidden. The opt-in `fallback: true` flag
+ * is preserved for callers that explicitly want best-effort market substitution
+ * after IOC reject, but the DEFAULT is `false` — failure must surface as a
+ * thrown error, never a silent market sweep.
  */
 /**
  * Infer tick size from orderbook prices.
@@ -77,12 +80,38 @@ function hasOrderError(result) {
         return true;
     return false;
 }
+/**
+ * Best-effort extraction of the embedded reject reason for the thrown error
+ * message. Falls back to JSON.stringify so the caller always gets actionable
+ * context.
+ */
+function describeOrderError(result) {
+    if (!result || typeof result !== "object")
+        return String(result);
+    const r = result;
+    const resp = r.response;
+    const data = resp?.data;
+    const statuses = data?.statuses;
+    if (Array.isArray(statuses) && statuses.length > 0 && statuses[0].error) {
+        return String(statuses[0].error);
+    }
+    if (typeof r.error === "string")
+        return r.error;
+    if (typeof r.message === "string")
+        return r.message;
+    try {
+        return JSON.stringify(result);
+    }
+    catch {
+        return String(result);
+    }
+}
 /**
  * Execute a smart order at best bid/ask + 1 tick.
  * Drop-in replacement for `adapter.marketOrder()`.
  */
 export async function smartOrder(adapter, symbol, side, size, opts = {}) {
-    const { tickTolerance = 1, fallback = true, reduceOnly = false } = opts;
+    const { tickTolerance = 1, fallback = false, reduceOnly = false } = opts;
     // 1. Fetch orderbook
     const book = await adapter.getOrderbook(symbol);
     // 2. Validate book has liquidity on the relevant side
@@ -111,15 +140,21 @@ export async function smartOrder(adapter, symbol, side, size, opts = {}) {
         });
         // Check for exchange-level rejection inside a "success" response
         // (e.g., Hyperliquid returns { status: "ok", response: { data: { statuses: [{ error: "..." }] } } })
-        if (fallback && hasOrderError(result)) {
-            const fallbackResult = await adapter.marketOrder(symbol, side, size);
-            return {
-                result: fallbackResult,
-                method: "market_fallback",
-                price: formattedPrice,
-                bestBookPrice: bestEntry[0],
-                tickSize: tick.toFixed(decimals),
-            };
+        // SSOT rule #2: when fallback is opt-out (default), an embedded reject
+        // must throw — otherwise the caller would silently receive a "limit_ioc"
+        // result for a rejected order and treat the failure as success.
+        if (hasOrderError(result)) {
+            if (fallback) {
+                const fallbackResult = await adapter.marketOrder(symbol, side, size);
+                return {
+                    result: fallbackResult,
+                    method: "market_fallback",
+                    price: formattedPrice,
+                    bestBookPrice: bestEntry[0],
+                    tickSize: tick.toFixed(decimals),
+                };
+            }
+            throw new Error(`smartOrder: exchange rejected IOC limit (${describeOrderError(result)})`);
         }
         return {
             result,

package/dist/strategies/funding-arb.js

@@ -1,4 +1,4 @@
-import { symbolMatch } from "../utils.js";
+import { symbolMatch, logSettledRejections } from "../utils.js";
 import { updateJobState } from "../jobs.js";
 import { fetchAllBalances, computeRebalancePlan, hasEnoughBalance } from "../rebalance.js";
 import { checkArbLiquidity } from "../liquidity.js";
@@ -6,6 +6,9 @@ import { computeAnnualSpread } from "../funding.js";
 import { fetchPacificaPrices, fetchHyperliquidMeta, fetchLighterOrderBookDetails, fetchLighterFundingRates, } from "../shared-api.js";
 import { computeMatchedSize, reconcileArbFills } from "../arb-sizing.js";
 async function fetchAllRates() {
+    // SSOT rule #2: each DEX is independent. allSettled keeps the comparison
+    // alive when one DEX errors out, while rejection reasons get logged to
+    // stderr (explicit failure, never silent).
     const [pacRates, hlRates, ltRates] = await Promise.allSettled([
         fetchPacificaPrices().then(assets => assets.map(p => ({
             exchange: "pacifica", symbol: p.symbol, fundingRate: p.funding, markPrice: p.mark,
@@ -20,14 +23,32 @@ async function fetchAllRates() {
             ]);
             const priceMap = new Map(details.map(d => [d.marketId, d.lastTradePrice]));
             const symMap = new Map(details.map(d => [d.marketId, d.symbol]));
-            return funding.map(fr => ({
-                exchange: "lighter",
-                symbol: fr.symbol || symMap.get(fr.marketId) || "",
-                fundingRate: fr.rate,
-                markPrice: fr.markPrice || priceMap.get(fr.marketId) || 0,
-            }));
+            const out = [];
+            for (const fr of funding) {
+                const symbol = fr.symbol || symMap.get(fr.marketId) || "";
+                if (!symbol)
+                    continue;
+                // Prefer fr.markPrice; fall back to orderBook last-trade as documented
+                // price source preference (NOT an error fallback).
+                const directMark = fr.markPrice;
+                const fallbackMark = priceMap.get(fr.marketId);
+                let markPrice;
+                if (directMark !== null && Number.isFinite(directMark) && directMark > 0) {
+                    markPrice = directMark;
+                }
+                else if (fallbackMark !== undefined && Number.isFinite(fallbackMark) && fallbackMark > 0) {
+                    markPrice = fallbackMark;
+                }
+                // SSOT rule #2: skip rows whose mark price cannot be resolved at all
+                // — never publish a 0 mark price downstream.
+                if (markPrice === undefined)
+                    continue;
+                out.push({ exchange: "lighter", symbol, fundingRate: fr.rate, markPrice });
+            }
+            return out;
         })(),
     ]);
+    logSettledRejections([pacRates, hlRates, ltRates], ["pacifica", "hyperliquid", "lighter"], "funding-arb");
     return [
         ...(pacRates.status === "fulfilled" ? pacRates.value : []),
         ...(hlRates.status === "fulfilled" ? hlRates.value : []),
@@ -141,7 +162,7 @@ export async function runFundingArb(adapters, params, jobId, log = console.log)
                                     for (const move of plan.moves) {
                                         log(`[ARB]   $${move.amount} ${move.from} → ${move.to}`);
                                     }
-                                    log(`[ARB] Run 'perp rebalance execute' to rebalance.`);
+                                    log(`[ARB] Run 'perp funds rebalance execute' to rebalance.`);
                                 }
                             }
                         }

package/dist/trade-validator.js

@@ -10,13 +10,26 @@ export async function validateTrade(adapter, params) {
     const checks = [];
     const warnings = [];
     const sym = params.symbol.toUpperCase();
-    // Fetch market data, balance, positions, orderbook in parallel
+    // Fetch market data, balance, positions, orderbook in parallel.
+    // SSOT rule #2: errors must propagate, never silently substitute defaults.
+    // getMarkets retains a tracked-error wrapper so the failed-load case surfaces
+    // a structured symbol_valid check (not a generic exception).
+    let marketsError = null;
     const [markets, balance, positions, orderbook] = await Promise.all([
-        adapter.getMarkets().catch(() => []),
-        adapter.getBalance().catch(() => ({ equity: "0", available: "0", marginUsed: "0", unrealizedPnl: "0" })),
-        adapter.getPositions().catch(() => []),
-        params.type !== "limit" ? adapter.getOrderbook(sym).catch(() => ({ bids: [], asks: [] })) : Promise.resolve({ bids: [], asks: [] }),
+        adapter.getMarkets().catch((e) => {
+            marketsError = e instanceof Error ? e.message : String(e);
+            return [];
+        }),
+        adapter.getBalance(),
+        adapter.getPositions(),
+        params.type !== "limit"
+            ? adapter.getOrderbook(sym)
+            : Promise.resolve({ bids: [], asks: [] }),
     ]);
+    if (markets.length === 0 && marketsError) {
+        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();
@@ -30,9 +43,21 @@ export async function validateTrade(adapter, params) {
         return { valid: false, checks, warnings, timestamp: new Date().toISOString() };
     }
     const markPrice = Number(market.markPrice);
+    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.`);
+    }
+    if (markPrice <= 0 && params.price === undefined) {
+        throw new Error(`No mark price available for ${sym} on ${adapter.name} and no override price supplied; cannot validate trade.`);
+    }
     const price = params.price ?? markPrice;
     const notional = params.size * price;
+    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;
+    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);

package/dist/utils.d.ts

@@ -38,3 +38,13 @@ export declare function jsonError(code: string, message: string, meta?: Partial<
  *  In JSON mode, errors are returned as JSON instead of crashing.
  */
 export declare function withJsonErrors<T>(isJson: boolean, fn: () => Promise<T>, exchange?: string): Promise<T | undefined>;
+/**
+ * Log each rejected outcome from Promise.allSettled to stderr with a
+ * per-source label. SSOT rule #2 helper: turn a quiet rejection inside a
+ * multi-DEX comparison into an explicit one-line failure on stderr.
+ *
+ * @param settled  Outcomes from Promise.allSettled.
+ * @param labels   Source label per index (e.g. ["pacifica", "hyperliquid", ...]).
+ * @param prefix   Bracketed prefix prepended to each line (e.g. "arb-auto").
+ */
+export declare function logSettledRejections(settled: PromiseSettledResult<unknown>[], labels: string[], prefix: string): void;

package/dist/utils.js

@@ -221,3 +221,22 @@ export async function withJsonErrors(isJson, fn, exchange) {
         return undefined;
     }
 }
+/**
+ * Log each rejected outcome from Promise.allSettled to stderr with a
+ * per-source label. SSOT rule #2 helper: turn a quiet rejection inside a
+ * multi-DEX comparison into an explicit one-line failure on stderr.
+ *
+ * @param settled  Outcomes from Promise.allSettled.
+ * @param labels   Source label per index (e.g. ["pacifica", "hyperliquid", ...]).
+ * @param prefix   Bracketed prefix prepended to each line (e.g. "arb-auto").
+ */
+export function logSettledRejections(settled, labels, prefix) {
+    for (let i = 0; i < settled.length; i++) {
+        const r = settled[i];
+        if (r.status === "rejected") {
+            const reason = r.reason instanceof Error ? r.reason.message : String(r.reason);
+            // eslint-disable-next-line no-console
+            console.error(`[${prefix}] ${labels[i] ?? `index-${i}`} fetch failed: ${reason}`);
+        }
+    }
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "perp-cli",
-  "version": "0.9.8",
+  "version": "0.12.0",
   "description": "Multi-DEX Perpetual Futures CLI - Pacifica, Hyperliquid, Lighter, Aster",
   "bin": {
     "perp": "dist/index.js",
-    "perp-mcp": "dist/mcp-server.js"
+    "perp-mcp": "dist/mcp-server.js",
+    "perp-guardrail": "dist/guardrail/perp-guardrail.js"
   },
   "files": [
     "dist",
@@ -45,6 +46,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@msgpack/msgpack": "^3.1.3",
+    "@open-wallet-standard/core": "1.3.2",
     "@solana/web3.js": "^1.98.0",
     "@types/react": "^19.2.14",
     "bs58": "^6.0.0",

package/skills/perp-cli/SKILL.md

@@ -99,20 +99,30 @@ perp --json arb close ETH                   # sells spot + buys back perp
 
 Spot exchanges: HL, LT. Pacifica and Aster are perp-only.
 
-## Bot Engine (19 Strategies)
+## Strategy Engine (19 bot algorithms + nested scripted plans)
 
 ```bash
-perp bot list-strategies                              # list all 19 strategies
-perp bot run <strategy> [symbol]                      # run any registered strategy
-perp bot run funding-auto                             # multi-exchange funding arb
-perp bot apex [symbol]                                # APEX orchestrator (Radar+Pulse+Guard)
-perp bot reflect                                      # performance analysis (win rate, fees, PnL)
-perp bot preset-list                                  # list strategy presets
-perp bot preset <name> [symbol]                       # run from preset
-perp bot start <config.yaml>                          # start from YAML/JSON config
-perp bot quick-grid <symbol>                          # quick grid bot
-perp bot quick-dca <symbol> <side> <amount> <interval>
-perp bot quick-arb                                    # quick funding arb
+perp strategy list-strategies                         # list all 19 strategies
+perp strategy run <strategy> [symbol]                 # run any registered strategy
+perp strategy run funding-auto                        # multi-exchange funding arb
+perp strategy apex [symbol]                           # APEX orchestrator (Radar+Pulse+Guard)
+perp strategy reflect                                 # performance analysis (win rate, fees, PnL)
+perp strategy preset-list                             # list strategy presets
+perp strategy preset <name> [symbol]                  # run from preset
+perp strategy start <config.yaml>                     # start from YAML/JSON config
+perp strategy quick-grid <symbol>                     # quick grid bot
+perp strategy quick-dca <symbol> <side> <amount> <interval>
+perp strategy quick-arb                               # quick funding arb
+
+# Scripted plans (one-shot multi-step execution)
+perp strategy plan example                            # show plan format
+perp --json strategy plan validate <file>             # validate before run
+perp --json strategy plan execute <file> --dry-run    # dry-run plan
+
+# Background process supervisor (tmux)
+perp background list                                  # list running jobs
+perp background stop <id>                             # stop a job
+perp background logs <id> -f                          # follow logs
 ```
 
 **Strategies:** grid, dca, funding-arb, funding-arb-v2, funding-auto, basis-arb, simple-mm, engine-mm, avellaneda-mm, regime-mm, grid-mm, liquidation-mm, momentum-breakout, mean-reversion, aggressive-taker, hedge-agent, rfq-agent, claude-agent, apex
@@ -136,7 +146,6 @@ perp --json -e <EX> trade cancel <SYM>                  # cancel all orders for
 ## Agent Tools
 
 ```bash
-perp --json agent schema                          # discover all commands (don't guess)
 perp --json -e <EX> trade check <SYM> <SIDE> <SIZE>  # pre-validate trade
 perp --json portfolio                              # balances + positions + risk level
 perp --json --fields totalEquity,positions portfolio  # filtered output
@@ -172,7 +181,7 @@ Response format: `{ "ok": true, "data": {...} }` or `{ "ok": false, "error": { "
 | `SYMBOL_NOT_FOUND` | `market list` to verify symbol |
 | `SIZE_TOO_SMALL` | `market info <SYM>` for min size |
 | `DUPLICATE_ORDER` | already submitted — check positions |
-| Lighter `invalid signature` | `manage setup-api-key` to regenerate |
+| Lighter `invalid signature` | `perp wallet agent approve lighter` to regenerate |
 
 ## Examples
 

package/skills/perp-cli/references/agent-operations.md

@@ -81,12 +81,14 @@ perp --json arb scan --min 5
 ```
 
 ### Lighter API Key Setup
-Lighter uses a separate API key for trading, but **this is handled automatically**.
-When `LIGHTER_PRIVATE_KEY` is set (env var or `wallet set`), the CLI auto-generates and saves the API key on first use.
+Lighter uses a separate API key for trading. There are two paths:
 
-If auto-setup fails (e.g. no ETH for gas on Lighter chain), retry manually:
+1. **Auto-setup (default)**: When `LIGHTER_PRIVATE_KEY` is set (env var or `wallet set`), the CLI auto-generates and saves the API key (slot 4) on first use.
+2. **Managed agent (recommended for long-running agents)**: `perp wallet agent approve lighter --master <wallet> --api-key-index <slot>` registers a per-agent slot (4-254) with explicit expiry tracking + 3-tier signer routing.
+
+If auto-setup fails (e.g. transient network error), retry manually:
 ```bash
-perp --json -e lighter manage setup-api-key
+perp --json wallet agent approve lighter --master <wallet>
 ```
 
 ### Using the Same EVM Key for Multiple Exchanges