perp-cli 0.14.2 → 0.15.0

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

@@ -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, matchSymbol, fetchRates, scoreFunding, botSpotPerpMatches, assertFundingArbLegs, cancelBotSymbols, collectFundingSince } from "./funding-arb-utils.js";
+import { buildAdapterMap, getPerpSymbol, findRate, cappedLeverage, matchSymbol, fetchRates, scoreFunding, 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";
@@ -285,7 +285,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");
@@ -313,7 +313,7 @@ export class SpotPerpArbStrategy {
             const allowed = allowedByBase.get(pos.symbol.toUpperCase());
             if (allowed === undefined)
                 continue;
-            const candidates = await this.findPerpCandidates(pos.symbol, adapters, ratesByExchange, allowed);
+            const candidates = await this.findPerpCandidates(pos.symbol, adapters, ratesByExchange, allowed, ctx.log);
             const best = candidates[0];
             if (!best || best.exchange === pos.perpExchange)
                 continue;
@@ -331,12 +331,12 @@ export class SpotPerpArbStrategy {
                 continue;
             const perpSym = getPerpSymbol(pos.symbol, pos.perpExchange);
             const newMaxLev = findRate(ratesByExchange, best.exchange, getPerpSymbol(pos.symbol, best.exchange))?.maxLeverage
-                ?? findRate(ratesByExchange, best.exchange, pos.symbol)?.maxLeverage ?? 1;
+                ?? findRate(ratesByExchange, best.exchange, pos.symbol)?.maxLeverage;
             const ok = await this.executor.rotateShort({
                 symbol: pos.symbol, perpSymbol: perpSym,
                 currentExchange: pos.perpExchange, newExchange: best.exchange,
                 currentAdapter: oldAdapter, newAdapter,
-                size: pos.size, leverage: Math.min(p.leverage, newMaxLev), log: ctx.log,
+                size: pos.size, leverage: cappedLeverage(p.leverage, [{ exchange: best.exchange, maxLeverage: newMaxLev }], ctx.log), log: ctx.log,
             });
             if (ok.ok) {
                 // The spot leg is unchanged: the state entry follows the short to its new venue.
@@ -375,7 +375,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
@@ -387,7 +387,7 @@ export class SpotPerpArbStrategy {
                         continue;
                     if (this.quarantined(base, ctx))
                         continue;
-                    const candidates = await this.findPerpCandidates(base, adapters, ratesByExchange, allowed);
+                    const candidates = await this.findPerpCandidates(base, adapters, ratesByExchange, allowed, ctx.log);
                     for (const cand of candidates) {
                         if (cand.score.annualized < p.min_rate || cand.score.consistency < p.min_consistency)
                             continue;
@@ -501,7 +501,7 @@ export class SpotPerpArbStrategy {
         return byBase;
     }
     /** Find all perp exchanges for a symbol, sorted by annualized rate (highest first). */
-    async findPerpCandidates(symbol, adapters, ratesByExchange, allowedPerpVenues) {
+    async findPerpCandidates(symbol, adapters, ratesByExchange, allowedPerpVenues, log) {
         const candidates = [];
         for (const [exName, adapter] of adapters) {
             if (!allowedPerpVenues.has(exName))
@@ -510,8 +510,20 @@ export class SpotPerpArbStrategy {
             const ri = findRate(ratesByExchange, exName, perpSym) ?? findRate(ratesByExchange, exName, symbol);
             if (!ri || ri.rate <= 0)
                 continue;
-            const score = await this.scoreFundingLocal(adapter, perpSym, exName)
-                ?? await this.scoreFundingLocal(adapter, symbol, exName);
+            // A failed history read is not "too little history": say so, then try the next symbol form;
+            // a venue with no readable form is left out this cycle.
+            let score = null;
+            for (const sym of perpSym === symbol ? [perpSym] : [perpSym, symbol]) {
+                try {
+                    score = await this.scoreFundingLocal(adapter, sym, exName);
+                }
+                catch (e) {
+                    log(`  [SPA] ${sym} on ${exName}: funding history unreadable — not a candidate this cycle: ${e instanceof Error ? e.message : String(e)}`);
+                    continue;
+                }
+                if (score)
+                    break;
+            }
             if (!score)
                 continue;
             candidates.push({ exchange: exName, rate: ri.rate, score });
@@ -569,8 +581,7 @@ export class SpotPerpArbStrategy {
             const perpSymbol = getPerpSymbol(symbol, perpExchange);
             const rateInfo = findRate(ratesByExchange, perpExchange, perpSymbol)
                 ?? findRate(ratesByExchange, perpExchange, symbol);
-            const perpMaxLev = rateInfo?.maxLeverage ?? 1;
-            const leverage = Math.min(p.leverage, perpMaxLev);
+            const leverage = cappedLeverage(p.leverage, [{ exchange: perpExchange, maxLeverage: rateInfo?.maxLeverage }], ctx.log);
             // Pre-entry: verify fundingHours (aster lazy bootstrap may not have run yet)
             if (perpExchange === "aster" && rateInfo && "getFundingHours" in perpAdapter) {
                 const actualFh = await perpAdapter.getFundingHours(symbol);

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

@@ -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
@@ -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`,
+        });
+    });
+}

package/dist/commands/agent-import.d.ts

@@ -90,6 +90,13 @@ export declare function importSecretLineCount(venue: VenueId): number;
 export declare function importSecretFromLines(venue: VenueId, lines: string[]): ImportSecret;
 /** Read the secret: hidden TTY prompt, else piped stdin (ondo: 2 lines key id + secret; others: 1 line). */
 export declare function readImportSecret(venue: VenueId): Promise<ImportSecret>;
+/**
+ * Venues whose keys cannot be imported. TxFlow: market-data-only (unofficial read-only API).
+ * RISEx: perp-cli trades only with a signer it registered itself and then restricted ON-CHAIN to
+ * the trading permission; a signer created in the RISEx app keeps every permission (including
+ * deposit / withdraw), so it is never stored here.
+ */
+export declare function assertImportSupported(venue: VenueId, network: Network): void;
 /** Venues whose import cannot be checked against the venue (stored as "unverified"). */
 export declare const UNVERIFIED_IMPORT_VENUES: readonly VenueId[];
 /**

package/dist/commands/agent-import.js

@@ -24,7 +24,8 @@
 import chalk from "chalk";
 import { PerpError, classifyError } from "../errors.js";
 import { acquireLock, releaseLock, getAgent, setAgent, deleteAgent, listAgents, agentNetworkOf, agentSourceOf, getVenueAgent, setVenueAgent, deleteVenueAgent, } from "../agent-wallet/store.js";
-import { getVenue, networkConfig } from "../exchanges/venue.js";
+import { getVenue, networkConfig, roleUnsupported } from "../exchanges/venue.js";
+import { unsupported } from "../exchanges/trading-v2.js";
 import { LIGHTER_RH_RESERVED_KEY_INDEXES } from "../exchanges/venues/lighter-family.js";
 import { loadOws } from "../signer/ows-loader.js";
 import { defaultAgentName, isLighterFamilyVenue, parseExpiresIn, promptHidden, qfexWithdrawKeyWarning } from "./agent.js";
@@ -67,6 +68,11 @@ export function importSecretLabel(venue) {
         case "arcus": return "Arcus API key private key (Ed25519)";
         case "ondo": return "Ondo API secret";
         case "qfex": return "QFEX API secret";
+        case "risex": return "RISEx signer private key";
+        case "txflow": return "TxFlow key (not supported)";
+        case "variational": return "Variational key (not supported)";
+        case "grvt": return "GRVT key (not supported)";
+        case "extended": return "Extended key (not supported)";
     }
 }
 /**
@@ -154,6 +160,20 @@ function redacted(err, secrets, venue) {
         details.remediation = scrub(e.remediation, forms);
     return new PerpError(e.code, scrub(e.message, forms), details);
 }
+/**
+ * Venues whose keys cannot be imported. TxFlow: market-data-only (unofficial read-only API).
+ * RISEx: perp-cli trades only with a signer it registered itself and then restricted ON-CHAIN to
+ * the trading permission; a signer created in the RISEx app keeps every permission (including
+ * deposit / withdraw), so it is never stored here.
+ */
+export function assertImportSupported(venue, network) {
+    const def = getVenue(venue);
+    if (!def.roles.includes("trading"))
+        throw roleUnsupported(def, "agentImport");
+    if (venue === "risex") {
+        throw unsupported("risex", "agentImport", "perp-cli only uses RISEx signers it registered and restricted on-chain to trading-only permissions; an app-created signer keeps deposit / withdraw permissions", `Register a restricted signer with your master wallet: perp${network === "testnet" ? " -n testnet" : ""} wallet agent approve risex --master <ows-wallet>`);
+    }
+}
 /** Venues whose import cannot be checked against the venue (stored as "unverified"). */
 export const UNVERIFIED_IMPORT_VENUES = ["pacifica"];
 /**
@@ -722,6 +742,8 @@ async function importQfex(p, agentName, s, replacing) {
  * appears in a thrown error.
  */
 export async function importVenueAgent(p) {
+    // Refused before the secret is even inspected (nothing read, stored or sent).
+    assertImportSupported(p.venue, p.network);
     const secrets = secretsOf(p.secret);
     if (secrets.some(x => x.trim().length === 0))
         throw new PerpError("INVALID_PARAMS", "Empty key — nothing was imported");
@@ -751,6 +773,13 @@ export async function importVenueAgent(p) {
             case "lighter":
             case "lighter-rh":
                 return await importLighter(p, p.venue, agentName, key, replacing);
+            case "risex":
+            case "txflow":
+            case "variational":
+            case "grvt":
+            case "extended":
+                // Unreachable: assertImportSupported() refused these before the lock.
+                throw new PerpError("CAPABILITY_UNSUPPORTED", `${p.venue} keys cannot be imported`);
         }
     }
     catch (err) {

package/dist/commands/agent.d.ts

@@ -1,5 +1,5 @@
 import { Command, Option } from "commander";
-import { loadSettings, type OndoAgentMeta, type ArcusAgentMeta, type QfexAgentMeta } from "../settings.js";
+import { loadSettings, type OndoAgentMeta, type ArcusAgentMeta, type QfexAgentMeta, type RisexAgentMeta } from "../settings.js";
 import "../exchanges/venues/index.js";
 import type { Network, VenueId } from "../exchanges/venue-types.js";
 import { type LighterVenueId } from "../exchanges/venues/lighter-family.js";
@@ -27,7 +27,7 @@ export interface VerifyResult {
 /** Extract the agent list from a Pacifica /agent/list envelope; throws on an unrecognized shape. */
 export declare function parsePacAgentList(json: unknown): unknown[];
 /**
- * Confirmation of the account a QFEX key was resolved to (design §14.12 #9). In a terminal: a
+ * Confirmation of the account a QFEX key was resolved to. In a terminal: a
  * y/N prompt showing the UUID. Without one (piped stdin, --json): only an explicit --account-id
  * that equals the resolved account counts — the resolved UUID is printed on stderr either way.
  */
@@ -94,6 +94,9 @@ export type ApproveAgentOutcome = {
 } | {
     venue: "arcus";
     meta: ArcusAgentMeta;
+} | {
+    venue: "risex";
+    meta: RisexAgentMeta;
 } | {
     venue: LighterVenueId;
     agentName: string;
@@ -131,7 +134,7 @@ export declare function qfexWithdrawKeyWarning(meta: Pick<QfexAgentMeta, "agentN
 /** Venues `wallet agent rotate` (and `approve --rotate`) can rotate. */
 type RotatableVenue = "aster" | "hyperliquid" | "pacifica" | LighterVenueId;
 type RotatedAgentOutcome = Exclude<ApproveAgentOutcome, {
-    venue: "ondo" | "arcus";
+    venue: "ondo" | "arcus" | "risex";
 }>;
 export interface RotateAgentParams {
     exchange: RotatableVenue;