perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/aster.js

@@ -18,6 +18,9 @@
  * Docs: https://docs.asterdex.com/product/aster-perpetuals/api/api-documentation
  * Base: https://fapi.asterdex.com
  */
+import { nonEmptyOrListed } from "./unknown-symbol.js";
+import { asterCliSymbol, isAsterListedPerpetual } from "../ws/aster-market.js";
+import { decimalsOf } from "./venue-types.js";
 import { accountCacheEpoch } from "../cache.js";
 import { isExpired } from "../agent-wallet/expiry.js";
 import { classifyError, DEFINITE_ORDER_FAILURE_CODES, isTransportFailure, orderNotSent, orderOutcomeUnknown, PerpError, sendFailure } from "../errors.js";
@@ -30,7 +33,7 @@ import { approvalFromMax, bpsToRate, builderGateOf, NO_BUILDER, rateToBps, requi
 import { ASTER_CLIENT_ID_RE, ASTER_FUNDS_CHAINS, asterVenue } from "./venues/aster.js";
 import { assertAsterWithdrawAmount, assertAsterWithdrawSignature, parseAsterWithdrawLimits, requireAsterFundsNetwork, } from "./aster-funds.js";
 import { nextAsterNonce } from "./aster-nonce.js";
-/** Common TIF (§13.3) → Aster perp timeInForce. Live exchangeInfo lists GTC/IOC/GTX/HIDDEN — no FOK. */
+/** Common TIF → Aster perp timeInForce. Live exchangeInfo lists GTC/IOC/GTX/HIDDEN — no FOK. */
 function asterTif(raw) {
     const t = raw.toUpperCase();
     if (t === "GTC" || t === "IOC" || t === "GTX")
@@ -72,6 +75,16 @@ export function asterIocOutcome(raw) {
     const filledSize = plainQty(r.executedQty);
     return filledSize === null ? null : { filledSize, final: true };
 }
+/** The numeric `code` of an Aster error body ({"code":-1121,"msg":"Invalid symbol."}); null when absent. */
+function asterErrorCode(body) {
+    try {
+        const j = JSON.parse(body);
+        return typeof j.code === "number" ? j.code : null;
+    }
+    catch {
+        return null; // not JSON (e.g. an HTML error page): no venue code
+    }
+}
 /**
  * Order-placement refusals by documented venue code (asterdex/api-docs V3 futures "Error
  * Codes"; "Codes are universal,but messages can vary"). [PerpError code, docs name, remediation].
@@ -163,6 +176,11 @@ export const ASTER_INCOME_MAX_PAGES = 60;
 const ASTER_KLINE_PAGE = 1500;
 /** Page cap for one range (150 000 bars). */
 const ASTER_KLINE_MAX_PAGES = 100;
+/**
+ * Kline intervals verified live 2026-10-19 (/fapi/v3/klines BTCUSDT: each answers bars of that
+ * length; "7m" / "2d" → -1120 "Invalid interval."). Anything else is refused before a request.
+ */
+export const ASTER_KLINE_INTERVALS = new Set(["1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "6h", "8h", "12h", "1d", "3d", "1w", "1M"]);
 export class AsterAdapter {
     name = "aster";
     chain = "bnb";
@@ -186,6 +204,8 @@ export class AsterAdapter {
     /** API symbol → price filters; null = listed but PRICE_FILTER / PERCENT_PRICE unreadable. */
     _priceFilters = new Map();
     _priceFiltersLoadedAt = 0;
+    /** The in-flight exchangeInfo load shared by concurrent first uses (_ensureDirectory). */
+    _directoryLoad = null;
     _accountCache = null;
     _positionsCache = null;
     _ordersCache = null;
@@ -283,7 +303,7 @@ export class AsterAdapter {
             return null;
         }
     }
-    // ── Spot host access (design §12, used by AsterSpotAdapter) ──
+    // ── Spot host access (used by AsterSpotAdapter) ──
     /**
      * Aster spot REST host. Spot shares the perp EIP-712 Domain B signing
      * (chainId 1666 mainnet / 714 testnet) and the per-agent nonce space.
@@ -316,12 +336,23 @@ export class AsterAdapter {
         return this._agentMeta;
     }
     // ── Symbol helpers ──
-    /** CLI symbol → Aster API symbol (ETH → ETHUSDT) */
+    /**
+     * CLI symbol → Aster API symbol through the LOADED market directory (exchangeInfo): the exact
+     * venue symbol first (BTCUSDT, BTCUSD1, BTCU — a non-USDT market's CLI symbol is its venue
+     * symbol, asterCliSymbol), then the USDT market of a base (ETH → ETHUSDT, USD1 → USD1USDT),
+     * else SYMBOL_NOT_FOUND — never a guessed suffix. Callers load the directory first (_apiSymbol).
+     */
     _toApi(symbol) {
         const s = symbol.toUpperCase().replace(/-PERP$/, "");
-        if (s.endsWith("USDT") || s.endsWith("BUSD"))
+        // A bare base names its USDT market first (X → XUSDT), even if a non-USDT venue symbol is
+        // spelled X too; an exact venue symbol otherwise (BTCUSD1, BTCU, XUSDT).
+        if (this._priceFilters.has(`${s}USDT`))
+            return `${s}USDT`;
+        if (this._priceFilters.has(s))
             return s;
-        return `${s}USDT`;
+        throw new PerpError("SYMBOL_NOT_FOUND", `Aster has no market ${s} (neither the venue symbol ${s} nor ${s}USDT is listed)`, {
+            exchange: "aster", remediation: "List markets: perp -e aster market list",
+        });
     }
     /** Aster API symbol → CLI symbol (ETHUSDT → ETH) */
     _fromApi(symbol) {
@@ -397,10 +428,9 @@ export class AsterAdapter {
         }
         const premiumMap = new Map(premiums.map(p => [String(p.symbol), p]));
         this._ingestPriceFilters(info.symbols);
-        // USDT-quoted perps only: the CLI symbol mapping (ETH ↔ ETHUSDT) cannot address the USD1 / U
-        // quoted markets (live 2026-10-13: 22 USD1 + 2 U), so listing them would offer untradeable rows.
-        const tradingSymbols = info.symbols
-            .filter((s) => String(s.contractType) === "PERPETUAL" && String(s.status) === "TRADING" && String(s.quoteAsset) === "USDT");
+        // Every listed perpetual, any quote (the WS directory's set): USDT-quoted ones by base (ETH),
+        // USD1 / U quoted ones by venue symbol (BTCUSD1, BTCU — asterCliSymbol), with quoteAsset.
+        const tradingSymbols = info.symbols.filter((s) => isAsterListedPerpetual(s));
         const result = tradingSymbols.flatMap((s) => {
             const sym = String(s.symbol);
             const ticker = tickerMap.get(sym);
@@ -412,17 +442,24 @@ export class AsterAdapter {
             const maxLev = null;
             const lotFilter = s.filters
                 ?.find(f => f.filterType === "LOT_SIZE");
+            const cliSymbol = asterCliSymbol({ symbol: sym, baseAsset: String(s.baseAsset), quoteAsset: s.quoteAsset });
             const fundingHours = this._fundingHoursCache.get(this._fromApi(sym));
             return [{
-                    symbol: this._fromApi(sym),
+                    symbol: cliSymbol,
+                    venueSymbol: sym,
+                    quoteAsset: typeof s.quoteAsset === "string" ? s.quoteAsset : null,
                     markPrice: String(premium.markPrice),
                     indexPrice: premium?.indexPrice != null ? String(premium.indexPrice) : null,
                     fundingRate: premium?.lastFundingRate != null ? String(premium.lastFundingRate) : null,
+                    // premiumIndex lastFundingRate moves during the period (same value as WS markPrice@arr `r`: accruing).
+                    fundingRateKind: premium?.lastFundingRate != null ? "accruing" : null,
                     volume24h: ticker?.quoteVolume != null ? String(ticker.quoteVolume) : null,
                     // /fapi/v3/exchangeInfo and ticker/24hr carry no open interest.
                     openInterest: null,
                     maxLeverage: maxLev,
-                    sizeDecimals: s.quantityPrecision != null ? Number(s.quantityPrecision) : null,
+                    // The LOT_SIZE step is the authoritative grid (quantityPrecision can disagree with it: CFX
+                    // step "1", precision 1); its decimals, the public directory's rule (venueMarketRow).
+                    sizeDecimals: lotFilter?.stepSize != null ? decimalsOf(String(lotFilter.stepSize)) : s.quantityPrecision != null ? Number(s.quantityPrecision) : null,
                     stepSize: lotFilter?.stepSize != null ? String(lotFilter.stepSize) : null,
                     fundingHours: fundingHours ?? null,
                     marginTiers: null,
@@ -457,16 +494,38 @@ export class AsterAdapter {
         this._priceFiltersLoadedAt = Date.now();
     }
     /** PRICE_FILTER / PERCENT_PRICE of an API symbol (exchangeInfo, cached CACHE_TTL). */
-    async _symbolPriceFilters(apiSymbol) {
-        if (!this._priceFiltersLoadedAt || Date.now() - this._priceFiltersLoadedAt >= AsterAdapter.CACHE_TTL) {
-            const info = await this._publicGet("/fapi/v3/exchangeInfo");
-            if (!Array.isArray(info?.symbols)) {
-                throw new PerpError("EXCHANGE_ERROR", "Aster /fapi/v3/exchangeInfo returned no symbols", { exchange: "aster" });
-            }
-            this._ingestPriceFilters(info.symbols);
+    /** exchangeInfo symbols (the market directory) loaded / refreshed per CACHE_TTL. */
+    /**
+     * exchangeInfo symbols (the market directory), refreshed per CACHE_TTL. Concurrent first uses
+     * share ONE in-flight request; a failed load is not cached (the next call retries).
+     */
+    async _ensureDirectory() {
+        if (this._priceFiltersLoadedAt && Date.now() - this._priceFiltersLoadedAt < AsterAdapter.CACHE_TTL)
+            return;
+        if (this._directoryLoad === null) {
+            this._directoryLoad = (async () => {
+                const info = await this._publicGet("/fapi/v3/exchangeInfo");
+                if (!Array.isArray(info?.symbols)) {
+                    throw new PerpError("EXCHANGE_ERROR", "Aster /fapi/v3/exchangeInfo returned no symbols", { exchange: "aster" });
+                }
+                this._ingestPriceFilters(info.symbols);
+            })().finally(() => { this._directoryLoad = null; });
         }
+        return this._directoryLoad;
+    }
+    /**
+     * CLI symbol → Aster API symbol, resolved through the market directory (_toApi), loaded on first
+     * use and cached CACHE_TTL — so the answer never depends on what was read before (a cold
+     * adapter resolves BTCU, USD1 → USD1USDT, an unknown symbol is SYMBOL_NOT_FOUND).
+     */
+    async _apiSymbol(symbol) {
+        await this._ensureDirectory();
+        return this._toApi(symbol);
+    }
+    async _symbolPriceFilters(apiSymbol) {
+        await this._ensureDirectory();
         if (!this._priceFilters.has(apiSymbol)) {
-            throw new PerpError("SYMBOL_NOT_FOUND", `Aster market ${apiSymbol} not found in exchangeInfo`, { exchange: "aster" });
+            throw new PerpError("SYMBOL_NOT_FOUND", `Aster market ${apiSymbol} not found in exchangeInfo`, { exchange: "aster", remediation: "List markets: perp -e aster market list" });
         }
         const f = this._priceFilters.get(apiSymbol);
         if (!f) {
@@ -475,12 +534,12 @@ export class AsterAdapter {
         return f;
     }
     /**
-     * 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.
      */
     async referencePrice(symbol) {
-        const apiSymbol = this._toApi(symbol);
+        const apiSymbol = await this._apiSymbol(symbol);
         let mark;
         try {
             const res = await this._publicGet("/fapi/v3/premiumIndex", { symbol: apiSymbol });
@@ -525,7 +584,7 @@ export class AsterAdapter {
      * against PRICE_FILTER / PERCENT_PRICE. appliedBps = the bound after tick alignment.
      */
     async computeProtectionPrice(symbol, side, slippage) {
-        const apiSymbol = this._toApi(symbol);
+        const apiSymbol = await this._apiSymbol(symbol);
         const f = await this._symbolPriceFilters(apiSymbol);
         const ref = await this.referencePrice(symbol);
         const protectionPrice = alignProtectionPrice(slippagePrice(ref, side, slippage.bps), f.tickSize, side);
@@ -538,7 +597,7 @@ export class AsterAdapter {
         return asterIocOutcome(raw);
     }
     async getOrderbook(symbol) {
-        const res = await this._publicGet("/fapi/v3/depth", { symbol: this._toApi(symbol), limit: "50" });
+        const res = await this._publicGet("/fapi/v3/depth", { symbol: await this._apiSymbol(symbol), limit: "50" });
         return {
             bids: res?.bids ?? [],
             asks: res?.asks ?? [],
@@ -546,27 +605,33 @@ export class AsterAdapter {
     }
     async getRecentTrades(symbol, limit = 20) {
         const trades = await this._publicGet("/fapi/v3/trades", {
-            symbol: this._toApi(symbol),
+            symbol: await this._apiSymbol(symbol),
             limit: String(limit),
         });
-        return (trades ?? []).map((t) => ({
-            time: Number(t.time ?? 0),
-            symbol: this._fromApi(String(t.symbol ?? symbol)),
-            side: t.isBuyerMaker ? "sell" : "buy",
-            price: String(t.price ?? "0"),
-            size: String(t.qty ?? "0"),
-            fee: "0",
-        }));
+        if (!Array.isArray(trades))
+            throw new PerpError("EXCHANGE_ERROR", `Aster trades is not a list (${JSON.stringify(trades).slice(0, 120)})`, { exchange: "aster" });
+        // The tape rows carry no symbol: the normalized venue symbol (was the raw argument, "BTC-PERP").
+        const sym = this._fromApi(await this._apiSymbol(symbol));
+        return trades.map((t) => {
+            if (typeof t.time !== "number" || typeof t.price !== "string" || typeof t.qty !== "string" || typeof t.isBuyerMaker !== "boolean") {
+                throw new PerpError("EXCHANGE_ERROR", `Aster trade row without time / price / qty / isBuyerMaker: ${JSON.stringify(t).slice(0, 160)}`, { exchange: "aster" });
+            }
+            return { time: t.time, symbol: sym, side: t.isBuyerMaker ? "sell" : "buy", price: t.price, size: t.qty, fee: null }; // the public tape carries no fee
+        });
     }
     async getFundingHistory(symbol, limit = 10) {
         const data = await this._publicGet("/fapi/v3/fundingRate", {
-            symbol: this._toApi(symbol),
+            symbol: await this._apiSymbol(symbol),
             limit: String(limit),
         });
         if (!Array.isArray(data)) {
             throw new PerpError("EXCHANGE_ERROR", `Aster fundingRate history is not a list (${JSON.stringify(data).slice(0, 120)})`, { exchange: "aster" });
         }
-        return data.map((d) => {
+        // Per-market interval (/fapi/v3/fundingInfo); null when the venue lists none for the symbol.
+        const hours = await this.getFundingHours(symbol);
+        const intervalHours = hours === undefined ? null : hours;
+        // `200 []` for an unlisted symbol (live 2026-10-14): checked against the market directory.
+        return nonEmptyOrListed(this, symbol, data.map((d) => {
             const time = Number(d.fundingTime);
             if (d.fundingTime === undefined || d.fundingTime === null || !Number.isFinite(time) || time <= 0) {
                 throw new PerpError("EXCHANGE_ERROR", `Aster fundingRate row without a numeric fundingTime: ${JSON.stringify(d).slice(0, 160)}`, { exchange: "aster" });
@@ -575,8 +640,10 @@ export class AsterAdapter {
                 time,
                 rate: venueRateField(d.fundingRate, "fundingRate fundingRate", "aster"),
                 price: d.markPrice ? String(d.markPrice) : null,
+                intervalHours,
+                rateKind: "lastSettled",
             };
-        });
+        }), this._fromApi(await this._apiSymbol(symbol)));
     }
     /**
      * Candles over [startTime, endTime]. GET /fapi/v3/klines returns at most 1500 bars per request
@@ -584,6 +651,11 @@ export class AsterAdapter {
      * range is never cut to the first page. More than ASTER_KLINE_MAX_PAGES pages → INVALID_PARAMS.
      */
     async getKlines(symbol, interval, startTime, endTime) {
+        if (!ASTER_KLINE_INTERVALS.has(interval)) {
+            throw new PerpError("INVALID_PARAMS", `Aster: unsupported candle interval "${interval}"`, {
+                remediation: `Use one of: ${[...ASTER_KLINE_INTERVALS].join(", ")}`,
+            });
+        }
         if (!(startTime <= endTime)) {
             throw new PerpError("INVALID_PARAMS", `Aster klines: start ${startTime} is after end ${endTime}`, {
                 remediation: "Pass a --start that is before --end",
@@ -598,7 +670,7 @@ export class AsterAdapter {
                 });
             }
             const data = await this._publicGet("/fapi/v3/klines", {
-                symbol: this._toApi(symbol), interval,
+                symbol: await this._apiSymbol(symbol), interval,
                 startTime: String(from), endTime: String(endTime), limit: String(ASTER_KLINE_PAGE),
             });
             if (!Array.isArray(data)) {
@@ -607,10 +679,11 @@ export class AsterAdapter {
             for (const k of data) {
                 const time = Number(k[0]);
                 const trades = Number(k[8]);
-                if (!Number.isFinite(time) || !Number.isFinite(trades)) {
-                    throw new PerpError("EXCHANGE_ERROR", `Aster kline row without open time / trade count: ${JSON.stringify(k).slice(0, 120)}`, { exchange: "aster" });
+                const numeric = (v) => (typeof v === "string" || typeof v === "number") && String(v).trim() !== "" && Number.isFinite(Number(v));
+                if (!Number.isFinite(time) || !Number.isFinite(trades) || !numeric(k[5]) || !numeric(k[7])) {
+                    throw new PerpError("EXCHANGE_ERROR", `Aster kline row without open time / volume / quote volume / trade count: ${JSON.stringify(k).slice(0, 120)}`, { exchange: "aster" });
                 }
-                out.push({ time, open: String(k[1]), high: String(k[2]), low: String(k[3]), close: String(k[4]), volume: String(k[5]), trades });
+                out.push({ time, open: String(k[1]), high: String(k[2]), low: String(k[3]), close: String(k[4]), volume: String(k[5]), quoteVolume: String(k[7]), trades });
             }
             if (data.length < ASTER_KLINE_PAGE)
                 break;
@@ -975,12 +1048,12 @@ export class AsterAdapter {
     }
     // ── Trading ──
     async marketOrder(symbol, side, size, opts) {
-        // Design §13.2 / §13.10 #6: never native MARKET (no price cap) — an IOC LIMIT at the
+        // Never native MARKET (no price cap) — an IOC LIMIT at the
         // protection price (mark ± opts.slippage.bps, tick-aligned toward crossing, inside
         // PRICE_FILTER / PERCENT_PRICE). newOrderRespType=RESULT makes the response carry the
         // final IOC status (FILLED / EXPIRED) and executedQty.
         const r = this._resolveSigner();
-        const apiSymbol = this._toApi(symbol);
+        const apiSymbol = await this._apiSymbol(symbol);
         const clientOrderId = opts.clientOrderId === undefined ? null : requireAsterClientOrderId(opts.clientOrderId);
         let protectionPrice;
         let protection;
@@ -1068,11 +1141,11 @@ export class AsterAdapter {
     }
     async limitOrder(symbol, side, price, size, opts) {
         const r = this._resolveSigner();
-        const apiSymbol = this._toApi(symbol);
+        const apiSymbol = await this._apiSymbol(symbol);
         const clientOrderId = opts?.clientOrderId === undefined ? null : requireAsterClientOrderId(opts.clientOrderId);
         let params;
         try {
-            // Common TIF names (§13.3): GTC / IOC / ALO→GTX (GTX accepted as alias); FOK unsupported.
+            // Common TIF names: GTC / IOC / ALO→GTX (GTX accepted as alias); FOK unsupported.
             const tif = asterTif(opts?.tif ?? "GTC");
             // Price must already be on PRICE_FILTER.tickSize — validated, never rounded (INVALID_TICK).
             const px = requireOnTick(price, (await this._symbolPriceFilters(apiSymbol)).tickSize);
@@ -1104,14 +1177,14 @@ export class AsterAdapter {
     /**
      * 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).
      */
     async editOrder(symbol, orderId, price, size) {
         const r = this._resolveSigner();
-        const apiSymbol = this._toApi(symbol);
+        const apiSymbol = await this._apiSymbol(symbol);
         const rawOrders = await this._signedGetEip712("/fapi/v3/openOrders", {}, r);
         const existing = (rawOrders ?? []).find(o => String(o.orderId ?? "") === orderId);
         if (!existing) {
@@ -1158,7 +1231,7 @@ export class AsterAdapter {
         const label = ref.kind === "orderId" ? ref.value : `c:${ref.value}`;
         let row;
         try {
-            row = await this._signedGetEip712("/fapi/v3/order", { symbol: this._toApi(symbol), ...key }, this._resolveSigner());
+            row = await this._signedGetEip712("/fapi/v3/order", { symbol: await this._apiSymbol(symbol), ...key }, this._resolveSigner());
         }
         catch (e) {
             if (e instanceof PerpError && e.structured.details?.venueCode === -2013) {
@@ -1177,7 +1250,7 @@ export class AsterAdapter {
         const r = this._resolveSigner();
         try {
             return await this._signedDeleteEip712("/fapi/v3/order", {
-                symbol: this._toApi(symbol),
+                symbol: await this._apiSymbol(symbol),
                 ...key,
             }, r);
         }
@@ -1198,6 +1271,7 @@ export class AsterAdapter {
         const r = this._resolveSigner();
         if (!symbol) {
             const orders = await this.getOpenOrders();
+            await this._ensureDirectory();
             const apiSymbols = new Set(orders.map(o => this._toApi(o.symbol)));
             const results = [];
             for (const sym of apiSymbols) {
@@ -1205,7 +1279,7 @@ export class AsterAdapter {
             }
             return results;
         }
-        return this._signedDeleteEip712("/fapi/v3/allOpenOrders", { symbol: this._toApi(symbol) }, r);
+        return this._signedDeleteEip712("/fapi/v3/allOpenOrders", { symbol: await this._apiSymbol(symbol) }, r);
     }
     // ── Risk ──
     async setLeverage(symbol, leverage, marginMode) {
@@ -1213,7 +1287,7 @@ export class AsterAdapter {
         if (marginMode) {
             try {
                 await this._signedPostEip712("/fapi/v3/marginType", {
-                    symbol: this._toApi(symbol),
+                    symbol: await this._apiSymbol(symbol),
                     marginType: marginMode === "cross" ? "CROSSED" : "ISOLATED",
                 }, r);
             }
@@ -1252,7 +1326,7 @@ export class AsterAdapter {
             }
         }
         return this._signedPostEip712("/fapi/v3/leverage", {
-            symbol: this._toApi(symbol),
+            symbol: await this._apiSymbol(symbol),
             leverage: String(leverage),
         }, r);
     }
@@ -1271,7 +1345,7 @@ export class AsterAdapter {
      */
     async stopOrder(symbol, side, size, triggerPrice, opts) {
         const r = this._resolveSigner();
-        const apiSymbol = this._toApi(symbol);
+        const apiSymbol = await this._apiSymbol(symbol);
         const what = `stop ${side} ${size} ${symbol} @ ${triggerPrice}`;
         let params;
         try {
@@ -1757,6 +1831,11 @@ export class AsterAdapter {
         if (!res.ok) {
             const text = await res.text();
             const clean = text.replace(/<[^>]*>/g, " ").replace(/\s+/g, " ").trim().slice(0, 120);
+            // -1121 BAD_SYMBOL ("Invalid symbol.", live on /fapi/v3/depth for an unlisted symbol): the
+            // symbol does not exist — SYMBOL_NOT_FOUND, not an UNKNOWN 500.
+            if (asterErrorCode(text) === -1121) {
+                throw new PerpError("SYMBOL_NOT_FOUND", `Aster: ${clean} [${method} ${path}]`, { exchange: "aster", remediation: "List markets: perp -e aster market list" });
+            }
             throw new Error(`${method} ${path} failed (${res.status}): ${clean}`);
         }
         return res.json();
@@ -1768,10 +1847,31 @@ export class AsterAdapter {
         const url = `${this._baseUrl}${path}${qs ? `?${qs}` : ""}`;
         for (let attempt = 0; attempt < 3; attempt++) {
             const res = await fetch(url);
-            const result = await this._handleResponse(res, "GET", path, attempt);
+            let result;
+            try {
+                result = await this._handleResponse(res, "GET", path, attempt);
+            }
+            catch (e) {
+                if (e instanceof PerpError)
+                    throw e;
+                // A public read never surfaces as UNKNOWN: rate limit / server-side / other HTTP failure.
+                const msg = e instanceof Error ? e.message : String(e);
+                throw new PerpError(res.status === 429 ? "RATE_LIMITED" : res.status >= 500 ? "EXCHANGE_UNREACHABLE" : "EXCHANGE_ERROR", `Aster ${msg}`, {
+                    exchange: "aster", status: res.status, remediation: res.status === 429 || res.status >= 500 ? "Retry later" : "Check the request (symbol / parameters)",
+                });
+            }
+            // A parameter rejection arrives as HTTP 200 with an error body (live 2026-10-19,
+            // fundingRate limit=1001: {"status":"ERROR","type":"VALID","code":"000002","errorData":{"limit":"…"}}).
+            if (result !== null && typeof result === "object" && !Array.isArray(result) && result.status === "ERROR") {
+                const r = result;
+                const detail = JSON.stringify(r.errorData ?? r).slice(0, 200);
+                throw new PerpError(r.type === "VALID" ? "INVALID_PARAMS" : "EXCHANGE_ERROR", `Aster ${path} rejected the request: ${detail}`, {
+                    exchange: "aster", venueCode: r.code, remediation: "Check the request parameters (e.g. --limit 1..1000)",
+                });
+            }
             if (result !== null)
                 return result;
         }
-        throw new Error(`GET ${path} failed: max retries exceeded`);
+        throw new PerpError("RATE_LIMITED", `Aster GET ${path}: rate limited after 3 attempts`, { exchange: "aster", remediation: "Retry later" });
     }
 }

package/dist/exchanges/builder-fee.d.ts

@@ -21,7 +21,7 @@
  *     `builder: { b: <address>, f: <tenths of a bp> }`; max 0.1% perps / 1% spot; status
  *     info `{ type: "maxBuilderFee", user, builder }`. HIP-3 dexes are not covered by the
  *     docs → never attached there.
- * - pacifica     https://pacifica.gitbook.io/docs/programs/builder-program.md
+ * - pacifica     https://docs.pacifica.fi/programs/builder-program.md
  *     approve_builder_code { builder_code, max_fee_rate } signed by the account; per-order
  *     `builder_code` on create_market / create / stop/create / positions/tpsl. TWAP
  *     (create_twap_order) does not document builder_code → never sent there.

package/dist/exchanges/builder-fee.js

@@ -21,7 +21,7 @@
  *     `builder: { b: <address>, f: <tenths of a bp> }`; max 0.1% perps / 1% spot; status
  *     info `{ type: "maxBuilderFee", user, builder }`. HIP-3 dexes are not covered by the
  *     docs → never attached there.
- * - pacifica     https://pacifica.gitbook.io/docs/programs/builder-program.md
+ * - pacifica     https://docs.pacifica.fi/programs/builder-program.md
  *     approve_builder_code { builder_code, max_fee_rate } signed by the account; per-order
  *     `builder_code` on create_market / create / stop/create / positions/tpsl. TWAP
  *     (create_twap_order) does not document builder_code → never sent there.
@@ -49,6 +49,7 @@
  */
 import { PerpError, classifyError, isDefiniteOrderFailure, isTransportFailure, isUnknownOutcomeServerError } from "../errors.js";
 import { isVenueId } from "./venue-types.js";
+import { VARIATIONAL_READ_ONLY_REMEDIATION } from "./venues/variational.js";
 export const BUILDER_FEE_CAPABILITIES = {
     hyperliquid: {
         approval: "master", identity: "address", perpCapBps: 10, spotCapBps: 100, hip3: false, testnet: true,
@@ -56,7 +57,7 @@ export const BUILDER_FEE_CAPABILITIES = {
     },
     pacifica: {
         approval: "master", identity: "code", perpCapBps: 10, spotCapBps: null, hip3: null, testnet: true,
-        feeStepBps: 0.01, feeKind: "max", docs: "https://pacifica.gitbook.io/docs/programs/builder-program.md",
+        feeStepBps: 0.01, feeKind: "max", docs: "https://docs.pacifica.fi/programs/builder-program.md",
     },
     aster: {
         approval: "master", identity: "address", perpCapBps: 10, spotCapBps: null, hip3: null, testnet: false,
@@ -73,11 +74,21 @@ export const BUILDER_FEE_CAPABILITIES = {
     lighter: null,
     "lighter-rh": null,
     arcus: null,
+    risex: null,
+    txflow: null,
+    variational: null,
+    grvt: null,
+    extended: null,
 };
 /** Why a venue has no builder-fee support (shown in CAPABILITY_UNSUPPORTED). */
 export const BUILDER_FEE_UNSUPPORTED = {
     lighter: "not yet implemented in perp-cli — the official lighter-go signer can sign ApproveIntegrator and the per-order integrator fields, but perp-cli sends them as 0 (https://apidocs.lighter.xyz/docs/partner-integration)",
     "lighter-rh": "not yet implemented in perp-cli — Lighter RH uses the same official lighter-go signer; partner-attribution fields are sent as 0 (https://apidocs.rh.lighter.xyz/docs/partner-attribution.md)",
+    risex: "not implemented yet in perp-cli (RISEx builder codes are planned; note the venue's \"bps\" field is parts-per-million)",
+    txflow: "TxFlow is integrated through an unofficial read-only API (market data only)",
+    variational: VARIATIONAL_READ_ONLY_REMEDIATION,
+    grvt: "GRVT is read-only (market data) in this version; trading is planned for a later release",
+    extended: "Extended is available for market data only in this version (trading is planned for a later release)",
     arcus: "Arcus has no perps builder fee; its integrator fee applies to the spot router only and needs a partner key from Arcus (https://docs.arcus.xyz/concepts/spot-router)",
 };
 export function builderFeeUnsupported(venue) {

package/dist/exchanges/canonical-symbols.d.ts

@@ -1,7 +1,6 @@
 /**
  * Cross-venue canonical symbols — the single mapping source used to decide
- * that two markets on different venues are the same underlying
- * (design §4 L4, §10.9).
+ * that two markets on different venues are the same underlying.
  *
  * Rules by asset class:
  * - crypto:  ticker identity after the adapter strips its quote suffix, plus
@@ -30,3 +29,10 @@ export declare function isNeverMatch(a: string, b: string): boolean;
  * @param symbol   plain symbol as reported by the adapter (no quote suffix, no dex prefix)
  */
 export declare function canonicalFor(venueKey: VenueId | `hl:${string}`, symbol: string, assetClass: AssetClass): string | null;
+/**
+ * Canonical key for a symbol a USER typed (no venue / asset class known — `arb scan --compare`):
+ * a "-PERP" suffix is dropped, a denomination alias maps to its canonical ticker (kPEPE →
+ * 1000PEPE, UBTC → BTC), and a venue ticker of the explicit table maps to its canonical key when
+ * every venue that lists it agrees (XAU → GOLD, CL → CRUDE_OIL_WTI). Anything else: upper-cased.
+ */
+export declare function canonicalQuerySymbol(symbol: string): string;

package/dist/exchanges/canonical-symbols.js

@@ -1,7 +1,6 @@
 /**
  * Cross-venue canonical symbols — the single mapping source used to decide
- * that two markets on different venues are the same underlying
- * (design §4 L4, §10.9).
+ * that two markets on different venues are the same underlying.
  *
  * Rules by asset class:
  * - crypto:  ticker identity after the adapter strips its quote suffix, plus
@@ -47,19 +46,44 @@ export const EXPLICIT_CANONICAL = {
     "hl:xyz|SILVER": "SILVER",
     "qfex|GOLD": "GOLD",
     "qfex|SILVER": "SILVER",
+    "risex|XAU": "GOLD",
+    "risex|XAG": "SILVER",
+    "txflow|XAU": "GOLD",
+    "txflow|XAG": "SILVER",
+    "variational|XAU": "GOLD",
+    "variational|XAG": "SILVER",
+    "grvt|XAU": "GOLD",
+    "grvt|XAG": "SILVER",
+    "extended|XAU": "GOLD",
+    "extended|XAG": "SILVER",
     // Crude oil (WTI)
     "ondo|WTI": "CRUDE_OIL_WTI",
     "hl:xyz|CL": "CRUDE_OIL_WTI",
     "hl:flx|OIL": "CRUDE_OIL_WTI",
     // QFEX CL blends expiring futures; roll-week gaps are caught by the cross-venue price filter.
     "qfex|CL": "CRUDE_OIL_WTI",
+    "risex|CL": "CRUDE_OIL_WTI",
+    // Brent crude
+    "risex|BZ": "CRUDE_OIL_BRENT",
+    "txflow|BZ": "CRUDE_OIL_BRENT",
+    "txflow|CL": "CRUDE_OIL_WTI",
+    "variational|BZ": "CRUDE_OIL_BRENT",
+    "variational|CL": "CRUDE_OIL_WTI",
+    "grvt|BZ": "CRUDE_OIL_BRENT",
+    "grvt|CL": "CRUDE_OIL_WTI",
+    "extended|WTI": "CRUDE_OIL_WTI",
+    "extended|XBR": "CRUDE_OIL_BRENT",
     // US equity indices
     "ondo|US500": "SPX",
     "ondo|US100": "NDX",
     "qfex|US500": "SPX",
     "qfex|US100": "NDX",
+    // Extended SPX500m / TECH100m: S&P 500 / Nasdaq-100 index perps (uiName SPX-USD / NDX-USD).
+    "extended|SPX500M": "SPX",
+    "extended|TECH100M": "NDX",
     // FX
     "ondo|USDJPY": "USDJPY",
+    "extended|USDJPY": "USDJPY",
 };
 /** Pairs verified to be DIFFERENT products despite similar names. Never match. */
 export const NEVER_MATCH = new Set([
@@ -92,5 +116,25 @@ export function canonicalFor(venueKey, symbol, assetClass) {
         case "fx":
         case "preIpo":
             return EXPLICIT_CANONICAL[`${venueKey}|${up}`] ?? null;
+        case "unclassified":
+            return null; // ambiguous ticker: listed, never matched across venues
     }
 }
+/**
+ * Canonical key for a symbol a USER typed (no venue / asset class known — `arb scan --compare`):
+ * a "-PERP" suffix is dropped, a denomination alias maps to its canonical ticker (kPEPE →
+ * 1000PEPE, UBTC → BTC), and a venue ticker of the explicit table maps to its canonical key when
+ * every venue that lists it agrees (XAU → GOLD, CL → CRUDE_OIL_WTI). Anything else: upper-cased.
+ */
+export function canonicalQuerySymbol(symbol) {
+    const up = symbol.trim().toUpperCase().replace(/-PERP$/, "");
+    const alias = DENOMINATION_ALIASES[up];
+    if (alias !== undefined)
+        return alias;
+    const targets = new Set();
+    for (const [key, canonical] of Object.entries(EXPLICIT_CANONICAL)) {
+        if (key.slice(key.indexOf("|") + 1) === up)
+            targets.add(canonical);
+    }
+    return targets.size === 1 ? [...targets][0] : up;
+}

package/dist/exchanges/capabilities.d.ts

@@ -29,6 +29,8 @@ export interface TriggerOrderCapable {
 export interface DexCapable {
     readonly dex: string;
     setDex(dex: string): void;
+    /** An independent adapter for `dex` with this account configuration and its own market state (never mutates this one). */
+    forDex(dex: string): ExchangeAdapter & DexCapable;
     listDeployedDexes(): Promise<{
         name: string;
         deployer: string;

package/dist/exchanges/capabilities.js

@@ -18,7 +18,8 @@ export function isTriggerOrderCapable(adapter) {
 }
 export function isDexCapable(adapter) {
     return typeof adapter.setDex === "function"
-        && typeof adapter.listDeployedDexes === "function";
+        && typeof adapter.listDeployedDexes === "function"
+        && typeof adapter.forDex === "function";
 }
 export function isSubAccountCapable(adapter) {
     return typeof adapter.createSubAccount === "function";