perp-cli 0.14.3 → 0.15.0

package/dist/exchanges/precision.d.ts

@@ -1,5 +1,5 @@
 /**
- * Decimal-string precision helpers for order entry (design §10.10).
+ * Decimal-string precision helpers for order entry.
  *
  * All math is done on scaled BigInt to avoid float drift. Rules:
  * - limit prices that are not on tick are REJECTED (INVALID_TICK), never rounded;
@@ -24,6 +24,8 @@ export declare function requirePositive(value: string, what: string): void;
 export declare function requireOnTick(price: string, tickSize: string): string;
 /** Exact (a + b) / 2 of two plain decimal strings (no float arithmetic: 0.1 and 0.2 → "0.15"). */
 export declare function midDecimal(a: string, b: string): string;
+/** Exact decimal a + b (plain decimal strings). */
+export declare function addDecimal(a: string, b: string): string;
 /** Exact decimal a − b (plain decimal strings). */
 export declare function subDecimal(a: string, b: string): string;
 /** Exact decimal a × b (plain decimal strings). */

package/dist/exchanges/precision.js

@@ -1,5 +1,5 @@
 /**
- * Decimal-string precision helpers for order entry (design §10.10).
+ * Decimal-string precision helpers for order entry.
  *
  * All math is done on scaled BigInt to avoid float drift. Rules:
  * - limit prices that are not on tick are REJECTED (INVALID_TICK), never rounded;
@@ -119,6 +119,13 @@ export function midDecimal(a, b) {
     const scale = Math.max(x.scale, y.scale) + 1; // one more digit holds the possible ".5"
     return format((rescale(x, scale) + rescale(y, scale)) / 2n, scale);
 }
+/** Exact decimal a + b (plain decimal strings). */
+export function addDecimal(a, b) {
+    const x = parseDecimal(a);
+    const y = parseDecimal(b);
+    const scale = Math.max(x.scale, y.scale);
+    return format(rescale(x, scale) + rescale(y, scale), scale);
+}
 /** Exact decimal a − b (plain decimal strings). */
 export function subDecimal(a, b) {
     const x = parseDecimal(a);
@@ -195,7 +202,7 @@ export async function lotStepOf(adapter, symbol) {
         m = bare[0];
     }
     if (m === undefined) {
-        throw new PerpError("SYMBOL_NOT_FOUND", `${adapter.name}: market ${symbol} not found — lot step unknown`, { exchange: adapter.name });
+        throw new PerpError("SYMBOL_NOT_FOUND", `${adapter.name}: market ${symbol} not found — lot step unknown`, { exchange: adapter.name, remediation: `List markets: perp -e ${adapter.name} market list` });
     }
     if (m.stepSize !== null)
         return m.stepSize;

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

@@ -1,6 +1,5 @@
 /**
  * QFEX adapter — native TradingV2 + legacy ExchangeAdapter shim
- * (design §14.3–§14.6 as amended by §14.12; §10.7, §10.10, §13).
  *
  * Signer: imported HMAC API key only (QfexAgentMeta → ~/.perp/qfex-agents/<publicKey>.json).
  * Orders go over the Trade WebSocket (ws-transport.ts); account reads, leverage and transfers
@@ -42,7 +41,7 @@
 import { PerpError } from "../../errors.js";
 import type { WithdrawGate } from "../../settings.js";
 import { type BuilderFeeGate } from "../builder-fee.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 { IocOutcome } from "../ioc-outcome.js";
 import type { ResolvedSlippage } from "../slippage.js";
 import type { TradingV2 } from "../trading-v2.js";
@@ -52,6 +51,20 @@ import { type QfexReduceOnlyWire } from "./signing.js";
 import { qfexPendingRemediation, type QfexOrderResponse } from "./ws-transport.js";
 /** A mark price entry older than this (its own venue `time`) is not used as an order reference. */
 export declare const QFEX_MARK_MAX_AGE_MS = 10000;
+/**
+ * Candle volumes. GET /candles returns `usdVolume` (populated) and `baseTokenVolume`, which the
+ * venue leaves "0" on traded candles (live 2026-10-14, CL-USD 1HOUR: baseTokenVolume "0" with
+ * usdVolume "52534.48506" on every row; startingOpenInterest / orderbookMidPrice* are "0" too).
+ * A base "0" next to a non-zero USD volume is a placeholder → null (unknown), never 0; when
+ * both are zero the candle really had no volume.
+ */
+export declare function qfexCandleVolumes(c: {
+    baseTokenVolume: unknown;
+    usdVolume: unknown;
+}): {
+    volume: string | null;
+    quoteVolume: string;
+};
 /** Client order id sent to the venue: a fresh UUID (the format the venue itself generates). */
 export declare function qfexClientOrderId(): string;
 /**
@@ -215,7 +228,7 @@ export declare class QfexAdapter implements ExchangeAdapter, TradingV2 {
     /**
      * A reduce-only order the venue did not confirm as reduce-only (`reduce_only` false or absent
      * on an order frame — reduceOnlyUnconfirmedFrame — or on a read-back row of THIS order). The order may be live as a normal order, so the outcome is
-     * unknown (ORDER_PENDING, design §14.12 #4e: never re-sent). It is NOT cancelled here: a cancel
+     * unknown (ORDER_PENDING, never re-sent). It is NOT cancelled here: a cancel
      * is a second mutating command with its own unknown outcome and cannot undo a fill.
      */
     private reduceOnlyEchoError;
@@ -225,7 +238,7 @@ export declare class QfexAdapter implements ExchangeAdapter, TradingV2 {
     private orderResultOf;
     /**
      * Final filled size of an order placed through the legacy shim — non-null ONLY when a venue
-     * terminal frame was received (design §14.12 #3). A pending result is never an outcome.
+     * terminal frame was received. A pending result is never an outcome.
      */
     iocOutcomeOf(raw: unknown): IocOutcome | null;
     amendOrder(req: AmendRequest): Promise<OrderResult>;
@@ -253,7 +266,7 @@ export declare class QfexAdapter implements ExchangeAdapter, TradingV2 {
         bids: [string, string][];
         asks: [string, string][];
     }>;
-    getRecentTrades(): Promise<ExchangeTrade[]>;
+    getRecentTrades(): Promise<ExchangePublicTrade[]>;
     /** Hourly funding windows (GET /funding/{symbol}, intervalMinutes 60). `limit` = hours back (default 24). */
     getFundingHistory(symbol: string, limit?: number): Promise<{
         time: number;

package/dist/exchanges/qfex/adapter.js

@@ -1,6 +1,5 @@
 /**
  * QFEX adapter — native TradingV2 + legacy ExchangeAdapter shim
- * (design §14.3–§14.6 as amended by §14.12; §10.7, §10.10, §13).
  *
  * Signer: imported HMAC API key only (QfexAgentMeta → ~/.perp/qfex-agents/<publicKey>.json).
  * Orders go over the Trade WebSocket (ws-transport.ts); account reads, leverage and transfers
@@ -78,6 +77,24 @@ const STOP_TYPES = new Set(["TAKE_PROFIT", "STOP_LOSS"]);
 const KLINE_RESOLUTION = {
     "1m": "1MIN", "5m": "5MINS", "15m": "15MINS", "30m": "30MINS", "1h": "1HOUR", "4h": "4HOURS", "1d": "1DAY",
 };
+/**
+ * Candle volumes. GET /candles returns `usdVolume` (populated) and `baseTokenVolume`, which the
+ * venue leaves "0" on traded candles (live 2026-10-14, CL-USD 1HOUR: baseTokenVolume "0" with
+ * usdVolume "52534.48506" on every row; startingOpenInterest / orderbookMidPrice* are "0" too).
+ * A base "0" next to a non-zero USD volume is a placeholder → null (unknown), never 0; when
+ * both are zero the candle really had no volume.
+ */
+export function qfexCandleVolumes(c) {
+    const decimal = (v, what) => {
+        if (typeof v !== "string" || v.trim() === "" || !Number.isFinite(Number(v))) {
+            throw new PerpError("EXCHANGE_ERROR", `QFEX candles: ${what} is not a decimal string (${JSON.stringify(v)})`, { exchange: "qfex" });
+        }
+        return v;
+    };
+    const quoteVolume = decimal(c.usdVolume, "usdVolume");
+    const base = decimal(c.baseTokenVolume, "baseTokenVolume");
+    return { volume: Number(base) === 0 && Number(quoteVolume) !== 0 ? null : base, quoteVolume };
+}
 /** Client order id sent to the venue: a fresh UUID (the format the venue itself generates). */
 export function qfexClientOrderId() {
     return randomUUID();
@@ -262,7 +279,7 @@ export class QfexAdapter {
         const venueSymbol = qfexVenueSymbol(symbol);
         const i = (await this.instrumentMap()).get(venueSymbol);
         if (i === undefined) {
-            throw new PerpError("SYMBOL_NOT_FOUND", `QFEX has no market ${venueSymbol}`, { exchange: "qfex", remediation: "List markets with: perp market list -e qfex" });
+            throw new PerpError("SYMBOL_NOT_FOUND", `QFEX has no market ${venueSymbol}`, { exchange: "qfex", remediation: "List markets: perp -e qfex market list" });
         }
         return i;
     }
@@ -339,7 +356,7 @@ export class QfexAdapter {
     stopOrderGate() {
         if (QFEX_STOP_CLIENT_ID_ECHO === true)
             return null;
-        return unsupported("qfex", "stopOrder", "the stop order acknowledgement is not documented to echo a client order id, so a stop cannot be correlated safely (Q21)", "Set stops / TP / SL on the QFEX web app until docs/TEST-PLAN.md QFEX item Q21 passes");
+        return unsupported("qfex", "stopOrder", "the stop order acknowledgement is not documented to echo a client order id, so a stop cannot be correlated safely (Q21)", "Set stops / TP / SL on the QFEX web app until QFEX item Q21 passes");
     }
     /**
      * One reduce-only stop-market order (add_order with order_type TAKE_PROFIT / STOP_LOSS).
@@ -571,7 +588,7 @@ export class QfexAdapter {
     /**
      * A reduce-only order the venue did not confirm as reduce-only (`reduce_only` false or absent
      * on an order frame — reduceOnlyUnconfirmedFrame — or on a read-back row of THIS order). The order may be live as a normal order, so the outcome is
-     * unknown (ORDER_PENDING, design §14.12 #4e: never re-sent). It is NOT cancelled here: a cancel
+     * unknown (ORDER_PENDING, never re-sent). It is NOT cancelled here: a cancel
      * is a second mutating command with its own unknown outcome and cannot undo a fill.
      */
     reduceOnlyEchoError(i, orderId, clientOrderId, echo, venueRaw) {
@@ -746,7 +763,7 @@ export class QfexAdapter {
             }
             if (isZeroDecimal(filled)) {
                 if (ctx.immediate) {
-                    // A terminal frame with nothing filled — IOC_CANCELLED or CANCELLED alike (§13.10 #4).
+                    // A terminal frame with nothing filled — IOC_CANCELLED or CANCELLED alike.
                     throw new PerpError("ORDER_REJECTED", `QFEX ${i.venueSymbol}: the ${t.time_in_force} order filled nothing and was cancelled (${t.status})`, {
                         exchange: "qfex", reason: "iocNoFill", venueStatus: t.status, orderId: add.orderId, clientOrderId: add.clientOrderId, venueRaw,
                         remediation: "Nothing was filled. Widen --slippage-bps (within the price band), reduce the size, or place a resting limit order",
@@ -781,7 +798,7 @@ export class QfexAdapter {
     }
     /**
      * Final filled size of an order placed through the legacy shim — non-null ONLY when a venue
-     * terminal frame was received (design §14.12 #3). A pending result is never an outcome.
+     * terminal frame was received. A pending result is never an outcome.
      */
     iocOutcomeOf(raw) {
         const r = raw;
@@ -1098,7 +1115,9 @@ export class QfexAdapter {
         return (await this.getVenueMarkets()).map(toLegacyMarketInfo);
     }
     async getOrderbook(symbol) {
-        const venueSymbol = qfexVenueSymbol(symbol);
+        // Resolved against refdata first: an unknown symbol is SYMBOL_NOT_FOUND, not the venue's
+        // HTTP 404 surfacing as a retryable EXCHANGE_ERROR.
+        const venueSymbol = (await this.instrumentOf(symbol)).venueSymbol;
         const book = await this.client.publicGet(`/md/orderbook/${encodeURIComponent(venueSymbol)}`, null);
         // The venue lists empty price levels (quantity "0"); they are not part of the book.
         const side = (v, what) => listOf(v, what)
@@ -1111,7 +1130,7 @@ export class QfexAdapter {
     }
     /** Hourly funding windows (GET /funding/{symbol}, intervalMinutes 60). `limit` = hours back (default 24). */
     async getFundingHistory(symbol, limit) {
-        const venueSymbol = qfexVenueSymbol(symbol);
+        const venueSymbol = (await this.instrumentOf(symbol)).venueSymbol;
         const hours = limit === undefined ? 24 : limit;
         if (!Number.isInteger(hours) || hours < 1)
             throw new PerpError("INVALID_PARAMS", `funding history limit must be a positive integer of hours (got ${hours})`);
@@ -1135,14 +1154,15 @@ export class QfexAdapter {
         if (resolution === undefined) {
             throw new PerpError("INVALID_PARAMS", `Unsupported kline interval "${interval}" on QFEX`, { remediation: `Use one of: ${Object.keys(KLINE_RESOLUTION).join(", ")}` });
         }
-        const body = await this.client.publicGet(`/candles/${encodeURIComponent(qfexVenueSymbol(symbol))}`, {
+        const venueSymbol = (await this.instrumentOf(symbol)).venueSymbol;
+        const body = await this.client.publicGet(`/candles/${encodeURIComponent(venueSymbol)}`, {
             resolution, fromISO: new Date(startTime).toISOString(), toISO: new Date(endTime).toISOString(),
         });
         return listOf(body.candles, "candles").map(c => {
             const time = Date.parse(c.startedAt);
             if (!Number.isFinite(time))
                 throw new PerpError("EXCHANGE_ERROR", `QFEX candles: invalid startedAt "${c.startedAt}"`);
-            return { time, open: c.open, high: c.high, low: c.low, close: c.close, volume: c.baseTokenVolume, trades: null };
+            return { time, open: c.open, high: c.high, low: c.low, close: c.close, ...qfexCandleVolumes(c), trades: null };
         }).sort((a, b) => a.time - b.time);
     }
     // ── Legacy ExchangeAdapter: account ──
@@ -1258,7 +1278,7 @@ export class QfexAdapter {
     async getFundingPayments() {
         throw unsupported("qfex", "fundingPayments", "funding payments are GET /executions rows, but the execution_type that marks them is not documented (Q10)", "See funding in the QFEX web app; net funding per position is in: perp account positions -e qfex --json");
     }
-    // ── Legacy ExchangeAdapter: trading (shim → TradingV2, design §10.7). Client ids are generated here. ──
+    // ── Legacy ExchangeAdapter: trading (shim → TradingV2). Client ids are generated here. ──
     async marketOrder(symbol, side, size, opts) {
         return this.placeOrder({
             symbol, side, type: "market", size, price: null, triggerPrice: null, triggerSource: null, tif: null,
@@ -1294,7 +1314,7 @@ export class QfexAdapter {
             reduceOnly: opts?.reduceOnly === true, clientOrderId: qfexClientOrderId(), slippage: null, tpsl: null,
         });
     }
-    // ── Funds (design §14.6, §14.12 #8) ──
+    // ── Funds ──
     /**
      * Deposit address for USDC on Arbitrum One (banker GET /address). The address is returned
      * only when the venue confirms exactly that network and asset — anything else is refused,

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

@@ -1,5 +1,5 @@
 /**
- * QFEX API key import (design §14.5 as amended by §14.12 #9).
+ * QFEX API key import.
  *
  * Keys are created on the QFEX website (Developer Settings, 2FA) — there is no programmatic
  * approval. The public key + secret are entered via hidden prompt / stdin only (never flags,

package/dist/exchanges/qfex/agent.js

@@ -1,5 +1,5 @@
 /**
- * QFEX API key import (design §14.5 as amended by §14.12 #9).
+ * QFEX API key import.
  *
  * Keys are created on the QFEX website (Developer Settings, 2FA) — there is no programmatic
  * approval. The public key + secret are entered via hidden prompt / stdin only (never flags,

package/dist/exchanges/qfex/client.d.ts

@@ -1,5 +1,5 @@
 /**
- * QFEX raw REST client (design §14.1, §14.4, §14.6): raw fetch + node:crypto HMAC, no SDK.
+ * QFEX raw REST client: raw fetch + node:crypto HMAC, no SDK.
  *
  * Two hosts: the API (`api.qfex.*` — market data, account reads, leverage, subaccount
  * transfer) and the banker (`banker.qfex.*` — deposit address, withdraw). Both take the same

package/dist/exchanges/qfex/client.js

@@ -1,5 +1,5 @@
 /**
- * QFEX raw REST client (design §14.1, §14.4, §14.6): raw fetch + node:crypto HMAC, no SDK.
+ * QFEX raw REST client: raw fetch + node:crypto HMAC, no SDK.
  *
  * Two hosts: the API (`api.qfex.*` — market data, account reads, leverage, subaccount
  * transfer) and the banker (`banker.qfex.*` — deposit address, withdraw). Both take the same

package/dist/exchanges/qfex/errors.d.ts

@@ -1,5 +1,5 @@
 /**
- * QFEX venue status / error → PerpError (design §14.3 error table, §14.12 #3, #8, #11).
+ * QFEX venue status / error → PerpError.
  *
  * Three sources:
  *  - order_response.status   engine verdict on one order (definite once correlated);

package/dist/exchanges/qfex/errors.js

@@ -1,5 +1,5 @@
 /**
- * QFEX venue status / error → PerpError (design §14.3 error table, §14.12 #3, #8, #11).
+ * QFEX venue status / error → PerpError.
  *
  * Three sources:
  *  - order_response.status   engine verdict on one order (definite once correlated);
@@ -90,7 +90,7 @@ const STATUS_REMEDIATION = {
     CANNOT_MODIFY_PARTIAL_FILL: "A partially filled order cannot be modified — cancel it and place a new order",
     CANNOT_MODIFY_ALO_WOULD_CROSS: "The new price would cross the book — choose a passive price, or cancel and place a LIMIT order",
     REJECTED_MARKET_CLOSED: "The market is closed for this order right now — check the session: perp market info <symbol> -e qfex",
-    INVALID_CLIENT_ORDER_ID: "The venue refused the generated client order id — report it (docs/TEST-PLAN.md QFEX Q18)",
+    INVALID_CLIENT_ORDER_ID: "The venue refused the generated client order id — report it (QFEX item Q18)",
 };
 /** "… retry after 200ms" / "… retry after 2 seconds" → ms; null when the message carries no hint. */
 export function parseRetryAfterMs(message) {

package/dist/exchanges/qfex/public.d.ts

@@ -1,5 +1,5 @@
 /**
- * QFEX public market data (design §14.8 as amended by §14.12 #6, #7, #10).
+ * QFEX public market data.
  *
  * Sources (all public):
  *   GET /refdata                 instruments: tick, lot, min/max quantity, price band, status,
@@ -8,7 +8,7 @@
  *                                24h notional volume
  *   GET /md/contracts            funding_rate / next_funding_rate_timestamp (funding reads only)
  *
- * Coupling (§14.12 #10): order-entry precision comes from /refdata ALONE (fetchQfexInstruments).
+ * Coupling: order-entry precision comes from /refdata ALONE (fetchQfexInstruments).
  * Markets need /refdata + the MDS snapshot. Only funding reads need /md/contracts — its failure
  * fails fetchFundingRates, never market listing or order entry.
  *
@@ -89,7 +89,7 @@ export declare function qfexPlainSymbol(venueSymbol: string): string;
 export declare function qfexVenueSymbol(symbol: string): string;
 export declare function qfexAssetClass(row: Pick<QfexRefdataRow, "symbol" | "product_category" | "base_asset">): AssetClass;
 export declare function toQfexInstrument(raw: unknown): QfexInstrument;
-/** Is the market one perp-cli may send orders to? USD-quoted and ACTIVE (§14.12 #7). */
+/** Is the market one perp-cli may send orders to? USD-quoted and ACTIVE. */
 export declare function qfexTradable(i: Pick<QfexInstrument, "status" | "quoteAsset">): boolean;
 /**
  * Whether `nowMs` falls inside a `session: "open"` window of the instrument's market_hours

package/dist/exchanges/qfex/public.js

@@ -1,5 +1,5 @@
 /**
- * QFEX public market data (design §14.8 as amended by §14.12 #6, #7, #10).
+ * QFEX public market data.
  *
  * Sources (all public):
  *   GET /refdata                 instruments: tick, lot, min/max quantity, price band, status,
@@ -8,7 +8,7 @@
  *                                24h notional volume
  *   GET /md/contracts            funding_rate / next_funding_rate_timestamp (funding reads only)
  *
- * Coupling (§14.12 #10): order-entry precision comes from /refdata ALONE (fetchQfexInstruments).
+ * Coupling: order-entry precision comes from /refdata ALONE (fetchQfexInstruments).
  * Markets need /refdata + the MDS snapshot. Only funding reads need /md/contracts — its failure
  * fails fetchFundingRates, never market listing or order entry.
  *
@@ -103,7 +103,7 @@ export function toQfexInstrument(raw) {
         marketHours: hours !== null && typeof hours === "object" && !Array.isArray(hours) ? hours : null,
     };
 }
-/** Is the market one perp-cli may send orders to? USD-quoted and ACTIVE (§14.12 #7). */
+/** Is the market one perp-cli may send orders to? USD-quoted and ACTIVE. */
 export function qfexTradable(i) {
     return i.status === "ACTIVE" && i.quoteAsset === "USD";
 }

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

@@ -1,5 +1,5 @@
 /**
- * QFEX request signing + wire-number conversion (design §14.2, §14.3).
+ * QFEX request signing + wire-number conversion.
  *
  * Auth (docs /websocket/channels/trade/authenticate, OpenAPI securitySchemes):
  *   signature = hex(HMAC-SHA256(secret, `${nonce}:${unix_ts}`))
@@ -12,7 +12,7 @@
  * fromWireNumber are the only places a decimal string becomes a float or the reverse.
  *
  * Wire facts that needed a live check are single constants here; while one is unset every code
- * path that needs it refuses with the uniform CAPABILITY_UNSUPPORTED response (design §14.12).
+ * path that needs it refuses with the uniform CAPABILITY_UNSUPPORTED response.
  */
 import { PerpError } from "../../errors.js";
 export interface QfexCredentials {

package/dist/exchanges/qfex/signing.js

@@ -1,5 +1,5 @@
 /**
- * QFEX request signing + wire-number conversion (design §14.2, §14.3).
+ * QFEX request signing + wire-number conversion.
  *
  * Auth (docs /websocket/channels/trade/authenticate, OpenAPI securitySchemes):
  *   signature = hex(HMAC-SHA256(secret, `${nonce}:${unix_ts}`))
@@ -12,7 +12,7 @@
  * fromWireNumber are the only places a decimal string becomes a float or the reverse.
  *
  * Wire facts that needed a live check are single constants here; while one is unset every code
- * path that needs it refuses with the uniform CAPABILITY_UNSUPPORTED response (design §14.12).
+ * path that needs it refuses with the uniform CAPABILITY_UNSUPPORTED response.
  */
 import { createHmac, randomBytes } from "node:crypto";
 import { PerpError } from "../../errors.js";
@@ -108,8 +108,7 @@ export const QFEX_MODIFY_KEEPS_CLIENT_ID = true;
  * (it may be the user id). true → a mismatch is ORDER_PENDING.
  */
 export const QFEX_USER_ID_IS_ACCOUNT = null;
-const Q2_REMEDIATION = "Reduce / close the position on the QFEX web app. perp-cli sends reduce-only orders on QFEX only with the wire format of item Q2 "
-    + "(docs/TEST-PLAN.md) set";
+const Q2_REMEDIATION = "Reduce / close the position on the QFEX web app. perp-cli sends reduce-only orders on QFEX only with the wire format of item Q2 set";
 /** The uniform refusal of every reduce-only path when the wire format is unset; null when it is set. */
 export function qfexReduceOnlyGate(wire) {
     if (wire !== null)
@@ -121,7 +120,7 @@ export function qfexAutomationGate(verified) {
     if (verified === true)
         return null;
     return unsupported("qfex", "automation", "funding is unverified (Q4) and a resting reduce-only order the market reaches while flat is not proven harmless (Q2), and no automated flow places its own protective stop yet", "Trade QFEX with the manual commands (perp trade market / limit / stop / tpsl / close / reduce / close-all / flatten -e qfex) and watch the position yourself; "
-        + "automation opens once docs/TEST-PLAN.md QFEX items Q2 / Q4 are settled");
+        + "automation opens once QFEX items Q2 / Q4 are settled");
 }
 /** `reduce_only` value for the wire in the verified format. */
 export function reduceOnlyWireValue(wire, reduceOnly) {

package/dist/exchanges/qfex/ws-transport.d.ts

@@ -1,5 +1,5 @@
 /**
- * QFEX Trade WebSocket transport (design §14.2 as amended by §14.12 #2, #3, #4, #11, #13).
+ * QFEX Trade WebSocket transport.
  *
  * The venue has no request id. Correlation therefore rests on four rules:
  *  1. ONE command at a time per connection (FIFO) — reads share the queue.
@@ -94,7 +94,7 @@ export interface QfexFillResponse {
 export declare function orderResponseOf(frame: QfexFrame): QfexOrderResponse | null;
 export declare function fillResponseOf(frame: QfexFrame): QfexFillResponse | null;
 /**
- * Error frame in any documented shape (design §14.12 #11):
+ * Error frame in any documented shape:
  *   { "err": { error_code, message, incoming_message } }            /websocket/errors + AsyncAPI
  *   { "type": "Err", error_code, message, incoming_message }         /websocket/rate
  *   { "type": "error", error_code, message }                         the docs' own client samples

package/dist/exchanges/qfex/ws-transport.js

@@ -1,5 +1,5 @@
 /**
- * QFEX Trade WebSocket transport (design §14.2 as amended by §14.12 #2, #3, #4, #11, #13).
+ * QFEX Trade WebSocket transport.
  *
  * The venue has no request id. Correlation therefore rests on four rules:
  *  1. ONE command at a time per connection (FIFO) — reads share the queue.
@@ -66,7 +66,7 @@ export function fillResponseOf(frame) {
     return r;
 }
 /**
- * Error frame in any documented shape (design §14.12 #11):
+ * Error frame in any documented shape:
  *   { "err": { error_code, message, incoming_message } }            /websocket/errors + AsyncAPI
  *   { "type": "Err", error_code, message, incoming_message }         /websocket/rate
  *   { "type": "error", error_code, message }                         the docs' own client samples
@@ -86,7 +86,7 @@ export function errFrameOf(frame) {
         : null;
     return { errorCode: body.error_code, message: typeof body.message === "string" ? body.message : null, echo };
 }
-/** Auth outcome frame: both documented success shapes are accepted (§14.12 #11). */
+/** Auth outcome frame: both documented success shapes are accepted. */
 function authVerdictOf(frame) {
     if (typeof frame.authenticated === "boolean")
         return frame.authenticated;

package/dist/exchanges/rate-limiter.d.ts

@@ -1,5 +1,5 @@
 /**
- * Per-process token-bucket rate limiter keyed by venue (design §3 L4, §10.9).
+ * Per-process token-bucket rate limiter keyed by venue.
  *
  * Limitation (documented): this only coordinates requests inside one process.
  * CLI + MCP server + bots running at once can still exceed a venue's limit.

package/dist/exchanges/rate-limiter.js

@@ -1,5 +1,5 @@
 /**
- * Per-process token-bucket rate limiter keyed by venue (design §3 L4, §10.9).
+ * Per-process token-bucket rate limiter keyed by venue.
  *
  * Limitation (documented): this only coordinates requests inside one process.
  * CLI + MCP server + bots running at once can still exceed a venue's limit.
@@ -19,7 +19,10 @@ class TokenBucket {
     }
     refill() {
         const now = Date.now();
-        this.tokens = Math.min(this.policy.capacity, this.tokens + ((now - this.last) / 1000) * this.policy.refillPerSec);
+        // Clamped: a wall clock stepping backwards (NTP, VM resume, fake timers) must not drive the bucket
+        // negative and stall every request until the clock catches up.
+        const elapsedMs = Math.max(0, now - this.last);
+        this.tokens = Math.min(this.policy.capacity, this.tokens + (elapsedMs / 1000) * this.policy.refillPerSec);
         this.last = now;
     }
     acquire(weight) {

package/dist/exchanges/registry.d.ts

@@ -1,6 +1,6 @@
 /**
  * Adapter registry — legacy name/alias API, now derived from the venue
- * definitions (src/exchanges/venues/, design §10.10). New venues are added by
+ * definitions (src/exchanges/venues/). New venues are added by
  * registering a VenueDefinition, not here.
  */
 import "./venues/index.js";

package/dist/exchanges/registry.js

@@ -1,6 +1,6 @@
 /**
  * Adapter registry — legacy name/alias API, now derived from the venue
- * definitions (src/exchanges/venues/, design §10.10). New venues are added by
+ * definitions (src/exchanges/venues/). New venues are added by
  * registering a VenueDefinition, not here.
  */
 import { getVenue, listVenues, tryResolveVenueId } from "./venue.js";

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

@@ -0,0 +1,148 @@
+/**
+ * RISEx adapter — market data (public), account reads (public by address) and trading through the
+ * registered, trading-only session signer (EIP-712 VerifyWitness permits; the server submits the
+ * on-chain transaction and pays gas).
+ *
+ * Account address: the signer's account (agent meta), else the master wallet's address (reads
+ * only, nothing is signed with it here). Writes need the signer.
+ *
+ * Order safety:
+ *  - every refusal (market flags, maintenance, precision, pins) happens before a nonce is
+ *    allocated or anything is signed;
+ *  - every permit consumes a fresh (anchor, bit) pair that is persisted BEFORE the send, so a
+ *    pair is never reused, even when the outcome is unknown;
+ *  - a client order id is always attached (generated uint64 when the caller gives none);
+ *  - an unknown send outcome → one read-only reconciliation (permit nonce consumed on-chain? the
+ *    client order id in open orders / order history?) → a proven result carries notes
+ *    ["reconciled"]; otherwise ORDER_PENDING ("do NOT resubmit") and the symbol is quarantined.
+ *    The permit deadline is short (RISEX_PERMIT_TTL_S), so an unproven permit expires quickly.
+ */
+import { PerpError } from "../../errors.js";
+import type { RisexAgentMeta } from "../../settings.js";
+import type { EvmSigner } from "../../signer/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";
+import { type AmendRequest, type CancelResult, type LeverageResult, type Network, type OrderRef, type OrderRequest, type OrderResult, type VenueMarket } from "../venue-types.js";
+import { type RisexChainReader } from "./session.js";
+/** Permit lifetime: long enough for the server to submit, short enough that an unproven permit expires soon. */
+export declare const RISEX_PERMIT_TTL_S = 120;
+/** How long a successful on-chain trading-only proof is trusted before the next permit re-checks it. */
+export declare const RISEX_TRADING_ONLY_TTL_MS = 60000;
+export interface RisexAdapterDeps {
+    /** Account the reads and permits are for; null = public market data only. */
+    account: string | null;
+    /** Trading-only session signer; null = no trading. */
+    signer: EvmSigner | null;
+    /** Agent meta the signer came from (for messages); null when none. */
+    meta: RisexAgentMeta | null;
+    /** Why trading is unavailable when `signer` is null (the uniform refusal). */
+    noSignerReason: PerpError | null;
+    nonceDir?: string;
+    chain?: RisexChainReader;
+    sleep?: (ms: number) => Promise<void>;
+    /** Quarantine hook for unknown outcomes (default: bot/quarantine.ts). */
+    quarantine?: (symbol: string, reason: string, remediation: string) => void;
+}
+export declare class RisexAdapter implements ExchangeAdapter, TradingV2 {
+    readonly name: "risex";
+    readonly aliases: readonly ["rise"];
+    readonly venue: VenueDefinition;
+    readonly network: Network;
+    private readonly client;
+    private readonly deps;
+    private markets;
+    constructor(def: VenueDefinition, network: Network, deps: RisexAdapterDeps);
+    /** Resolve the account and the trading-only signer from the create context (OWS only). */
+    static create(def: VenueDefinition, ctx: VenueCreateContext): Promise<RisexAdapter>;
+    /**
+     * Trading capabilities — also the adapter-level release gate: while the trading role is gated
+     * (risex-release.ts) this throws CAPABILITY_UNSUPPORTED before any validation, nonce or
+     * signature. Read paths never touch it, so the adapter still serves market data / account reads.
+     */
+    private get caps();
+    private requireAccount;
+    private requireSigner;
+    private sleep;
+    private rawMarkets;
+    /** Active market by symbol ("BTC", "BTC/USDC", "BTC-PERP") or market id. */
+    private market;
+    private symbolOfId;
+    /**
+     * The on-chain trading-only proof, re-checked at most every RISEX_TRADING_ONLY_TTL_MS before a
+     * permit (long-lived adapters — perp-mcp, bots — must notice a contract upgrade). A failed proof
+     * (refusal or RPC error) is never cached.
+     */
+    private tradingOnlyProof;
+    private permit;
+    private chainRead;
+    private quarantine;
+    /** The account reads / permits are for (signer's account, else the master address). */
+    accountAddress(): string;
+    /** Testnet faucet: 1000 test USDC, once per wallet (also registers the account). Refused on mainnet. */
+    testnetFaucet(): Promise<{
+        txHash: string | null;
+    }>;
+    getVenueMarkets(): Promise<VenueMarket[]>;
+    /** Legacy rows plus the venue's market-level order restrictions. */
+    getMarkets(): Promise<Array<ExchangeMarketInfo & {
+        marketId: string;
+        reduceOnlyMarket: boolean;
+        postOnlyMarket: boolean;
+        tradable: boolean;
+    }>>;
+    getOrderbook(symbol: string): Promise<{
+        bids: [string, string][];
+        asks: [string, string][];
+    }>;
+    getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
+    getFundingHistory(symbol: string, limit?: number): Promise<{
+        time: number;
+        rate: string;
+        price: string | null;
+    }[]>;
+    getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
+    private portfolio;
+    getBalance(): Promise<ExchangeBalance>;
+    getPositions(): Promise<ExchangePosition[]>;
+    private openOrdersRaw;
+    private historyOrders;
+    private toExchangeOrder;
+    /** On-chain open orders, enriched with the indexer's decimals / fills (one retry for indexer lag). */
+    getOpenOrders(): Promise<ExchangeOrder[]>;
+    getOrderHistory(limit?: number): Promise<ExchangeOrder[]>;
+    getTradeHistory(limit?: number): Promise<ExchangeTrade[]>;
+    /** `payment` is positive when RECEIVED (RISEx `funding_payment` is positive when paid — negated here). */
+    getFundingPayments(limit?: number): Promise<ExchangeFundingPayment[]>;
+    placeOrder(req: OrderRequest): Promise<OrderResult>;
+    /** One read-only reconciliation of an unknown place outcome. */
+    private reconcilePlace;
+    amendOrder(_req: AmendRequest): Promise<OrderResult>;
+    cancelByRef(symbol: string, ref: OrderRef): Promise<CancelResult>;
+    cancelAllV2(symbol: string | null): Promise<CancelResult>;
+    applyLeverage(symbol: string, leverage: number, marginMode: "cross" | "isolated" | null): Promise<LeverageResult>;
+    private sendAccountAction;
+    getOrderStatus(symbol: string, ref: OrderRef): Promise<OrderResult>;
+    marketOrder(symbol: string, side: "buy" | "sell", size: string, opts: {
+        reduceOnly: boolean;
+        slippage: ResolvedSlippage;
+        clientOrderId?: string;
+    }): Promise<unknown>;
+    limitOrder(symbol: string, side: "buy" | "sell", price: string, size: string, opts?: {
+        reduceOnly?: boolean;
+        tif?: string;
+        clientOrderId?: string;
+    }): Promise<unknown>;
+    editOrder(): Promise<unknown>;
+    cancelOrder(symbol: string, orderId: string): Promise<unknown>;
+    cancelAllOrders(symbol?: string): Promise<unknown>;
+    setLeverage(symbol: string, leverage: number, marginMode?: "cross" | "isolated"): Promise<unknown>;
+    stopOrder(): Promise<unknown>;
+    /** TP/SL entries are refused before the entry is sent (not implemented yet). */
+    stopOrderGate(): PerpError;
+    /** Bots / TWAP / grid / funding-arb legs stay off until RISEx trading is verified on mainnet. */
+    automationGate(): PerpError;
+}
+/** Candle intervals → ms (the venue takes the interval in ns). */
+export declare const KLINE_INTERVAL_MS: Readonly<Record<string, number>>;