perp-cli 0.14.3 → 0.16.0

package/dist/commands/account.js

@@ -1,9 +1,14 @@
 import { listConfiguredAccountVenues } from "../config.js";
-import { makeTable, formatUsd, formatPnl, printJson, jsonOk, jsonError, symbolMatch } from "../utils.js";
+import { makeTable, formatUsd, formatPnl, printJson, jsonOk, jsonError, symbolMatch, withJsonErrors } from "../utils.js";
 import chalk from "chalk";
 import { hasPacificaSdk, isDexCapable } from "../exchanges/capabilities.js";
 import { PerpError } from "../errors.js";
 import { unsupported } from "../exchanges/trading-v2.js";
+/** The configured Pacifica account of an account read; keyless → NO_SIGNER_AVAILABLE (never the throwaway keypair's). */
+function pacificaAccount(adapter) {
+    const read = adapter.accountForReads;
+    return typeof read === "function" ? read.call(adapter) : adapter.publicKey;
+}
 function pac(adapter) {
     if (!hasPacificaSdk(adapter))
         throw new Error("Market settings are only available on Pacifica.");
@@ -28,8 +33,14 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
     // user what to run and exit non-zero so scripts can detect the rename.
     account
         .command("balance")
-        .description("[renamed] Use 'perp portfolio' (exchange-aggregated) or 'perp portfolio -e <ex>'")
-        .action(async () => {
+        .description("Any account's balances by public address, keyless (--address). Your own balance: 'perp portfolio' (renamed in v0.12)")
+        .option("--address <address>", "Read this public address — keyless (hyperliquid, lighter, lighter-rh, risex: 0x address; pacifica: Solana address). Without -e: every venue that supports it")
+        .option("--account-index <n>", "With --address on Lighter: only this account (sub-account) of the address")
+        .action(async (opts) => {
+        if (opts.address !== undefined) {
+            const explicitExchange = program.getOptionValueSource?.("exchange") === "cli";
+            return void await withJsonErrors(isJson(), () => balanceByAddress(opts.address, explicitExchange ? String(program.opts().exchange) : null, opts));
+        }
         const msg = "'account balance' was renamed in v0.12 — use 'portfolio' instead.";
         const remediation = "perp portfolio                      # all exchanges\nperp portfolio -e <exchange>        # single exchange detail";
         if (isJson()) {
@@ -47,9 +58,8 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
     async function fetchHip3Data(hlAdapter, fetcher) {
         const dexes = await hlAdapter.listDeployedDexes();
         const results = await Promise.allSettled(dexes.map(async (d) => {
-            // Clone adapter with dex set
-            const dexAdapter = Object.create(hlAdapter);
-            dexAdapter.setDex(d.name);
+            // An independent per-dex adapter (a prototype copy + setDex emptied the native adapter's maps)
+            const dexAdapter = hlAdapter.forDex(d.name);
             const items = await fetcher(dexAdapter);
             return { dex: d.name, items };
         }));
@@ -58,12 +68,158 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
             .map(r => r.value)
             .filter(r => r.items.length > 0);
     }
+    /** `account balance --address`: keyless public read (registry: VenuePublicData.fetchBalanceByAddress). */
+    async function balanceByAddress(address, venue, opts) {
+        const { readBalanceByAddress, readBalanceByAddressAll } = await import("../balance-by-address.js");
+        const { networkOf } = await import("../cli-flags.js");
+        let accountIndex;
+        if (opts.accountIndex !== undefined) {
+            if (!/^\d+$/.test(opts.accountIndex.trim()))
+                throw new PerpError("INVALID_PARAMS", `--account-index must be a whole number, got "${opts.accountIndex}"`);
+            accountIndex = Number(opts.accountIndex);
+        }
+        const net = networkOf(program);
+        const balanceRows = (d) => {
+            const row = (label, b) => [
+                label, `$${formatUsd(b.equity)}`, `$${formatUsd(b.available)}`, `$${formatUsd(b.marginUsed)}`, formatPnl(b.unrealizedPnl),
+            ];
+            return [
+                ...(d.balance !== null ? [row(d.accountMode !== undefined ? `native (${d.accountMode})` : "account", d.balance)] : []),
+                ...(d.accounts ?? []).map(a => row(`account ${a.accountIndex}`, a.balance)),
+                ...Object.entries(d.dexes ?? {}).map(([dex, b]) => row(chalk.magenta(`dex ${dex}`), b)),
+            ];
+        };
+        const spotRows = (d) => [
+            ...(d.spot ?? []).map(s => ["-", s.token, s.total, s.available, s.held]),
+            ...(d.accounts ?? []).flatMap(a => a.spot.map(s => [String(a.accountIndex), s.token, s.total, s.available, s.held])),
+        ];
+        const extras = (d) => {
+            const b = d.balance;
+            if (b === null)
+                return [];
+            return ["usdcBalance", "borrowedUsdc", "pendingInterest", "availableToWithdraw"].filter(k => k in b).map(k => `${k}: ${b[k] === null ? "-" : String(b[k])}`);
+        };
+        const printVenue = (ex, d) => {
+            console.log(chalk.cyan.bold(`\n  ${ex}`));
+            const rows = balanceRows(d);
+            if (rows.length > 0)
+                console.log(makeTable(["Account", "Equity", "Available", "Margin Used", "uPnL"], rows));
+            const x = extras(d);
+            if (x.length > 0)
+                console.log(chalk.gray(`  ${x.join("  ")}`));
+            const sr = spotRows(d);
+            if (sr.length > 0)
+                console.log(makeTable(["Acct", "Spot token", "Total", "Available", "Held"], sr));
+            if (rows.length === 0 && sr.length === 0)
+                console.log(chalk.gray("  no balance (see notes)"));
+        };
+        if (venue !== null) {
+            const r = await readBalanceByAddress(venue, net, address, { accountIndex });
+            if (isJson()) {
+                return printJson(jsonOk({ exchange: r.venue, address, ...r.data }, {
+                    exchange: r.venue, address, source: "public",
+                    ...(r.warnings.length > 0 ? { warnings: r.warnings, errors: r.errors } : {}),
+                    ...(r.notes.length > 0 ? { notes: r.notes } : {}),
+                }));
+            }
+            for (const w of r.warnings)
+                console.log(chalk.yellow(`  ${w}`));
+            printVenue(r.venue, r.data);
+            for (const n of r.notes)
+                console.log(chalk.gray(`  ${n}`));
+            console.log();
+            return;
+        }
+        const all = await readBalanceByAddressAll(net, address, { accountIndex });
+        if (isJson()) {
+            return printJson(jsonOk({
+                venues: all.venues,
+                ...(Object.keys(all.errors).length > 0 ? { errors: all.errors } : {}),
+                ...(Object.keys(all.notes).length > 0 ? { notes: all.notes } : {}),
+            }, { address, source: "public", ...(all.warnings.length > 0 ? { warnings: all.warnings } : {}) }));
+        }
+        for (const [ex, d] of Object.entries(all.venues))
+            printVenue(ex, d);
+        console.log();
+        for (const [ex, e] of Object.entries(all.errors))
+            console.log(chalk.gray(`  ${ex}: ${e.code} ${e.message}`));
+        for (const [ex, n] of Object.entries(all.notes))
+            console.log(chalk.gray(`  ${ex}: ${n.join("; ")}`));
+    }
+    /** `account positions --address`: keyless public read (registry: VenuePublicData.fetchPositionsByAddress). */
+    async function positionsByAddress(address, venue, opts) {
+        const { readPositionsByAddress, readPositionsByAddressAll } = await import("../positions-by-address.js");
+        const { networkOf } = await import("../cli-flags.js");
+        let accountIndex;
+        if (opts.accountIndex !== undefined) {
+            if (!/^\d+$/.test(opts.accountIndex.trim()))
+                throw new PerpError("INVALID_PARAMS", `--account-index must be a whole number, got "${opts.accountIndex}"`);
+            accountIndex = Number(opts.accountIndex);
+        }
+        const net = networkOf(program);
+        const row = (p, ex) => [
+            chalk.white.bold(p.symbol),
+            ...(ex !== null ? [chalk.gray(ex)] : []),
+            p.dex != null ? chalk.magenta(p.dex) : p.accountIndex !== undefined ? chalk.gray(String(p.accountIndex)) : chalk.gray("-"),
+            p.side === "long" ? chalk.green("LONG") : chalk.red("SHORT"),
+            p.size,
+            `$${formatUsd(p.entryPrice)}`,
+            `$${formatUsd(p.markPrice)}`,
+            p.liquidationPrice === null ? chalk.gray("-") : `$${formatUsd(p.liquidationPrice)}`,
+            formatPnl(p.unrealizedPnl),
+            `${p.leverage}x`,
+        ];
+        if (venue !== null) {
+            const r = await readPositionsByAddress(venue, net, address, { accountIndex, symbol: opts.symbol });
+            if (isJson()) {
+                return printJson(jsonOk(r.positions, {
+                    exchange: r.venue, address, source: "public",
+                    ...(r.warnings.length > 0 ? { warnings: r.warnings, errors: r.errors } : {}),
+                    ...(r.notes.length > 0 ? { notes: r.notes } : {}),
+                }));
+            }
+            for (const w of r.warnings)
+                console.log(chalk.yellow(`  ${w}`));
+            if (r.positions.length === 0) {
+                console.log(chalk.gray(`\n  No open positions for ${address} on ${r.venue}${r.notes.length > 0 ? ` (${r.notes.join("; ")})` : ""}.\n`));
+                return;
+            }
+            console.log(makeTable(["Symbol", "Dex/Acct", "Side", "Size", "Entry", "Mark", "Liq", "PnL", "Lev"], r.positions.map(p => row(p, null))));
+            return;
+        }
+        const all = await readPositionsByAddressAll(net, address, { accountIndex, symbol: opts.symbol });
+        if (isJson()) {
+            return printJson(jsonOk({
+                venues: all.venues,
+                ...(Object.keys(all.errors).length > 0 ? { errors: all.errors } : {}),
+                ...(Object.keys(all.notes).length > 0 ? { notes: all.notes } : {}),
+            }, { address, source: "public", ...(all.warnings.length > 0 ? { warnings: all.warnings } : {}) }));
+        }
+        const rows = Object.entries(all.venues).flatMap(([ex, ps]) => ps.map(p => row(p, ex)));
+        if (rows.length > 0)
+            console.log(makeTable(["Symbol", "Exch", "Dex/Acct", "Side", "Size", "Entry", "Mark", "Liq", "PnL", "Lev"], rows));
+        else
+            console.log(chalk.gray(`\n  No open positions for ${address} on ${Object.keys(all.venues).join(", ") || "any venue"}.\n`));
+        for (const [ex, e] of Object.entries(all.errors))
+            console.log(chalk.gray(`  ${ex}: ${e.code} ${e.message}`));
+        for (const [ex, n] of Object.entries(all.notes))
+            console.log(chalk.gray(`  ${ex}: ${n.join("; ")}`));
+    }
     account
         .command("positions")
-        .description("Show open positions")
+        .description("Show open positions (yours; or any account's, keyless, with --address)")
         .option("--hip3", "Include HIP-3 dex positions (Hyperliquid)")
+        .option("--address <address>", "Read this public address instead of your account — keyless (hyperliquid, lighter, lighter-rh, risex: 0x address; pacifica: Solana address). Without -e: every venue that supports it")
+        .option("--account-index <n>", "With --address on Lighter: only this account (sub-account) of the address")
+        .option("--symbol <symbol>", "With --address: only this market (plain asset, e.g. BTC)")
         .action(async (opts) => {
         const explicitExchange = program.getOptionValueSource?.("exchange") === "cli";
+        if (opts.address !== undefined) {
+            return void await withJsonErrors(isJson(), () => positionsByAddress(opts.address, explicitExchange ? String(program.opts().exchange) : null, opts));
+        }
+        if (opts.accountIndex !== undefined || opts.symbol !== undefined) {
+            throw new PerpError("INVALID_PARAMS", "--account-index / --symbol apply to --address reads", { remediation: "Add --address <address>, or drop the option" });
+        }
         if (!explicitExchange && getAdapterForExchange) {
             const EXCHANGES = await listConfiguredAccountVenues();
             const allRows = [];
@@ -316,7 +472,7 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
         // Pacifica: use dedicated SDK endpoint
         if (hasPacificaSdk(adapter)) {
             const sdk = adapter.sdk;
-            const settings = await sdk.getAccountSettings(adapter.publicKey);
+            const settings = await sdk.getAccountSettings(pacificaAccount(adapter));
             if (isJson())
                 return printJson(jsonOk(settings));
             // GET /account/settings returns an object; per-market entries are in `margin_settings`
@@ -404,7 +560,8 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
         .description("Margin details for a specific symbol position")
         .action(async (symbol) => {
         const sym = symbol.toUpperCase();
-        try {
+        // Errors: the one envelope (code, status, remediation) and exit 1 via withJsonErrors.
+        return void await withJsonErrors(isJson(), async () => {
             const adapter = await getAdapter();
             const [balance, positions] = await Promise.all([
                 adapter.getBalance(),
@@ -452,20 +609,7 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
             console.log(`  Liquidation:      ${pos.liquidationPrice === null ? chalk.gray("-") : `$${formatUsd(pos.liquidationPrice)}`}`);
             console.log(`  Unrealized PnL:   ${formatPnl(pos.unrealizedPnl)}`);
             console.log();
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (isJson()) {
-                const { classifyError } = await import("../errors.js");
-                const classified = classifyError(err);
-                return printJson(jsonError(classified.code, classified.message, {
-                    status: classified.status,
-                    retryable: classified.retryable,
-                }));
-            }
-            console.error(chalk.red(`Error: ${msg}`));
-            process.exitCode = 1;
-        }
+        });
     });
     // ── PnL Report ──
     account
@@ -609,7 +753,7 @@ export function registerAccountCommands(program, getAdapter, isJson, getAdapterF
         }
         const p = pac(adapter);
         const sdk = p.sdk;
-        const orders = await sdk.getTWAPOrders(p.publicKey);
+        const orders = await sdk.getTWAPOrders(pacificaAccount(p));
         if (isJson())
             return printJson(jsonOk(orders));
         if (!orders || orders.length === 0) {

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;