perp-cli 0.14.3 → 0.16.0

package/dist/bot/strategies/spot-perp-arb-strategy.js

@@ -1,7 +1,7 @@
 /**
  * Spot-Perp Arbitrage Strategy
  *
- * Focused strategy: buy spot (HL or Lighter) + short perp on the BEST of 4 exchanges.
+ * Focused strategy: buy spot (HL or Lighter) + short perp on the best of the configured perp exchanges (`exchanges`).
  * No perp-perp logic. History-based entry/exit with short rotation.
  *
  * Strategy layer handles ONLY decisions (opportunity scanning, scoring, close/rotation decisions).
@@ -12,7 +12,7 @@ import { registerStrategy } from "../strategy-registry.js";
 import { getFundingHours } from "../../funding.js";
 import { annualizeHourlyRate } from "../../funding/normalize.js";
 import { pruneExecutionLog } from "../../execution-log.js";
-import { buildAdapterMap, getPerpSymbol, findRate, cappedLeverage, matchSymbol, fetchRates, scoreFunding, botSpotPerpMatches, assertFundingArbLegs, cancelBotSymbols, collectFundingSince } from "./funding-arb-utils.js";
+import { buildAdapterMap, getPerpSymbol, findRate, cappedLeverage, matchSymbol, fetchRates, scoreFunding, assertFundingHistoryPeriods, botSpotPerpMatches, assertFundingArbLegs, cancelBotSymbols, collectFundingSince } from "./funding-arb-utils.js";
 import { SpotPerpExecutor } from "./spot-perp-executor.js";
 import { findSpotQuoteBalance, getBotSpotAdapter, nonQuoteSpotBalances, spotNetworkOf, spotSharesPerpMargin, spotTokenBase } from "../../exchanges/spot-factory.js";
 import { getVenue } from "../../exchanges/venue.js";
@@ -80,6 +80,8 @@ export class SpotPerpArbStrategy {
         catch { /* non-critical */ }
         this._config = ctx.config;
         const p = this.params;
+        // Config-time check: a history_periods above a leg venue's cap would fail every tick.
+        assertFundingHistoryPeriods(p.history_periods, p.exchanges);
         ctx.state.set("arbRunning", true);
         ctx.state.set("spaPositions", []);
         ctx.state.set("arbPositions", 0);
@@ -285,7 +287,7 @@ export class SpotPerpArbStrategy {
             ctx.state.set("spaPositions", remaining);
             ctx.state.set("arbPositions", remaining.length);
         }
-        // ── Rotation check (only to perp venues that match the spot leg, §12.4 #6) ──
+        // ── Rotation check (only to perp venues that match the spot leg) ──
         const perpMarketsCache = new Map();
         const allowedBySpotVenue = new Map();
         const currentPositions = ctx.state.get("spaPositions");
@@ -375,7 +377,7 @@ export class SpotPerpArbStrategy {
                 const spotAdapter = await getBotSpotAdapter(spotExName, spotExAdapter);
                 if (!spotAdapter)
                     continue;
-                // Canonical symbol + price guard (§12.4 #6): base → perp venues it may hedge on.
+                // Canonical symbol + price guard: base → perp venues it may hedge on.
                 const allowedByBase = await this.spotPerpVenues(spotExName, await spotAdapter.getSpotMarkets(), adapters, perpMarketsCache, ctx);
                 for (const [base, allowed] of allowedByBase) {
                     // HL spot: skip tokens not in whitelist

package/dist/bot/strategies/spot-perp-executor.d.ts

@@ -26,7 +26,7 @@ export type ExecutionResult = {
 /**
  * closed = position fully closed; remainingSize = partially closed, this size is still open (hedged).
  * manual = the outcome is unknown / unverified or a leg is unhedged: the caller must quarantine
- * the position and never retry it automatically (design §12.3).
+ * the position and never retry it automatically.
  */
 export type CloseResult = {
     closed: true;

package/dist/bot/strategies/spot-perp-executor.js

@@ -65,8 +65,8 @@ export class SpotPerpExecutor {
             }
             // Price estimate
             const price = await getPriceEstimate(perpAdapter, perpSymbol, symbol);
-            if (price <= 0)
-                return { success: false, error: "price <= 0" };
+            if (price === null)
+                return { success: false, error: `no positive mark price for ${perpSymbol} on ${perpExchange}` };
             // Liquidity check
             const liq = await checkSpotPerpLiquidity(spotAdapter, perpAdapter, symbol, perpSymbol, sizeUsd, 0.5, (msg) => log(`  ${msg}`));
             if (!liq.viable)
@@ -140,7 +140,7 @@ export class SpotPerpExecutor {
                     await this.returnToPerp(spotAdapter, actualTransferred, spotExchange, log);
                 return { success: false, error: `pre-trade balance: ${msg}` };
             }
-            // Step 1: Buy spot — the hedge is sized to what actually filled (§12.4 #5)
+            // Step 1: Buy spot — the hedge is sized to what actually filled
             let fill;
             try {
                 fill = await spotMarketFill(spotAdapter, symbol, "buy", matched.size, spotStep);

package/dist/bot/strategy-types.d.ts

@@ -10,7 +10,8 @@ export interface EnrichedSnapshot extends MarketSnapshot {
         bids: [string, string][];
         asks: [string, string][];
     };
-    openInterest: string;
+    /** Base-asset open interest; null = not read / not published (never "0" as a stand-in). */
+    openInterest: string | null;
 }
 export type StrategyAction = {
     type: "place_order";

package/dist/bot/tui/BotDashboard.d.ts

@@ -28,7 +28,7 @@ export interface BotTuiState {
     exchange: string;
     price: number;
     volume24h: number;
-    openInterest: string;
+    openInterest: string | null;
     fundingRate: number;
     volatility24h: number;
     positions: Position[];

package/dist/bot/tui/BotDashboard.js

@@ -78,7 +78,7 @@ export function BotDashboard({ initialState, onQuit, onPause, subscribe }) {
     const askOrders = state.openOrders.filter((o) => o.side.toLowerCase() === "sell");
     const hasMultiExchange = (state.exchangeBalances?.length ?? 0) > 1;
     const isMultiSymbol = state.symbol.toUpperCase() === "ALL";
-    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", marginBottom: 1, children: [_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "cyan", children: [state.strategy, " | ", state.symbol, " | ", state.exchange] }), _jsxs(Text, { color: "gray", children: ["Runtime: ", formatDuration(state.runtime), " | Tick: ", state.tick] })] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: phaseColor(state.phase), children: phaseIndicator(state.phase) }) })] }), isMultiSymbol ? (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Exchanges: ", _jsx(Text, { bold: true, color: "white", children: state.exchangeBalances?.length ?? 1 })] }), _jsxs(Text, { color: "gray", children: ["Positions: ", _jsx(Text, { bold: true, color: state.positions.length > 0 ? "yellow" : "white", children: state.positions.length })] }), _jsxs(Text, { color: "gray", children: ["Total Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(totalEquity) })] }), _jsxs(Text, { color: "gray", children: ["PnL: ", _jsxs(Text, { bold: true, color: state.totalPnl >= 0 ? "green" : "red", children: ["$", state.totalPnl.toFixed(2)] })] })] })) : (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Price: ", _jsxs(Text, { bold: true, color: "white", children: ["$", state.price.toFixed(2)] })] }), _jsxs(Text, { color: "gray", children: ["Vol24h: ", _jsx(Text, { color: "white", children: Number.isFinite(state.volatility24h) ? `${state.volatility24h.toFixed(1)}%` : "unknown" })] }), _jsxs(Text, { color: "gray", children: ["FR: ", _jsxs(Text, { color: state.fundingRate >= 0 ? "green" : "red", children: [(state.fundingRate * 100).toFixed(4), "%"] })] }), _jsxs(Text, { color: "gray", children: ["OI: ", _jsx(Text, { color: "white", children: state.openInterest })] })] })), _jsxs(Box, { marginTop: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Account" }), _jsxs(Text, { children: ["Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(state.equity) }), _jsxs(Text, { color: "gray", children: [" (peak: ", usd(state.peakEquity), ")"] })] }), _jsxs(Text, { children: ["Daily P&L: ", _jsxs(Text, { bold: true, color: pnlColor(state.dailyPnl), children: ["$", state.dailyPnl.toFixed(2)] })] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: " " }), _jsxs(Text, { children: ["Drawdown: ", _jsx(Text, { bold: true, color: drawdown === null ? "gray" : drawdown > 0 ? "red" : "green", children: drawdown === null ? "unknown" : `${usd(drawdown)} (${drawdownPct.toFixed(1)}%)` })] }), _jsxs(Text, { children: ["Orders: ", _jsx(Text, { bold: true, color: "white", children: state.ordersPlaced }), _jsx(Text, { color: "gray", children: " | Fills: " }), _jsx(Text, { bold: true, color: "white", children: state.fills }), _jsx(Text, { color: "gray", children: " | Total P&L: " }), _jsxs(Text, { bold: true, color: pnlColor(state.totalPnl), children: ["$", state.totalPnl.toFixed(2)] })] })] })] }), state.exchangeBalances && state.exchangeBalances.length > 1 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Exchange Balances" }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "gray", children: pad("Exchange", 16) }), _jsx(Text, { color: "gray", children: pad("Equity", 14) }), _jsx(Text, { color: "gray", children: "Available" })] }), state.exchangeBalances.map((eb, i) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "white", children: pad(eb.exchange, 16) }), eb.equity === null ? (_jsxs(Text, { color: "red", children: ["unavailable", eb.error ? ` (${eb.error})` : ""] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: "white", children: pad(`$${parseFloat(eb.equity).toFixed(2)}`, 14) }), _jsx(Text, { color: "gray", children: eb.available === null ? "unavailable" : `$${parseFloat(eb.available).toFixed(2)}` })] }))] }, i)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Positions" }), positionErrors.map((pe, i) => (_jsxs(Text, { color: "red", children: ["  ", pe.exchange, ": unavailable (", pe.error, ")"] }, `err-${i}`))), state.positions.length === 0 ? (positionErrors.length === 0 && _jsx(Text, { color: "gray", children: "  No open positions" })) : (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [hasMultiExchange && _jsx(Text, { color: "gray", children: pad("Exchange", 14) }), _jsx(Text, { color: "gray", children: pad("Symbol", 10) }), _jsx(Text, { color: "gray", children: pad("Side", 6) }), _jsx(Text, { color: "gray", children: pad("Size", 12) }), _jsx(Text, { color: "gray", children: pad("Entry", 12) }), _jsx(Text, { color: "gray", children: pad("Mark", 12) }), _jsx(Text, { color: "gray", children: "uPnL" })] }), state.positions.map((p, i) => {
+    return (_jsxs(Box, { flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { flexDirection: "row", justifyContent: "space-between", marginBottom: 1, children: [_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { bold: true, color: "cyan", children: [state.strategy, " | ", state.symbol, " | ", state.exchange] }), _jsxs(Text, { color: "gray", children: ["Runtime: ", formatDuration(state.runtime), " | Tick: ", state.tick] })] }), _jsx(Box, { children: _jsx(Text, { bold: true, color: phaseColor(state.phase), children: phaseIndicator(state.phase) }) })] }), isMultiSymbol ? (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Exchanges: ", _jsx(Text, { bold: true, color: "white", children: state.exchangeBalances?.length ?? 1 })] }), _jsxs(Text, { color: "gray", children: ["Positions: ", _jsx(Text, { bold: true, color: state.positions.length > 0 ? "yellow" : "white", children: state.positions.length })] }), _jsxs(Text, { color: "gray", children: ["Total Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(totalEquity) })] }), _jsxs(Text, { color: "gray", children: ["PnL: ", _jsxs(Text, { bold: true, color: state.totalPnl >= 0 ? "green" : "red", children: ["$", state.totalPnl.toFixed(2)] })] })] })) : (_jsxs(Box, { borderStyle: "single", borderColor: "gray", paddingX: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Text, { children: ["Price: ", _jsxs(Text, { bold: true, color: "white", children: ["$", state.price.toFixed(2)] })] }), _jsxs(Text, { color: "gray", children: ["Vol24h: ", _jsx(Text, { color: "white", children: Number.isFinite(state.volatility24h) ? `${state.volatility24h.toFixed(1)}%` : "unknown" })] }), _jsxs(Text, { color: "gray", children: ["FR: ", _jsxs(Text, { color: state.fundingRate >= 0 ? "green" : "red", children: [(state.fundingRate * 100).toFixed(4), "%"] })] }), _jsxs(Text, { color: "gray", children: ["OI: ", _jsx(Text, { color: "white", children: state.openInterest ?? "-" })] })] })), _jsxs(Box, { marginTop: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Account" }), _jsxs(Text, { children: ["Equity: ", _jsx(Text, { bold: true, color: "white", children: usd(state.equity) }), _jsxs(Text, { color: "gray", children: [" (peak: ", usd(state.peakEquity), ")"] })] }), _jsxs(Text, { children: ["Daily P&L: ", _jsxs(Text, { bold: true, color: pnlColor(state.dailyPnl), children: ["$", state.dailyPnl.toFixed(2)] })] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { children: " " }), _jsxs(Text, { children: ["Drawdown: ", _jsx(Text, { bold: true, color: drawdown === null ? "gray" : drawdown > 0 ? "red" : "green", children: drawdown === null ? "unknown" : `${usd(drawdown)} (${drawdownPct.toFixed(1)}%)` })] }), _jsxs(Text, { children: ["Orders: ", _jsx(Text, { bold: true, color: "white", children: state.ordersPlaced }), _jsx(Text, { color: "gray", children: " | Fills: " }), _jsx(Text, { bold: true, color: "white", children: state.fills }), _jsx(Text, { color: "gray", children: " | Total P&L: " }), _jsxs(Text, { bold: true, color: pnlColor(state.totalPnl), children: ["$", state.totalPnl.toFixed(2)] })] })] })] }), state.exchangeBalances && state.exchangeBalances.length > 1 && (_jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Exchange Balances" }), _jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "gray", children: pad("Exchange", 16) }), _jsx(Text, { color: "gray", children: pad("Equity", 14) }), _jsx(Text, { color: "gray", children: "Available" })] }), state.exchangeBalances.map((eb, i) => (_jsxs(Box, { flexDirection: "row", children: [_jsx(Text, { color: "white", children: pad(eb.exchange, 16) }), eb.equity === null ? (_jsxs(Text, { color: "red", children: ["unavailable", eb.error ? ` (${eb.error})` : ""] })) : (_jsxs(_Fragment, { children: [_jsx(Text, { color: "white", children: pad(`$${parseFloat(eb.equity).toFixed(2)}`, 14) }), _jsx(Text, { color: "gray", children: eb.available === null ? "unavailable" : `$${parseFloat(eb.available).toFixed(2)}` })] }))] }, i)))] })), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsx(Text, { color: "cyan", bold: true, children: "Positions" }), positionErrors.map((pe, i) => (_jsxs(Text, { color: "red", children: ["  ", pe.exchange, ": unavailable (", pe.error, ")"] }, `err-${i}`))), state.positions.length === 0 ? (positionErrors.length === 0 && _jsx(Text, { color: "gray", children: "  No open positions" })) : (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Box, { flexDirection: "row", children: [hasMultiExchange && _jsx(Text, { color: "gray", children: pad("Exchange", 14) }), _jsx(Text, { color: "gray", children: pad("Symbol", 10) }), _jsx(Text, { color: "gray", children: pad("Side", 6) }), _jsx(Text, { color: "gray", children: pad("Size", 12) }), _jsx(Text, { color: "gray", children: pad("Entry", 12) }), _jsx(Text, { color: "gray", children: pad("Mark", 12) }), _jsx(Text, { color: "gray", children: "uPnL" })] }), state.positions.map((p, i) => {
                                 const upnl = parseFloat(p.unrealizedPnl);
                                 return (_jsxs(Box, { flexDirection: "row", children: [hasMultiExchange && _jsx(Text, { color: "cyan", children: pad(p.exchange ?? "—", 14) }), _jsx(Text, { color: "white", children: pad(p.symbol, 10) }), _jsx(Text, { color: p.side.toLowerCase() === "long" ? "green" : "red", children: pad(p.side, 6) }), _jsx(Text, { color: "white", children: pad(p.size, 12) }), _jsx(Text, { color: "white", children: pad(p.entryPrice, 12) }), _jsx(Text, { color: "white", children: pad(p.markPrice, 12) }), _jsx(Text, { color: isNaN(upnl) ? "gray" : pnlColor(upnl), children: isNaN(upnl) ? "$—" : `$${upnl.toFixed(2)}` })] }, i));
                             })] }))] }), openOrdersError !== null ? (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Open orders unavailable (", openOrdersError, ")"] }) })) : (_jsxs(Box, { marginTop: 1, flexDirection: "row", justifyContent: "space-between", children: [_jsxs(Box, { flexDirection: "column", width: "50%", children: [_jsxs(Text, { color: "green", bold: true, children: ["Bids (", bidOrders.length, ")"] }), bidOrders.length === 0 ? (_jsx(Text, { color: "gray", children: "  --" })) : (bidOrders.slice(0, 8).map((o, i) => (_jsxs(Text, { color: "green", children: [pad(o.price, 12), " ", pad(o.size, 10), " ", o.type] }, i))))] }), _jsxs(Box, { flexDirection: "column", width: "50%", children: [_jsxs(Text, { color: "red", bold: true, children: ["Asks (", askOrders.length, ")"] }), askOrders.length === 0 ? (_jsx(Text, { color: "gray", children: "  --" })) : (askOrders.slice(0, 8).map((o, i) => (_jsxs(Text, { color: "red", children: [pad(o.price, 12), " ", pad(o.size, 10), " ", o.type] }, i))))] })] })), _jsx(Box, { marginTop: 1, flexDirection: "column", children: state.strategyState.fundingTotal !== undefined ? (_jsxs(_Fragment, { children: [_jsx(Text, { color: "cyan", bold: true, children: "Funding & Arb" }), _jsxs(Box, { flexDirection: "row", marginLeft: 2, children: [_jsx(Text, { color: "gray", children: "Funding Income: " }), _jsx(Text, { color: "white", children: String(state.strategyState.fundingTotal) }), _jsx(Text, { color: "gray", children: "        Positions: " }), _jsx(Text, { color: "white", children: String(state.strategyState.arbPositions ?? 0) })] }), Array.isArray(state.strategyState.arbPositionDetails) &&

package/dist/cache.js

@@ -7,6 +7,7 @@
 import { mkdirSync, readFileSync, writeFileSync, renameSync, readdirSync, unlinkSync } from "fs";
 import { join } from "path";
 import { tmpdir } from "os";
+import { randomBytes } from "crypto";
 const CACHE_DIR = join(tmpdir(), "perp-cli-cache");
 // TTL presets
 export const TTL_ACCOUNT = 15_000; // 15s — balance, positions, orders (ticks are 30s; 15s ensures same-tick dedup)
@@ -41,16 +42,21 @@ export function getCached(key) {
 }
 export function setCached(key, data, ttlMs) {
     ensureDir();
+    const file = join(CACHE_DIR, `${safeKey(key)}.json`);
+    // Unique per writer: concurrent processes writing the same key must not share one tmp file
+    // (a rename of another writer's half-written tmp would publish a partial entry).
+    const tmp = `${file}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
     try {
         const entry = { ts: Date.now(), ttl: ttlMs, data };
-        const content = JSON.stringify(entry);
-        const file = join(CACHE_DIR, `${safeKey(key)}.json`);
-        const tmp = file + ".tmp";
-        writeFileSync(tmp, content);
+        writeFileSync(tmp, JSON.stringify(entry));
         renameSync(tmp, file);
     }
     catch {
-        // cache write failure is non-fatal
+        // cache write failure is non-fatal; never leave this writer's tmp file behind
+        try {
+            unlinkSync(tmp);
+        }
+        catch { /* not written */ }
     }
 }
 /**
@@ -94,7 +100,7 @@ export function invalidateCache(keyPrefix) {
         const files = readdirSync(CACHE_DIR);
         for (const f of files) {
             if (!f.endsWith(".json"))
-                continue;
+                continue; // also skips in-flight "<key>.json.<pid>.<rand>.tmp" files
             if (!prefix || f.startsWith(prefix)) {
                 try {
                     unlinkSync(join(CACHE_DIR, f));

package/dist/cli-program.d.ts

@@ -28,8 +28,23 @@ export declare function landingData(program: Command, version: string): {
         name: string;
         description: string;
     }[];
+    venues: {
+        id: string;
+        displayName: string;
+        roles: string[];
+        apiStatus: "official" | "unofficial";
+        note: string | null;
+    }[];
 };
 export declare function buildProgram(opts: {
     defaultExchange: string;
     version: string;
 }): CliProgram;
+/**
+ * The trading-role gate at command resolution: `perp -e <venue> trade <write>`, every
+ * `perp trade multi <venue>:…` leg and `perp wallet agent approve|import|revoke|rotate <venue>`
+ * (revoke --force / --local-only excepted: local cleanup only) and every `strategy … --exchanges` leg refuse with roleUnsupported() (CAPABILITY_UNSUPPORTED) when the venue has no trading role. Runs
+ * before the dry-run guard and before any action, so a dry-run plan can never present a gated
+ * venue as tradable. Unknown venue names are left to the command's own UNKNOWN_VENUE handling.
+ */
+export declare function assertCommandVenueRole(actionCommand: Command, exchangeOpt: string): void;

package/dist/cli-program.js

@@ -6,13 +6,15 @@ import { Command } from "commander";
 import { cliCredentialOptsFrom, hasCredentials, resolveCredentials } from "./config.js";
 import { PacificaAdapter } from "./exchanges/pacifica.js";
 import { HyperliquidAdapter } from "./exchanges/hyperliquid.js";
-import { getVenue, listVenues, resolveVenueId, READ_ONLY_CREDENTIALS } from "./exchanges/venue.js";
+import { getVenue, listVenues, resolveVenueId, roleUnsupported, tryResolveVenueId, READ_ONLY_CREDENTIALS } from "./exchanges/venue.js";
 import { registerAdapterNetwork } from "./exchanges/adapter-network.js";
 import "./exchanges/venues/index.js";
 import { PerpError } from "./errors.js";
 import { registerMarketCommands } from "./commands/market.js";
 import { registerAccountCommands } from "./commands/account.js";
 import { registerOutcomeCommands } from "./commands/outcome.js";
+import { registerOptionsCommands } from "./commands/options.js";
+import { registerPacificaEarnCommands } from "./commands/pacifica-earn.js";
 import { registerTradeCommands } from "./commands/trade.js";
 // manage commands now register under `wallet manage ...` via registerWalletCommands.
 // stream commands removed — WS feeds still used by dashboard/event-stream internally
@@ -86,6 +88,11 @@ export function landingData(program, version) {
     return {
         name: program.name(),
         version,
+        // Registry facts only (no reads): an "unofficial" venue is read through an undocumented API.
+        venues: listVenues().map(v => ({
+            id: v.id, displayName: v.displayName, roles: [...v.roles], apiStatus: v.apiStatus.kind,
+            note: v.apiStatus.kind === "unofficial" ? v.apiStatus.note : null,
+        })),
         usage: `${program.name()} [options] <command> [args] (add --json for one JSON document on stdout)`,
         help: `${program.name()} <command> --help`,
         commands: program.commands
@@ -104,7 +111,7 @@ export function buildProgram(opts) {
         .option("-e, --exchange <exchange>", `Exchange: ${listVenues().map(v => v.id).join(", ")} (default: ${defaultExchange})`, defaultExchange)
         .option("-k, --private-key <key>", "REJECTED — a raw key on argv leaks via ps / shell history. Import it instead: perp wallet set <exchange> (stdin)")
         .option("--json", "Output raw JSON (for piping)")
-        .option("--fields <fields>", "Comma-separated fields to include in JSON output (e.g. totalEquity,positions)")
+        .option("--fields <fields>", "Comma-separated fields to include in JSON output (dot paths allowed, e.g. totals.equity,exchanges)")
         .option("--ndjson", "Output newline-delimited JSON (one object per line for streaming)")
         .option("-w, --wallet <name>", "Use a specific wallet by name (from 'perp wallet list')")
         .option("--ows <name>", "Use an OWS (Open Wallet Standard) wallet by name")
@@ -131,9 +138,9 @@ export function buildProgram(opts) {
     });
     let _adapter = null;
     /**
-     * One adapter per `${venueId}:${network}:${wallet}:${hlDex}` (design §3 L1 cache key).
+     * One adapter per `${venueId}:${network}:${wallet}:${hlDex}`.
      * Every adapter is built by the venue definition's create(ctx) — the single
-     * creation path shared with the MCP server (design §10.2).
+     * creation path shared with the MCP server.
      */
     const _adapters = new Map();
     function cliCredentialOpts() {
@@ -147,7 +154,7 @@ export function buildProgram(opts) {
         const wallet = opts.ows ? `ows:${opts.ows}` : (opts.wallet ?? "default");
         return `${venue}:${network}:${wallet}:${hlDex ?? "-"}`;
     }
-    /** restrictedRegions notice: stderr, once per venue per process (design §9.1 #2 — warn, never block). */
+    /** restrictedRegions notice: stderr, once per venue per process (warn, never block). */
     const _restrictedWarned = new Set();
     function warnRestrictedRegions(def) {
         if (def.restrictedRegions.length === 0 || _restrictedWarned.has(def.id))
@@ -167,6 +174,10 @@ export function buildProgram(opts) {
                 remediation: `${def.id} is market-data only — use the funding/market public commands (e.g. perp arb scan)`,
             });
         }
+        // A market-data-only venue (TxFlow: unofficial read-only API) never gets a credentialed adapter:
+        // every account / trading / funds / bot path refuses here, before any credential or request.
+        if (!publicOnly && !def.roles.includes("account"))
+            throw roleUnsupported(def, "account");
         const network = currentNetwork();
         const hlDex = def.id === "hyperliquid" ? dex : null;
         const key = publicOnly ? `${def.id}:${network}:public:${hlDex ?? "-"}` : adapterCacheKey(def.id, network, hlDex);
@@ -246,6 +257,8 @@ export function buildProgram(opts) {
     registerMarketCommands(program, getPublicAdapter, isJson, getPublicAdapterForExchange, getAdapter);
     registerAccountCommands(program, getAdapter, isJson, getAdapterForExchange);
     registerOutcomeCommands(program, getAdapterForExchange, isJson);
+    registerOptionsCommands(program, isJson);
+    registerPacificaEarnCommands(program, getAdapterForExchange, isJson);
     registerTradeCommands(program, getAdapter, isJson, isDryRunFlag, getAdapterForExchange);
     // manage tree wired inside registerWalletCommands below.
     // stream commands removed
@@ -273,7 +286,15 @@ export function buildProgram(opts) {
     // registerFundsCommands above.
     // Background processes & strategies
     registerBackgroundCommands(program, isJson, getAdapterForExchange);
-    registerStrategyCommands(program, getAdapter, getAdapterForExchange, isJson);
+    // Every strategy command (bots, plans, TWAP / DCA / grid, `strategy run`, `--exchanges` legs,
+    // config-file venues) builds its adapters through these: a venue without the trading role
+    // (TxFlow, release-gated RISEx) is refused here, before any key is opened — also under --dry-run.
+    const strategyVenueGate = (venue) => {
+        const def = getVenue(venue);
+        if (!def.roles.includes("trading"))
+            throw roleUnsupported(def, "automation");
+    };
+    registerStrategyCommands(program, async () => { strategyVenueGate(getExchange()); return getAdapter(); }, async (exchange) => { strategyVenueGate(exchange); return getAdapterForExchange(exchange); }, isJson);
     // Agent-friendly commands
     registerRiskCommands(program, getAdapterForExchange, isJson);
     registerHistoryCommands(program, isJson, getAdapterForExchange);
@@ -286,7 +307,12 @@ export function buildProgram(opts) {
     registerPortfolioCommand(program, getAdapterForExchange, isJson, version, getHLAdapterForDex);
     registerInitCommand(program);
     registerAlertCommands(program, isJson);
+    installNestedHelp(program);
+    installMissingSubcommandError(program);
     // Switch shared API URLs if --network testnet is used
+    // A venue without the trading role (market-data-only TxFlow, release-gated RISEx) refuses every
+    // trading command before anything else — also under --dry-run, whose plans skip the adapter.
+    program.hook("preAction", (_root, actionCommand) => assertCommandVenueRole(actionCommand, program.opts().exchange));
     // Validates -n and enforces default-deny --dry-run before any action runs.
     installDryRunGuard(program);
     // Secrets on argv (review L10): -k is rejected outright; --passphrase still works but warns loudly.
@@ -301,3 +327,97 @@ export function buildProgram(opts) {
     program.hook("preAction", () => setQuarantineNetwork(networkOf(program)));
     return { program, getAdapterForExchange, isJson };
 }
+/** `perp trade <leaf>` commands that only read (order status, fills, P&L tracking, spot reads). */
+const TRADE_READ_COMMANDS = new Set(["status", "fills", "pnl-track", "spot-orders", "spot-balance"]);
+/**
+ * The trading-role gate at command resolution: `perp -e <venue> trade <write>`, every
+ * `perp trade multi <venue>:…` leg and `perp wallet agent approve|import|revoke|rotate <venue>`
+ * (revoke --force / --local-only excepted: local cleanup only) and every `strategy … --exchanges` leg refuse with roleUnsupported() (CAPABILITY_UNSUPPORTED) when the venue has no trading role. Runs
+ * before the dry-run guard and before any action, so a dry-run plan can never present a gated
+ * venue as tradable. Unknown venue names are left to the command's own UNKNOWN_VENUE handling.
+ */
+export function assertCommandVenueRole(actionCommand, exchangeOpt) {
+    const path = commandPath(actionCommand).split(" ");
+    const leaf = path[path.length - 1];
+    let venueArgs;
+    let feature;
+    if (leaf === "multi" && (path[0] === "trade" || path.length === 1)) {
+        venueArgs = actionCommand.args.map(leg => leg.split(":")[0]);
+        feature = "trading";
+    }
+    else if (path[0] === "strategy" && typeof actionCommand.opts().exchanges === "string") {
+        // `--exchanges` legs (strategy run / funding-arb / quick-arb / delta-neutral, incl. their defaults):
+        // refused before the first leg's adapter is built. The -e venue is gated by the strategy adapter factory.
+        venueArgs = String(actionCommand.opts().exchanges).split(",").map(v => v.trim()).filter(v => v !== "");
+        feature = "automation";
+    }
+    else if (path[0] === "trade" && path.length === 2 && !TRADE_READ_COMMANDS.has(leaf)) {
+        venueArgs = [exchangeOpt];
+        feature = "trading";
+    }
+    else if (path[0] === "wallet" && path[1] === "agent" && ["approve", "import", "revoke", "rotate"].includes(path[2] ?? "")) {
+        // `revoke --force` / `--local-only` only clears local records (nothing signed or sent): allowed.
+        const o = actionCommand.opts();
+        if (path[2] === "revoke" && (o.force === true || o.localOnly === true))
+            return;
+        venueArgs = actionCommand.args.slice(0, 1);
+        feature = path[2] === "import" ? "agentImport" : `agent ${path[2]}`;
+    }
+    else {
+        return;
+    }
+    for (const v of venueArgs) {
+        const id = tryResolveVenueId(v);
+        if (id !== null && !getVenue(id).roles.includes("trading"))
+            throw roleUnsupported(getVenue(id), feature);
+    }
+}
+/** `perp a b c` path of a command (root name excluded). */
+function commandPath(cmd) {
+    const names = [];
+    for (let c = cmd; c !== null && c.parent !== null; c = c.parent)
+        names.unshift(c.name());
+    return names.join(" ");
+}
+/**
+ * `perp help <group> <leaf> ...` shows the help of the deepest named command. Commander's built-in
+ * root help command resolves only its first operand, so `perp help market list` printed the
+ * `market` group help. Groups keep their own built-in `help` subcommand (`perp market help list`).
+ */
+function installNestedHelp(program) {
+    program.helpCommand(false);
+    program
+        .command("help [command...]")
+        .description("display help for command (any depth: perp help trade limit)")
+        .action((names) => {
+        let cmd = program;
+        for (const name of names) {
+            const sub = cmd.commands.find(c => c.name() === name || c.aliases().includes(name));
+            if (sub === undefined) {
+                const where = cmd === program ? "perp" : `perp ${commandPath(cmd)}`;
+                throw new PerpError("INVALID_PARAMS", `Unknown command '${name}' under '${where}'`, {
+                    remediation: `Available: ${cmd.commands.map(c => c.name()).join(", ")} — see: ${where} --help`,
+                });
+            }
+            cmd = sub;
+        }
+        cmd.help();
+    });
+}
+/**
+ * A command group run without a subcommand (`perp history`): Commander prints the group's help as
+ * an error. In --json mode that reached stdout as a CLI_ERROR whose message was the usage text;
+ * it is now one INVALID_PARAMS document naming the subcommands, with remediation (exit 1).
+ * Human mode keeps the usage listing on stderr.
+ */
+function installMissingSubcommandError(program) {
+    program.on("beforeAllHelp", (ctx) => {
+        if (!ctx.error || program.opts().json !== true)
+            return;
+        const path = `perp ${commandPath(ctx.command)}`.trim();
+        const subs = ctx.command.commands.map(c => c.name()).filter(n => n !== "help");
+        throw new PerpError("INVALID_PARAMS", `'${path}' needs a subcommand: ${subs.join(", ")}`, {
+            remediation: `Run one of them, e.g. ${path} ${subs[0]} — list them with: ${path} --help`,
+        });
+    });
+}