perp-cli 0.12.17 → 0.14.1

package/dist/dashboard/ui.js

@@ -234,6 +234,7 @@ function connect() {
 
 // ── Helpers ──
 function fmt(v, d=2) { const n=Number(v)||0; return n.toLocaleString('en-US',{minimumFractionDigits:d,maximumFractionDigits:d}); }
+function usdOrDash(v, d=2) { return v==null ? '-' : '$'+fmt(v,d); }
 function pnlClass(v) { return Number(v)>=0?'pnl-pos':'pnl-neg'; }
 function pnlSign(v) { const n=Number(v)||0; return n>=0?'+$'+fmt(Math.abs(n)):'-$'+fmt(Math.abs(n)); }
 function rateClass(v) { const n=Number(v)||0; return n>0?'rate-positive':n<0?'rate-negative':'rate-neutral'; }
@@ -310,7 +311,7 @@ function renderPanels(exchanges) {
         const notional = Math.abs(Number(p.size)) * Number(p.markPrice);
         const margin = p.leverage > 0 ? notional / p.leverage : notional;
         const roe = margin > 0 ? (Number(p.unrealizedPnl) / margin * 100) : 0;
-        return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${dex}</td>\`:''}<td>\${sym}</td><td class="side-\${p.side}">\${p.side.toUpperCase()}</td><td>\${p.size}</td><td>$\${fmt(p.entryPrice)}</td><td>$\${fmt(p.markPrice)}</td><td>\${p.liquidationPrice==='N/A'?'N/A':'$'+fmt(p.liquidationPrice)}</td><td style="color:var(--muted)">$\${fmt(notional)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${pnlSign(p.unrealizedPnl)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${roe>=0?'+':''}\${fmt(roe,1)}%</td><td>\${p.leverage}x</td></tr>\`;
+        return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${dex}</td>\`:''}<td>\${sym}</td><td class="side-\${p.side}">\${p.side.toUpperCase()}</td><td>\${p.size}</td><td>$\${fmt(p.entryPrice)}</td><td>$\${fmt(p.markPrice)}</td><td>\${(p.liquidationPrice==null||p.liquidationPrice==='N/A')?'-':'$'+fmt(p.liquidationPrice)}</td><td style="color:var(--muted)">$\${fmt(notional)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${pnlSign(p.unrealizedPnl)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${roe>=0?'+':''}\${fmt(roe,1)}%</td><td>\${p.leverage}x</td></tr>\`;
       }).join('')}</tbody></table>\`:'<div class="empty-msg">No open positions</div>'}
       <div class="section-title">Open Orders (\${filteredOrders.length})</div>
       \${filteredOrders.length?\`<table><thead><tr>\${isHL?'<th>DEX</th>':''}<th>Symbol</th><th>Side</th><th>Type</th><th>Price</th><th>Size</th><th>Filled</th><th>Status</th></tr></thead><tbody>\${filteredOrders.map(o=>{
@@ -319,7 +320,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>\`:'<div class="empty-msg">No open orders</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>$\${fmt(m.indexPrice)}</td><td class="\${rateClass(fr)}">\${(fr*100).toFixed(4)}%</td><td>$\${fmt(m.volume24h,0)}</td><td>$\${fmt(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}x</td></tr>\`;}).join('')}</tbody></table>\`:'<div class="empty-msg">No market data</div>'}
     </div>\`;
   }).join('');
 
@@ -345,9 +346,10 @@ function renderPanels(exchanges) {
 function renderArb() {
   if (!arbData) { $('#arb-table').innerHTML='<div class="empty-msg">Loading arb data...</div>'; return; }
 
-  // Status
+  // Status (hover shows the venue's error message)
+  const escapeHtml = (v) => String(v).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'})[c]);
   const statusHtml = Object.entries(arbData.exchangeStatus||{}).map(([ex,st])=>
-    \`<span class="exchange-status"><span class="dot-sm \${st==='ok'?'dot-ok':'dot-err'}"></span>\${ex}</span>\`
+    \`<span class="exchange-status" title="\${escapeHtml((arbData.exchangeErrors||{})[ex]||'')}"><span class="dot-sm \${st==='ok'?'dot-ok':'dot-err'}"></span>\${ex}</span>\`
   ).join('');
   $('#arb-status').innerHTML = statusHtml;
 

package/dist/dashboard/ws-feeds.js

@@ -223,7 +223,7 @@ class HyperliquidFeed extends ExchangeWsFeed {
                         size: String(Math.abs(szi)),
                         entryPrice: pos.entryPx ?? "0",
                         markPrice: String(pos.positionValue ? (Number(pos.positionValue) / Math.abs(szi)).toFixed(2) : "0"),
-                        liquidationPrice: pos.liquidationPx ?? "N/A",
+                        liquidationPrice: pos.liquidationPx ?? null, // HL sends null when there is no liquidation price
                         unrealizedPnl: pos.unrealizedPnl ?? "0",
                         leverage: Number(ap.leverage?.value ?? 1),
                     };
@@ -241,6 +241,7 @@ class HyperliquidFeed extends ExchangeWsFeed {
                     filled: "0",
                     status: "open",
                     type: String(o.orderType ?? "limit"),
+                    triggerPrice: o.isTrigger === true && Number(o.triggerPx) > 0 ? String(o.triggerPx) : null,
                 }));
             }
             this.emitUpdate();
@@ -407,7 +408,7 @@ class PacificaFeed extends ExchangeWsFeed {
                 size: String(size),
                 entryPrice: String(entryPrice),
                 markPrice: mark ?? "0",
-                liquidationPrice: String(p.l ?? p.liquidation_price ?? "N/A"),
+                liquidationPrice: p.l != null ? String(p.l) : p.liquidation_price != null ? String(p.liquidation_price) : null,
                 unrealizedPnl: pnl.toFixed(4),
                 leverage: Number(p.leverage ?? 1),
             };
@@ -428,6 +429,7 @@ class PacificaFeed extends ExchangeWsFeed {
             filled: String(o.f ?? o.filled ?? "0"),
             status: "open",
             type: String(o.ot ?? o.order_type ?? ""),
+            triggerPrice: Number(o.sp ?? o.stop_price) > 0 ? String(o.sp ?? o.stop_price) : null,
         }));
         this.emitUpdate();
     }
@@ -437,8 +439,8 @@ class PacificaFeed extends ExchangeWsFeed {
         super.close();
     }
 }
-// ── Lighter WS Feed ──
-// WS: wss://mainnet.zklighter.elliot.ai/stream
+// ── Lighter WS Feed (lighter, lighter-rh) ──
+// WS: the adapter's venue+network config (venues/lighter-family.ts); null → REST
 // Auth: signer.createAuthToken() passed as `auth` field in subscribe messages
 // Channels: account_all_positions/{index} (auth), account_all_orders/{index} (auth),
 //           user_stats/{index} (public — balance info)
@@ -449,7 +451,16 @@ class LighterFeed extends ExchangeWsFeed {
         const adapter = exchange.adapter;
         this.accountIndex = Number(adapter._accountIndex ?? -1);
     }
-    get wsUrl() { return "wss://mainnet.zklighter.elliot.ai/stream"; }
+    /** Venue+network WS URL from the adapter's network config; null = none published. */
+    get configuredWsUrl() {
+        return this.exchange.adapter.network.wsUrl;
+    }
+    get wsUrl() {
+        const url = this.configuredWsUrl;
+        if (url === null)
+            throw new Error(`${this.exchange.name}: no WebSocket URL for this network`);
+        return url;
+    }
     async getAuthToken() {
         try {
             const adapter = this.exchange.adapter;
@@ -464,7 +475,7 @@ class LighterFeed extends ExchangeWsFeed {
         }
     }
     async connect() {
-        if (this.accountIndex < 0) {
+        if (this.accountIndex < 0 || this.configuredWsUrl === null) {
             this.startRestFallback();
             return;
         }
@@ -566,7 +577,7 @@ class LighterFeed extends ExchangeWsFeed {
                         markPrice: posSize !== 0
                             ? String((Number(p.position_value ?? 0) / Math.abs(posSize)).toFixed(4))
                             : "0",
-                        liquidationPrice: String(p.liquidation_price || "N/A"),
+                        liquidationPrice: p.liquidation_price ? String(p.liquidation_price) : null,
                         unrealizedPnl: String(p.unrealized_pnl ?? "0"),
                         leverage: Number(p.initial_margin_fraction ?? 0) > 0
                             ? Math.round(10000 / Number(p.initial_margin_fraction))
@@ -592,6 +603,7 @@ class LighterFeed extends ExchangeWsFeed {
                     filled: String(o.filled_base_amount ?? "0"),
                     status: "open",
                     type: String(o.type ?? "limit"),
+                    triggerPrice: Number(o.trigger_price) > 0 ? String(o.trigger_price) : null,
                 }));
                 this.emitUpdate();
             }
@@ -613,7 +625,7 @@ export class WsFeedManager {
             else if (ex.name === "pacifica") {
                 feed = new PacificaFeed(ex, handler);
             }
-            else if (ex.name === "lighter") {
+            else if (ex.name === "lighter" || ex.name === "lighter-rh") {
                 feed = new LighterFeed(ex, handler);
             }
             else {

package/dist/dex-asset-map.js

@@ -13,7 +13,7 @@
  *   SILVERJM ≠ SILVER
  *   URNM ≠ URANIUM
  */
-const HL_INFO_URL = "https://api.hyperliquid.xyz/info";
+import { HYPERLIQUID_API_URL, sharedApiNetwork } from "./api/public/urls.js";
 /** Known aliases: different symbol → same underlying */
 const ALIASES = {
     // Crude oil (WTI benchmark)
@@ -45,7 +45,8 @@ function isBlacklisted(a, b) {
     return BLACKLIST_PAIRS.has(key1) || BLACKLIST_PAIRS.has(key2);
 }
 async function hlInfoPost(body) {
-    const res = await fetch(HL_INFO_URL, {
+    // Selected network (review L7): HYPERLIQUID_API_URL follows -n via setSharedApiNetwork (live binding).
+    const res = await fetch(HYPERLIQUID_API_URL, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -59,7 +60,8 @@ async function hlInfoPost(body) {
  */
 export async function fetchAllDexAssets() {
     const { withCache, TTL_MARKET } = await import("./cache.js");
-    return withCache("pub:hl:allDexAssets", TTL_MARKET, () => _fetchAllDexAssetsLive());
+    // Network in the key: a mainnet snapshot must never answer a testnet run (L7).
+    return withCache(`pub:hl:${sharedApiNetwork()}:allDexAssets`, TTL_MARKET, () => _fetchAllDexAssetsLive());
 }
 async function _fetchAllDexAssetsLive() {
     const allMetas = await hlInfoPost({ type: "allPerpMetas" });

package/dist/errors.d.ts

@@ -50,6 +50,11 @@ export declare const ERROR_CODES: {
         readonly status: 409;
         readonly retryable: false;
     };
+    readonly DEPOSIT_REQUIRED: {
+        readonly code: "DEPOSIT_REQUIRED";
+        readonly status: 403;
+        readonly retryable: false;
+    };
     readonly NO_SIGNER_AVAILABLE: {
         readonly code: "NO_SIGNER_AVAILABLE";
         readonly status: 401;
@@ -101,11 +106,73 @@ export declare const ERROR_CODES: {
         readonly status: 401;
         readonly retryable: false;
     };
+    readonly INVALID_PASSPHRASE: {
+        readonly code: "INVALID_PASSPHRASE";
+        readonly status: 401;
+        readonly retryable: false;
+    };
     readonly NOT_IMPLEMENTED: {
         readonly code: "NOT_IMPLEMENTED";
         readonly status: 501;
         readonly retryable: false;
     };
+    readonly UNKNOWN_VENUE: {
+        readonly code: "UNKNOWN_VENUE";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly TIF_REQUIRED: {
+        readonly code: "TIF_REQUIRED";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly INVALID_TICK: {
+        readonly code: "INVALID_TICK";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly NO_ENV_TIER: {
+        readonly code: "NO_ENV_TIER";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly NO_BRIDGE_ROUTE: {
+        readonly code: "NO_BRIDGE_ROUTE";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly CAPABILITY_UNSUPPORTED: {
+        readonly code: "CAPABILITY_UNSUPPORTED";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    /** Part of a multi-leg placement was accepted and part failed; retrying would duplicate the accepted legs. */
+    readonly ORDER_PARTIAL: {
+        readonly code: "ORDER_PARTIAL";
+        readonly status: 500;
+        readonly retryable: false;
+    };
+    /** The order was submitted but its outcome is not confirmed; retrying could double-trade. */
+    readonly ORDER_PENDING: {
+        readonly code: "ORDER_PENDING";
+        readonly status: 202;
+        readonly retryable: false;
+    };
+    /** The order was definitely NOT placed: the venue rejected it, or it failed before it was sent (design §12.3). */
+    readonly ORDER_REJECTED: {
+        readonly code: "ORDER_REJECTED";
+        readonly status: 422;
+        readonly retryable: false;
+    };
+    /**
+     * The venue explicitly refused a non-order account action (withdraw / transfer / approval) and
+     * executed nothing — distinct from a network / unknown outcome (EXCHANGE_ERROR, UNKNOWN).
+     */
+    readonly ACTION_REJECTED: {
+        readonly code: "ACTION_REJECTED";
+        readonly status: 422;
+        readonly retryable: false;
+    };
     readonly EXCHANGE_UNREACHABLE: {
         readonly code: "EXCHANGE_UNREACHABLE";
         readonly status: 503;
@@ -175,3 +242,58 @@ export declare class PerpError extends Error {
     readonly structured: StructuredError;
     constructor(code: ErrorCode, message: string, details?: Record<string, unknown>);
 }
+/**
+ * Codes that mean "the order was definitely not placed / filled nothing": a validation
+ * or policy failure before sending (incl. PRICE_STALE: no price to build the order), or an
+ * explicit venue rejection. Every other code
+ * (EXCHANGE_UNREACHABLE, TIMEOUT, EXCHANGE_ERROR, RATE_LIMITED, UNKNOWN, …) raised by
+ * an order call leaves the outcome unknown.
+ */
+export declare const DEFINITE_ORDER_FAILURE_CODES: ReadonlySet<ErrorCode>;
+/**
+ * true when `e` is a PerpError that says the order was definitely not placed: by its code, or —
+ * whatever the code — by `details.sent === false`, the thrower's explicit statement that it
+ * refused locally and sent nothing (QFEX: POSITION_NOT_FOUND from the pre-send position read).
+ * POSITION_NOT_FOUND is deliberately NOT in DEFINITE_ORDER_FAILURE_CODES: classifyError() also
+ * derives it from free message text ("position" + "not found"), and Aster / Lighter test such
+ * derived codes against the set — a text match is not proof that nothing was placed.
+ */
+export declare function isDefiniteOrderFailure(e: unknown): boolean;
+/**
+ * Failure BEFORE an order was sent (resolution, validation, pricing, nonce, signing):
+ * definitely not placed. A PerpError that already carries a definite code is kept.
+ */
+export declare function orderNotSent(venue: string, what: string, e: unknown): PerpError;
+/**
+ * Failure AFTER an order was sent (transport error, timeout, 5xx, unreadable body):
+ * the outcome is unknown — ORDER_PENDING (non-retryable, never resubmit).
+ */
+export declare function orderOutcomeUnknown(venue: string, what: string, e: unknown, remediation?: string): PerpError;
+/**
+ * A plain Error an adapter throws AFTER the order request reached the venue with an
+ * HTTP 5xx: Hyperliquid `HL exchange API error (5xx): …` (exchange POST, unparseable
+ * body) and Pacifica `POST <path> failed (5xx): …`. The outcome is unknown, never a
+ * rejection.
+ */
+export declare function isUnknownOutcomeServerError(e: unknown): boolean;
+/** A thrown value that looks like a transport failure (fetch/network/timeout/unparseable body). */
+export declare function isTransportFailure(e: unknown): boolean;
+/**
+ * A fetch failure where no connection was ever established (DNS failure, connection refused,
+ * connect timeout — read from the error's `code` / `cause` chain): the request was not sent.
+ */
+export declare function isConnectFailure(e: unknown): boolean;
+/**
+ * Failure of the request that SENDS an order / cancel / withdraw / transfer / leverage change.
+ * No connection was established (isConnectFailure) → not sent (definite). Anything else
+ * (connection reset, timeout, unreadable body, 5xx) → outcome unknown: ORDER_PENDING, never the
+ * retryable EXCHANGE_UNREACHABLE / TIMEOUT. A PerpError that is already definite is kept.
+ */
+export declare function sendFailure(venue: string, what: string, e: unknown, remediation?: string): PerpError;
+/** Remediation for an unknown-outcome account action (not an order). */
+export declare function unknownActionRemediation(venue: string, action: string): string;
+/**
+ * Strict positive decimal amount ("10", "10.5"; no sign, exponent, or trailing text — "10abc"
+ * and "1e3" are refused). Returns the trimmed string.
+ */
+export declare function parsePositiveDecimal(raw: string, what: string): string;

package/dist/errors.js

@@ -11,6 +11,7 @@ export const ERROR_CODES = {
     SIZE_TOO_LARGE: { code: "SIZE_TOO_LARGE", status: 400, retryable: false },
     RISK_VIOLATION: { code: "RISK_VIOLATION", status: 403, retryable: false },
     DUPLICATE_ORDER: { code: "DUPLICATE_ORDER", status: 409, retryable: false },
+    DEPOSIT_REQUIRED: { code: "DEPOSIT_REQUIRED", status: 403, retryable: false },
     // Agent-wallet error codes (OWS / Phase 2a)
     NO_SIGNER_AVAILABLE: { code: "NO_SIGNER_AVAILABLE", status: 401, retryable: false },
     AGENT_NOT_REGISTERED: { code: "AGENT_NOT_REGISTERED", status: 401, retryable: false },
@@ -22,7 +23,26 @@ export const ERROR_CODES = {
     APPROVE_FAILED: { code: "APPROVE_FAILED", status: 500, retryable: false },
     LOCK_HELD: { code: "LOCK_HELD", status: 423, retryable: true, retryAfterMs: 5000 },
     PASSPHRASE_REQUIRED: { code: "PASSPHRASE_REQUIRED", status: 401, retryable: false },
+    INVALID_PASSPHRASE: { code: "INVALID_PASSPHRASE", status: 401, retryable: false },
     NOT_IMPLEMENTED: { code: "NOT_IMPLEMENTED", status: 501, retryable: false },
+    // Venue abstraction (docs/DESIGN-venue-abstraction.md §10)
+    UNKNOWN_VENUE: { code: "UNKNOWN_VENUE", status: 400, retryable: false },
+    TIF_REQUIRED: { code: "TIF_REQUIRED", status: 400, retryable: false },
+    INVALID_TICK: { code: "INVALID_TICK", status: 400, retryable: false },
+    NO_ENV_TIER: { code: "NO_ENV_TIER", status: 401, retryable: false },
+    NO_BRIDGE_ROUTE: { code: "NO_BRIDGE_ROUTE", status: 400, retryable: false },
+    CAPABILITY_UNSUPPORTED: { code: "CAPABILITY_UNSUPPORTED", status: 400, retryable: false },
+    /** Part of a multi-leg placement was accepted and part failed; retrying would duplicate the accepted legs. */
+    ORDER_PARTIAL: { code: "ORDER_PARTIAL", status: 500, retryable: false },
+    /** The order was submitted but its outcome is not confirmed; retrying could double-trade. */
+    ORDER_PENDING: { code: "ORDER_PENDING", status: 202, retryable: false },
+    /** The order was definitely NOT placed: the venue rejected it, or it failed before it was sent (design §12.3). */
+    ORDER_REJECTED: { code: "ORDER_REJECTED", status: 422, retryable: false },
+    /**
+     * The venue explicitly refused a non-order account action (withdraw / transfer / approval) and
+     * executed nothing — distinct from a network / unknown outcome (EXCHANGE_ERROR, UNKNOWN).
+     */
+    ACTION_REJECTED: { code: "ACTION_REJECTED", status: 422, retryable: false },
     // 5xx - System / transient errors
     EXCHANGE_UNREACHABLE: { code: "EXCHANGE_UNREACHABLE", status: 503, retryable: true },
     RATE_LIMITED: { code: "RATE_LIMITED", status: 429, retryable: true, retryAfterMs: 1000 },
@@ -117,12 +137,55 @@ export function classifyError(err, exchange) {
     if (lower.includes("passphrase required") || lower.includes("passphrase missing")) {
         return { ...ERROR_CODES.PASSPHRASE_REQUIRED, message, exchange };
     }
+    // OWS vault decrypt failure (NAPI binding throws "decryption failed: aead::Error"
+    // when the AEAD tag check fails — wrong passphrase or tampered ciphertext).
+    // Distinct from PASSPHRASE_REQUIRED (which means no passphrase was supplied):
+    // here a passphrase WAS supplied but did not unlock the vault.
+    if (lower.includes("aead::error") || lower.includes("decryption failed") || lower.includes("decryption error")) {
+        return {
+            ...ERROR_CODES.INVALID_PASSPHRASE,
+            message,
+            exchange,
+            remediation: "Re-check OWS passphrase. Confirm with: perp --json wallet show --passphrase $PP. If wallet was rekeyed, restore from backup or re-import.",
+        };
+    }
     if (lower.includes("partial") && (lower.includes("approve") || lower.includes("approval"))) {
         return { ...ERROR_CODES.APPROVE_PARTIAL, message, exchange };
     }
     if (lower.includes("approve_failed") || (lower.includes("approve failed") && lower.includes("clean"))) {
         return { ...ERROR_CODES.APPROVE_FAILED, message, exchange };
     }
+    // Aster V3 gates every authenticated endpoint behind a first main-wallet
+    // deposit as of 2026-09-01 (venue code -5050 DEPOSIT_REQUIRED, message
+    // "This function can only be used after deposit."). Without this branch the
+    // message falls through to a bare EXCHANGE_ERROR and the user never learns
+    // that a deposit — not a key/permission problem — is what blocks them. The
+    // agent-wallet and builder endpoints are exempt, so onboarding succeeds and
+    // the first read is what fails.
+    if (lower.includes("after deposit") || lower.includes("deposit_required") || lower.includes("-5050")) {
+        return {
+            ...ERROR_CODES.DEPOSIT_REQUIRED,
+            message,
+            exchange,
+            remediation: "This venue requires a completed deposit to the main wallet before any authenticated endpoint works. " +
+                "Deposit with: perp funds deposit aster <amount> (USDT on BNB Chain; --chain arbitrum / --asset USDC also work), " +
+                "or from the exchange UI, then retry. Public market data and agent-wallet setup are unaffected.",
+        };
+    }
+    // Aster -4061: the account is in Hedge Mode, where `positionSide` is
+    // mandatory and `reduceOnly` is forbidden. This adapter always sends one-way
+    // shape, so every order is rejected until the account switches back. Without
+    // this branch the user sees a bare "position side does not match" with no
+    // indication that the ACCOUNT MODE is the thing to change.
+    if (lower.includes("-4061") || lower.includes("position side does not match") || lower.includes("position_side_not_match")) {
+        return {
+            ...ERROR_CODES.INVALID_PARAMS,
+            message,
+            exchange,
+            remediation: "The account appears to be in Hedge Mode, which this adapter does not support (it sends one-way orders). " +
+                "Switch to One-way Mode in the exchange UI, or via POST /fapi/v3/positionSide/dual with dualSidePosition=false, then retry.",
+        };
+    }
     if (lower.includes("not found") && (lower.includes("symbol") || lower.includes("market") || lower.includes("asset"))) {
         return { ...ERROR_CODES.SYMBOL_NOT_FOUND, message, exchange };
     }
@@ -172,3 +235,134 @@ export class PerpError extends Error {
         };
     }
 }
+// ── Order outcome classification (design §12.3) ──
+/**
+ * Codes that mean "the order was definitely not placed / filled nothing": a validation
+ * or policy failure before sending (incl. PRICE_STALE: no price to build the order), or an
+ * explicit venue rejection. Every other code
+ * (EXCHANGE_UNREACHABLE, TIMEOUT, EXCHANGE_ERROR, RATE_LIMITED, UNKNOWN, …) raised by
+ * an order call leaves the outcome unknown.
+ */
+export const DEFINITE_ORDER_FAILURE_CODES = new Set([
+    "INVALID_PARAMS", "SYMBOL_NOT_FOUND", "INSUFFICIENT_BALANCE", "MARGIN_INSUFFICIENT",
+    "SIZE_TOO_SMALL", "SIZE_TOO_LARGE", "RISK_VIOLATION", "DEPOSIT_REQUIRED",
+    "NO_SIGNER_AVAILABLE", "AGENT_NOT_REGISTERED", "AGENT_EXPIRED", "POLICY_DENIED",
+    "KEY_NOT_FOUND", "WALLET_LOCKED", "PASSPHRASE_REQUIRED", "INVALID_PASSPHRASE",
+    "NOT_IMPLEMENTED", "UNKNOWN_VENUE", "TIF_REQUIRED", "INVALID_TICK",
+    "NO_ENV_TIER", "CAPABILITY_UNSUPPORTED", "SIGNATURE_FAILED", "ORDER_REJECTED", "ACTION_REJECTED",
+    // No usable price to build/check the order — raised only before an order is sent.
+    "PRICE_STALE",
+]);
+/**
+ * true when `e` is a PerpError that says the order was definitely not placed: by its code, or —
+ * whatever the code — by `details.sent === false`, the thrower's explicit statement that it
+ * refused locally and sent nothing (QFEX: POSITION_NOT_FOUND from the pre-send position read).
+ * POSITION_NOT_FOUND is deliberately NOT in DEFINITE_ORDER_FAILURE_CODES: classifyError() also
+ * derives it from free message text ("position" + "not found"), and Aster / Lighter test such
+ * derived codes against the set — a text match is not proof that nothing was placed.
+ */
+export function isDefiniteOrderFailure(e) {
+    if (!(e instanceof PerpError))
+        return false;
+    return DEFINITE_ORDER_FAILURE_CODES.has(e.structured.code) || e.structured.details?.sent === false;
+}
+/**
+ * Failure BEFORE an order was sent (resolution, validation, pricing, nonce, signing):
+ * definitely not placed. A PerpError that already carries a definite code is kept.
+ */
+export function orderNotSent(venue, what, e) {
+    // By CODE only: a not-sent error with a retryable code (TIMEOUT / EXCHANGE_UNREACHABLE with
+    // details.sent === false) is still re-typed, so an order call never surfaces a retryable code.
+    if (e instanceof PerpError && DEFINITE_ORDER_FAILURE_CODES.has(e.structured.code))
+        return e;
+    return new PerpError("ORDER_REJECTED", `${venue} ${what} not sent: ${extractErrorMessage(e)}`, { exchange: venue });
+}
+/**
+ * Failure AFTER an order was sent (transport error, timeout, 5xx, unreadable body):
+ * the outcome is unknown — ORDER_PENDING (non-retryable, never resubmit).
+ */
+export function orderOutcomeUnknown(venue, what, e, remediation) {
+    if (e instanceof PerpError && e.structured.code === "ORDER_PENDING")
+        return e;
+    return new PerpError("ORDER_PENDING", `${venue} ${what}: outcome unknown — ${extractErrorMessage(e)}`, {
+        exchange: venue,
+        remediation: remediation ?? `Do NOT resubmit — the order may have been placed. Check open orders, balances and positions on ${venue}`,
+    });
+}
+/**
+ * A plain Error an adapter throws AFTER the order request reached the venue with an
+ * HTTP 5xx: Hyperliquid `HL exchange API error (5xx): …` (exchange POST, unparseable
+ * body) and Pacifica `POST <path> failed (5xx): …`. The outcome is unknown, never a
+ * rejection.
+ */
+export function isUnknownOutcomeServerError(e) {
+    if (e instanceof PerpError)
+        return false;
+    return /^HL exchange API error \(5\d\d\)|^POST \S+ failed \(5\d\d\)/.test(extractErrorMessage(e));
+}
+/** A thrown value that looks like a transport failure (fetch/network/timeout/unparseable body). */
+export function isTransportFailure(e) {
+    if (e instanceof PerpError)
+        return false;
+    if (e instanceof TypeError || e instanceof SyntaxError)
+        return true;
+    const name = e instanceof Error ? e.name : "";
+    if (name === "AbortError" || name === "TimeoutError")
+        return true;
+    // "network" alone is NOT a transport signal: definite refusals such as "wrong network" /
+    // "unsupported network" mention it too. Only transport phrasings ("network error",
+    // "NetworkError when attempting to fetch", "network request failed", …) count.
+    return /fetch failed|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|socket hang up|\bnetwork ?(error|request failed|failure|unreachable|is unreachable|connection lost)\b|timed? ?out/i.test(extractErrorMessage(e));
+}
+const CONNECT_FAILURE_CODES = new Set(["ENOTFOUND", "EAI_AGAIN", "ECONNREFUSED", "UND_ERR_CONNECT_TIMEOUT", "ENETUNREACH", "EHOSTUNREACH"]);
+/**
+ * A fetch failure where no connection was ever established (DNS failure, connection refused,
+ * connect timeout — read from the error's `code` / `cause` chain): the request was not sent.
+ */
+export function isConnectFailure(e) {
+    const seen = new Set();
+    const walk = (x) => {
+        if (x === null || typeof x !== "object" || seen.has(x))
+            return false;
+        seen.add(x);
+        const o = x;
+        if (typeof o.code === "string" && CONNECT_FAILURE_CODES.has(o.code))
+            return true;
+        if (Array.isArray(o.errors) && o.errors.length > 0 && o.errors.every(walk))
+            return true;
+        return walk(o.cause);
+    };
+    return walk(e);
+}
+/**
+ * Failure of the request that SENDS an order / cancel / withdraw / transfer / leverage change.
+ * No connection was established (isConnectFailure) → not sent (definite). Anything else
+ * (connection reset, timeout, unreadable body, 5xx) → outcome unknown: ORDER_PENDING, never the
+ * retryable EXCHANGE_UNREACHABLE / TIMEOUT. A PerpError that is already definite is kept.
+ */
+export function sendFailure(venue, what, e, remediation) {
+    if (e instanceof PerpError && DEFINITE_ORDER_FAILURE_CODES.has(e.structured.code))
+        return e;
+    if (isDefiniteOrderFailure(e))
+        return orderNotSent(venue, what, e);
+    if (isConnectFailure(e))
+        return orderNotSent(venue, what, e);
+    return orderOutcomeUnknown(venue, what, e, remediation);
+}
+/** Remediation for an unknown-outcome account action (not an order). */
+export function unknownActionRemediation(venue, action) {
+    return `Do NOT resubmit — the ${action} may have been executed. Check balances, positions and open orders on ${venue} first`;
+}
+/**
+ * Strict positive decimal amount ("10", "10.5"; no sign, exponent, or trailing text — "10abc"
+ * and "1e3" are refused). Returns the trimmed string.
+ */
+export function parsePositiveDecimal(raw, what) {
+    const s = String(raw).trim();
+    if (!/^(\d+(\.\d+)?|\.\d+)$/.test(s) || !(Number(s) > 0)) {
+        throw new PerpError("INVALID_PARAMS", `${what} must be a positive decimal number (got "${raw}")`, {
+            remediation: "Pass a plain decimal amount, e.g. 10 or 10.5",
+        });
+    }
+    return s;
+}