perp-cli 0.14.3 → 0.15.0

package/dist/pacifica/rate-limit.js

@@ -0,0 +1,267 @@
+/**
+ * Pacifica credit rate limit, read from the venue's own response headers.
+ *
+ * docs.pacifica.fi api-documentation/api/rate-limits (read 2026-10-19): credit-based, rolling
+ * 60 s window; 100 credits / 60 s per unidentified IP, 300 with a valid API Config Key (more for
+ * higher fee tiers); standard request 1, cancel 0.5, heavy GET 3-12 (1-4 with a key). Exhausted →
+ * HTTP 429. "All credit values are multiplied by 10 to support fractional costs":
+ *
+ *   ratelimit: "credits";r=1200;t=32        r = remaining (×10), t = seconds until refresh
+ *   ratelimit-policy: "credits";q=1250;w=60 q = quota per window (×10), w = window seconds
+ *
+ * Live mainnet GET /info/prices (2026-10-19, no key): `ratelimit: "credits";r=980;t=22`,
+ * `ratelimit-policy: "credits";q=1000;w=60`. Values below stay in those ×10 units.
+ *
+ * CloudFront caches some GETs (/info: `x-cache: Hit from cloudfront`, `age: 16`): a cache hit
+ * replays the headers of whoever filled the cache (live: q=3000, a keyed caller) — not this
+ * caller's quota, so a hit carries no information.
+ *
+ * Scope: one state per REST base URL (mainnet / testnet), credential tier (no key = IP quota;
+ * an API Config Key has its own) and request kind (signed POST vs unsigned GET). Process-local: other perp-cli processes (CLI + MCP + bots) on the
+ * same IP spend the same quota unseen, so a 429 can still happen — it is then surfaced as
+ * RATE_LIMITED, never retried here.
+ */
+import { createHash } from "crypto";
+import { PerpError } from "../errors.js";
+/** `"credits";k=v;k=v` with non-negative integer values; null on any deviation. */
+function parseCreditsItem(raw) {
+    if (raw === null)
+        return null;
+    const parts = raw.trim().split(";").map((p) => p.trim());
+    if (parts[0] !== '"credits"')
+        return null;
+    const out = new Map();
+    for (const p of parts.slice(1)) {
+        const m = /^([a-z][a-z0-9_-]*)=(\d{1,12})$/.exec(p);
+        if (m === null || out.has(m[1]))
+            return null;
+        out.set(m[1], Number(m[2]));
+    }
+    return out;
+}
+/**
+ * Strict parse of the `ratelimit` / `ratelimit-policy` header values. `ratelimit` absent or
+ * malformed (no `"credits"` item, missing / non-integer / duplicate r or t) → null: no info, never
+ * a guessed value. A malformed policy only nulls quota / windowSec.
+ */
+export function parsePacificaRateLimit(ratelimit, policy) {
+    const rl = parseCreditsItem(ratelimit);
+    const r = rl?.get("r");
+    const t = rl?.get("t");
+    if (r === undefined || t === undefined)
+        return null;
+    const pol = parseCreditsItem(policy);
+    const q = pol?.get("q");
+    const w = pol?.get("w");
+    const policyOk = q !== undefined && w !== undefined && w > 0;
+    return { remaining: r, resetSec: t, quota: policyOk ? q : null, windowSec: policyOk ? w : null };
+}
+/** `Retry-After` in delta-seconds → ms; absent / HTTP-date / malformed → null. */
+export function parseRetryAfterMs(raw) {
+    if (raw === null || !/^\d{1,9}$/.test(raw.trim()))
+        return null;
+    return Number(raw.trim()) * 1000;
+}
+function header(res, name) {
+    // Every real fetch Response has headers; a value without them carries no rate-limit info.
+    const h = res?.headers;
+    return h !== undefined && typeof h.get === "function" ? h.get(name) : null;
+}
+/** A CloudFront cache hit replays someone else's headers (see module doc). */
+function isCacheHit(res) {
+    const xc = header(res, "x-cache");
+    return (xc !== null && /^(Hit|RefreshHit)\b/i.test(xc.trim())) || header(res, "age") !== null;
+}
+/** Parsed rate-limit info of a response this caller's request produced; null = no info. */
+export function pacificaRateLimitOf(res) {
+    if (isCacheHit(res))
+        return null;
+    return parsePacificaRateLimit(header(res, "ratelimit"), header(res, "ratelimit-policy"));
+}
+/** Read reserve (credits ×10): the largest documented heavy-GET cost (12 credits) stays unspent after a read. */
+export const PACIFICA_READ_RESERVE = 120;
+/** Cost (credits ×10) of a standard request / action (docs: 1 credit). */
+export const PACIFICA_COST_STANDARD = 10;
+/** Cost (credits ×10) of an order cancellation (docs: 0.5 credits). */
+export const PACIFICA_COST_CANCEL = 5;
+/** Slack after the venue's `t` (whole seconds) before the window is treated as refreshed. */
+const RESET_MARGIN_MS = 250;
+/** Documented window (docs: "60-second rolling window") — only an upper clamp for `t` / Retry-After. */
+const DOC_WINDOW_SEC = 60;
+/** A reset / Retry-After longer than the window + this is clamped (a bogus value must not stall). */
+const RESET_CLAMP_MARGIN_MS = 1_000;
+/** Longest pre-send wait before failing fast with RATE_LIMITED. */
+export const PACIFICA_MAX_THROTTLE_WAIT_MS = 15_000;
+/** Longest wait between signing and sending (signed bodies expire after expiry_window = 5 s). */
+export const PACIFICA_SIGNED_MAX_WAIT_MS = 2_000;
+/** Monotonic: elapsed time never follows a wall-clock step (NTP, VM resume). */
+const realClock = {
+    now: () => performance.now(),
+    sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+};
+export const PACIFICA_READ_NEED = { cost: PACIFICA_COST_STANDARD, reserve: PACIFICA_READ_RESERVE, maxWaitMs: PACIFICA_MAX_THROTTLE_WAIT_MS };
+function clampResetMs(ms, windowSec) {
+    const cap = (windowSec !== null ? windowSec : DOC_WINDOW_SEC) * 1000 + RESET_CLAMP_MARGIN_MS;
+    return Math.min(ms, cap);
+}
+export class PacificaRateLimiter {
+    label;
+    clock;
+    obs = null;
+    /** Credits ×10 reserved by requests sent and not yet settled — not reset by observe(). */
+    inFlight = 0;
+    lastRaw = Number.NEGATIVE_INFINITY;
+    skew = 0;
+    constructor(label, clock = realClock) {
+        this.label = label;
+        this.clock = clock;
+    }
+    /** clock.now() made monotonic: a backwards step is absorbed instead of restarting elapsed time. */
+    now() {
+        const raw = this.clock.now();
+        if (raw < this.lastRaw)
+            this.skew += this.lastRaw - raw;
+        this.lastRaw = raw;
+        return raw + this.skew;
+    }
+    /** ms until the observed window refreshes; null = no live observation. */
+    resetWaitMs() {
+        if (this.obs === null)
+            return null;
+        const left = this.obs.resetInMs + RESET_MARGIN_MS - (this.now() - this.obs.observedAt);
+        if (left <= 0) {
+            this.obs = null;
+            return null;
+        } // window refreshed: the observation is spent
+        return left;
+    }
+    /** Current state for diagnostics (credits ×10); null = no live observation. */
+    snapshot() {
+        const wait = this.resetWaitMs();
+        if (wait === null || this.obs === null)
+            return null;
+        return { remaining: this.obs.remaining, inFlight: this.inFlight, effectiveRemaining: this.obs.remaining - this.inFlight, resetInMs: wait };
+    }
+    /** ms to wait before a request with `need` may be sent: 0 = now (no info, or enough credits left). */
+    waitMs(need) {
+        const wait = this.resetWaitMs();
+        if (wait === null || this.obs === null)
+            return 0;
+        return this.obs.remaining - this.inFlight - need.cost >= need.reserve ? 0 : wait;
+    }
+    ticket(cost) {
+        this.inFlight += cost;
+        let open = true;
+        const release = () => { if (open) {
+            open = false;
+            this.inFlight -= cost;
+        } };
+        return {
+            release,
+            settle: (res) => { release(); return this.observe(res); },
+        };
+    }
+    /**
+     * Pre-send throttle + reservation. Enough credits (or no info) → the cost is reserved
+     * synchronously, before any await, so concurrent callers see each other. Otherwise waits for the
+     * window to refresh (total ≤ need.maxWaitMs) or fails fast with RATE_LIMITED (sent: false).
+     */
+    async acquire(what, need) {
+        let budget = need.maxWaitMs;
+        for (;;) {
+            const wait = this.waitMs(need);
+            if (wait === 0)
+                return this.ticket(need.cost);
+            if (wait > budget)
+                throw this.throttled(what, wait);
+            const waitedOn = this.obs;
+            const start = this.now();
+            await this.clock.sleep(wait);
+            budget -= this.now() - start;
+            // The window that observation described has refreshed; a newer one (a response that landed
+            // meanwhile) is kept and re-checked.
+            if (this.obs === waitedOn)
+                this.obs = null;
+        }
+    }
+    /** Like acquire but never waits or refuses (health probe): reserves and records only. */
+    track(cost) {
+        return this.ticket(cost);
+    }
+    /** Wait (no reservation) until `need` would pass — used before signing, so the post-sign acquire finds credits. */
+    async awaitCapacity(what, need) {
+        (await this.acquire(what, need)).release();
+    }
+    throttled(what, wait) {
+        return new PerpError("RATE_LIMITED", `Pacifica ${what} not sent: rate-limit credits nearly exhausted (${this.label}), window refreshes in ${Math.ceil(wait / 1000)} s`, {
+            exchange: "pacifica", sent: false, retryAfterMs: Math.ceil(wait),
+            remediation: `Nothing was sent. Retry after ${Math.ceil(wait / 1000)} s; other perp-cli processes on this IP share the same Pacifica quota — reduce request frequency or use an API Config Key (300 credits / 60 s)`,
+        });
+    }
+    /**
+     * Record a response's headers (any status). No / malformed / cached headers → unchanged. Within
+     * the live window an observation with a higher `r` (a late response from before others landed)
+     * or a different `q` (another quota: account vs IP) is dropped.
+     */
+    observe(res) {
+        const info = pacificaRateLimitOf(res);
+        if (info === null)
+            return null;
+        const live = this.resetWaitMs() !== null && this.obs !== null ? this.obs : null;
+        if (live !== null) {
+            if (info.remaining > live.remaining)
+                return null;
+            if (live.quota !== null && info.quota !== null && info.quota !== live.quota)
+                return null;
+        }
+        this.obs = { remaining: info.remaining, resetInMs: clampResetMs(info.resetSec * 1000, info.windowSec), observedAt: this.now(), quota: info.quota };
+        return info;
+    }
+    /**
+     * HTTP 429 → RATE_LIMITED (structural, by status). retryAfterMs = `Retry-After`, else the
+     * ratelimit reset `t`, else absent (clamped to the window). The quota is recorded as exhausted.
+     *
+     * `sent: false` ("not executed") is OUR reading of the docs — "When credits are exhausted,
+     * requests return HTTP 429" — i.e. the request is refused before processing. Pacifica does not
+     * state explicitly that a 429'd write was not executed.
+     */
+    rateLimitedError(what, res, body) {
+        const info = pacificaRateLimitOf(res);
+        const fromHeader = parseRetryAfterMs(header(res, "retry-after"));
+        const raw = fromHeader !== null ? fromHeader : info !== null ? info.resetSec * 1000 : null;
+        const retryAfterMs = raw !== null ? clampResetMs(raw, info !== null ? info.windowSec : null) : null;
+        if (retryAfterMs !== null)
+            this.obs = { remaining: 0, resetInMs: retryAfterMs, observedAt: this.now(), quota: info !== null ? info.quota : null };
+        return new PerpError("RATE_LIMITED", `Pacifica ${what} rate limited (HTTP 429); nothing was executed: ${body.slice(0, 200)}`, {
+            exchange: "pacifica", httpStatus: 429, sent: false,
+            ...(retryAfterMs !== null ? { retryAfterMs } : {}),
+            remediation: `${retryAfterMs !== null ? `Retry after ${Math.ceil(retryAfterMs / 1000)} s` : "Wait for the 60 s window to refresh, then retry"}; other perp-cli processes on this IP share the same Pacifica quota — reduce request frequency or use an API Config Key (300 credits / 60 s)`,
+        });
+    }
+}
+/** A Pacifica RATE_LIMITED that sent nothing (pre-send throttle or HTTP 429): a definite refusal. */
+export function isPacificaRateLimited(e) {
+    return e instanceof PerpError && e.structured.code === "RATE_LIMITED"
+        && e.structured.details?.exchange === "pacifica" && e.structured.details?.sent === false;
+}
+const limiters = new Map();
+/**
+ * The process-local limiter for a REST base URL + credential tier (no key = IP quota) + request
+ * kind. Signed POSTs are kept apart from unsigned GETs: credits are shared per main account and
+ * scale with its fee tier, so signed responses can report an account quota (e.g. q=3000) while
+ * keyless GETs report the IP quota (q=1000).
+ */
+export function pacificaRateLimiter(baseUrl, apiKey, kind) {
+    const tier = apiKey ? `key:${createHash("sha256").update(apiKey).digest("hex").slice(0, 12)}` : "ip";
+    const key = `${baseUrl}|${tier}|${kind}`;
+    let l = limiters.get(key);
+    if (l === undefined) {
+        l = new PacificaRateLimiter(`${baseUrl} ${apiKey ? "API Config Key" : "IP"} ${kind} quota`);
+        limiters.set(key, l);
+    }
+    return l;
+}
+/** Test hook: forget every limiter's state. */
+export function resetPacificaRateLimiters() {
+    limiters.clear();
+}

package/dist/pacifica/types/order.d.ts

@@ -71,7 +71,8 @@ export interface TPSLParams {
         stop_price: string;
     };
 }
-export type BatchActionType = "Create" | "Cancel";
+/** docs rest-api/orders/batch-order `type` (case sensitive; not the signing operation type). */
+export type BatchActionType = "Create" | "CreateMarket" | "Cancel" | "Edit" | "SetPositionTpsl" | "CancelStopOrder";
 export interface BatchAction {
     type: BatchActionType;
     data: Record<string, unknown>;

package/dist/plan-executor.js

@@ -1,4 +1,5 @@
 import { assertCanClosePositions } from "./exchanges/trading-v2.js";
+import { getVenue, requireRole, tryResolveVenueId } from "./exchanges/venue.js";
 import { symbolMatch } from "./utils.js";
 import { logExecution } from "./execution-log.js";
 import { randomUUID } from "crypto";
@@ -83,6 +84,10 @@ export async function executePlan(adapter, plan, opts) {
     const completedSteps = new Map();
     const dryRun = opts?.dryRun ?? false;
     const log = opts?.log ?? (() => { });
+    // A venue without the trading role (TxFlow, release-gated RISEx) runs no plan — dry-run included.
+    const venueId = tryResolveVenueId(adapter.name);
+    if (venueId !== null)
+        requireRole(getVenue(venueId), "trading", "plan");
     // A plan that places orders must be able to close them (rollback / close_position are
     // reduce-only): refuse before the first step on a venue that cannot.
     if (!dryRun && plan.steps.some(s => PLAN_ORDER_ACTIONS.has(s.action))) {
@@ -155,7 +160,7 @@ export async function executePlan(adapter, plan, opts) {
             const onFailure = step.onFailure ?? "abort";
             if (ORDER_ACTIONS.has(step.action) && isOutcomeUnknown(err)) {
                 // The order may have been placed: never treat it as failed, never resubmit or roll it
-                // back. Stop the plan and quarantine the symbol (design §12.3).
+                // back. Stop the plan and quarantine the symbol.
                 const sym = String(step.params.symbol ?? "").toUpperCase();
                 log(`[plan:${planId}] Step ${step.id} (${step.action}): OUTCOME UNKNOWN — ${message}`);
                 quarantine(sym, `step ${step.id} (${step.action}) outcome unknown: ${message}`);
@@ -300,7 +305,7 @@ async function executeStep(adapter, step, log, placed) {
             const closeSide = pos.side === "long" ? "sell" : "buy";
             // Size from the live position (abs), reduce-only: a stale / repeated close can never open
             // or flip a position — the venue rejects it instead. Fill measured (ORDER_PENDING when unconfirmed).
-            // A partial close (venue-final IOC partial fills are accepted, §13.10 #4) gets ONE residual
+            // A partial close (venue-final IOC partial fills are accepted) gets ONE residual
             // close (closePerpVerified); a residual still open fails the step with ORDER_PARTIAL.
             const liveSize = pos.size.replace(/^-/, "");
             const c = await closePerpVerified(adapter, adapter.name, pos.symbol, closeSide, liveSize);

package/dist/rebalance.js

@@ -1,7 +1,7 @@
 import { PerpError } from "./errors.js";
 import { getVenue, tryResolveVenueId } from "./exchanges/venue.js";
 import "./exchanges/venues/index.js";
-/** Settlement chains with no withdraw → bridge → deposit route in this CLI (design §10.10). */
+/** Settlement chains with no withdraw → bridge → deposit route in this CLI. */
 const NO_ROUTE_CHAINS = new Set(["robinhood", "offchain"]);
 /** Throws NO_BRIDGE_ROUTE when the venue's funds live where no bridge route exists. */
 export function assertBridgeRoute(exchange) {

package/dist/risk.d.ts

@@ -52,7 +52,8 @@ export interface RiskAssessment {
         marginUtilization: number;
         largestPositionUsd: number;
         maxLeverageUsed: number;
-        minLiquidationDistancePct: number;
+        /** null = no position with a known liquidation price (no positions, or none reported) — never a -1 sentinel */
+        minLiquidationDistancePct: number | null;
     };
     liquidationDistances: LiquidationDistanceInfo[];
     limits: RiskLimits;

package/dist/risk.js

@@ -159,9 +159,9 @@ export function assessRisk(balances, positions, limits) {
     }
     // Check liquidation distances
     const liquidationDistances = getLiquidationDistances(positions, lim);
-    let minLiquidationDistancePct = Infinity;
+    let minLiquidationDistancePct = null;
     for (const ld of liquidationDistances) {
-        if (ld.distancePct < minLiquidationDistancePct) {
+        if (minLiquidationDistancePct === null || ld.distancePct < minLiquidationDistancePct) {
             minLiquidationDistancePct = ld.distancePct;
         }
         if (ld.distancePct < lim.minLiquidationDistance) {
@@ -174,8 +174,6 @@ export function assessRisk(balances, positions, limits) {
             });
         }
     }
-    if (minLiquidationDistancePct === Infinity)
-        minLiquidationDistancePct = -1; // no positions
     // Determine overall risk level
     let level = "low";
     if (violations.some(v => v.severity === "critical"))

package/dist/settings.d.ts

@@ -168,7 +168,36 @@ export interface QfexAgentMeta {
     approvedAt: string;
     source: "imported";
 }
-export type AnyAgentMeta = AgentMeta | OndoAgentMeta | ArcusAgentMeta | QfexAgentMeta;
+/**
+ * RISEx session signer (EVM key). Registered by the master with RegisterSigner (+ the signer's
+ * VerifySigner) and then restricted ON-CHAIN to the trading permission (DisablePermission for every
+ * other permission, signed by the signer and sent by the master). The private key lives only in OWS wallet `agentWalletName`
+ * (SSOT Rule #3).
+ */
+export interface RisexAgentMeta {
+    kind: "risex";
+    agentName: string;
+    agentWalletName: string;
+    /** Signer (session key) address. */
+    signerAddress: `0x${string}`;
+    /** The RISEx account (master wallet address) the signer trades for. */
+    accountAddress: `0x${string}`;
+    /** ISO timestamp of the on-chain expiration signed in RegisterSigner. */
+    expiresAt: string;
+    /**
+     * On-chain permission state proven after registration (Authorization.hasPermission):
+     * trading-only = only the router permission enabled. Never written from a guess.
+     */
+    permissions: {
+        tradingOnly: boolean;
+        disabled: number[];
+        verifiedAt: string | null;
+    };
+    network: "mainnet" | "testnet";
+    approvedAt: string;
+    source: "approved";
+}
+export type AnyAgentMeta = AgentMeta | OndoAgentMeta | ArcusAgentMeta | QfexAgentMeta | RisexAgentMeta;
 export interface AgentsByExchange {
     aster?: Record<string, AgentMeta>;
     hyperliquid?: Record<string, AgentMeta>;
@@ -178,6 +207,7 @@ export interface AgentsByExchange {
     ondo?: Record<string, OndoAgentMeta>;
     arcus?: Record<string, ArcusAgentMeta>;
     qfex?: Record<string, QfexAgentMeta>;
+    risex?: Record<string, RisexAgentMeta>;
 }
 export interface Settings {
     /** Default exchange when -e flag is omitted */
@@ -203,8 +233,7 @@ export interface Settings {
     /** OWS-native agent wallets registered per exchange (Phase 2a: Aster only) */
     agents?: AgentsByExchange;
     /**
-     * Per-venue slippage bound override (basis points) for market-type orders
-     * (design §13.2). Absent key = use `defaultSlippageBps`.
+     * Per-venue slippage bound override (basis points) for market-type orders. Absent key = use `defaultSlippageBps`.
      * Resolved only by resolveSlippage() (src/exchanges/slippage.ts).
      */
     slippageBps: {

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

@@ -17,7 +17,7 @@ export declare class OwsEvmSigner implements EvmSigner {
     }>>, value: Record<string, unknown>): Promise<string>;
     /**
      * Sign an unsigned EVM transaction (on-chain txs sent by the master wallet — Lighter RH
-     * deposit, design §13). The digest is computed HERE from the transaction (`unsignedHash`),
+     * deposit). The digest is computed HERE from the transaction (`unsignedHash`),
      * so callers can never feed an arbitrary 32-byte hash to the master key. Returns the
      * 65-byte 0x signature; the caller attaches it and checks the recovered sender.
      */

package/dist/signer/ows-evm.js

@@ -44,7 +44,7 @@ export class OwsEvmSigner {
     }
     /**
      * Sign an unsigned EVM transaction (on-chain txs sent by the master wallet — Lighter RH
-     * deposit, design §13). The digest is computed HERE from the transaction (`unsignedHash`),
+     * deposit). The digest is computed HERE from the transaction (`unsignedHash`),
      * so callers can never feed an arbitrary 32-byte hash to the master key. Returns the
      * 65-byte 0x signature; the caller attaches it and checks the recovered sender.
      */

package/dist/smart-order.d.ts

@@ -16,7 +16,7 @@
  * - Saves 5-50+ bps vs raw market orders on thin books
  * - Predictable execution price
  *
- * Order-outcome typing (design §12.3): every failure BEFORE the IOC is sent (orderbook read,
+ * Order-outcome typing: every failure BEFORE the IOC is sent (orderbook read,
  * empty book, unusable price), an explicit venue rejection embedded in the response, and an
  * explicit IOC no-match (nothing filled, nothing rests) throw a definite ORDER_REJECTED
  * (orderNotSent), so placePerpVerified does not quarantine a leg that never traded. Anything

package/dist/smart-order.js

@@ -16,7 +16,7 @@
  * - Saves 5-50+ bps vs raw market orders on thin books
  * - Predictable execution price
  *
- * Order-outcome typing (design §12.3): every failure BEFORE the IOC is sent (orderbook read,
+ * Order-outcome typing: every failure BEFORE the IOC is sent (orderbook read,
  * empty book, unusable price), an explicit venue rejection embedded in the response, and an
  * explicit IOC no-match (nothing filled, nothing rests) throw a definite ORDER_REJECTED
  * (orderNotSent), so placePerpVerified does not quarantine a leg that never traded. Anything

package/dist/strategies/funding-arb.d.ts

@@ -13,7 +13,7 @@ export interface FundingArbParams {
     maxDrawdown?: number;
 }
 /**
- * `perp strategy funding-arb` loop. With autoExecute (design §12.3):
+ * `perp strategy funding-arb` loop. With autoExecute:
  *  - entry = openPerpPairVerified (long, then the short sized to the long's VERIFIED fill;
  *    definite short failure → reduce-only rollback; unknown outcome → quarantine). A lot-size
  *    rejection is never resubmitted blindly: the long is re-sized only when it was definitely

package/dist/strategies/funding-arb.js

@@ -72,7 +72,7 @@ async function fetchAllRates() {
 }
 // annualize: use computeAnnualSpread from funding.ts for cross-exchange comparison
 /**
- * `perp strategy funding-arb` loop. With autoExecute (design §12.3):
+ * `perp strategy funding-arb` loop. With autoExecute:
  *  - entry = openPerpPairVerified (long, then the short sized to the long's VERIFIED fill;
  *    definite short failure → reduce-only rollback; unknown outcome → quarantine). A lot-size
  *    rejection is never resubmitted blindly: the long is re-sized only when it was definitely

package/dist/trade-validator.js

@@ -12,7 +12,7 @@ export async function validateTrade(adapter, params) {
     const checks = [];
     const warnings = [];
     const sym = params.symbol.toUpperCase();
-    // Liquidity threshold = the bound a market order on this venue would carry (design §13.10 #14).
+    // Liquidity threshold = the bound a market order on this venue would carry.
     const maxSlippage = resolveAdapterSlippage(adapter, null).bps / 10_000;
     // Fetch market list, balance, and positions in parallel.
     // Defer the orderbook call until symbol membership is confirmed so invalid
@@ -264,7 +264,7 @@ export async function enforceOrderRisk(adapter, p) {
         const markets = await adapter.getMarkets();
         const m = markets.find((mk) => symbolMatch(mk.symbol, p.symbol));
         if (!m) {
-            throw new PerpError("SYMBOL_NOT_FOUND", `${p.symbol} not found on ${adapter.name}`, { exchange: adapter.name });
+            throw new PerpError("SYMBOL_NOT_FOUND", `${p.symbol} not found on ${adapter.name}`, { exchange: adapter.name, remediation: `List markets: perp -e ${adapter.name} market list` });
         }
         price = Number(m.markPrice);
     }

package/dist/utils.d.ts

@@ -1,6 +1,11 @@
 import type { OrderResult } from "./exchanges/venue-types.js";
 export declare function symbolMatch(candidate: string, target: string): boolean;
 export declare function formatUsd(value: string | number): string;
+/**
+ * Symbol argument as typed, normalized for display and lookup: upper case, except a HIP-3 dex
+ * prefix, which is lower case on the venue ("xyz:xyz100" / "XYZ:XYZ100" → "xyz:XYZ100").
+ */
+export declare function normalizeSymbolArg(symbol: string): string;
 export declare function formatPnl(value: string | number): string;
 export declare function formatPercent(value: string | number): string;
 export declare function makeTable(head: string[], rows: string[][]): string;
@@ -26,6 +31,10 @@ export interface ApiResponse<T = unknown> {
         exchange?: string;
         timestamp: string;
         duration_ms?: number;
+        skippedRows?: {
+            count: number;
+            reason: string;
+        };
     };
 }
 /** Wrap successful result in standard envelope */
@@ -50,18 +59,18 @@ export declare function withJsonErrors<T>(isJson: boolean, fn: () => Promise<T>,
 /**
  * Central CLI error printer. JSON: the structured envelope incl. details and
  * remediation. Human: the uniform "not supported" line for CAPABILITY_UNSUPPORTED
- * (design §13.6) — `✗ <Venue>: <feature> not supported — <reason>. Alternative: <remediation>` —
+ * — `✗ <Venue>: <feature> not supported — <reason>. Alternative: <remediation>` —
  * otherwise `Error: <message>` plus the remediation.
  */
 export declare function printCliError(err: unknown, isJson: boolean, exchange?: string): void;
 /**
- * JSON payload of an order result (design §13.7): the uniform OrderResult (+ execution)
+ * JSON payload of an order result: the uniform OrderResult (+ execution)
  * with the venue's raw response duplicated under `legacy` for one release.
  */
 export declare function orderResultJson(r: OrderResult & {
     remediation?: string | null;
 }, extra?: Record<string, unknown>): Record<string, unknown>;
-/** Human lines for an order result — one format for every venue (design §13.7). */
+/** Human lines for an order result — one format for every venue. */
 export declare function formatOrderResult(r: OrderResult & {
     remediation?: string | null;
 }): string[];

package/dist/utils.js

@@ -30,6 +30,14 @@ export function formatUsd(value) {
         maximumFractionDigits: maxDecimals,
     });
 }
+/**
+ * Symbol argument as typed, normalized for display and lookup: upper case, except a HIP-3 dex
+ * prefix, which is lower case on the venue ("xyz:xyz100" / "XYZ:XYZ100" → "xyz:XYZ100").
+ */
+export function normalizeSymbolArg(symbol) {
+    const i = symbol.indexOf(":");
+    return i === -1 ? symbol.toUpperCase() : `${symbol.slice(0, i).toLowerCase()}:${symbol.slice(i + 1).toUpperCase()}`;
+}
 export function formatPnl(value) {
     const num = Number(value);
     if (isNaN(num))
@@ -235,7 +243,7 @@ export async function withJsonErrors(isJson, fn, exchange) {
 /**
  * Central CLI error printer. JSON: the structured envelope incl. details and
  * remediation. Human: the uniform "not supported" line for CAPABILITY_UNSUPPORTED
- * (design §13.6) — `✗ <Venue>: <feature> not supported — <reason>. Alternative: <remediation>` —
+ * — `✗ <Venue>: <feature> not supported — <reason>. Alternative: <remediation>` —
  * otherwise `Error: <message>` plus the remediation.
  */
 export function printCliError(err, isJson, exchange) {
@@ -262,13 +270,13 @@ export function printCliError(err, isJson, exchange) {
     }
 }
 /**
- * JSON payload of an order result (design §13.7): the uniform OrderResult (+ execution)
+ * JSON payload of an order result: the uniform OrderResult (+ execution)
  * with the venue's raw response duplicated under `legacy` for one release.
  */
 export function orderResultJson(r, extra) {
     return { ...r, ...extra, legacy: r.venueRaw };
 }
-/** Human lines for an order result — one format for every venue (design §13.7). */
+/** Human lines for an order result — one format for every venue. */
 export function formatOrderResult(r) {
     const lines = [];
     const statusColor = r.status === "filled" ? chalk.green

package/dist/venue-health.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Venue connectivity probe — the one implementation behind `perp health`,
+ * `perp portfolio --health` and the MCP `health_check` tool.
+ *
+ * Pacifica / Hyperliquid / Lighter / Aster / QFEX / GRVT: a REST ping (status = HTTP status, 0 = no
+ * response). Every other venue — including read-only (market-data-only) venues such as TxFlow —
+ * is probed with its public market-data read (status null). A venue with no environment on the
+ * selected network (TxFlow has no testnet) is not probed and is listed in `skipped`.
+ *
+ * The ping helpers (shared-api) read the shared API URLs, which follow the network the caller
+ * selected (setSharedApiNetwork); Aster / QFEX / market-data probes take `network` directly.
+ */
+import type { Network, VenueId } from "./exchanges/venue-types.js";
+import "./exchanges/venues/index.js";
+export interface VenueProbe {
+    venue: VenueId;
+    ok: boolean;
+    latencyMs: number;
+    /** HTTP status of a REST ping (0 = no response); null for a market-data probe. */
+    status: number | null;
+    /** null when ok. */
+    error: string | null;
+    probe: "ping" | "markets";
+    /** "unofficial" = the venue is read through an undocumented API (VenueDefinition.apiStatus). */
+    apiStatus: "official" | "unofficial";
+}
+export interface VenueHealth {
+    probes: VenueProbe[];
+    /** Venues requested but not probed: no environment on `network`. */
+    skipped: Array<{
+        venue: VenueId;
+        reason: string;
+    }>;
+    allHealthy: boolean;
+}
+/**
+ * Probe `venueIds` (default: every registered venue) on `network`, in parallel. Never throws for a
+ * venue failure — each failure is a probe with ok:false and its message.
+ */
+export declare function probeVenueHealth(network: Network, venueIds?: readonly string[]): Promise<VenueHealth>;