perp-cli 0.14.2 → 0.15.0

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;

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

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 } from "../interface.js";
 import type { ResolvedSlippage } from "../slippage.js";
 import { type TradingV2 } from "../trading-v2.js";
 import type { VenueCreateContext, VenueDefinition } from "../venue.js";
@@ -92,7 +92,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,7 +143,7 @@ export declare class ArcusAdapter implements ExchangeAdapter, TradingV2 {
         bids: [string, string][];
         asks: [string, string][];
     }>;
-    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
     getFundingHistory(symbol: string, limit?: number): Promise<{
         time: number;
         rate: string;
@@ -182,7 +182,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
@@ -196,13 +196,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;
@@ -462,7 +462,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 +609,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
@@ -886,7 +886,7 @@ export class ArcusAdapter {
         const m = await this.market(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" }));
+        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);
@@ -915,7 +915,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 +995,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 +1036,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 +1060,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/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).
  *

package/dist/exchanges/arcus/spot-chain.d.ts

@@ -1,5 +1,5 @@
 /**
- * Robinhood Chain reads/txs for Arcus spot (design §12.4 #7), over
+ * Robinhood Chain reads/txs for Arcus spot, over
  * `VenueNetworkConfig.rpcUrl` with ethers.
  *
  * Permit2 allowance logic ported from @arcus-xyz/arcus-spot-sdk@1.0.2

package/dist/exchanges/arcus/spot-chain.js

@@ -1,5 +1,5 @@
 /**
- * Robinhood Chain reads/txs for Arcus spot (design §12.4 #7), over
+ * Robinhood Chain reads/txs for Arcus spot, over
  * `VenueNetworkConfig.rpcUrl` with ethers.
  *
  * Permit2 allowance logic ported from @arcus-xyz/arcus-spot-sdk@1.0.2

package/dist/exchanges/arcus/spot-router.d.ts

@@ -1,5 +1,5 @@
 /**
- * Arcus Spot Router HTTP client + wire types (design §12, §12.4 #7).
+ * Arcus Spot Router HTTP client + wire types.
  *
  * Ported from @arcus-xyz/arcus-spot-sdk@1.0.2 (src/client.ts, src/types.ts,
  * src/chains.ts) — Copyright Arcus, licensed under the Apache License 2.0

package/dist/exchanges/arcus/spot-router.js

@@ -1,5 +1,5 @@
 /**
- * Arcus Spot Router HTTP client + wire types (design §12, §12.4 #7).
+ * Arcus Spot Router HTTP client + wire types.
  *
  * Ported from @arcus-xyz/arcus-spot-sdk@1.0.2 (src/client.ts, src/types.ts,
  * src/chains.ts) — Copyright Arcus, licensed under the Apache License 2.0
@@ -167,7 +167,7 @@ export class ArcusSpotRouter {
             sellAmount: p.sellAmount.toString(),
             taker: p.taker,
             slippageBps: String(p.slippageBps),
-            allowWrapped: "false", // §12.4 #7 — never accept a wrapped placeholder
+            allowWrapped: "false", // never accept a wrapped placeholder
         });
     }
     /** Single attempt — never retried (a resend could double-execute). Throws RouterHttpError / PerpError. */

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

@@ -1,6 +1,5 @@
 /**
- * Arcus spot = Stock Token swaps through the Arcus Spot Router (design §12,
- * §12.4 #5 #7). Not an exchange account: balances are the master wallet's
+ * Arcus spot = Stock Token swaps through the Arcus Spot Router. Not an exchange account: balances are the master wallet's
  * ERC-20 balances on Robinhood Chain, and every trade is an exact-input swap
  * settled on-chain (Permit2 `PermitWitnessTransferFrom` + `TakerIntent`).
  *
@@ -79,7 +78,7 @@ export declare class ArcusSpotAdapter implements SpotAdapter, SpotPricesCapable
      *   all-in buy price at that notional. The signed intent must then carry
      *   minBuyAmount ≥ size × (1 − slippageBps), else nothing is signed.
      * Both sides also require minBuyAmount ≥ quote.buyAmount × (1 − slippageBps).
-     * slippageBps = the caller's resolveSlippage() value (design §13.2); the router
+     * slippageBps = the caller's resolveSlippage() value; the router
      * takes an integer bound.
      */
     spotMarketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {

package/dist/exchanges/arcus/spot.js

@@ -1,6 +1,5 @@
 /**
- * Arcus spot = Stock Token swaps through the Arcus Spot Router (design §12,
- * §12.4 #5 #7). Not an exchange account: balances are the master wallet's
+ * Arcus spot = Stock Token swaps through the Arcus Spot Router. Not an exchange account: balances are the master wallet's
  * ERC-20 balances on Robinhood Chain, and every trade is an exact-input swap
  * settled on-chain (Permit2 `PermitWitnessTransferFrom` + `TakerIntent`).
  *
@@ -335,7 +334,7 @@ export class ArcusSpotAdapter {
      *   all-in buy price at that notional. The signed intent must then carry
      *   minBuyAmount ≥ size × (1 − slippageBps), else nothing is signed.
      * Both sides also require minBuyAmount ≥ quote.buyAmount × (1 − slippageBps).
-     * slippageBps = the caller's resolveSlippage() value (design §13.2); the router
+     * slippageBps = the caller's resolveSlippage() value; the router
      * takes an integer bound.
      */
     async spotMarketOrder(symbol, side, size, opts) {

package/dist/exchanges/aster-spot.d.ts

@@ -1,5 +1,5 @@
 /**
- * Aster Spot Adapter (design §12, §12.4 #8).
+ * Aster Spot Adapter.
  *
  * Host `sapi.asterdex.com` (testnet `sapi.asterdex-testnet.com`), paths
  * `/api/v3/*`. Signing is the perp EIP-712 Domain B scheme, reused through
@@ -11,7 +11,7 @@
  * Venue rules enforced locally (official spot V3 docs):
  *  - TIF GTC | IOC | GTX (post-only). FOK is rejected by the venue (-1115).
  *  - LIMIT price must be on PRICE_FILTER.tickSize (never rounded).
- *  - Market orders are IOC LIMIT at a protection price (design §13.2): bookTicker
+ *  - Market orders are IOC LIMIT at a protection price: bookTicker
  *    mid ± slippage, aligned toward crossing on tickSize, inside PRICE_FILTER
  *    min/max and PERCENT_PRICE (venue native MARKET is never sent).
  *  - quantity on LOT_SIZE step, min, max (MARKET_LOT_SIZE only for native MARKET).
@@ -95,7 +95,7 @@ export declare class AsterSpotAdapter implements SpotAdapter, SpotTransferCapabl
     /** Effective minimum notional, or null when no filter applies. */
     private _minNotional;
     private _checkNotional;
-    /** §12.4 #8: gate only when the active signer is an agent lacking canSpotTrade. */
+    /** gate only when the active signer is an agent lacking canSpotTrade. */
     private _requireSpotPermission;
     private _signed;
     private _publicGet;

package/dist/exchanges/aster-spot.js

@@ -1,5 +1,5 @@
 /**
- * Aster Spot Adapter (design §12, §12.4 #8).
+ * Aster Spot Adapter.
  *
  * Host `sapi.asterdex.com` (testnet `sapi.asterdex-testnet.com`), paths
  * `/api/v3/*`. Signing is the perp EIP-712 Domain B scheme, reused through
@@ -11,7 +11,7 @@
  * Venue rules enforced locally (official spot V3 docs):
  *  - TIF GTC | IOC | GTX (post-only). FOK is rejected by the venue (-1115).
  *  - LIMIT price must be on PRICE_FILTER.tickSize (never rounded).
- *  - Market orders are IOC LIMIT at a protection price (design §13.2): bookTicker
+ *  - Market orders are IOC LIMIT at a protection price: bookTicker
  *    mid ± slippage, aligned toward crossing on tickSize, inside PRICE_FILTER
  *    min/max and PERCENT_PRICE (venue native MARKET is never sent).
  *  - quantity on LOT_SIZE step, min, max (MARKET_LOT_SIZE only for native MARKET).
@@ -24,7 +24,7 @@
 import { unsupported } from "./trading-v2.js";
 import { asterIocOutcome } from "./aster.js";
 import { PerpError, isTransportFailure, orderNotSent, orderOutcomeUnknown, sendFailure, unknownActionRemediation } from "../errors.js";
-import { alignProtectionPrice, exactUnits, floorSize, requireOnTick, requirePositive, slippagePrice, subDecimal } from "./precision.js";
+import { addDecimal, alignProtectionPrice, exactUnits, floorSize, requireOnTick, requirePositive, slippagePrice, subDecimal } from "./precision.js";
 /** Default quote for a bare base symbol (= venue spot quoteAssets[0]). */
 const DEFAULT_QUOTE = "USDT";
 const SPOT_REMEDIATION = "perp wallet agent rotate aster --can-spot";
@@ -41,9 +41,6 @@ function cmp(a, b) {
         return -1;
     return d === "0" ? 0 : 1;
 }
-function addDecimal(a, b) {
-    return subDecimal(a, b.startsWith("-") ? b.slice(1) : `-${b}`);
-}
 function isZero(v) {
     return cmp(v, "0") === 0;
 }
@@ -150,7 +147,7 @@ export class AsterSpotAdapter {
     }
     // ── Trading ──
     async spotMarketOrder(symbol, side, size, opts) {
-        // §13.2: IOC LIMIT at the protection price, never native MARKET (no price cap).
+        // IOC LIMIT at the protection price, never native MARKET (no price cap).
         // Pre-send (market, size, price, min notional, permission): a failure is a definite "not placed".
         let m;
         let qty;
@@ -246,7 +243,7 @@ export class AsterSpotAdapter {
     }
     async spotLimitOrder(symbol, side, price, size, opts) {
         const m = this._resolveTrading(symbol);
-        // Aster is a legacy family: limit orders keep the GTC default (design §10.7 #6).
+        // Aster is a legacy family: limit orders keep the GTC default.
         const tif = this._mapTif(opts?.tif === undefined ? "GTC" : opts.tif);
         const px = requireOnTick(price, m.tickSize);
         const qty = this._sizeFor(m, size, false);
@@ -517,7 +514,7 @@ export class AsterSpotAdapter {
             });
         }
     }
-    /** §12.4 #8: gate only when the active signer is an agent lacking canSpotTrade. */
+    /** gate only when the active signer is an agent lacking canSpotTrade. */
     _requireSpotPermission() {
         const meta = this._perp.activeAgentMeta();
         if (meta !== null && meta.permissions?.canSpotTrade !== true) {

package/dist/exchanges/aster-typed-data.d.ts

@@ -95,7 +95,7 @@ export interface DelAgentParams {
 /**
  * Build the EIP-712 typed-data payload for `DELETE /fapi/v3/agent`.
  *
- * OPEN ITEM (docs/TEST-PLAN.md "Aster DelAgent struct — mainnet verification"): the
+ * OPEN ITEM (Aster DelAgent struct — mainnet verification): the
  * public Aster V3 docs (asterdex/api-docs, futures api v3 + testnet, checked 2026-10-02)
  * document no agent-delete endpoint or DelAgent struct, and HypurrQuant_FE has no
  * revoke method. This field set mirrors the ApproveAgent terminal fields (AgentAddress,

package/dist/exchanges/aster-typed-data.js

@@ -99,7 +99,7 @@ export function buildApproveAgentTypedData(params) {
 /**
  * Build the EIP-712 typed-data payload for `DELETE /fapi/v3/agent`.
  *
- * OPEN ITEM (docs/TEST-PLAN.md "Aster DelAgent struct — mainnet verification"): the
+ * OPEN ITEM (Aster DelAgent struct — mainnet verification): the
  * public Aster V3 docs (asterdex/api-docs, futures api v3 + testnet, checked 2026-10-02)
  * document no agent-delete endpoint or DelAgent struct, and HypurrQuant_FE has no
  * revoke method. This field set mirrors the ApproveAgent terminal fields (AgentAddress,

package/dist/exchanges/aster.d.ts

@@ -18,7 +18,7 @@
  * Docs: https://docs.asterdex.com/product/aster-perpetuals/api/api-documentation
  * Base: https://fapi.asterdex.com
  */
-import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
 import type { ResolvedSlippage } from "./slippage.js";
 import type { EvmSigner } from "../signer/interface.js";
 import type { AgentMeta } from "../settings.js";
@@ -161,7 +161,7 @@ export declare class AsterAdapter implements ExchangeAdapter {
     /** PRICE_FILTER / PERCENT_PRICE of an API symbol (exchangeInfo, cached CACHE_TTL). */
     private _symbolPriceFilters;
     /**
-     * Declared protection-price reference (§13.10 #5): the venue mark price from
+     * Declared protection-price reference: the venue mark price from
      * GET /fapi/v3/premiumIndex — the same price PERCENT_PRICE is evaluated against.
      * No runtime substitute (no mid / last fallback): unavailable → PRICE_STALE.
      */
@@ -190,12 +190,17 @@ export declare class AsterAdapter implements ExchangeAdapter {
         bids: [string, string][];
         asks: [string, string][];
     }>;
-    getRecentTrades(symbol: string, limit?: number): Promise<ExchangeTrade[]>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
     getFundingHistory(symbol: string, limit?: number): Promise<{
         time: number;
         rate: string;
         price: string | null;
     }[]>;
+    /**
+     * Candles over [startTime, endTime]. GET /fapi/v3/klines returns at most 1500 bars per request
+     * (1501 → -1130), so the range is read in pages that start after the last bar returned — a long
+     * range is never cut to the first page. More than ASTER_KLINE_MAX_PAGES pages → INVALID_PARAMS.
+     */
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
     getBalance(): Promise<ExchangeBalance>;
     /**
@@ -267,7 +272,7 @@ export declare class AsterAdapter implements ExchangeAdapter {
     /**
      * Native modify (PUT /fapi/v3/order, V3 futures docs "Modify Order"): LIMIT orders
      * only; TIF (incl. GTX) and reduceOnly stay on the order. `size` is the NEW UNFILLED
-     * quantity (§13.10 #10); the venue's `quantity` is the order total, so
+     * quantity; the venue's `quantity` is the order total, so
      * quantity = size + executedQty (read just before). A fill landing between the read
      * and the PUT can only shrink the remainder, never over-size it. A venue rejection
      * leaves the original order untouched (docs).