perp-cli 0.14.3 → 0.16.0

package/dist/cross-chain-margin.js

@@ -94,11 +94,13 @@ export function marginEntryBlocks(check, minMarginPct = 30) {
  * @param maxSlippagePct - Max acceptable slippage (default: 0.3%)
  * @returns USD size per leg, or 0 if not viable
  */
-export async function computeAutoSize(longAdapter, shortAdapter, symbol, maxSlippagePct = 0.3) {
+export async function computeAutoSize(longAdapter, shortAdapter, symbol, maxSlippagePct = 0.3, 
+/** The short venue's own symbol when it differs (kPEPE ↔ 1000PEPE); default `symbol`. */
+shortSymbol = symbol) {
     // Step 1: Get orderbooks from both sides
     const [longOB, shortOB, longBal, shortBal] = await Promise.all([
         longAdapter.getOrderbook(symbol),
-        shortAdapter.getOrderbook(symbol),
+        shortAdapter.getOrderbook(shortSymbol),
         longAdapter.getBalance(),
         shortAdapter.getBalance(),
     ]);

package/dist/dashboard/server.js

@@ -44,11 +44,11 @@ async function pollArbData() {
     let exchangeStatus = {};
     let exchangeErrors = {};
     try {
-        const { fetchAllFundingRates } = await import("../funding/rates.js");
+        const { fetchAllFundingRates, isRankedComparison } = await import("../funding/rates.js");
         const snapshot = await fetchAllFundingRates({ minSpread: 5 });
         exchangeStatus = snapshot.exchangeStatus;
         exchangeErrors = snapshot.exchangeErrors;
-        for (const sym of snapshot.symbols.slice(0, 20)) {
+        for (const sym of snapshot.symbols.filter(isRankedComparison).slice(0, 20)) {
             opportunities.push({
                 symbol: sym.symbol,
                 longExchange: sym.longExchange,
@@ -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

@@ -235,6 +235,8 @@ 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); }
+// Market row cells: prices in the row's quote currency (QFEX SAMSUNG-KRW: "220,150.00 KRW", never $); OI is BASE units (never $); funding null = "-" (not 0%).
+function marketCells(m) { const q=(typeof m.quoteAsset==='string'&&m.quoteAsset!=='USD')?escHtml(m.quoteAsset):null; const px=(v,d=2)=>v==null?'-':(q===null?'$'+fmt(v,d):fmt(v,d)+' '+q); const vol=m.volume24h==null&&typeof m.volume24hQuote==='string'?px(m.volume24hQuote,0):usdOrDash(m.volume24h,0); const base=escHtml(String(m.symbol).split(':').pop().replace(/-PERP$/i,'')); return { mark: px(m.markPrice), index: px(m.indexPrice), funding: m.fundingRate==null?'-':(Number(m.fundingRate)*100).toFixed(4)+'%', volume: vol, oi: m.openInterest==null?'-':Number(m.openInterest).toLocaleString('en-US',{maximumFractionDigits:4})+' '+base }; }
 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'; }
@@ -243,7 +245,8 @@ function spreadClass(v) { return v>=50?'spread-high':v>=20?'spread-mid':'spread-
 const NA = '<span style="color:var(--yellow,#e5c07b)">unavailable</span>';
 function usdOrNA(v, d=2) { return v==null ? NA : '$'+fmt(v,d); }
 function pnlOrNA(v) { return v==null ? NA : pnlSign(v); }
-function escHtml(v) { return String(v).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'})[c]); }
+// Every venue-supplied string (symbol, quoteAsset, dex, exchange, order fields) goes through this before innerHTML.
+function escHtml(v) { return String(v).replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'})[c]); }
 
 // ── Portfolio Rendering ──
 function renderTotals(t) {
@@ -325,16 +328,16 @@ function renderPanels(exchanges) {
         const notional = p.markPrice == null ? null : Math.abs(Number(p.size)) * Number(p.markPrice);
         const margin = notional == null ? null : p.leverage > 0 ? notional / p.leverage : notional;
         const roe = margin != null && margin > 0 && p.unrealizedPnl != null ? (Number(p.unrealizedPnl) / margin * 100) : null;
-        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>\${usdOrNA(p.entryPrice)}</td><td>\${usdOrNA(p.markPrice)}</td><td>\${(p.liquidationPrice==null||p.liquidationPrice==='N/A')?'-':'$'+fmt(p.liquidationPrice)}</td><td style="color:var(--muted)">\${usdOrNA(notional)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${pnlOrNA(p.unrealizedPnl)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${roe==null?NA:(roe>=0?'+':'')+fmt(roe,1)+'%'}</td><td>\${p.leverage}x</td></tr>\`;
+        return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${escHtml(dex)}</td>\`:''}<td>\${escHtml(sym)}</td><td class="side-\${escHtml(p.side)}">\${escHtml(String(p.side).toUpperCase())}</td><td>\${escHtml(p.size)}</td><td>\${usdOrNA(p.entryPrice)}</td><td>\${usdOrNA(p.markPrice)}</td><td>\${(p.liquidationPrice==null||p.liquidationPrice==='N/A')?'-':'$'+fmt(p.liquidationPrice)}</td><td style="color:var(--muted)">\${usdOrNA(notional)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${pnlOrNA(p.unrealizedPnl)}</td><td class="\${pnlClass(p.unrealizedPnl)}">\${roe==null?NA:(roe>=0?'+':'')+fmt(roe,1)+'%'}</td><td>\${p.leverage}x</td></tr>\`;
       }).join('')}</tbody></table>\`:(posKnown?'<div class="empty-msg">No open positions</div>':'<div class="empty-msg">Positions '+NA+'</div>')}
       <div class="section-title">Open Orders (\${ordKnown ? 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=>{
         const dex = getDex(o.symbol);
         const sym = o.symbol.includes(':') ? o.symbol.split(':').slice(1).join(':') : o.symbol;
-        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>\`;
+        return \`<tr>\${isHL?\`<td style="color:var(--purple);font-size:11px">\${escHtml(dex)}</td>\`:''}<td>\${escHtml(sym)}</td><td class="side-\${escHtml(o.side)}">\${escHtml(String(o.side).toUpperCase())}</td><td>\${escHtml(o.type)}</td><td>$\${fmt(o.price)}</td><td>\${escHtml(o.size)}</td><td>\${escHtml(o.filled)}</td><td>\${escHtml(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==null?'-':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);const c=marketCells(m);return\`<tr><td>\${escHtml(m.symbol)}</td><td>\${c.mark}</td><td>\${c.index}</td><td class="\${rateClass(fr)}">\${c.funding}</td><td>\${c.volume}</td><td>\${c.oi}</td><td>\${m.maxLeverage==null?'-':m.maxLeverage+'x'}</td></tr>\`;}).join('')}</tbody></table>\`:'<div class="empty-msg">No market data</div>'}
     </div>\`;
   }).join('');
 
@@ -419,7 +422,7 @@ function renderArb() {
       const barColor = o.spreadAnnual>=50?'var(--green)':o.spreadAnnual>=20?'var(--yellow)':'var(--muted)';
       const bestMark = o.rates.reduce((best,r) => r.markPrice>0?r.markPrice:best, 0);
       return \`<tr>
-        <td style="font-weight:600">\${o.symbol}</td>
+        <td style="font-weight:600">\${escHtml(o.symbol)}</td>
         <td>
           <div class="\${spreadClass(o.spreadAnnual)}">\${fmt(o.spreadAnnual,1)}%</div>
           <div class="spread-bar"><div class="spread-bar-fill" style="width:\${barW}%;background:\${barColor}"></div></div>
@@ -514,7 +517,7 @@ function renderEvents() {
   if (!events.length) { el.innerHTML='<div class="empty-msg">Waiting for events...</div>'; return; }
   el.innerHTML = events.map(e => {
     const cls = e.isCrit?'crit':e.isWarn?'warn':'';
-    return \`<div class="event"><span class="event-time">\${e.time}</span> <span class="event-type \${cls}">[\${e.type}]</span> <span>\${e.exchange}</span> <span style="color:var(--muted)">\${JSON.stringify(e.data).slice(0,120)}</span></div>\`;
+    return \`<div class="event"><span class="event-time">\${e.time}</span> <span class="event-type \${cls}">[\${e.type}]</span> <span>\${escHtml(e.exchange)}</span> <span style="color:var(--muted)">\${escHtml(JSON.stringify(e.data).slice(0,120))}</span></div>\`;
   }).join('');
 }
 

package/dist/errors.d.ts

@@ -158,7 +158,7 @@ export declare const ERROR_CODES: {
         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). */
+    /** The order was definitely NOT placed: the venue rejected it, or it failed before it was sent. */
     readonly ORDER_REJECTED: {
         readonly code: "ORDER_REJECTED";
         readonly status: 422;
@@ -173,6 +173,29 @@ export declare const ERROR_CODES: {
         readonly status: 422;
         readonly retryable: false;
     };
+    /** A venue frame could not be parsed or classified (never silently dropped). */
+    readonly WS_PROTOCOL_ERROR: {
+        readonly code: "WS_PROTOCOL_ERROR";
+        readonly status: 502;
+        readonly retryable: false;
+    };
+    readonly WS_AUTH_FAILED: {
+        readonly code: "WS_AUTH_FAILED";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    /** A subscription / connection budget (venue limit or caller budget) would be exceeded. */
+    readonly SUBSCRIPTION_LIMIT: {
+        readonly code: "SUBSCRIPTION_LIMIT";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    /** An event stream's bounded buffer overflowed; the subscription was closed. */
+    readonly STREAM_OVERFLOW: {
+        readonly code: "STREAM_OVERFLOW";
+        readonly status: 507;
+        readonly retryable: false;
+    };
     readonly EXCHANGE_UNREACHABLE: {
         readonly code: "EXCHANGE_UNREACHABLE";
         readonly status: 503;
@@ -297,3 +320,8 @@ export declare function unknownActionRemediation(venue: string, action: string):
  * and "1e3" are refused). Returns the trimmed string.
  */
 export declare function parsePositiveDecimal(raw: string, what: string): string;
+/**
+ * A keyless account read (positions, balance, orders, history): the one typed refusal every venue
+ * returns — NO_SIGNER_AVAILABLE with the setup remediation (never an UNKNOWN 500).
+ */
+export declare function noAccountKeyError(venue: string): PerpError;

package/dist/errors.js

@@ -25,7 +25,7 @@ export const ERROR_CODES = {
     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)
+    // Venue abstraction
     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 },
@@ -36,13 +36,21 @@ export const ERROR_CODES = {
     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). */
+    /** The order was definitely NOT placed: the venue rejected it, or it failed before it was sent. */
     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 },
+    // WebSocket library (perp-cli/ws, src/ws/errors.ts keeps a parity-tested copy)
+    /** A venue frame could not be parsed or classified (never silently dropped). */
+    WS_PROTOCOL_ERROR: { code: "WS_PROTOCOL_ERROR", status: 502, retryable: false },
+    WS_AUTH_FAILED: { code: "WS_AUTH_FAILED", status: 401, retryable: false },
+    /** A subscription / connection budget (venue limit or caller budget) would be exceeded. */
+    SUBSCRIPTION_LIMIT: { code: "SUBSCRIPTION_LIMIT", status: 400, retryable: false },
+    /** An event stream's bounded buffer overflowed; the subscription was closed. */
+    STREAM_OVERFLOW: { code: "STREAM_OVERFLOW", status: 507, 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 },
@@ -92,6 +100,12 @@ export function classifyError(err, exchange) {
         const ex = (err.structured.exchange ?? exchange);
         return ex !== undefined ? { ...err.structured, exchange: ex } : { ...err.structured };
     }
+    // Structural PerpError (perp-cli/ws WsError is a separate leaf class): keep its registered code.
+    if (err instanceof Error && isStructuredLike(err)) {
+        const s = err.structured;
+        const ex = s.exchange ?? exchange;
+        return ex !== undefined ? { ...s, exchange: ex } : { ...s };
+    }
     const message = extractErrorMessage(err);
     const lower = message.toLowerCase();
     // Margin-specific checks first (before generic "insufficient" catch)
@@ -216,6 +230,14 @@ export function classifyError(err, exchange) {
     }
     return { ...ERROR_CODES.UNKNOWN, message };
 }
+function isStructuredLike(err) {
+    const s = err.structured;
+    if (s === null || typeof s !== "object")
+        return false;
+    const { code, message, status, retryable } = s;
+    return typeof code === "string" && Object.prototype.hasOwnProperty.call(ERROR_CODES, code)
+        && typeof message === "string" && typeof status === "number" && typeof retryable === "boolean";
+}
 /** Custom error class that carries a structured error code */
 export class PerpError extends Error {
     structured;
@@ -235,7 +257,7 @@ export class PerpError extends Error {
         };
     }
 }
-// ── Order outcome classification (design §12.3) ──
+// ── Order outcome classification ──
 /**
  * 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
@@ -366,3 +388,13 @@ export function parsePositiveDecimal(raw, what) {
     }
     return s;
 }
+/**
+ * A keyless account read (positions, balance, orders, history): the one typed refusal every venue
+ * returns — NO_SIGNER_AVAILABLE with the setup remediation (never an UNKNOWN 500).
+ */
+export function noAccountKeyError(venue) {
+    return new PerpError("NO_SIGNER_AVAILABLE", `${venue}: no account key configured — account data unavailable`, {
+        exchange: venue,
+        remediation: `Set up an account for ${venue}: perp setup (or perp -e ${venue} wallet show to check)`,
+    });
+}

package/dist/exchanges/address.d.ts

@@ -0,0 +1,8 @@
+export type AddressKind = "evm" | "solana";
+export declare function isEvmAddress(value: string): boolean;
+/** A base58 string that decodes to a 32-byte public key. */
+export declare function isSolanaAddress(value: string): boolean;
+/** Pacifica account / Print order / vault address: base58 32 bytes, else INVALID_PARAMS. */
+export declare function requireSolanaAddress(value: string, field?: string): string;
+/** `address` in the form `kind` expects (trimmed), else INVALID_PARAMS naming the expected form. */
+export declare function requireAddressOfKind(venue: string, kind: AddressKind, address: string): string;

package/dist/exchanges/address.js

@@ -0,0 +1,47 @@
+/**
+ * Public account address formats (keyless reads by address): EVM `0x` + 40 hex (Hyperliquid,
+ * Lighter) and base58 Solana public keys (Pacifica). A wrong format is refused with
+ * INVALID_PARAMS before any request — the venues answer a foreign address with an empty success
+ * (Pacifica `success: true, []`), which would read as "no positions".
+ */
+import bs58 from "bs58";
+import { PerpError } from "../errors.js";
+const EVM_RE = /^0x[0-9a-fA-F]{40}$/;
+export function isEvmAddress(value) {
+    return EVM_RE.test(value.trim());
+}
+/** A base58 string that decodes to a 32-byte public key. */
+export function isSolanaAddress(value) {
+    try {
+        return bs58.decode(value.trim()).length === 32;
+    }
+    catch {
+        return false;
+    }
+}
+/** Pacifica account / Print order / vault address: base58 32 bytes, else INVALID_PARAMS. */
+export function requireSolanaAddress(value, field = "address") {
+    const a = value.trim();
+    if (!isSolanaAddress(a)) {
+        throw new PerpError("INVALID_PARAMS", `Not a Solana (base58) ${field}: "${value}"${isEvmAddress(a) ? " — that is an EVM address; Pacifica accounts are Solana addresses" : ""}`, {
+            exchange: "pacifica", remediation: "Pass the base58 Solana address you use on Pacifica",
+        });
+    }
+    return a;
+}
+/** `address` in the form `kind` expects (trimmed), else INVALID_PARAMS naming the expected form. */
+export function requireAddressOfKind(venue, kind, address) {
+    const a = address.trim();
+    if (kind === "evm") {
+        if (isEvmAddress(a))
+            return a;
+        throw new PerpError("INVALID_PARAMS", `${venue} expects an EVM 0x address (0x + 40 hex)${isSolanaAddress(a) ? " — that is a Solana address" : ""}: "${address}"`, {
+            exchange: venue, remediation: `Pass the 0x address of the ${venue} account`,
+        });
+    }
+    if (isSolanaAddress(a))
+        return a;
+    throw new PerpError("INVALID_PARAMS", `${venue} expects a base58 Solana address${isEvmAddress(a) ? " — that is an EVM address" : ""}: "${address}"`, {
+        exchange: venue, remediation: `Pass the base58 Solana address of the ${venue} account`,
+    });
+}

package/dist/exchanges/arcus/adapter.d.ts

@@ -1,5 +1,5 @@
 /**
- * Arcus adapter — native TradingV2 + legacy ExchangeAdapter shim (design §10.7).
+ * Arcus adapter — native TradingV2 + legacy ExchangeAdapter shim.
  *
  * Signing: the agent API key is an Ed25519 key in OWS wallet
  * `meta.agentWalletName` (raw signMessage on the Solana account — no prefix).
@@ -7,12 +7,12 @@
  * (master creds only, for spot swaps) every perp private call throws
  * AGENT_NOT_REGISTERED from requireAccount().
  *
- * Order entry rules (docs.arcus.xyz, design §10.10):
+ * Order entry rules (docs.arcus.xyz):
  * - every order carries goodTilTime ≥ 1 month ahead (ARCUS_GOOD_TIL_HORIZON_MS),
  *   body in µs, signed `g` in ns;
  * - market orders = IOC LIMIT at a protection price derived from mark and an
  *   explicit slippage bound, rejected locally when > 10 % from mark;
- * - TIF (design §13.3): common GTC is sent as GTT with goodTil = now +
+ * - TIF: common GTC is sent as GTT with goodTil = now +
  *   ARCUS_GOOD_TIL_HORIZON_MS (recorded as execution.expiresAt); IOC / FOK / ALO
  *   are native; a limit order without a TIF is GTC;
  * - clientId is always sent (orderAck async) and every OrderResult from a
@@ -22,7 +22,7 @@
  *   an `entryTpsl` bundle.
  */
 import type { EvmSigner } from "../../signer/interface.js";
-import type { ExchangeAdapter, ExchangeBalance, ExchangeFundingPayment, ExchangeKline, ExchangeMarketInfo, ExchangeOrder, ExchangePosition, ExchangeTrade } from "../interface.js";
+import type { ExchangeAdapter, ExchangeBalance, ExchangeFundingPayment, ExchangeKline, ExchangeMarketInfo, ExchangeOrder, ExchangePosition, ExchangeTrade, ExchangePublicTrade, FundingHistoryRow } from "../interface.js";
 import type { ResolvedSlippage } from "../slippage.js";
 import { type TradingV2 } from "../trading-v2.js";
 import type { VenueCreateContext, VenueDefinition } from "../venue.js";
@@ -37,6 +37,8 @@ export declare const ARCUS_GOOD_TIL_HORIZON_MS: number;
 export declare const ARCUS_MAX_PROTECTION_DEVIATION = 0.1;
 /** clientId max (36) minus the "-tp"/"-sl" suffix of entryTpsl child legs. */
 export declare const ARCUS_TPSL_CLIENT_ID_MAX = 33;
+/** /v1/trades and /v1/fundingRates take `limit` ≤ 1000 (docs; the venue answered 1000 rows for more). */
+export declare const ARCUS_HISTORY_CAP = 1000;
 export declare class ArcusAdapter implements ExchangeAdapter, TradingV2 {
     readonly name: "arcus";
     readonly venue: VenueDefinition;
@@ -57,6 +59,12 @@ export declare class ArcusAdapter implements ExchangeAdapter, TradingV2 {
     private accountQuery;
     private loadMarkets;
     private market;
+    /**
+     * A market-data read (book / trades / funding / candles) of a listed market that is not ONLINE
+     * is refused like `market info` / `market list` treat it (not listed): SYMBOL_NOT_FOUND naming
+     * the venue status — the venue answered `[]` or HTTP 404 ORDER_NOT_FOUND for it before.
+     */
+    private onlineMarket;
     private symbolOf;
     /** Protection price: slippage from `ref`, aligned toward crossing on the tier tick, ≤ 10 % from `ref`. */
     private protectionPrice;
@@ -92,7 +100,7 @@ export declare class ArcusAdapter implements ExchangeAdapter, TradingV2 {
     /**
      * modifyOrder (docs modify-order / authentication).
      *
-     * Size: the CLI's `req.size` is the new OPEN (unfilled) size (design §13.4), while
+     * Size: the CLI's `req.size` is the new OPEN (unfilled) size, while
      * Arcus modifies take the order's new TOTAL size, filled quantity included
      * (OrderRejectionReason MODIFY_SIZE_ALREADY_FILLED: "the order's new TOTAL size,
      * filled quantity included"). So body `quantity` and signed `q` are
@@ -143,12 +151,8 @@ export declare class ArcusAdapter implements ExchangeAdapter, TradingV2 {
         bids: [string, string][];
         asks: [string, string][];
     }>;
-    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
-    getFundingHistory(symbol: string, limit?: number): Promise<{
-        time: number;
-        rate: string;
-        price: string | null;
-    }[]>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
+    getFundingHistory(symbol: string, limit?: number): Promise<FundingHistoryRow[]>;
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
     private rawPositions;
     getBalance(): Promise<ExchangeBalance>;
@@ -182,7 +186,7 @@ export declare class ArcusAdapter implements ExchangeAdapter, TradingV2 {
     }): Promise<unknown>;
     private masterSigner;
     private requireMasterKey;
-    /** Master EVM signer for on-chain actions outside the Arcus API (spot swaps, design §12.4 #7). */
+    /** Master EVM signer for on-chain actions outside the Arcus API (spot swaps). */
     masterEvmSigner(): Promise<EvmSigner>;
     /** Sign an unsigned EVM transaction with the master key (digest derived here). Returns a 65-byte 0x signature. */
     signMasterTransaction(tx: import("ethers").Transaction): Promise<string>;

package/dist/exchanges/arcus/adapter.js

@@ -1,5 +1,5 @@
 /**
- * Arcus adapter — native TradingV2 + legacy ExchangeAdapter shim (design §10.7).
+ * Arcus adapter — native TradingV2 + legacy ExchangeAdapter shim.
  *
  * Signing: the agent API key is an Ed25519 key in OWS wallet
  * `meta.agentWalletName` (raw signMessage on the Solana account — no prefix).
@@ -7,12 +7,12 @@
  * (master creds only, for spot swaps) every perp private call throws
  * AGENT_NOT_REGISTERED from requireAccount().
  *
- * Order entry rules (docs.arcus.xyz, design §10.10):
+ * Order entry rules (docs.arcus.xyz):
  * - every order carries goodTilTime ≥ 1 month ahead (ARCUS_GOOD_TIL_HORIZON_MS),
  *   body in µs, signed `g` in ns;
  * - market orders = IOC LIMIT at a protection price derived from mark and an
  *   explicit slippage bound, rejected locally when > 10 % from mark;
- * - TIF (design §13.3): common GTC is sent as GTT with goodTil = now +
+ * - TIF: common GTC is sent as GTT with goodTil = now +
  *   ARCUS_GOOD_TIL_HORIZON_MS (recorded as execution.expiresAt); IOC / FOK / ALO
  *   are native; a limit order without a TIF is GTC;
  * - clientId is always sent (orderAck async) and every OrderResult from a
@@ -22,6 +22,7 @@
  *   an `entryTpsl` bundle.
  */
 import { PerpError } from "../../errors.js";
+import { isArcusOnlineMarket } from "../../ws/arcus-market.js";
 import { OwsEvmSigner } from "../../signer/ows-evm.js";
 import { OwsSolanaSigner } from "../../signer/ows-solana.js";
 import { alignProtectionPrice, floorSize, mulDecimal, requirePositive, slippagePrice, subDecimal, toUnitsExact, unitsToString } from "../precision.js";
@@ -90,6 +91,15 @@ function finalityOf(s) {
     return s === "filled" || s === "rejected" || s === "cancelled" ? "final" : "pending";
 }
 const usToMs = (us) => Math.floor(us / 1000);
+/** /v1/trades and /v1/fundingRates take `limit` ≤ 1000 (docs; the venue answered 1000 rows for more). */
+export const ARCUS_HISTORY_CAP = 1000;
+function arcusLimit(what, limit) {
+    if (!Number.isInteger(limit) || limit < 1 || limit > ARCUS_HISTORY_CAP) {
+        throw new PerpError("INVALID_PARAMS", `Arcus: ${what} limit must be 1..${ARCUS_HISTORY_CAP} (got ${limit})`, {
+            remediation: `Arcus serves at most ${ARCUS_HISTORY_CAP} rows per request`,
+        });
+    }
+}
 function sideLower(s) { return s === "BUY" ? "buy" : "sell"; }
 function tifFromRead(t) {
     // Reads report resting (GTT) orders as the legacy "GTC".
@@ -196,13 +206,13 @@ export class ArcusAdapter {
         const meta = ctx.noAgent ? null : ctx.credentials.agent;
         if (meta === null) {
             if (!hasMaster) {
-                // §12.4 #7: no agent key and no master EVM key — nothing can sign.
+                // no agent key and no master EVM key — nothing can sign.
                 throw new PerpError("NO_SIGNER_AVAILABLE", "No Arcus signer: no agent API key and no master EVM wallet / private key", {
                     remediation: "Spot swaps: pass --wallet <ows-wallet> (master EVM key). Perp trading: perp wallet agent approve arcus --master <ows-wallet>",
                 });
             }
             // Master-only (also --no-agent): spot swaps (master EVM signer) work; perp
-            // private calls throw AGENT_NOT_REGISTERED in requireAccount() (design §12.4 #7).
+            // private calls throw AGENT_NOT_REGISTERED in requireAccount().
             this.client = new ArcusClient(ctx.network, null);
             this.account = null;
             return;
@@ -281,6 +291,21 @@ export class ArcusAdapter {
         }
         return m;
     }
+    /**
+     * A market-data read (book / trades / funding / candles) of a listed market that is not ONLINE
+     * is refused like `market info` / `market list` treat it (not listed): SYMBOL_NOT_FOUND naming
+     * the venue status — the venue answered `[]` or HTTP 404 ORDER_NOT_FOUND for it before.
+     */
+    async onlineMarket(symbol) {
+        const m = await this.market(symbol);
+        if (!isArcusOnlineMarket(m)) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `Arcus: market ${m.marketDisplayName} is ${m.status} (not tradable; no live market data)`, {
+                exchange: "arcus", status: m.status, tradable: false,
+                remediation: "List live markets with: perp market list -e arcus",
+            });
+        }
+        return m;
+    }
     async symbolOf(marketId) {
         let m = (await this.loadMarkets(false)).byId.get(marketId);
         if (!m)
@@ -462,7 +487,7 @@ export class ArcusAdapter {
         return onlineArcusMarkets(raw).map(toArcusVenueMarket);
     }
     async placeOrder(input) {
-        // §13.3: GTC is the uniform default for a limit order without a TIF.
+        // GTC is the uniform default for a limit order without a TIF.
         const tifRequested = input.tif;
         const req = input.type === "limit" && input.tif === null ? { ...input, tif: "GTC" } : input;
         validateOrderRequest(this.venue, this.caps, req);
@@ -609,7 +634,7 @@ export class ArcusAdapter {
     /**
      * modifyOrder (docs modify-order / authentication).
      *
-     * Size: the CLI's `req.size` is the new OPEN (unfilled) size (design §13.4), while
+     * Size: the CLI's `req.size` is the new OPEN (unfilled) size, while
      * Arcus modifies take the order's new TOTAL size, filled quantity included
      * (OrderRejectionReason MODIFY_SIZE_ALREADY_FILLED: "the order's new TOTAL size,
      * filled quantity included"). So body `quantity` and signed `q` are
@@ -878,20 +903,22 @@ export class ArcusAdapter {
         return (await this.getVenueMarkets()).map(toLegacyMarketInfo);
     }
     async getOrderbook(symbol) {
-        const m = await this.market(symbol);
+        const m = await this.onlineMarket(symbol);
         const ob = await this.client.get(`/v1/l2OrderBook/${encodeURIComponent(m.marketDisplayName)}`, "l2OrderBook", { nLevels: ORDERBOOK_LEVELS });
         return { bids: ob.bids, asks: ob.asks };
     }
     async getRecentTrades(symbol, limit = 50) {
-        const m = await this.market(symbol);
+        arcusLimit("trades", limit);
+        const m = await this.onlineMarket(symbol);
         const res = await this.client.get("/v1/trades", "trades", { market: m.marketDisplayName, limit });
-        // Public tape carries no fee; "0" follows the legacy ExchangeTrade convention for public trades.
-        return res.trades.map(t => ({ time: usToMs(t.timestamp), symbol: m.baseAsset, side: sideLower(t.side), price: t.price, size: t.size, fee: "0" }));
+        // Public tape: no fee applies to the viewer → null, never "0".
+        return res.trades.map(t => ({ time: usToMs(t.timestamp), symbol: m.baseAsset, side: sideLower(t.side), price: t.price, size: t.size, fee: null }));
     }
     async getFundingHistory(symbol, limit = 100) {
-        const m = await this.market(symbol);
+        arcusLimit("funding history", limit);
+        const m = await this.onlineMarket(symbol);
         const res = await this.client.get("/v1/fundingRates", "fundingRates", { market: m.marketDisplayName, limit });
-        return res.fundingRates.map(f => ({ time: usToMs(f.time), rate: f.fundingRate, price: null }));
+        return res.fundingRates.map(f => ({ time: usToMs(f.time), rate: f.fundingRate, price: null, intervalHours: 1, rateKind: "lastSettled" }));
     }
     async getKlines(symbol, interval, startTime, endTime) {
         if (!CANDLE_TIMEFRAMES.has(interval)) {
@@ -899,7 +926,7 @@ export class ArcusAdapter {
                 remediation: `Use one of: ${[...CANDLE_TIMEFRAMES].join(", ")}`,
             });
         }
-        const m = await this.market(symbol);
+        const m = await this.onlineMarket(symbol);
         const span = CANDLE_WINDOW_BARS * CANDLE_MS[interval];
         const windows = Math.max(1, Math.ceil((endTime - startTime) / span));
         if (windows > CANDLE_MAX_WINDOWS) {
@@ -915,7 +942,7 @@ export class ArcusAdapter {
             const res = await this.client.get("/v1/candles", "candles", { market: m.marketDisplayName, timeframe: interval, from: from * 1000, to: to * 1000 });
             for (const c of res.candles) {
                 const time = usToMs(c.openTime);
-                byTime.set(time, { time, open: c.open, high: c.high, low: c.low, close: c.close, volume: c.volume, trades: c.tradeCount });
+                byTime.set(time, { time, open: c.open, high: c.high, low: c.low, close: c.close, volume: c.volume, quoteVolume: null, trades: c.tradeCount });
             }
         }
         return [...byTime.values()].sort((x, y) => x.time - y.time);
@@ -995,7 +1022,7 @@ export class ArcusAdapter {
             out.push({ time: usToMs(p.time), symbol: await this.symbolOf(p.marketId), payment: p.payment });
         return out;
     }
-    // ── Legacy: trading shims (§10.7) ──
+    // ── Legacy: trading shims ──
     /** `clientOrderId`: the caller's id when given; otherwise one is generated (orderAck async needs one). */
     async marketOrder(symbol, side, size, opts) {
         return this.placeOrder({
@@ -1036,7 +1063,7 @@ export class ArcusAdapter {
             tif: isLimit ? "GTC" : null, // sent as GTT at the max horizon
             reduceOnly: opts?.reduceOnly === true, // non-reduce-only → CAPABILITY_UNSUPPORTED in validation
             clientOrderId: newClientOrderId(),
-            // The caller's resolved bound (the adapter never reads settings, §13.10 #1);
+            // The caller's resolved bound (the adapter never reads settings);
             // a stop-market without it → INVALID_PARAMS in placeOrder.
             slippage: isLimit ? null : opts?.slippage ?? null,
             tpsl: null,
@@ -1060,7 +1087,7 @@ export class ArcusAdapter {
             });
         }
     }
-    /** Master EVM signer for on-chain actions outside the Arcus API (spot swaps, design §12.4 #7). */
+    /** Master EVM signer for on-chain actions outside the Arcus API (spot swaps). */
     async masterEvmSigner() {
         this.requireMasterKey();
         return this.masterSigner();

package/dist/exchanges/arcus/agent.d.ts

@@ -1,5 +1,5 @@
 /**
- * Arcus agent (API key) lifecycle — design §10.4.
+ * Arcus agent (API key) lifecycle.
  *
  * approve:
  *  1. Resolve the master EVM signer from OWS (`masterOwsWallet`).

package/dist/exchanges/arcus/agent.js

@@ -1,5 +1,5 @@
 /**
- * Arcus agent (API key) lifecycle — design §10.4.
+ * Arcus agent (API key) lifecycle.
  *
  * approve:
  *  1. Resolve the master EVM signer from OWS (`masterOwsWallet`).

package/dist/exchanges/arcus/client.js

@@ -198,7 +198,7 @@ export class ArcusClient {
     async send(method, url, endpoint, headers, body) {
         // Timeout covers fetch + body read. A GET failure is definite (TIMEOUT /
         // EXCHANGE_UNREACHABLE); a POST failure may have reached the venue → outcome
-        // unknown (ORDER_PENDING, never resubmit — design §12.3).
+        // unknown (ORDER_PENDING, never resubmit).
         const signal = AbortSignal.timeout(TIMEOUT_MS);
         let res;
         let text;

package/dist/exchanges/arcus/public.js

@@ -24,6 +24,7 @@
  * - tradable: status === "ONLINE".
  */
 import { PerpError } from "../../errors.js";
+import { isArcusOnlineMarket } from "../../ws/arcus-market.js";
 import { canonicalFor } from "../canonical-symbols.js";
 import { arcusVenue } from "../venues/arcus.js";
 import { ArcusClient } from "./client.js";
@@ -101,7 +102,7 @@ export function toArcusVenueMarket(m) {
         maxLeverage: maxLeverageOf(m),
         marginTiers: null,
         session: sessionOf(m),
-        tradable: m.status === "ONLINE",
+        tradable: isArcusOnlineMarket(m),
     };
 }
 /**
@@ -110,7 +111,7 @@ export function toArcusVenueMarket(m) {
  * market / funding lists rather than listed at a $0 price and 0 % funding.
  */
 export function onlineArcusMarkets(raw) {
-    return raw.filter(m => m.status === "ONLINE");
+    return raw.filter(isArcusOnlineMarket);
 }
 async function fetchMarkets(net) {
     const raw = await fetchArcusRawMarkets(new ArcusClient(net, null));

package/dist/exchanges/arcus/signing.d.ts

@@ -14,7 +14,7 @@
  *   "everything else" rule, scheduleCancel — unverified):
  *     ed25519(timestampNs + action + canonicalJson(body))
  *
- * Time units (design §10.10): `ct` and X-Timestamp are Unix NANOseconds;
+ * Time units: `ct` and X-Timestamp are Unix NANOseconds;
  * signed `g` is NANOseconds; the request body `goodTilTime` is a MICROsecond
  * decimal string (g = goodTilTime × 1000).
  *
@@ -78,8 +78,7 @@ export declare function placePayload(f: ArcusPlaceFields, untriggered: boolean):
  *  - authentication page: always `id`, plus `c` "only if the resting order was placed
  *    with a client id … the engine rejects a mismatch".
  * Default follows the openapi spec ("idOnly": sign `id`, never `c`; the body sends
- * orderId only). "idAndClientId" is the authentication-page variant. Settled by the
- * docs/TEST-PLAN.md step "Arcus modify signature identity" on testnet.
+ * orderId only). "idAndClientId" is the authentication-page variant. Settled by the "Arcus modify signature identity" testnet check.
  */
 export type ArcusModifyIdentity = "idOnly" | "idAndClientId";
 export declare const ARCUS_MODIFY_SIGNED_IDENTITY: ArcusModifyIdentity;

package/dist/exchanges/arcus/signing.js

@@ -14,7 +14,7 @@
  *   "everything else" rule, scheduleCancel — unverified):
  *     ed25519(timestampNs + action + canonicalJson(body))
  *
- * Time units (design §10.10): `ct` and X-Timestamp are Unix NANOseconds;
+ * Time units: `ct` and X-Timestamp are Unix NANOseconds;
  * signed `g` is NANOseconds; the request body `goodTilTime` is a MICROsecond
  * decimal string (g = goodTilTime × 1000).
  *