perp-cli 0.14.2 → 0.15.0

package/dist/commands/trade.js

@@ -1,5 +1,5 @@
 import { networkOf, supportsDryRun } from "../cli-flags.js";
-import { printJson, errorAndExit, withJsonErrors, jsonOk, jsonError, symbolMatch, formatUsd, formatOrderResult, orderResultJson } from "../utils.js";
+import { printJson, errorAndExit, withJsonErrors, jsonOk, jsonError, symbolMatch, formatUsd, formatOrderResult, orderResultJson, normalizeSymbolArg } from "../utils.js";
 import { ERROR_CODES, extractErrorMessage, isDefiniteOrderFailure, parsePositiveDecimal, PerpError } from "../errors.js";
 import { logExecution } from "../execution-log.js";
 import { validateTrade, enforceOrderRisk } from "../trade-validator.js";
@@ -24,9 +24,10 @@ import { resolveAdapterSlippage, resolveSlippage } from "../exchanges/slippage.j
 import { exactUnits, floorSize, floorToStep, lotStepOf, unitsToString } from "../exchanges/precision.js";
 import { isSpotOpenOrdersCapable } from "../exchanges/spot-interface.js";
 import { builderPlanFor } from "../exchanges/builder-fee.js";
+import { registerPacificaOrderCommands } from "./pacifica-orders.js";
 import { HL_MIN_ORDER_VALUE_USD } from "../constants.js";
 import { defaultSpotQuote, readSpotQuoteAvailableFresh, requireSpotAdapter, requireSpotDefinition, transferQuoteToPerp, transferQuoteToSpot, transferShortfallError } from "../exchanges/spot-factory.js";
-// ── Uniform order surface (design §13) ──
+// ── Uniform order surface ──
 //
 // Every venue's trade market/buy/sell/limit/stop/edit/cancel goes through TradingV2:
 // native on ondo/arcus, the legacy wrapper (exchanges/legacy-trading-v2.ts) on
@@ -34,7 +35,7 @@ import { defaultSpotQuote, readSpotQuoteAvailableFresh, requireSpotAdapter, requ
 // shape (OrderResult + execution), one printer.
 /** Families with the legacy smart-order path (--smart: IOC at best book ± 1 tick). */
 const LEGACY_ORDER_FAMILIES = new Set(["pacifica", "hyperliquid", "lighter", "aster"]);
-/** Common default time-in-force for every venue (design §13.3; venues map GTC internally, e.g. GTT). */
+/** Common default time-in-force for every venue (venues map GTC internally, e.g. GTT). */
 const DEFAULT_TIF = "GTC";
 function tradingVenueOf(adapter) {
     const def = getVenue(adapter.name);
@@ -43,7 +44,7 @@ function tradingVenueOf(adapter) {
 function isLegacyOrderVenue(def) {
     return LEGACY_ORDER_FAMILIES.has(def.family);
 }
-function parseSlippageBpsFlag(raw) {
+export function parseSlippageBpsFlag(raw) {
     if (raw === undefined)
         return null;
     const n = Number(raw);
@@ -68,11 +69,13 @@ const V2_CLIENT_ID_RULES = {
     pacifica: { re: PACIFICA_UUID_RE, desc: "a full UUID, e.g. f47ac10b-58cc-4372-a567-0e02b2c3d479" },
     hyperliquid: { re: HL_CLOID_RE, desc: "a 128-bit hex cloid: 0x + 32 lowercase hex chars, e.g. 0x1234567890abcdef1234567890abcdef (or --auto-id)" },
     aster: { re: ASTER_CLIENT_ID_RE, desc: "1-36 chars of A-Z a-z 0-9 . : / _ -" },
+    // uint64 decimal (range checked by the adapter).
+    risex: { re: /^[1-9][0-9]{0,19}$/, desc: "a decimal integer from 1 to 2^64 - 1" },
 };
 /**
  * Venues whose client order ids perp-cli GENERATES and never takes from the user: QFEX ids are
  * not unique on the venue, so a reused id would attribute another order's fills / cancels to
- * this one (design §14.12 #4c). --auto-id still works (the generated id is reported).
+ * this one (c). --auto-id still works (the generated id is reported).
  */
 const GENERATED_CLIENT_ID_ONLY = new Set(["qfex"]);
 function validateV2ClientId(def, id) {
@@ -111,7 +114,7 @@ function v2ClientOrderId(def, caps, userId) {
  * --auto-id: venue-format id where the venue has client ids; a venue without them refuses it
  * (v2ClientOrderId — the locally generated id is never sent).
  * Ondo / Pacifica limit orders: undefined — the adapter generates its own id, which encodes
- * post-only (Ondo) / the TIF (Pacifica) for a later edit (design §13.10 #10, #11); the result
+ * post-only (Ondo) / the TIF (Pacifica) for a later edit; the result
  * reports that id. A Pacifica market order has no generated id, so --auto-id sends a UUID.
  * Generated-only venues (qfex): undefined — v2ClientOrderId generates the venue id itself.
  */
@@ -314,7 +317,7 @@ function positionTpSlAdapter(adapter) {
     }
     return adapter;
 }
-/** Refuse when position-level TP/SL orders already exist (never overwrite, §13.10 #12). */
+/** Refuse when position-level TP/SL orders already exist (never overwrite). */
 async function refuseExistingPositionTpSl(adapter, def, symbol) {
     const existing = await adapter.positionTpSlOrders(symbol);
     if (existing.length > 0) {
@@ -439,7 +442,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         logExecution({
             type: action.includes("split") ? "split_order" : action.includes("limit") ? "limit_order" : action.includes("stop") ? "stop_order" : action.includes("cancel") ? "cancel" : "market_order",
             exchange: details.exchange ?? "unknown",
-            symbol: (details.symbol ?? "").toUpperCase(),
+            symbol: normalizeSymbolArg(details.symbol ?? ""),
             side: details.side ?? "",
             size: String(details.size ?? details.totalUsd ?? "0"),
             price: details.price,
@@ -606,7 +609,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         console.log();
     }
     /**
-     * Validate an entry's --tp/--sl before anything is sent (design §13.10 #12): the venue has
+     * Validate an entry's --tp/--sl before anything is sent: the venue has
      * TP/SL, the entry opens (not reduce-only), separateOrders / positionLevel venues need an
      * immediate entry (market or IOC — a resting entry has no verified fill to size the legs to),
      * and the prices sit on the right sides of `ref`.
@@ -625,7 +628,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
     }
     /**
      * Place an entry carrying --tp/--sl — one meaning on every venue: protect THIS entry's
-     * verified fill (design §13.5, §13.10 #12).
+     * verified fill.
      *  - attached (ondo) / batchGroup (arcus): the venue attaches the legs to the entry.
      *  - separateOrders (hl, lighter, aster): entry fill VERIFIED (placePerpVerified: venue-final
      *    report cross-checked with the position delta), then reduce-only TP/SL triggers sized to it.
@@ -855,7 +858,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const s = side.toLowerCase();
         if (s !== "buy" && s !== "sell")
             errorAndExit("Side must be buy or sell");
-        const sym = symbol.toUpperCase();
+        const sym = normalizeSymbolArg(symbol);
         // ── Split execution branch ──
         if (opts.split) {
             // runSplitOrder has no reduce-only path — refuse rather than silently place opening orders.
@@ -888,7 +891,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         .option("--tp <price>", "Take-profit trigger protecting this entry's verified fill (every venue; separate-order venues need a market / IOC entry)")
         .option("--sl <price>", "Stop-loss trigger protecting this entry's verified fill (every venue; separate-order venues need a market / IOC entry)")
         .action(async (symbol, size, opts) => {
-        await runMarketOrder(symbol.toUpperCase(), "buy", size, opts);
+        await runMarketOrder(normalizeSymbolArg(symbol), "buy", size, opts);
     });
     supportsDryRun(trade.command("sell <symbol> <size>"))
         .description("Market sell (shortcut for: trade market <symbol> sell <size>)")
@@ -901,7 +904,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         .option("--tp <price>", "Take-profit trigger protecting this entry's verified fill (every venue; separate-order venues need a market / IOC entry)")
         .option("--sl <price>", "Stop-loss trigger protecting this entry's verified fill (every venue; separate-order venues need a market / IOC entry)")
         .action(async (symbol, size, opts) => {
-        await runMarketOrder(symbol.toUpperCase(), "sell", size, opts);
+        await runMarketOrder(normalizeSymbolArg(symbol), "sell", size, opts);
     });
     // ── Split Order (orderbook-aware) ──
     supportsDryRun(trade.command("split <symbol> <side> <usd>"))
@@ -912,7 +915,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         .option("--min-slice <usd>", "Minimum slice size in USD", "100")
         .option("--force", "Bypass local risk-limit checks (maxPosition / total exposure)")
         .action(async (symbol, side, usd, opts) => {
-        const sym = symbol.toUpperCase();
+        const sym = normalizeSymbolArg(symbol);
         const orderSide = side.toLowerCase();
         const totalUsd = parseFloat(usd);
         if (!["buy", "sell"].includes(orderSide))
@@ -946,7 +949,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const s = side.toLowerCase();
         if (s !== "buy" && s !== "sell")
             errorAndExit("Side must be buy or sell");
-        const sym = symbol.toUpperCase();
+        const sym = normalizeSymbolArg(symbol);
         // One parsed size for the risk check and the order ("1,000" / "abc" refused up front).
         const size = parsePositiveDecimal(rawSize, "size");
         if (opts.clientId && isOrderDuplicate(opts.clientId)) {
@@ -1062,7 +1065,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         };
         if (orderId) {
             // cancel <symbol> <orderId>
-            await cancelOne(symbolOrOrderId.toUpperCase(), orderId);
+            await cancelOne(normalizeSymbolArg(symbolOrOrderId), orderId);
             return;
         }
         // Single argument — an order reference (c:<clientOrderId>, numeric / UUID / 0x-hex order id)
@@ -1095,7 +1098,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             return;
         }
         // cancel <symbol> — cancel all open orders for this symbol
-        const symbol = symbolOrOrderId.toUpperCase();
+        const symbol = normalizeSymbolArg(symbolOrOrderId);
         const orders = await adapter.getOpenOrders();
         const matching = orders.filter((o) => symbolMatch(o.symbol, symbol));
         if (matching.length === 0) {
@@ -1167,16 +1170,16 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             const bgAdapter = await getAdapter();
             const exchange = bgAdapter.name;
             // Risk check (and its --force bypass) runs here: the child `strategy twap` has none.
-            await openingOrderGate(bgAdapter, { symbol: symbol.toUpperCase(), size: Number(size), reduceOnly: opts.reduceOnly, force: opts.force });
+            await openingOrderGate(bgAdapter, { symbol: normalizeSymbolArg(symbol), size: Number(size), reduceOnly: opts.reduceOnly, force: opts.force });
             const cliArgs = [
-                "strategy", "twap", symbol.toUpperCase(), s, size, duration,
+                "strategy", "twap", normalizeSymbolArg(symbol), s, size, duration,
                 ...(opts.slices ? ["--slices", opts.slices] : []),
                 ...(opts.reduceOnly ? ["--reduce-only"] : []),
             ];
             const job = startJob({
                 strategy: "twap",
                 exchange,
-                params: { symbol: symbol.toUpperCase(), side: s, size, duration, slices: opts.slices, reduceOnly: opts.reduceOnly === true },
+                params: { symbol: normalizeSymbolArg(symbol), side: s, size, duration, slices: opts.slices, reduceOnly: opts.reduceOnly === true },
                 venue: exchange, network: networkOf(program), dryRun: isDryRun(), selectors: jobSelectorsOf(program),
                 cliArgs,
             });
@@ -1190,17 +1193,17 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             return;
         }
         const adapter = await getAdapter();
-        await openingOrderGate(adapter, { symbol: symbol.toUpperCase(), size: Number(size), reduceOnly: opts.reduceOnly, force: opts.force });
+        await openingOrderGate(adapter, { symbol: normalizeSymbolArg(symbol), size: Number(size), reduceOnly: opts.reduceOnly, force: opts.force });
         // Native TWAP: Pacifica (SDK) or Hyperliquid (twapOrder)
         // Fallback: client-side TWAP for any exchange without native support
         let result;
         if (hasPacificaSdk(adapter)) {
-            // One slippage resolver (design §13.2): bps → Pacifica's slippage_percent.
+            // One slippage resolver: bps → Pacifica's slippage_percent.
             const slippage = resolveAdapterSlippage(adapter, parseSlippageBpsFlag(opts.slippageBps));
             requirePacificaTwapSigner(adapter, "TWAP order");
             const sdk = adapter.sdk;
             result = await sdk.createTWAP({
-                symbol: symbol.toUpperCase(),
+                symbol: normalizeSymbolArg(symbol),
                 amount: size,
                 side: s === "buy" ? "bid" : "ask",
                 slippage_percent: String(slippage.bps / 100),
@@ -1213,13 +1216,13 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             if (!/^\d+$/.test(duration.trim()))
                 errorAndExit("HL TWAP duration must be a whole number of minutes");
             const minutes = Number(duration.trim());
-            result = await adapter.twapOrder(symbol.toUpperCase(), s, size, minutes, { reduceOnly: opts.reduceOnly });
+            result = await adapter.twapOrder(normalizeSymbolArg(symbol), s, size, minutes, { reduceOnly: opts.reduceOnly });
         }
         else {
             // Client-side TWAP (foreground) for exchanges without native TWAP
             const { runTWAP } = await import("../strategies/twap.js");
             const twapResult = await runTWAP(adapter, {
-                symbol: symbol.toUpperCase(),
+                symbol: normalizeSymbolArg(symbol),
                 side: s,
                 totalSize: parseFloat(size),
                 durationSec: parseInt(duration),
@@ -1233,7 +1236,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         }
         if (isJson())
             return printJson(jsonOk(result));
-        console.log(chalk.green(`\n  TWAP ${s.toUpperCase()} ${size} ${symbol.toUpperCase()} over ${duration} placed on ${adapter.name}.\n`));
+        console.log(chalk.green(`\n  TWAP ${s.toUpperCase()} ${size} ${normalizeSymbolArg(symbol)} over ${duration} placed on ${adapter.name}.\n`));
     });
     // === Stop / Trigger orders (every trading venue) ===
     supportsDryRun(trade.command("stop <symbol> <side> <size> <stopPrice>"))
@@ -1251,7 +1254,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         if (opts.triggerType && !["mark", "last", "mid"].includes(opts.triggerType)) {
             errorAndExit("--trigger-type must be one of: mark, last, mid");
         }
-        const sym = symbol.toUpperCase();
+        const sym = normalizeSymbolArg(symbol);
         const adapter = await getAdapter();
         const { def: venueDef, caps: venueCaps } = tradingVenueOf(adapter);
         const isLimit = opts.limitPrice !== undefined;
@@ -1317,7 +1320,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const tpLimit = positivePriceOpt(opts.tpLimit, "--tp-limit");
         if (tpLimit !== null && prices.tp === null)
             throw new PerpError("INVALID_PARAMS", "--tp-limit needs --tp");
-        const sym = symbol.toUpperCase();
+        const sym = normalizeSymbolArg(symbol);
         const adapter = await getAdapter();
         const { def, caps } = tradingVenueOf(adapter);
         if (caps.tpsl === null) {
@@ -1419,7 +1422,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         .requiredOption("--levels <levels>", "[required] Comma-separated price:percent pairs (e.g., 72000:25,75000:25,80000:50)")
         .option("--size <size>", "Override total position size (default: uses current position)")
         .action(async (symbol, opts) => {
-        const sym = symbol.toUpperCase();
+        const sym = normalizeSymbolArg(symbol);
         const adapter = await getAdapter();
         if (adapter.name === "ondo") {
             // docs.ondoperps.xyz take-profit-and-stop-loss: position TP/SL "Via Risk Management Module
@@ -1496,9 +1499,9 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const amendTif = opts.tif !== undefined ? validateLegacyTif(venueDef, venueCaps, opts.tif) : null;
         if (opts.forceTif === true && amendTif === null)
             throw new PerpError("INVALID_PARAMS", "--force-tif needs --tif");
-        if (dryRunGuard("edit_order", { exchange: adapter.name, symbol: symbol.toUpperCase(), orderId, price, size }))
+        if (dryRunGuard("edit_order", { exchange: adapter.name, symbol: normalizeSymbolArg(symbol), orderId, price, size }))
             return;
-        const result = await v2Of(adapter).amendOrder({ symbol: symbol.toUpperCase(), ref: parseOrderRef(orderId), price, size, tif: amendTif, forceTif: opts.forceTif === true });
+        const result = await v2Of(adapter).amendOrder({ symbol: normalizeSymbolArg(symbol), ref: parseOrderRef(orderId), price, size, tif: amendTif, forceTif: opts.forceTif === true });
         if (isJson())
             return printJson(jsonOk(orderResultJson(result)));
         printOrder(`Edit of ${orderId} → $${price} x ${size} on ${adapter.name}`, result);
@@ -1510,7 +1513,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const adapter = await getAdapter();
         if (adapter.name === "qfex" && isTradingV2(adapter)) {
             // QFEX: cancelByRef reads the row first and routes a TAKE_PROFIT / STOP_LOSS row to cancel_stop_order.
-            const sym = symbol.toUpperCase();
+            const sym = normalizeSymbolArg(symbol);
             if (dryRunGuard("cancel_stop", { exchange: adapter.name, symbol: sym, stopOrderId }))
                 return;
             const r = await adapter.cancelByRef(sym, parseOrderRef(stopOrderId));
@@ -1528,7 +1531,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const pac = adapter;
         if (typeof pac.cancelStopOrder !== "function") {
             const { def } = tradingVenueOf(adapter);
-            throw unsupported(def.displayName, "cancelStop", "stop orders are cancelled like any other order on this venue", `Use: perp trade cancel ${symbol.toUpperCase()} <orderId> -e ${def.id}`);
+            throw unsupported(def.displayName, "cancelStop", "stop orders are cancelled like any other order on this venue", `Use: perp trade cancel ${normalizeSymbolArg(symbol)} <orderId> -e ${def.id}`);
         }
         const result = await pac.cancelStopOrder(symbol, stopOrderId);
         if (isJson())
@@ -1549,10 +1552,10 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         if (hasPacificaSdk(adapter)) {
             requirePacificaTwapSigner(adapter, "TWAP cancel");
             const sdk = adapter.sdk;
-            result = await sdk.cancelTWAP({ symbol: symbol.toUpperCase(), order_id: Number(twapOrderId) }, adapter.publicKey, adapter.signer);
+            result = await sdk.cancelTWAP({ symbol: normalizeSymbolArg(symbol), order_id: Number(twapOrderId) }, adapter.publicKey, adapter.signer);
         }
         else if (isTwapCapable(adapter)) {
-            result = await adapter.twapCancel(symbol.toUpperCase(), Number(twapOrderId));
+            result = await adapter.twapCancel(normalizeSymbolArg(symbol), Number(twapOrderId));
         }
         else {
             errorAndExit("Cancel TWAP requires --exchange pacifica or hyperliquid");
@@ -1561,6 +1564,8 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             return printJson(jsonOk(result));
         console.log(chalk.green(`\n  TWAP order ${twapOrderId} cancelled on ${adapter.name}.\n`));
     });
+    // === Pacifica-only order types (trade atomic) ===
+    registerPacificaOrderCommands(trade, getAdapter, isJson, isDryRun);
     // === Hyperliquid-only commands ===
     supportsDryRun(trade.command("leverage <symbol> <leverage>"))
         .description("Set leverage for a symbol")
@@ -1574,22 +1579,22 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const lev = Number(leverage.trim());
         const adapter = await getAdapter();
         const mode = opts.isolated ? "isolated" : "cross";
-        if (dryRunGuard("set_leverage", { exchange: adapter.name, symbol: symbol.toUpperCase(), leverage: lev, mode }))
+        if (dryRunGuard("set_leverage", { exchange: adapter.name, symbol: normalizeSymbolArg(symbol), leverage: lev, mode }))
             return;
         try {
-            const result = await adapter.setLeverage(symbol.toUpperCase(), lev, mode);
+            const result = await adapter.setLeverage(normalizeSymbolArg(symbol), lev, mode);
             logExecution({
-                type: "rebalance", exchange: adapter.name, symbol: symbol.toUpperCase(), side: mode,
+                type: "rebalance", exchange: adapter.name, symbol: normalizeSymbolArg(symbol), side: mode,
                 size: leverage, status: "success", dryRun: false,
                 meta: { action: "set_leverage", leverage: lev, mode },
             });
             if (isJson())
                 return printJson(jsonOk(result));
-            console.log(chalk.green(`\n  Leverage set to ${leverage}x (${mode}) for ${symbol.toUpperCase()} on ${adapter.name}.\n`));
+            console.log(chalk.green(`\n  Leverage set to ${leverage}x (${mode}) for ${normalizeSymbolArg(symbol)} on ${adapter.name}.\n`));
         }
         catch (err) {
             logExecution({
-                type: "rebalance", exchange: adapter.name, symbol: symbol.toUpperCase(), side: mode,
+                type: "rebalance", exchange: adapter.name, symbol: normalizeSymbolArg(symbol), side: mode,
                 size: leverage, status: "failed", dryRun: false,
                 error: extractErrorMessage(err),
                 meta: { action: "set_leverage", leverage: lev, mode },
@@ -1598,7 +1603,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         }
     });
     /**
-     * One verified reduce-only close (design §12.3, §13.10 #4): closePerpVerified (placePerpVerified
+     * One verified reduce-only close: closePerpVerified (placePerpVerified
      * + one residual market close), so the reported `closed` is a measured / venue-final fill, never
      * the requested size. Logged "success" only when fully verified. A residual or an unknown outcome
      * quarantines the symbol (CLI path "trade-close"); a definite rejection propagates unchanged.
@@ -1723,7 +1728,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         .option("--slippage-bps <n>", "Slippage bound in bps (default: settings defaultSlippageBps)")
         .action(async (symbol, opts) => {
         await withJsonErrors(isJson(), async () => {
-            const sym = symbol.toUpperCase();
+            const sym = normalizeSymbolArg(symbol);
             const adapter = await getAdapter();
             refuseGatedReduceOnly(adapter);
             const slippage = resolveAdapterSlippage(adapter, parseSlippageBpsFlag(opts.slippageBps));
@@ -1805,7 +1810,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         .option("--slippage-bps <n>", "Slippage bound in bps (default: settings defaultSlippageBps)")
         .action(async (symbol, percent, opts) => {
         await withJsonErrors(isJson(), async () => {
-            const sym = symbol.toUpperCase();
+            const sym = normalizeSymbolArg(symbol);
             const pct = parseFloat(percent);
             if (isNaN(pct) || pct <= 0 || pct > 100)
                 errorAndExit("Percent must be between 0 and 100");
@@ -1864,7 +1869,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                         remediation: `Pass --symbol <SYM>: perp trade status ${orderId} --symbol <SYM> -e ${adapter.venue.id}`,
                     });
                 }
-                const r = await adapter.getOrderStatus(opts.symbol.toUpperCase(), parseOrderRef(orderId));
+                const r = await adapter.getOrderStatus(normalizeSymbolArg(opts.symbol), parseOrderRef(orderId));
                 if (isJson())
                     return printJson(jsonOk(orderResultJson(r)));
                 printOrder(`Order ${orderId} (${r.symbol}) on ${adapter.name}`, r);
@@ -1885,7 +1890,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                         remediation: `Pass --symbol <SYM>: perp trade status ${orderId} --symbol <SYM> -e ${def.id}`,
                     });
                 }
-                const r = await v2Of(adapter).getOrderStatus(opts.symbol !== undefined ? opts.symbol.toUpperCase() : "", ref);
+                const r = await v2Of(adapter).getOrderStatus(opts.symbol !== undefined ? normalizeSymbolArg(opts.symbol) : "", ref);
                 if (isJson())
                     return printJson(jsonOk(orderResultJson(r)));
                 printOrder(`Order ${orderId} (${r.symbol}) on ${adapter.name}`, r);
@@ -1947,13 +1952,13 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             const trades = await adapter.getTradeHistory(limit);
             let filtered = trades;
             if (symbol) {
-                const sym = symbol.toUpperCase();
+                const sym = normalizeSymbolArg(symbol);
                 filtered = trades.filter(t => symbolMatch(t.symbol, sym));
             }
             if (isJson())
                 return printJson(jsonOk(filtered));
             if (filtered.length === 0) {
-                console.log(chalk.gray(`\n  No fills${symbol ? ` for ${symbol.toUpperCase()}` : ""}.\n`));
+                console.log(chalk.gray(`\n  No fills${symbol ? ` for ${normalizeSymbolArg(symbol)}` : ""}.\n`));
                 return;
             }
             const rows = filtered.map((t) => [
@@ -1982,7 +1987,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                 errorAndExit("Side must be buy or sell");
             const adapter = await getAdapter();
             const validation = await validateTrade(adapter, {
-                symbol: symbol.toUpperCase(),
+                symbol: normalizeSymbolArg(symbol),
                 side: s,
                 size: parseFloat(size),
                 price: opts.price ? parseFloat(opts.price) : undefined,
@@ -1992,7 +1997,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             });
             if (isJson())
                 return printJson(jsonOk(validation));
-            console.log(chalk.cyan.bold(`\n  Pre-Trade Check: ${symbol.toUpperCase()} ${s.toUpperCase()} ${size}\n`));
+            console.log(chalk.cyan.bold(`\n  Pre-Trade Check: ${normalizeSymbolArg(symbol)} ${s.toUpperCase()} ${size}\n`));
             for (const check of validation.checks) {
                 const icon = check.passed ? chalk.green("✓") : chalk.red("✗");
                 console.log(`  ${icon} ${check.check}: ${check.message}`);
@@ -2023,7 +2028,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         .option("--size <base>", "Total base amount (e.g., 0.01 BTC)")
         .option("--force", "Bypass local risk-limit checks (maxPosition / total exposure)")
         .action(async (symbol, side, opts) => {
-        const sym = symbol.toUpperCase();
+        const sym = normalizeSymbolArg(symbol);
         const s = side.toLowerCase();
         if (s !== "buy" && s !== "sell")
             errorAndExit("Side must be buy or sell");
@@ -2174,7 +2179,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         }
         console.log(chalk.yellow(`\n  PnL tracker stopped.\n`));
     });
-    // === Spot Trading (venue definitions, design §12) ===
+    // === Spot Trading (venue definitions) ===
     /** Spot adapter for the current venue via the factory; CAPABILITY_UNSUPPORTED when def.spot is null. */
     async function spotContext(confirmOnchainApprove) {
         const adapter = await getAdapter();
@@ -2186,7 +2191,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         const spot = await requireSpotAdapter(def.id, adapter, { confirmOnchainApprove });
         return { def, spotDef, spot };
     }
-    /** Uniform feature name per spot capability (§13.6). */
+    /** Uniform feature name per spot capability. */
     const SPOT_FEATURE = {
         limitOrder: "spotLimitOrder", orderbook: "spotOrderbook", cancel: "spotCancel", transfer: "spotTransfer",
     };
@@ -2255,7 +2260,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         console.log();
     }
     /**
-     * Execution record of a spot market order, same fields for every venue (design §13.8):
+     * Execution record of a spot market order, same fields for every venue:
      * the resolved bound (bps + source) and, where the adapter reports it, the protection
      * price actually sent and its reference (`protection` on the raw result / venueRaw).
      */
@@ -2332,7 +2337,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                 const slippageFlag = parseSlippageBpsFlag(opts.slippageBps);
                 const { def, spotDef, spot } = await spotContext(opts.yes === true);
                 const slippage = resolveSlippage(def.id, slippageFlag);
-                const sym = symbol.toUpperCase();
+                const sym = normalizeSymbolArg(symbol);
                 if (dryRunGuard(`spot ${verb}`, { exchange: def.id, symbol: sym, side, size }))
                     return;
                 const raw = await spot.spotMarketOrder(sym, side, size, { slippage });
@@ -2359,7 +2364,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
                 throw new PerpError("INVALID_PARAMS", `Side must be buy or sell (got "${side}")`);
             const { def, spotDef, spot } = await spotContext(false);
             requireSpotCapability(def, spotDef, "limitOrder", "limit orders");
-            const sym = symbol.toUpperCase();
+            const sym = normalizeSymbolArg(symbol);
             if (dryRunGuard("spot limit", { exchange: def.id, symbol: sym, side: s, price, size, tif: opts.tif ?? null }))
                 return;
             const raw = await spot.spotLimitOrder(sym, s, price, size, opts.tif !== undefined ? { tif: opts.tif } : undefined);
@@ -2379,7 +2384,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
         await withJsonErrors(isJson(), async () => {
             const { def, spotDef, spot } = await spotContext(false);
             requireSpotCapability(def, spotDef, "cancel", "order cancel");
-            const sym = symbol.toUpperCase();
+            const sym = normalizeSymbolArg(symbol);
             if (dryRunGuard("spot cancel", { exchange: def.id, symbol: sym, orderId }))
                 return;
             const result = spotCancelResult(def, sym, orderId, await spot.spotCancelOrder(sym, orderId));
@@ -2401,7 +2406,7 @@ export function registerTradeCommands(program, getAdapter, isJson, isDryRun = ()
             if (spotDef.accountModel === "wallet" || !isSpotOpenOrdersCapable(spot)) {
                 throw unsupported(def.displayName, "spotOpenOrders", spotDef.accountModel === "wallet" ? "spot is an on-chain swap that settles immediately — there are no resting orders" : "the spot adapter cannot list open orders", spotDef.accountModel === "wallet" ? `Check the wallet balance: perp -e ${def.id} trade spot-balance` : "Use the venue UI to inspect open spot orders");
             }
-            const orders = await spot.getSpotOpenOrders(symbol === undefined ? null : symbol.toUpperCase());
+            const orders = await spot.getSpotOpenOrders(symbol === undefined ? null : normalizeSymbolArg(symbol));
             if (isJson())
                 return printJson(jsonOk({ exchange: def.id, orders }));
             console.log(chalk.cyan(`\n  Open spot orders (${def.id}):\n`));
@@ -2520,7 +2525,7 @@ function parseMultiLeg(spec) {
     if (isNaN(Number(size)) || Number(size) <= 0) {
         throw new Error(`Invalid size "${size}" — must be a positive number`);
     }
-    return { exchange: normalizedExchange, symbol: symbol.toUpperCase(), side, size };
+    return { exchange: normalizedExchange, symbol: normalizeSymbolArg(symbol), side, size };
 }
 function registerMultiAction(parent, getAdapterForExchange, isJson, deprecated = false) {
     const cmd = parent

package/dist/commands/wallet.js

@@ -525,7 +525,7 @@ export function registerWalletCommands(program, isJson, getAdapter, getPacificaA
             const info = EXCHANGE_ENV_MAP[resolved];
             if (!info) {
                 throw new PerpError("INVALID_PARAMS", `Unknown exchange: ${exchange}`, {
-                    remediation: "Use: pacifica, hyperliquid, lighter, aster (or hl, pac, lt, ast). Lighter RH / Ondo / Arcus use: perp wallet agent approve <lighter-rh|ondo|arcus>; QFEX: perp wallet agent import qfex.",
+                    remediation: "Use: pacifica, hyperliquid, lighter, aster (or hl, pac, lt, ast). Lighter RH / Ondo / Arcus use: perp wallet agent approve <lighter-rh|ondo|arcus>; QFEX: perp wallet agent import qfex. TxFlow, Variational and Extended are market data only; RISEx is read-only in this release (trading later).",
                 });
             }
             const { promptHidden } = await import("./agent.js");

package/dist/config.d.ts

@@ -1,7 +1,7 @@
 import { Keypair } from "@solana/web3.js";
 import type { Network, VenueId } from "./exchanges/venue-types.js";
 import type { VenueCredentials } from "./exchanges/venue.js";
-/** @deprecated alias — every venue id is an exchange id (design §10.3). */
+/** @deprecated alias — every venue id is an exchange id. */
 export type Exchange = VenueId;
 /** CLI (and MCP) inputs that select credentials. Absent flag = null. */
 export interface CliCredentialOpts {
@@ -27,7 +27,7 @@ export declare function resolveOwsWallet(walletName: string): string | null;
 export declare function isOwsKey(key: string): boolean;
 /** Extract OWS wallet name from an ows: prefixed key string. */
 export declare function getOwsWalletName(key: string): string;
-/** CLI/MCP-shared credential resolution (design §10.2). */
+/** CLI/MCP-shared credential resolution. */
 export declare function resolveCredentials(venue: VenueId, opts: CliCredentialOpts, network: Network): Promise<VenueCredentials>;
 /**
  * Whether any credential source is configured for the venue (explicit checks,

package/dist/config.js

@@ -8,7 +8,7 @@ import { PerpError } from "./errors.js";
 import { isLegacyVenueId } from "./exchanges/venue-types.js";
 const _require = createRequire(import.meta.url);
 /**
- * Legacy env private-key variables (design §10.3). New venues have no env tier:
+ * Legacy env private-key variables. New venues have no env tier:
  * loadPrivateKey()/resolveCredentials() never read env keys for them.
  * v0.12.10 restored ASTER_PRIVATE_KEY so Aster Tier 3 env-PK loading works.
  */
@@ -50,7 +50,7 @@ function envKeyOf(venue) {
         if (v)
             return v;
     }
-    // config.ts generic PRIVATE_KEY — recorded as out of scope in §10.11, legacy venues only.
+    // config.ts generic PRIVATE_KEY — out of scope (legacy venues only).
     const generic = process.env.PRIVATE_KEY;
     return generic ? generic : null;
 }
@@ -106,6 +106,12 @@ async function agentOf(venue) {
         case "ondo": return store.getVenueAgent("ondo");
         case "arcus": return store.getVenueAgent("arcus");
         case "qfex": return store.getVenueAgent("qfex");
+        case "risex": return store.getVenueAgent("risex");
+        // Market-data-only venues: no agent.
+        case "txflow": return null;
+        case "variational": return null;
+        case "grvt": return null;
+        case "extended": return null;
         case "pacifica":
         case "hyperliquid":
         case "lighter":
@@ -125,6 +131,11 @@ async function agentForNetwork(venue, network) {
         case "ondo": return store.getVenueAgentForNetwork("ondo", network);
         case "arcus": return store.getVenueAgentForNetwork("arcus", network);
         case "qfex": return store.getVenueAgentForNetwork("qfex", network);
+        case "risex": return store.getVenueAgentForNetwork("risex", network);
+        case "txflow": return null;
+        case "variational": return null;
+        case "grvt": return null;
+        case "extended": return null;
         case "pacifica":
         case "hyperliquid":
         case "lighter":
@@ -151,11 +162,11 @@ function owsPassphraseOf(opts) {
 function owsKeyTokenOf(opts) {
     if (opts.owsKey !== null)
         return opts.owsKey;
-    // OWS_API_KEY env: recorded as out of scope in §10.11 (kept as before).
+    // OWS_API_KEY env: recorded as out of scope in (kept as before).
     const env = process.env.OWS_API_KEY;
     return env ? env : null;
 }
-/** CLI/MCP-shared credential resolution (design §10.2). */
+/** CLI/MCP-shared credential resolution. */
 export async function resolveCredentials(venue, opts, network) {
     const withToken = { ...opts, owsKey: owsKeyTokenOf(opts) };
     // Custodial venues (masterKeyKind "none": qfex) have no master key to resolve.

package/dist/constants.js

@@ -28,6 +28,11 @@ export const TAKER_FEES = {
     // orders (0.05%) are never under-estimated. Lower tiers / the lifetime-tier promotion: set
     // settings.fees.qfex.
     qfex: 0.001,
+    // RISEx Tier 1 ($0 rolling 14-day volume; docs.risechain.com/docs/risex/trading/fees, read
+    // 2026-10-14): taker 3.00 bps, maker 1.00 bps; higher tiers down to 1.50 / 0.00 bps — set
+    // settings.fees.risex for a higher tier.
+    risex: 0.0003,
+    // TxFlow: no trading in perp-cli (market data only) — no fee entry on purpose.
 };
 /**
  * Published maker fee per venue (fraction; negative = rebate). Only venues whose base-tier
@@ -41,6 +46,7 @@ export const MAKER_FEES = {
     aster: 0,
     "lighter-rh": 0, // Standard tier (Premium: 0.012% under $1M 14-day volume)
     qfex: 0.0005, // Tier 5 single stocks 0.05% (indices / commodities 0.02%); see TAKER_FEES.qfex
+    risex: 0.0001, // Tier 1 maker 1.00 bps; see TAKER_FEES.risex
 };
 /**
  * Taker fee for a venue: settings.fees[venue].taker → TAKER_FEES[venue] → DEFAULT_TAKER_FEE

package/dist/dashboard/server.js

@@ -100,7 +100,7 @@ async function pollArbData() {
             const row = {
                 base,
                 dexes: assets.map((a) => {
-                    // Venue ref: "hyperliquid" for native, "hl:<dex>" for HIP-3 (same basis, §10.1)
+                    // Venue ref: "hyperliquid" for native, "hl:<dex>" for HIP-3 (same basis)
                     const ann = annualizeRate(a.fundingRate, a.dex === "hl" ? "hyperliquid" : `hl:${a.dex}`);
                     return { dex: a.dex, rate: a.fundingRate, annualizedPct: ann, markPrice: a.markPrice, oi: a.openInterest };
                 }),

package/dist/dashboard/ui.js

@@ -334,7 +334,7 @@ function renderPanels(exchanges) {
         return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${dex}</td>\`:''}<td>\${sym}</td><td class="side-\${o.side}">\${o.side.toUpperCase()}</td><td>\${o.type}</td><td>$\${fmt(o.price)}</td><td>\${o.size}</td><td>\${o.filled}</td><td>\${o.status}</td></tr>\`;
       }).join('')}</tbody></table>\`:(ordKnown?'<div class="empty-msg">No open orders</div>':'<div class="empty-msg">Open orders '+NA+'</div>')}
       <div class="section-title">Markets (Top 10)</div>
-      \${ex.topMarkets.length?\`<table><thead><tr><th>Symbol</th><th>Mark</th><th>Index</th><th>Funding</th><th>24h Vol</th><th>OI</th><th>Max Lev</th></tr></thead><tbody>\${ex.topMarkets.map(m=>{const fr=Number(m.fundingRate);return\`<tr><td>\${m.symbol}</td><td>$\${fmt(m.markPrice)}</td><td>\${usdOrDash(m.indexPrice)}</td><td class="\${rateClass(fr)}">\${(fr*100).toFixed(4)}%</td><td>\${usdOrDash(m.volume24h,0)}</td><td>\${usdOrDash(m.openInterest,0)}</td><td>\${m.maxLeverage}x</td></tr>\`;}).join('')}</tbody></table>\`:'<div class="empty-msg">No market data</div>'}
+      \${ex.topMarkets.length?\`<table><thead><tr><th>Symbol</th><th>Mark</th><th>Index</th><th>Funding</th><th>24h Vol</th><th>OI</th><th>Max Lev</th></tr></thead><tbody>\${ex.topMarkets.map(m=>{const fr=Number(m.fundingRate);return\`<tr><td>\${m.symbol}</td><td>$\${fmt(m.markPrice)}</td><td>\${usdOrDash(m.indexPrice)}</td><td class="\${rateClass(fr)}">\${(fr*100).toFixed(4)}%</td><td>\${usdOrDash(m.volume24h,0)}</td><td>\${usdOrDash(m.openInterest,0)}</td><td>\${m.maxLeverage==null?'-':m.maxLeverage+'x'}</td></tr>\`;}).join('')}</tbody></table>\`:'<div class="empty-msg">No market data</div>'}
     </div>\`;
   }).join('');