perp-cli 0.15.0 → 0.16.0

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, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangePublicTrade, ExchangeFundingPayment, ExchangeKline, FundingHistoryRow } from "./interface.js";
 import type { ResolvedSlippage } from "./slippage.js";
 import type { EvmSigner } from "../signer/interface.js";
 import type { AgentMeta } from "../settings.js";
@@ -68,6 +68,11 @@ type ResolvedSigner = {
  * that the read refuses (EXCHANGE_ERROR) rather than returning a partial history.
  */
 export declare const ASTER_INCOME_MAX_PAGES = 60;
+/**
+ * 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 declare const ASTER_KLINE_INTERVALS: ReadonlySet<string>;
 export declare class AsterAdapter implements ExchangeAdapter {
     readonly name = "aster";
     readonly chain = "bnb";
@@ -89,6 +94,8 @@ export declare class AsterAdapter implements ExchangeAdapter {
     /** API symbol → price filters; null = listed but PRICE_FILTER / PERCENT_PRICE unreadable. */
     private _priceFilters;
     private _priceFiltersLoadedAt;
+    /** The in-flight exchangeInfo load shared by concurrent first uses (_ensureDirectory). */
+    private _directoryLoad;
     private _accountCache;
     private _positionsCache;
     private _ordersCache;
@@ -135,7 +142,12 @@ export declare class AsterAdapter implements ExchangeAdapter {
      * agent. Throws exactly like signed calls when no signer is usable.
      */
     activeAgentMeta(): AgentMeta | null;
-    /** 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).
+     */
     private _toApi;
     /** Aster API symbol → CLI symbol (ETHUSDT → ETH) */
     private _fromApi;
@@ -159,6 +171,18 @@ export declare class AsterAdapter implements ExchangeAdapter {
     /** Parse PRICE_FILTER + PERCENT_PRICE for every exchangeInfo symbol into the cache. */
     private _ingestPriceFilters;
     /** PRICE_FILTER / PERCENT_PRICE of an API symbol (exchangeInfo, cached CACHE_TTL). */
+    /** 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).
+     */
+    private _ensureDirectory;
+    /**
+     * 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).
+     */
+    private _apiSymbol;
     private _symbolPriceFilters;
     /**
      * Declared protection-price reference: the venue mark price from
@@ -191,11 +215,7 @@ export declare class AsterAdapter implements ExchangeAdapter {
         asks: [string, string][];
     }>;
     getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
-    getFundingHistory(symbol: string, limit?: number): Promise<{
-        time: number;
-        rate: string;
-        price: string | null;
-    }[]>;
+    getFundingHistory(symbol: string, limit?: number): Promise<FundingHistoryRow[]>;
     /**
      * 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

package/dist/exchanges/aster.js

@@ -19,6 +19,8 @@
  * 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";
@@ -174,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";
@@ -197,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;
@@ -327,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) {
@@ -408,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);
@@ -423,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,
@@ -468,14 +494,36 @@ 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", remediation: "List markets: perp -e aster market list" });
         }
@@ -491,7 +539,7 @@ export class AsterAdapter {
      * 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 });
@@ -536,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);
@@ -549,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 ?? [],
@@ -557,26 +605,31 @@ 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: null, // the public tape carries no fee
-        }));
+        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" });
         }
+        // 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);
@@ -587,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(this._toApi(symbol)));
+        }), this._fromApi(await this._apiSymbol(symbol)));
     }
     /**
      * Candles over [startTime, endTime]. GET /fapi/v3/klines returns at most 1500 bars per request
@@ -596,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",
@@ -610,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)) {
@@ -993,7 +1053,7 @@ export class AsterAdapter {
         // 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;
@@ -1081,7 +1141,7 @@ 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 {
@@ -1124,7 +1184,7 @@ export class AsterAdapter {
      */
     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) {
@@ -1171,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) {
@@ -1190,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);
         }
@@ -1211,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) {
@@ -1218,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) {
@@ -1226,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);
             }
@@ -1265,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);
     }
@@ -1284,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 {
@@ -1786,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/canonical-symbols.d.ts

@@ -29,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

@@ -116,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";

package/dist/exchanges/derive/options.d.ts

@@ -39,6 +39,11 @@ export declare function utcDate(ms: number): string;
 export declare function normalizeExpiry(input: string): string;
 /** User underlying → venue currency (upper case); INVALID_PARAMS for anything that is not a ticker. */
 export declare function normalizeUnderlying(input: string): string;
+/**
+ * CLI option name → Derive wire name: upper-cased, and a decimal point in the strike written as
+ * the venue's underscore (`PUMP-20261023-0.0045-C` → `PUMP-20261023-0_0045-C`).
+ */
+export declare function deriveInstrumentName(input: string): string;
 export declare function parseDeriveInstrument(raw: unknown): DeriveOptionInstrument;
 /** A ticker_slim snapshot (get_ticker / get_tickers value) of `inst` → OptionQuote. */
 export declare function parseDeriveOptionTicker(raw: unknown, inst: DeriveOptionInstrument): OptionQuote;

package/dist/exchanges/derive/options.js

@@ -75,6 +75,16 @@ export function normalizeUnderlying(input) {
     }
     return u;
 }
+/**
+ * CLI option name → Derive wire name: upper-cased, and a decimal point in the strike written as
+ * the venue's underscore (`PUMP-20261023-0.0045-C` → `PUMP-20261023-0_0045-C`).
+ */
+export function deriveInstrumentName(input) {
+    const parts = input.trim().toUpperCase().split("-");
+    if (parts.length === 4)
+        parts[2] = parts[2].replace(/\./g, "_");
+    return parts.join("-");
+}
 // ── parsing ──
 export function parseDeriveInstrument(raw) {
     const o = obj(raw, "instrument");
@@ -318,7 +328,7 @@ export class DeriveOptionsVenue {
         return buildChain(underlying, expiry, wanted === null ? "nearest" : "requested", listed, res.tickers, q.strikesAroundAtm);
     }
     async getQuote(instrumentInput) {
-        const name = instrumentInput.trim().toUpperCase();
+        const name = deriveInstrumentName(instrumentInput);
         // Both reads are needed (instrument facts + live ticker); issued together, judged instrument first.
         const [instR, tickR] = await Promise.allSettled([
             this.client.call("get_instrument", { instrument_name: name }),
@@ -339,6 +349,15 @@ export class DeriveOptionsVenue {
             });
         }
         const inst = parseDeriveInstrument(o);
+        if (!inst.isActive && inst.expiryMs <= Date.now()) {
+            // Expired (live: ETH-20261019-2400-C, is_active false after expiry, option_details.settlement_price set).
+            const sp = o.option_details?.settlement_price;
+            const settled = typeof sp === "string" && sp !== "" ? `, settled at ${sp}` : " (settlement price not published yet)";
+            throw new PerpError("SYMBOL_NOT_FOUND", `Derive option ${name} expired at ${new Date(inst.expiryMs).toISOString()}${settled}`, {
+                exchange: VENUE, expired: true, settlementPrice: typeof sp === "string" && sp !== "" ? sp : null,
+                remediation: `Active expiries: perp -e ${VENUE} options expiries ${inst.underlying}`,
+            });
+        }
         if (!inst.isActive) {
             throw new PerpError("SYMBOL_NOT_FOUND", `Derive option ${name} is listed but not active (activation ${new Date(inst.activationMs).toISOString()})`, {
                 exchange: VENUE, remediation: `Active expiries: perp -e ${VENUE} options expiries ${inst.underlying}`,

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

@@ -19,8 +19,18 @@ export declare const EXTENDED_KLINE_INTERVALS: Readonly<Record<string, {
     wire: string;
     ms: number;
 }>>;
-/** Documented per-request maximum of the candles and funding-history endpoints. */
+/** Documented per-request maximum of the candles and funding-history endpoints (accepted `limit`). */
 export declare const EXTENDED_MAX_RECORDS = 10000;
+/**
+ * Real server caps, measured live 2026-10-19 (BTC-USD; no pagination field, no error): candles
+ * return at most 2800 rows on every interval with that much history (PT1M … PT4H: 2800; PT8H 2445,
+ * PT12H 1631, PT24H 816, P7D 118, P30D 28 = the whole history since 2024-07), funding history at
+ * most 1000 (the newest). Both page backwards with `endTime` = before the oldest row and stop only
+ * on an empty page or at the window start — a short page is never taken as the end.
+ */
+export declare const EXTENDED_CANDLES_PAGE_CAP = 2800;
+export declare const EXTENDED_FUNDING_PAGE_CAP = 1000;
+export declare const EXTENDED_TRADES_CAP = 50;
 /** Legacy market row plus the Extended fields shown in JSON (asset class, precision, schedule). */
 export type ExtendedMarketInfo = ExchangeMarketInfo & {
     venueSymbol: string;
@@ -62,8 +72,12 @@ export declare class ExtendedPublicAdapter implements ExchangeAdapter {
         asks: [string, string][];
     }>;
     getRecentTrades(symbol: string, limit?: number): Promise<ExchangePublicTrade[]>;
-    /** Applied (settled) hourly rates, newest first — fraction per hour; no oracle price published. */
+    /**
+     * Applied (settled) hourly rates, newest first — fraction per hour; no oracle price published.
+     * Paged backwards in pages of EXTENDED_FUNDING_PAGE_CAP until `limit` rows or the window start.
+     */
     getFundingHistory(symbol: string, limit?: number): Promise<ExtendedFundingPrint[]>;
+    /** Candles paged backwards from `endTime` in pages of EXTENDED_CANDLES_PAGE_CAP (newest first on the wire). */
     getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
     private refuse;
     getBalance(): Promise<ExchangeBalance>;