perp-cli 0.12.17 → 0.14.1

package/dist/exchanges/aster.js

@@ -18,10 +18,142 @@
  * Docs: https://docs.asterdex.com/product/aster-perpetuals/api/api-documentation
  * Base: https://fapi.asterdex.com
  */
+import { accountCacheEpoch } from "../cache.js";
 import { isExpired } from "../agent-wallet/expiry.js";
-import { classifyError, PerpError } from "../errors.js";
-import { buildOrderTypedData } from "./aster-typed-data.js";
+import { classifyError, DEFINITE_ORDER_FAILURE_CODES, isTransportFailure, orderNotSent, orderOutcomeUnknown, PerpError, sendFailure } from "../errors.js";
+import { parseFiniteVenueNumber, venueRateField } from "../utils/numeric.js";
+import { buildOrderTypedData, buildWithdrawTypedData } from "./aster-typed-data.js";
+import { alignProtectionPrice, requireOnTick, requirePositive, slippagePrice, subDecimal } from "./precision.js";
+import { unsupported } from "./trading-v2.js";
+import { networkConfig } from "./venue.js";
+import { approvalFromMax, bpsToRate, builderGateOf, NO_BUILDER, rateToBps, requireFeeBps } from "./builder-fee.js";
+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. */
+function asterTif(raw) {
+    const t = raw.toUpperCase();
+    if (t === "GTC" || t === "IOC" || t === "GTX")
+        return t;
+    if (t === "ALO")
+        return "GTX";
+    if (t === "FOK") {
+        throw unsupported("Aster", "fok", "perp symbols offer timeInForce GTC/IOC/GTX only (exchangeInfo has no FOK)", "Use --tif IOC, GTC or ALO (post-only)");
+    }
+    throw new PerpError("INVALID_PARAMS", `Unsupported time-in-force "${raw}" for Aster`, {
+        exchange: "aster",
+        remediation: "Use --tif GTC, IOC or ALO (post-only)",
+    });
+}
+/** Plain non-negative decimal string of a venue quantity field, or null when absent/unreadable. */
+function plainQty(v) {
+    const s = typeof v === "number" && Number.isFinite(v) ? String(v) : v;
+    if (typeof s !== "string" || !/^\d+(\.\d+)?$/.test(s))
+        return null;
+    return subDecimal(s, "0");
+}
+/**
+ * Definite IOC outcome of a raw Aster order response (perp and spot share the
+ * Binance-compatible shape) — contract in ./ioc-outcome.ts. Final only for a terminal
+ * status (FILLED / EXPIRED / CANCELED) with a reported executedQty, on an IOC (or
+ * MARKET) order; anything else → null (caller measures).
+ */
+export function asterIocOutcome(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const r = raw;
+    const status = typeof r.status === "string" ? r.status.toUpperCase() : "";
+    if (status !== "FILLED" && status !== "EXPIRED" && status !== "CANCELED")
+        return null;
+    const tif = typeof r.timeInForce === "string" ? r.timeInForce.toUpperCase() : null;
+    const type = typeof r.type === "string" ? r.type.toUpperCase() : null;
+    if (tif !== null && tif !== "IOC" && type !== "MARKET")
+        return null;
+    const filledSize = plainQty(r.executedQty);
+    return filledSize === null ? null : { filledSize, final: true };
+}
+/**
+ * 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].
+ * A documented code that is not listed here is a plain ORDER_REJECTED.
+ */
+const ASTER_ORDER_REJECTIONS = {
+    [-1003]: ["ORDER_REJECTED", "TOO_MANY_REQUESTS", "The order was not placed. Wait, then place it again at a lower request rate"],
+    [-1015]: ["ORDER_REJECTED", "TOO_MANY_ORDERS", "The order was not placed. Wait, then place it again at a lower order rate"],
+    [-1121]: ["SYMBOL_NOT_FOUND", "BAD_SYMBOL", "Check the symbol: perp market list -e aster"],
+    [-2010]: ["ORDER_REJECTED", "NEW_ORDER_REJECTED", null],
+    [-2018]: ["INSUFFICIENT_BALANCE", "BALANCE_NOT_SUFFICIENT", "Check the balance: perp account balance -e aster"],
+    [-2019]: ["MARGIN_INSUFFICIENT", "MARGIN_NOT_SUFFICIEN", "Reduce the size, raise the leverage or add margin: perp account balance -e aster"],
+    [-2020]: ["ORDER_REJECTED", "UNABLE_TO_FILL", null],
+    [-2021]: ["ORDER_REJECTED", "ORDER_WOULD_IMMEDIATELY_TRIGGER", "Use a trigger price on the other side of the current mark / last price"],
+    [-2022]: ["ORDER_REJECTED", "REDUCE_ONLY_REJECT", "A reduce-only order needs an open position on the opposite side (and no larger than it): perp account positions -e aster"],
+    [-2024]: ["ORDER_REJECTED", "POSITION_NOT_SUFFICIENT", "Check the position size: perp account positions -e aster"],
+    [-2025]: ["ORDER_REJECTED", "MAX_OPEN_ORDER_EXCEEDED", "Cancel open orders first: perp account orders -e aster"],
+    [-2027]: ["ORDER_REJECTED", "MAX_LEVERAGE_RATIO", "Lower the leverage or the position size for this market"],
+    [-4004]: ["SIZE_TOO_SMALL", "QTY_LESS_THAN_MIN_QTY", "Increase the size: perp market info <symbol> -e aster"],
+    [-4005]: ["SIZE_TOO_LARGE", "QTY_GREATER_THAN_MAX_QTY", "Reduce the size: perp market info <symbol> -e aster"],
+    [-4014]: ["INVALID_TICK", "PRICE_NOT_INCREASED_BY_TICK_SIZE", "Use a price on the market's tick size"],
+    [-4023]: ["ORDER_REJECTED", "QTY_NOT_INCREASED_BY_STEP_SIZE", "Use a size on the market's lot step"],
+    [-4050]: ["MARGIN_INSUFFICIENT", "CROSS_BALANCE_INSUFFICIENT", "Check the balance: perp account balance -e aster"],
+    [-4051]: ["MARGIN_INSUFFICIENT", "ISOLATED_BALANCE_INSUFFICIENT", "Check the balance: perp account balance -e aster"],
+    [-4164]: ["SIZE_TOO_SMALL", "MIN_NOTIONAL", "Increase the order notional (size × price)"],
+    [-5050]: ["DEPOSIT_REQUIRED", "DEPOSIT_REQUIRED", "Deposit first: perp funds deposit aster <amount>"],
+};
+/**
+ * Codes whose docs text says the request may still have been processed — never a definite
+ * refusal: -1000 UNKNOWN "An unknown error occured while processing the request." · -1001
+ * DISCONNECTED "Internal error; unable to process your request." · -1006 UNEXPECTED_RESP
+ * "Execution status unknown." · -1007 TIMEOUT "Send status unknown; execution status unknown."
+ */
+const ASTER_UNKNOWN_OUTCOME_CODES = new Set([-1000, -1001, -1006, -1007]);
+/** The docs' error-code sections: 10xx / 11xx, 20xx, 40xx (incl. 41xx), 50xx. */
+function asterDocumentedCode(code) {
+    return Number.isInteger(code) && ((code <= -1000 && code >= -1199) || (code <= -2000 && code >= -2099)
+        || (code <= -4000 && code >= -4199) || (code <= -5000 && code >= -5099));
+}
+/**
+ * Verdict of a failed POST / PUT /fapi/v3/order that the venue ANSWERED with an HTTP 4xx and a
+ * documented error code: the order was refused — a definite, non-retryable PerpError (never the
+ * retryable EXCHANGE_ERROR, which callers must treat as an unknown write outcome). Live mainnet
+ * 2026-10-05: a reduce-only order without a position → 400 {"code":-2022,"msg":"ReduceOnly Order
+ * is rejected."}. Unchanged: HTTP 5xx, no / undocumented code, and the "status unknown" codes —
+ * those become ORDER_PENDING unless the error was already classified definite (e.g. the venue's
+ * -1000 "Signature check failed" → SIGNATURE_FAILED).
+ */
+export function asterOrderRejection(e) {
+    const d = e.structured.details;
+    const http = typeof d?.httpStatus === "number" ? d.httpStatus : null;
+    const code = typeof d?.venueCode === "number" ? d.venueCode : null;
+    if (http === null || http < 400 || http >= 500 || code === null || !asterDocumentedCode(code))
+        return e;
+    const definite = DEFINITE_ORDER_FAILURE_CODES.has(e.structured.code);
+    if (ASTER_UNKNOWN_OUTCOME_CODES.has(code))
+        return definite ? e : orderOutcomeUnknown("aster", "order", e);
+    const known = ASTER_ORDER_REJECTIONS[code];
+    if (known === undefined && definite)
+        return e;
+    const [perpCode, name, remediation] = known ?? ["ORDER_REJECTED", null, null];
+    return new PerpError(perpCode, `Aster rejected the order (${code}${name !== null ? ` ${name}` : ""}): ${e.message}`, {
+        exchange: "aster", httpStatus: http, venueCode: code,
+        ...(remediation !== null ? { remediation } : e.structured.remediation !== undefined ? { remediation: e.structured.remediation } : {}),
+    });
+}
+/**
+ * An Aster client order id as sent / queried. V3 futures "New Order" `newClientOrderId`: "A unique
+ * id among open orders. Automatically generated if not sent. Can only be string following the
+ * rule: ^[\.A-Z\:/a-z0-9_-]{1,36}$". Anything else → INVALID_PARAMS, nothing sent.
+ */
+export function requireAsterClientOrderId(id) {
+    if (!ASTER_CLIENT_ID_RE.test(id)) {
+        throw new PerpError("INVALID_PARAMS", `Aster client order id "${id}" must be 1-36 chars of A-Z a-z 0-9 . : / _ -`, {
+            exchange: "aster", remediation: "Pass a shorter id of that charset as --client-id, or use --auto-id",
+        });
+    }
+    return id;
+}
 // ── AsterAdapter ──────────────────────────────────────────────────────────────
+/** Max 1000-row pages of 7-day commission income read for symbol discovery (20 000 fills). */
+export const ASTER_INCOME_MAX_PAGES = 20;
 export class AsterAdapter {
     name = "aster";
     chain = "bnb";
@@ -40,18 +172,25 @@ export class AsterAdapter {
     _marketsCache = null;
     _marketsCacheTime = 0;
     _fundingHoursCache = new Map();
+    /** When the venue-wide funding-interval table was last loaded (0 = never). */
+    _fundingInfoLoadedAt = 0;
+    /** API symbol → price filters; null = listed but PRICE_FILTER / PERCENT_PRICE unreadable. */
+    _priceFilters = new Map();
+    _priceFiltersLoadedAt = 0;
     _accountCache = null;
     _positionsCache = null;
     _ordersCache = null;
     static CACHE_TTL = 30_000;
     static ACCOUNT_CACHE_TTL = 5_000;
-    // Nonce counter — ensures microsecond-precision uniqueness within process
-    _nonceCounter = 0;
+    /**
+     * Builder-fee gate (settings builder.aster + confirmed master approveBuilder); null = not
+     * configured. Set by createAster — the adapter never reads settings.
+     */
+    builderFee = null;
     constructor(privateKey, testnet = false) {
         this._testnet = testnet;
-        this._baseUrl = testnet
-            ? (process.env.ASTER_TESTNET_URL || "https://testnet.asterdex.com")
-            : "https://fapi.asterdex.com";
+        // SSOT: REST host from the venue definition (venues/aster.ts networks).
+        this._baseUrl = networkConfig(asterVenue, testnet ? "testnet" : "mainnet").restUrl;
         if (privateKey) {
             this._pendingPk = privateKey;
         }
@@ -59,7 +198,7 @@ export class AsterAdapter {
     // ── Lifecycle ──
     async init() {
         // Verify connectivity by fetching server time
-        await this._publicGet("/fapi/v1/time");
+        await this._publicGet("/fapi/v3/time");
         // Build LocalEvmSigner from ctor PK now that we're in an async context
         if (this._pendingPk) {
             const { LocalEvmSigner } = await import("../signer/index.js");
@@ -81,6 +220,48 @@ export class AsterAdapter {
     setNoAgent(noAgent) {
         this._useNoAgent = noAgent;
     }
+    // ── Builder fee ──
+    /** Builder decision for the next perp order (cached approval read; never throws). */
+    async builderDecision() {
+        const gate = builderGateOf(this);
+        return gate === null ? NO_BUILDER : gate.decide({ hip3: false });
+    }
+    /** `builder` + `feeRate` (decimal) order params, or none (not configured / not approved). */
+    async _builderParams() {
+        const d = await this.builderDecision();
+        return d.applied === null ? {} : { builder: d.applied.identity, feeRate: bpsToRate(requireFeeBps(d.applied)) };
+    }
+    /** Owner (`user`) address of the active signer — the account a builder approval belongs to. */
+    get userAddress() {
+        return this._resolveSigner().userAddress;
+    }
+    /**
+     * Builder approvals of this account: GET /fapi/v3/builder (asterdex/api-docs demo
+     * `getBuilders`, signed by the API wallet). The response shape is not documented, so
+     * anything but a list of rows carrying an address + maxFeeRate is "unknown" (never guessed).
+     */
+    async builderApprovalOf(target) {
+        const raw = await this.signedRequest(this._baseUrl, "GET", "/fapi/v3/builder", {});
+        const rec = raw !== null && typeof raw === "object" && !Array.isArray(raw) ? raw : null;
+        const list = Array.isArray(raw) ? raw : rec !== null && Array.isArray(rec.rows) ? rec.rows : rec !== null && Array.isArray(rec.data) ? rec.data : null;
+        if (list === null)
+            return { status: "unknown", reason: `unrecognized GET /fapi/v3/builder response ${JSON.stringify(raw).slice(0, 120)}` };
+        for (const r of list) {
+            if (r === null || typeof r !== "object")
+                return { status: "unknown", reason: "GET /fapi/v3/builder row is not an object" };
+            const row = r;
+            const addr = typeof row.builder === "string" ? row.builder : typeof row.builderAddress === "string" ? row.builderAddress : null;
+            if (addr === null)
+                return { status: "unknown", reason: "GET /fapi/v3/builder row has no builder address" };
+            if (addr.toLowerCase() !== target.identity.toLowerCase())
+                continue;
+            const max = rateToBps(row.maxFeeRate);
+            if (max === null)
+                return { status: "unknown", reason: `unreadable maxFeeRate ${JSON.stringify(row.maxFeeRate)}` };
+            return approvalFromMax(max, requireFeeBps(target));
+        }
+        return approvalFromMax(null, requireFeeBps(target));
+    }
     // ── Status accessors ──
     get isReadOnly() {
         return !this._agentSigner && !this._masterSigner && !this._pkSigner;
@@ -93,6 +274,38 @@ export class AsterAdapter {
             return null;
         }
     }
+    // ── Spot host access (design §12, 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.
+     * Hosts per the official spot V3 docs (mainnet + testnet variants).
+     */
+    get spotBaseUrl() {
+        return this._testnet ? "https://sapi.asterdex-testnet.com" : "https://sapi.asterdex.com";
+    }
+    /**
+     * Signed request against an arbitrary Aster host with the active signer.
+     * POST is single-shot; GET/DELETE use the same 429 retry loop as perp.
+     */
+    async signedRequest(host, method, path, params) {
+        const r = this._resolveSigner();
+        if (method === "POST")
+            return this._signedPostTo(host, path, params, r);
+        return this._signedRequestWithRetry(host, method, path, params, r);
+    }
+    /**
+     * Agent meta of the active signer, or null when the active signer is not an
+     * agent. Throws exactly like signed calls when no signer is usable.
+     */
+    activeAgentMeta() {
+        const r = this._resolveSigner();
+        if (r.tier !== "agent")
+            return null;
+        if (!this._agentMeta) {
+            throw new PerpError("AGENT_NOT_REGISTERED", "Aster agent signer is active but its metadata is missing", { exchange: "aster" });
+        }
+        return this._agentMeta;
+    }
     // ── Symbol helpers ──
     /** CLI symbol → Aster API symbol (ETH → ETHUSDT) */
     _toApi(symbol) {
@@ -106,32 +319,56 @@ export class AsterAdapter {
         return symbol.replace(/USDT$/, "").replace(/BUSD$/, "");
     }
     // ── Market Data ──
-    /** Get funding interval for a symbol (lazy bootstrap). */
+    /**
+     * Get funding interval for a symbol.
+     *
+     * Source of truth is `GET /fapi/v3/fundingInfo` (weight 1), which states
+     * `fundingIntervalHours` per symbol for the whole venue in a single call.
+     * This previously inferred the interval by differencing the last two
+     * `fundingRate` timestamps and bucketing to 1/4/8h — an estimate that is
+     * wrong for a newly listed symbol (fewer than two settlements), across a
+     * schedule change, or whenever a settlement is skipped/delayed, and Aster
+     * really does mix 1h, 4h and 8h symbols. Funding-interval misconfiguration is
+     * exactly what produced the v0.7.23 Aster funding bug, so it is read, not
+     * guessed.
+     */
     async getFundingHours(symbol) {
         const key = symbol.toUpperCase();
         const cached = this._fundingHoursCache.get(key);
         if (cached !== undefined)
             return cached;
-        try {
-            const apiSym = this._toApi(key);
-            const data = await this._publicGet("/fapi/v1/fundingRate", { symbol: apiSym, limit: "2" });
-            if (Array.isArray(data) && data.length >= 2) {
-                const hours = Math.abs(data[1].fundingTime - data[0].fundingTime) / 3600000;
-                const rounded = hours <= 1.5 ? 1 : hours <= 5 ? 4 : 8;
-                this._fundingHoursCache.set(key, rounded);
-                return rounded;
-            }
+        await this._loadFundingInfo();
+        return this._fundingHoursCache.get(key);
+    }
+    /** Populate the funding-interval cache for every symbol in one call. */
+    async _loadFundingInfo() {
+        if (this._fundingInfoLoadedAt && Date.now() - this._fundingInfoLoadedAt < AsterAdapter.CACHE_TTL)
+            return;
+        const rows = await this._publicGet("/fapi/v3/fundingInfo", {});
+        if (!Array.isArray(rows)) {
+            throw new PerpError("EXCHANGE_ERROR", "Aster /fapi/v3/fundingInfo did not return an array", { exchange: "aster" });
         }
-        catch { /* non-critical */ }
-        return undefined;
+        for (const row of rows) {
+            const hours = Number(row?.fundingIntervalHours);
+            if (!row?.symbol || !Number.isFinite(hours) || hours <= 0)
+                continue;
+            this._fundingHoursCache.set(this._fromApi(String(row.symbol)), hours);
+        }
+        this._fundingInfoLoadedAt = Date.now();
     }
     async getMarkets() {
         if (this._marketsCache && Date.now() - this._marketsCacheTime < AsterAdapter.CACHE_TTL) {
             return this._marketsCache;
         }
         const [info, tickers] = await Promise.all([
-            this._publicGet("/fapi/v1/exchangeInfo"),
-            this._publicGet("/fapi/v1/ticker/24hr"),
+            this._publicGet("/fapi/v3/exchangeInfo"),
+            this._publicGet("/fapi/v3/ticker/24hr"),
+            // Populate the funding-interval table (weight 1, whole venue in one call).
+            // The per-symbol read below consulted this cache but nothing ever filled
+            // it during getMarkets, so `fundingHours` came back undefined for every
+            // market — and Aster genuinely mixes 1h / 4h / 8h symbols, which funding
+            // math depends on.
+            this._loadFundingInfo(),
         ]);
         const tickerMap = new Map();
         for (const t of tickers ?? []) {
@@ -139,10 +376,11 @@ export class AsterAdapter {
         }
         let premiumMap = new Map();
         try {
-            const premiums = await this._publicGet("/fapi/v1/premiumIndex");
+            const premiums = await this._publicGet("/fapi/v3/premiumIndex");
             premiumMap = new Map(premiums.map(p => [String(p.symbol), p]));
         }
         catch { /* non-critical */ }
+        this._ingestPriceFilters(info?.symbols ?? []);
         const tradingSymbols = (info?.symbols ?? [])
             .filter((s) => String(s.contractType) === "PERPETUAL" && String(s.status) === "TRADING");
         const result = tradingSymbols.map((s) => {
@@ -156,29 +394,136 @@ export class AsterAdapter {
             return {
                 symbol: this._fromApi(sym),
                 markPrice: String(premium?.markPrice ?? ticker?.lastPrice ?? "0"),
-                indexPrice: String(premium?.indexPrice ?? "0"),
+                indexPrice: premium?.indexPrice != null ? String(premium.indexPrice) : null,
                 fundingRate: premium?.lastFundingRate != null ? String(premium.lastFundingRate) : null,
-                volume24h: String(ticker?.quoteVolume ?? ticker?.volume ?? "0"),
-                openInterest: "0",
+                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) : undefined,
-                stepSize: lotFilter?.stepSize != null ? String(lotFilter.stepSize) : undefined,
-                fundingHours,
+                sizeDecimals: s.quantityPrecision != null ? Number(s.quantityPrecision) : null,
+                stepSize: lotFilter?.stepSize != null ? String(lotFilter.stepSize) : null,
+                fundingHours: fundingHours ?? null,
+                marginTiers: null,
             };
         });
         this._marketsCache = result;
         this._marketsCacheTime = Date.now();
         return result;
     }
+    /** Parse PRICE_FILTER + PERCENT_PRICE for every exchangeInfo symbol into the cache. */
+    _ingestPriceFilters(symbols) {
+        this._priceFilters.clear();
+        for (const s of symbols) {
+            const filters = (Array.isArray(s.filters) ? s.filters : []);
+            const pf = filters.find(f => f.filterType === "PRICE_FILTER");
+            const pp = filters.find(f => f.filterType === "PERCENT_PRICE");
+            let entry = null;
+            const tick = pf?.tickSize, minP = pf?.minPrice, maxP = pf?.maxPrice;
+            if (typeof tick === "string" && Number(tick) > 0 && typeof minP === "string" && typeof maxP === "string") {
+                if (!pp) {
+                    entry = { tickSize: tick, minPrice: minP, maxPrice: maxP, percent: null };
+                }
+                else {
+                    const up = Number(pp.multiplierUp), down = Number(pp.multiplierDown);
+                    if (up > 0 && down > 0 && Number.isFinite(up) && Number.isFinite(down)) {
+                        entry = { tickSize: tick, minPrice: minP, maxPrice: maxP, percent: { up, down } };
+                    }
+                }
+            }
+            this._priceFilters.set(String(s.symbol), entry);
+        }
+        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);
+        }
+        if (!this._priceFilters.has(apiSymbol)) {
+            throw new PerpError("SYMBOL_NOT_FOUND", `Aster market ${apiSymbol} not found in exchangeInfo`, { exchange: "aster" });
+        }
+        const f = this._priceFilters.get(apiSymbol);
+        if (!f) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster ${apiSymbol}: PRICE_FILTER or PERCENT_PRICE missing/unreadable in exchangeInfo`, { exchange: "aster" });
+        }
+        return f;
+    }
+    /**
+     * Declared protection-price reference (§13.10 #5): 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);
+        let mark;
+        try {
+            const res = await this._publicGet("/fapi/v3/premiumIndex", { symbol: apiSymbol });
+            mark = res?.markPrice;
+        }
+        catch (e) {
+            throw new PerpError("PRICE_STALE", `Aster ${apiSymbol} mark price unavailable: ${e instanceof Error ? e.message : String(e)}`, { exchange: "aster" });
+        }
+        const str = typeof mark === "number" ? String(mark) : mark;
+        if (typeof str !== "string" || !(Number(str) > 0) || !Number.isFinite(Number(str))) {
+            throw new PerpError("PRICE_STALE", `Aster ${apiSymbol} premiumIndex returned no usable markPrice (${String(mark)})`, { exchange: "aster" });
+        }
+        return str;
+    }
+    /**
+     * Reject (never clamp) a price outside PRICE_FILTER min/max or the side's PERCENT_PRICE
+     * bound around `mark` — checked before anything is sent.
+     */
+    _checkPriceBand(apiSymbol, f, price, side, mark) {
+        const p = Number(price);
+        if (Number(f.minPrice) > 0 && p < Number(f.minPrice)) {
+            throw new PerpError("INVALID_PARAMS", `Aster ${apiSymbol}: price ${price} below PRICE_FILTER minPrice ${f.minPrice}`, { exchange: "aster" });
+        }
+        if (Number(f.maxPrice) > 0 && p > Number(f.maxPrice)) {
+            throw new PerpError("INVALID_PARAMS", `Aster ${apiSymbol}: price ${price} above PRICE_FILTER maxPrice ${f.maxPrice}`, { exchange: "aster" });
+        }
+        if (f.percent === null)
+            return;
+        const m = Number(mark);
+        const bound = side === "buy" ? m * f.percent.up : m * f.percent.down;
+        if (side === "buy" ? p > bound : p < bound) {
+            const bandBps = Math.round(Math.abs((side === "buy" ? f.percent.up : f.percent.down) - 1) * 10_000);
+            throw new PerpError("INVALID_PARAMS", `Aster ${apiSymbol}: ${side} protection price ${price} is outside PERCENT_PRICE (${side === "buy" ? "≤" : "≥"} mark ${mark} × ${side === "buy" ? f.percent.up : f.percent.down})`, {
+                exchange: "aster",
+                remediation: `Use --slippage-bps below ${bandBps} for ${this._fromApi(apiSymbol)} (PERCENT_PRICE band)`,
+            });
+        }
+    }
+    /**
+     * Protection price an IOC market order on `symbol` would be sent with now:
+     * mark ± slippage.bps, aligned toward crossing on PRICE_FILTER.tickSize, validated
+     * against PRICE_FILTER / PERCENT_PRICE. appliedBps = the bound after tick alignment.
+     */
+    async computeProtectionPrice(symbol, side, slippage) {
+        const apiSymbol = this._toApi(symbol);
+        const f = await this._symbolPriceFilters(apiSymbol);
+        const ref = await this.referencePrice(symbol);
+        const protectionPrice = alignProtectionPrice(slippagePrice(ref, side, slippage.bps), f.tickSize, side);
+        this._checkPriceBand(apiSymbol, f, protectionPrice, side, ref);
+        const appliedBps = Math.abs(Number(protectionPrice) - Number(ref)) / Number(ref) * 10_000;
+        return { referencePrice: ref, protectionPrice, appliedBps };
+    }
+    /** Definite IOC outcome of a raw order response (see asterIocOutcome). */
+    iocOutcomeOf(raw) {
+        return asterIocOutcome(raw);
+    }
     async getOrderbook(symbol) {
-        const res = await this._publicGet("/fapi/v1/depth", { symbol: this._toApi(symbol), limit: "50" });
+        const res = await this._publicGet("/fapi/v3/depth", { symbol: this._toApi(symbol), limit: "50" });
         return {
             bids: res?.bids ?? [],
             asks: res?.asks ?? [],
         };
     }
     async getRecentTrades(symbol, limit = 20) {
-        const trades = await this._publicGet("/fapi/v1/trades", {
+        const trades = await this._publicGet("/fapi/v3/trades", {
             symbol: this._toApi(symbol),
             limit: String(limit),
         });
@@ -192,18 +537,18 @@ export class AsterAdapter {
         }));
     }
     async getFundingHistory(symbol, limit = 10) {
-        const data = await this._publicGet("/fapi/v1/fundingRate", {
+        const data = await this._publicGet("/fapi/v3/fundingRate", {
             symbol: this._toApi(symbol),
             limit: String(limit),
         });
         return (data ?? []).map((d) => ({
             time: Number(d.fundingTime ?? 0),
-            rate: String(d.fundingRate ?? "0"),
+            rate: venueRateField(d.fundingRate, "fundingRate fundingRate", "aster"),
             price: d.markPrice ? String(d.markPrice) : null,
         }));
     }
     async getKlines(symbol, interval, startTime, endTime) {
-        const data = await this._publicGet("/fapi/v1/klines", {
+        const data = await this._publicGet("/fapi/v3/klines", {
             symbol: this._toApi(symbol),
             interval,
             startTime: String(startTime),
@@ -222,66 +567,138 @@ export class AsterAdapter {
     }
     // ── Account ──
     async getBalance() {
-        if (this._accountCache && Date.now() - this._accountCache.time < AsterAdapter.ACCOUNT_CACHE_TTL) {
+        if (this._accountCache && this._accountCache.epoch === accountCacheEpoch() && Date.now() - this._accountCache.time < AsterAdapter.ACCOUNT_CACHE_TTL) {
             return this._accountCache.data;
         }
         const r = this._resolveSigner();
-        // v3: /fapi/v2/account is HMAC-only; v3 EIP-712 uses /fapi/v3/accountWithJoinMargin.
+        // v3 EIP-712 account endpoint. (The legacy /fapi/v2/account was HMAC-only and
+        // is no longer documented in the Aster V3 spec.)
         const account = await this._signedGetEip712("/fapi/v3/accountWithJoinMargin", {}, r);
-        const totalWallet = Number(account.totalWalletBalance ?? 0);
-        const unrealizedPnl = Number(account.totalUnrealizedProfit ?? 0);
-        const available = Number(account.availableBalance ?? 0);
-        const marginUsed = Number(account.totalInitialMargin ?? 0);
+        const totalWallet = parseFiniteVenueNumber(account.totalWalletBalance, "totalWalletBalance", "aster");
+        const unrealizedPnl = parseFiniteVenueNumber(account.totalUnrealizedProfit, "totalUnrealizedProfit", "aster");
+        const available = parseFiniteVenueNumber(account.availableBalance, "availableBalance", "aster");
+        const marginUsed = parseFiniteVenueNumber(account.totalInitialMargin, "totalInitialMargin", "aster");
         const result = {
             equity: String(totalWallet + unrealizedPnl),
             available: String(available),
             marginUsed: String(marginUsed),
             unrealizedPnl: String(unrealizedPnl),
         };
-        this._accountCache = { data: result, time: Date.now() };
+        this._accountCache = { data: result, time: Date.now(), epoch: accountCacheEpoch() };
         return result;
     }
+    /**
+     * How much of ONE asset the perp account can transfer out: that asset's row of
+     * GET /fapi/v3/accountWithJoinMargin `assets[]` — `maxWithdrawAmount` ("maximum amount for
+     * transfer out", Aster futures API v3 "Account Information v3"). The account-level
+     * `availableBalance` (getBalance) is margin across ALL collateral assets in multi-asset mode
+     * and is not an amount of any one asset. Read uncached. A missing row / field is an error,
+     * never 0.
+     */
+    async getPerpAssetTransferable(asset) {
+        const r = this._resolveSigner();
+        const account = await this._signedGetEip712("/fapi/v3/accountWithJoinMargin", {}, r);
+        if (!Array.isArray(account.assets)) {
+            throw new PerpError("EXCHANGE_ERROR", "aster /fapi/v3/accountWithJoinMargin: response has no assets list", { exchange: "aster" });
+        }
+        const row = account.assets.find(a => a.asset === asset);
+        if (row === undefined || row.maxWithdrawAmount === undefined || row.maxWithdrawAmount === null) {
+            throw new PerpError("EXCHANGE_ERROR", `aster /fapi/v3/accountWithJoinMargin: no ${asset} maxWithdrawAmount in the assets list`, { exchange: "aster" });
+        }
+        return parseFiniteVenueNumber(row.maxWithdrawAmount, `assets[${asset}].maxWithdrawAmount`, "aster");
+    }
     async getPositions() {
-        if (this._positionsCache && Date.now() - this._positionsCache.time < AsterAdapter.ACCOUNT_CACHE_TTL) {
+        if (this._positionsCache && this._positionsCache.epoch === accountCacheEpoch() && Date.now() - this._positionsCache.time < AsterAdapter.ACCOUNT_CACHE_TTL) {
             return this._positionsCache.data;
         }
         const r = this._resolveSigner();
-        // v3: /fapi/v2/positionRisk has no v3 equivalent. Positions live inside
-        // /fapi/v3/accountWithJoinMargin under `positions`. Mark price + liquidation
-        // price are NOT included there — fetch from the public premiumIndex.
+        // Positions are enumerated from /fapi/v3/accountWithJoinMargin (`positions`
+        // array); that payload omits both mark and liquidation price. The signed
+        // Position Information v3 endpoint (GET /fapi/v3/positionRisk) supplies both
+        // per open symbol, so it replaces the older public premiumIndex mark-price probe.
         const account = await this._signedGetEip712("/fapi/v3/accountWithJoinMargin", {}, r);
         const positions = account.positions ?? [];
-        const open = positions.filter((p) => Number(p.positionAmt ?? 0) !== 0);
-        // Fetch mark prices for the open symbols (best-effort; non-fatal on failure)
-        const markMap = new Map();
+        const open = positions.filter((p) => parseFiniteVenueNumber(p.positionAmt, "position.positionAmt", "aster") !== 0);
+        // Hedge mode returns TWO rows per symbol (LONG and SHORT). This adapter
+        // keys everything by symbol alone — the riskMap below, and the mapped
+        // result — so the two legs collide and one silently inherits the other's
+        // mark/liquidation price. Orders are safe (the venue rejects them with
+        // -4061 because we never send positionSide), but positions and liquidation
+        // distance would be quietly wrong, so fail honestly instead.
+        const bySymbol = new Map();
+        for (const p of open) {
+            const k = String(p.symbol ?? "");
+            bySymbol.set(k, (bySymbol.get(k) ?? 0) + 1);
+        }
+        const dupes = [...bySymbol.entries()].filter(([, n]) => n > 1).map(([s]) => s);
+        if (dupes.length > 0) {
+            throw new PerpError("NOT_IMPLEMENTED", `Aster hedge mode is not supported: ${dupes.join(", ")} has both LONG and SHORT positions, which this adapter cannot represent (positions are keyed by symbol).`, {
+                exchange: "aster",
+                remediation: "Switch the account to One-way Mode (POST /fapi/v3/positionSide/dual with dualSidePosition=false) or close one side, then retry.",
+            });
+        }
+        // Enrich open positions with mark + liquidation price from /fapi/v3/positionRisk
+        // (best-effort; a transient failure leaves them "0" rather than failing the whole
+        // positions read). Response fields per Aster V3 spec: markPrice, liquidationPrice.
+        const riskMap = new Map();
         if (open.length > 0) {
             try {
-                const premiums = await this._publicGet("/fapi/v1/premiumIndex");
-                for (const p of premiums ?? []) {
-                    markMap.set(String(p.symbol), String(p.markPrice ?? "0"));
+                const risk = await this._signedGetEip712("/fapi/v3/positionRisk", {}, r);
+                for (const pr of risk ?? []) {
+                    // Aster V3 spec (userPositionRisk notes, same field): "`liquidationPrice` is reported as `0`
+                    // whenever the underlying value would be negative" — i.e. the position has no liquidation
+                    // price (e.g. a small cross long the margin fully covers). 0 is not a price → null.
+                    const liq = pr.liquidationPrice != null ? String(pr.liquidationPrice) : null;
+                    riskMap.set(String(pr.symbol), {
+                        mark: String(pr.markPrice ?? "0"),
+                        liq: liq !== null && liq.trim() !== "" && Number(liq) === 0 ? null : liq,
+                    });
                 }
             }
-            catch { /* non-critical */ }
+            catch (e) {
+                // NOT non-critical. A "0" liquidation price is not a neutral default:
+                // risk.ts filters positions on `liquidationPrice !== null && > 0` and
+                // event-stream.ts gates the liquidation warning on `liq > 0`, so a
+                // silent "0" drops EVERY Aster position out of liquidation monitoring —
+                // and the likeliest cause of this call failing (rate limiting)
+                // correlates with the volatility that makes those alerts matter most.
+                // Surface it, and report the values as unknown rather than as a price.
+                process.stderr.write(`[aster] positionRisk fetch failed — mark and liquidation prices are UNAVAILABLE this cycle, ` +
+                    `so liquidation warnings are suppressed for Aster positions: ` +
+                    `${e instanceof Error ? e.message : String(e)}\n`);
+            }
         }
         const result = open.map((p) => {
-            const amt = Number(p.positionAmt ?? 0);
+            const amt = parseFiniteVenueNumber(p.positionAmt, "position.positionAmt", "aster");
             const apiSym = String(p.symbol ?? "");
+            const risk = riskMap.get(apiSym);
             return {
                 symbol: this._fromApi(apiSym),
                 side: amt > 0 ? "long" : "short",
                 size: String(Math.abs(amt)),
                 entryPrice: String(p.entryPrice ?? "0"),
-                markPrice: markMap.get(apiSym) ?? "0",
-                liquidationPrice: "0", // v3 accountWithJoinMargin does not expose this
+                // Unknown mark is "N/A" (markPrice is a required string); unknown liq is null. Never "0" — a zero reads downstream as a real price.
+                // Matches the Pacifica adapter's convention for an absent liq price.
+                markPrice: risk?.mark ?? "N/A",
+                liquidationPrice: risk ? risk.liq : null,
                 unrealizedPnl: String(p.unrealizedProfit ?? "0"),
-                leverage: Number(p.leverage ?? 1),
+                leverage: parseFiniteVenueNumber(p.leverage, "position.leverage", "aster", { defaultValue: 1 }),
             };
         });
-        this._positionsCache = { data: result, time: Date.now() };
+        this._positionsCache = { data: result, time: Date.now(), epoch: accountCacheEpoch() };
         return result;
     }
+    /**
+     * Drop the in-process open-orders snapshot (after any order write, or before a verifying
+     * re-list). An order write also changes positions and balances, so those snapshots go too.
+     */
+    invalidateOpenOrdersCache() {
+        this._ordersCache = null;
+        this._positionsCache = null;
+        this._accountCache = null;
+    }
     async getOpenOrders() {
-        if (this._ordersCache && Date.now() - this._ordersCache.time < AsterAdapter.ACCOUNT_CACHE_TTL) {
+        if (this._ordersCache && this._ordersCache.epoch === accountCacheEpoch() && Date.now() - this._ordersCache.time < AsterAdapter.ACCOUNT_CACHE_TTL) {
             return this._ordersCache.data;
         }
         const r = this._resolveSigner();
@@ -295,68 +712,142 @@ export class AsterAdapter {
             filled: String(o.executedQty ?? "0"),
             status: String(o.status ?? ""),
             type: String(o.type ?? ""),
+            triggerPrice: Number(o.stopPrice) > 0 ? String(o.stopPrice) : null,
         }));
-        this._ordersCache = { data: result, time: Date.now() };
+        this._ordersCache = { data: result, time: Date.now(), epoch: accountCacheEpoch() };
         return result;
     }
-    async getOrderHistory(limit = 30) {
+    /**
+     * Symbols with account activity: open positions, open orders, and every symbol with a
+     * COMMISSION income row in the last 7 days (the venue's default window). Aster's userTrades /
+     * allOrders both require `symbol`, so this is the per-symbol fan-out set. Income is read in
+     * pages of 1000 (the endpoint max; startTime / endTime are inclusive) walking back from now;
+     * more than ASTER_INCOME_MAX_PAGES pages → EXCHANGE_ERROR, never a partial set. Orders on a
+     * symbol that never filled, is not open and has no position cannot be found (allOrders needs it).
+     */
+    async _tradedApiSymbols(r) {
         const positions = await this.getPositions();
         const apiSymbols = new Set(positions.map(p => this._toApi(p.symbol)));
-        if (apiSymbols.size === 0) {
-            for (const s of ["BTCUSDT", "ETHUSDT", "SOLUSDT", "BNBUSDT", "XRPUSDT"]) {
-                apiSymbols.add(s);
+        const open = await this._signedGetEip712("/fapi/v3/openOrders", {}, r);
+        if (!Array.isArray(open)) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster open orders is not a list (${JSON.stringify(open).slice(0, 120)})`, { exchange: "aster" });
+        }
+        for (const o of open) {
+            if (typeof o.symbol === "string" && o.symbol !== "")
+                apiSymbols.add(o.symbol);
+        }
+        const startTime = Date.now() - 7 * 86_400_000;
+        let endTime = Date.now();
+        for (let page = 0;; page++) {
+            if (page >= ASTER_INCOME_MAX_PAGES) {
+                throw new PerpError("EXCHANGE_ERROR", `Aster commission history exceeds ${ASTER_INCOME_MAX_PAGES * 1000} rows in 7 days — the symbol list would be incomplete`, {
+                    exchange: "aster", remediation: "Check fills per symbol in the Aster web app",
+                });
+            }
+            const income = await this._signedGetEip712("/fapi/v3/income", {
+                incomeType: "COMMISSION", startTime: String(startTime), endTime: String(endTime), limit: "1000",
+            }, r);
+            if (!Array.isArray(income)) {
+                throw new PerpError("EXCHANGE_ERROR", `Aster income history is not a list (${JSON.stringify(income).slice(0, 120)})`, { exchange: "aster" });
+            }
+            let oldest = Infinity;
+            for (const row of income) {
+                if (typeof row.symbol === "string" && row.symbol !== "")
+                    apiSymbols.add(row.symbol);
+                const t = Number(row.time);
+                if (!Number.isFinite(t)) {
+                    throw new PerpError("EXCHANGE_ERROR", `Aster income row without a numeric time: ${JSON.stringify(row).slice(0, 160)}`, { exchange: "aster" });
+                }
+                oldest = Math.min(oldest, t);
             }
+            if (income.length < 1000 || oldest <= startTime)
+                break;
+            endTime = oldest - 1;
         }
+        return apiSymbols;
+    }
+    /**
+     * Recent orders across the symbols with account activity (see _tradedApiSymbols), newest first.
+     * A failed read throws (never an empty list); a row without a readable field → EXCHANGE_ERROR.
+     */
+    async getOrderHistory(limit = 30) {
         const r = this._resolveSigner();
-        const allOrders = [];
+        const apiSymbols = await this._tradedApiSymbols(r);
+        const field = (o, k) => {
+            const v = o[k];
+            if ((typeof v === "string" && v !== "") || typeof v === "number")
+                return String(v);
+            throw new PerpError("EXCHANGE_ERROR", `Aster allOrders row without a readable ${k}: ${JSON.stringify(o).slice(0, 160)}`, { exchange: "aster" });
+        };
+        const rows = [];
         for (const sym of apiSymbols) {
-            try {
-                const orders = await this._signedGetEip712("/fapi/v3/allOrders", {
-                    symbol: sym,
-                    limit: String(limit),
-                }, r);
-                for (const o of orders ?? []) {
-                    allOrders.push({
-                        orderId: String(o.orderId ?? ""),
-                        symbol: this._fromApi(String(o.symbol ?? "")),
-                        side: String(o.side).toLowerCase(),
-                        price: String(o.price ?? "0"),
-                        size: String(o.origQty ?? "0"),
-                        filled: String(o.executedQty ?? "0"),
-                        status: String(o.status ?? ""),
-                        type: String(o.type ?? ""),
-                    });
+            const orders = await this._signedGetEip712("/fapi/v3/allOrders", { symbol: sym, limit: String(limit) }, r);
+            if (!Array.isArray(orders)) {
+                throw new PerpError("EXCHANGE_ERROR", `Aster allOrders for ${sym} is not a list (${JSON.stringify(orders).slice(0, 120)})`, { exchange: "aster" });
+            }
+            for (const o of orders) {
+                const side = field(o, "side").toLowerCase();
+                if (side !== "buy" && side !== "sell") {
+                    throw new PerpError("EXCHANGE_ERROR", `Aster allOrders row with unknown side "${side}"`, { exchange: "aster" });
                 }
+                const time = Number(field(o, "time"));
+                if (!Number.isFinite(time))
+                    throw new PerpError("EXCHANGE_ERROR", `Aster allOrders row with a non-numeric time`, { exchange: "aster" });
+                rows.push({
+                    time,
+                    order: {
+                        orderId: field(o, "orderId"),
+                        symbol: this._fromApi(field(o, "symbol")),
+                        side,
+                        price: field(o, "price"),
+                        size: field(o, "origQty"),
+                        filled: field(o, "executedQty"),
+                        status: field(o, "status"),
+                        type: field(o, "type"),
+                        triggerPrice: Number(o.stopPrice) > 0 ? String(o.stopPrice) : null,
+                    },
+                });
             }
-            catch { /* skip */ }
         }
-        return allOrders.slice(0, limit);
+        return rows.sort((x, y) => y.time - x.time).slice(0, limit).map(x => x.order);
     }
+    /**
+     * Recent fills. `GET /fapi/v3/userTrades` requires a symbol (asterdex/api-docs V3), so the
+     * symbols come from the open positions plus every symbol with a COMMISSION income row in the
+     * venue's default window (`GET /fapi/v3/income`: "the recent 7-day data" when no time is sent).
+     * A failed read throws (never an empty list); a row without a readable field → EXCHANGE_ERROR.
+     */
     async getTradeHistory(limit = 30) {
-        const positions = await this.getPositions();
-        const apiSymbols = new Set(positions.map(p => this._toApi(p.symbol)));
-        if (apiSymbols.size === 0)
-            apiSymbols.add("BTCUSDT");
         const r = this._resolveSigner();
+        const apiSymbols = await this._tradedApiSymbols(r);
+        const field = (t, k) => {
+            const v = t[k];
+            if ((typeof v === "string" && v !== "") || typeof v === "number")
+                return String(v);
+            throw new PerpError("EXCHANGE_ERROR", `Aster userTrades row without a readable ${k}: ${JSON.stringify(t).slice(0, 160)}`, { exchange: "aster" });
+        };
         const allTrades = [];
         for (const sym of apiSymbols) {
-            try {
-                const trades = await this._signedGetEip712("/fapi/v3/userTrades", {
-                    symbol: sym,
-                    limit: String(limit),
-                }, r);
-                for (const t of trades ?? []) {
-                    allTrades.push({
-                        time: Number(t.time ?? 0),
-                        symbol: this._fromApi(String(t.symbol ?? "")),
-                        side: t.buyer ? "buy" : "sell",
-                        price: String(t.price ?? "0"),
-                        size: String(t.qty ?? "0"),
-                        fee: String(t.commission ?? "0"),
-                    });
+            const trades = await this._signedGetEip712("/fapi/v3/userTrades", { symbol: sym, limit: String(limit) }, r);
+            if (!Array.isArray(trades)) {
+                throw new PerpError("EXCHANGE_ERROR", `Aster userTrades for ${sym} is not a list (${JSON.stringify(trades).slice(0, 120)})`, { exchange: "aster" });
+            }
+            for (const t of trades) {
+                if (typeof t.buyer !== "boolean") {
+                    throw new PerpError("EXCHANGE_ERROR", `Aster userTrades row without a boolean buyer: ${JSON.stringify(t).slice(0, 160)}`, { exchange: "aster" });
                 }
+                const time = Number(field(t, "time"));
+                if (!Number.isFinite(time))
+                    throw new PerpError("EXCHANGE_ERROR", `Aster userTrades row with a non-numeric time`, { exchange: "aster" });
+                allTrades.push({
+                    time,
+                    symbol: this._fromApi(field(t, "symbol")),
+                    side: t.buyer ? "buy" : "sell",
+                    price: field(t, "price"),
+                    size: field(t, "qty"),
+                    fee: field(t, "commission"),
+                });
             }
-            catch { /* skip */ }
         }
         return allTrades.sort((a, b) => b.time - a.time).slice(0, limit);
     }
@@ -372,24 +863,71 @@ export class AsterAdapter {
             payment: String(f.income ?? "0"),
         }));
     }
+    /**
+     * Per-market leverage / margin mode: every row of GET /fapi/v3/positionRisk ("Position
+     * Information v3", one row per symbol, position or not — docs example:
+     * `"marginType": "isolated"`, `"leverage": "10"`, `"positionAmt": "0.000"`; rows[].marginType
+     * "Margin type: `isolated` or `cross`"). An unreadable row throws — never a default.
+     */
+    async getMarketSettings() {
+        const rows = await this._signedGetEip712("/fapi/v3/positionRisk", {}, this._resolveSigner());
+        if (!Array.isArray(rows)) {
+            throw new PerpError("EXCHANGE_ERROR", "Aster /fapi/v3/positionRisk did not return an array — per-market settings unknown", { exchange: "aster" });
+        }
+        const seen = new Map();
+        for (const row of rows) {
+            const leverage = Number(row.leverage);
+            const type = typeof row.marginType === "string" ? row.marginType.toLowerCase() : "";
+            // "crossed" is the request enum spelling (CROSSED); the documented read value is "cross".
+            const marginMode = type === "isolated" ? "isolated" : type === "cross" || type === "crossed" ? "cross" : null;
+            if (typeof row.symbol !== "string" || !(leverage > 0) || marginMode === null) {
+                throw new PerpError("EXCHANGE_ERROR", `Aster positionRisk row without a readable symbol / leverage / marginType: ${JSON.stringify(row).slice(0, 160)}`, { exchange: "aster" });
+            }
+            // Hedge mode lists a symbol once per position side; leverage / margin type are per symbol.
+            seen.set(row.symbol, { symbol: this._fromApi(row.symbol), leverage, marginMode });
+        }
+        return [...seen.values()];
+    }
     // ── Trading ──
     async marketOrder(symbol, side, size, opts) {
+        // Design §13.2 / §13.10 #6: 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 clientOrderId = opts.clientOrderId === undefined ? null : requireAsterClientOrderId(opts.clientOrderId);
+        let protectionPrice;
+        let protection;
+        try {
+            protection = await this.computeProtectionPrice(symbol, side, opts.slippage);
+            ({ protectionPrice } = protection);
+        }
+        catch (e) {
+            throw orderNotSent("aster", `market ${side} ${size} ${symbol}`, e);
+        }
         const params = {
             symbol: apiSymbol,
             side: side.toUpperCase(),
-            type: "MARKET",
+            type: "LIMIT",
+            timeInForce: "IOC",
+            price: protectionPrice,
             quantity: size,
+            newOrderRespType: "RESULT",
         };
-        if (opts?.reduceOnly)
+        if (clientOrderId !== null)
+            params.newClientOrderId = clientOrderId;
+        if (opts.reduceOnly)
             params.reduceOnly = "true";
+        Object.assign(params, await this._builderParams());
         const result = await this._signedPostEip712("/fapi/v3/order", params, r);
         const ro = result;
         const executedQty = Number(ro.executedQty ?? 0);
         const orderId = String(ro.orderId ?? "");
+        // The protection actually sent rides along with the venue response (`protection`), read by
+        // the TradingV2 wrapper's execution record (the venue does not echo the reference).
         if (executedQty > 0 && ro.status === "FILLED")
-            return result;
+            return { ...ro, protection };
         if (ro.status === "NEW" && orderId) {
             for (let i = 0; i < 3; i++) {
                 await new Promise(res => setTimeout(res, 1000));
@@ -400,9 +938,10 @@ export class AsterAdapter {
                     }, r);
                     const filledQty = Number(check.executedQty ?? 0);
                     if (filledQty > 0)
-                        return check;
-                    if (check.status === "CANCELED" || check.status === "EXPIRED" || check.status === "REJECTED") {
-                        throw new Error(`Market ${side} ${symbol}: order ${check.status} (orderId: ${orderId})`);
+                        return { ...check, protection };
+                    if ((check.status === "CANCELED" || check.status === "EXPIRED" || check.status === "REJECTED") && check.executedQty !== undefined && check.executedQty !== null) {
+                        // Terminal status with a REPORTED 0 executed: nothing traded (definite).
+                        throw new PerpError("ORDER_REJECTED", `Market ${side} ${symbol}: order ${check.status} (orderId: ${orderId})`, { exchange: "aster", orderId });
                     }
                 }
                 catch (e) {
@@ -410,45 +949,165 @@ export class AsterAdapter {
                         throw e;
                 }
             }
+            let cancelledQty = null;
+            let cancelRow = null;
             try {
-                await this._signedDeleteEip712("/fapi/v3/order", { symbol: apiSymbol, orderId }, r);
+                const c = await this._signedDeleteEip712("/fapi/v3/order", { symbol: apiSymbol, orderId }, r);
+                const q = Number(c?.executedQty);
+                cancelledQty = Number.isFinite(q) ? q : null;
+                cancelRow = c;
             }
-            catch { /* best effort cancel */ }
-            throw new Error(`Market ${side} ${symbol}: order not filled after 3s, cancelled (orderId: ${orderId})`);
+            catch { /* cancel failed: the order may still be live — outcome stays unknown below */ }
+            // The cancel answered with executedQty > 0: the order PARTIALLY filled before the cancel —
+            // report that fill (the cancel row carries executedQty / status CANCELED; asterIocOutcome
+            // reads it), never "not filled".
+            if (cancelledQty !== null && cancelledQty > 0 && cancelRow !== null) {
+                console.error(`[aster] market ${side} ${symbol}: order ${orderId} partially filled (${String(cancelRow.executedQty)}) before the remainder was cancelled`);
+                return { ...cancelRow, protection };
+            }
+            const msg = `Market ${side} ${symbol}: order not filled after 3s, cancelled (orderId: ${orderId})`;
+            // Definite only when the cancel was confirmed with 0 executed; otherwise it may have filled / be live.
+            if (cancelledQty === 0)
+                throw new PerpError("ORDER_REJECTED", msg, { exchange: "aster", orderId });
+            throw new Error(msg);
         }
         if (executedQty === 0) {
-            throw new Error(`Market ${side} ${symbol}: order accepted but 0 filled (status: ${ro.status}, orderId: ${orderId})`);
+            const msg = `Market ${side} ${symbol}: order accepted but 0 filled (status: ${ro.status}, orderId: ${orderId})`;
+            // A terminal status (EXPIRED IOC / CANCELED / REJECTED) with 0 executed is a definite no-fill.
+            if ((ro.status === "EXPIRED" || ro.status === "CANCELED" || ro.status === "REJECTED") && ro.executedQty !== undefined && ro.executedQty !== null) {
+                throw new PerpError("ORDER_REJECTED", msg, { exchange: "aster", orderId });
+            }
+            throw new Error(msg);
         }
-        return result;
+        return { ...ro, protection };
     }
     async limitOrder(symbol, side, price, size, opts) {
         const r = this._resolveSigner();
-        const params = {
-            symbol: this._toApi(symbol),
-            side: side.toUpperCase(),
-            type: "LIMIT",
-            price,
-            quantity: size,
-            timeInForce: opts?.tif?.toUpperCase() || "GTC",
-        };
-        if (opts?.reduceOnly)
-            params.reduceOnly = "true";
+        const apiSymbol = this._toApi(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.
+            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);
+            params = {
+                symbol: apiSymbol,
+                side: side.toUpperCase(),
+                type: "LIMIT",
+                price: px,
+                quantity: size,
+                timeInForce: tif,
+            };
+            // IOC / GTX: ask for the final status + executedQty in the response (iocOutcomeOf). Docs (futures
+            // V3, New Order): with `newOrderRespType` RESULT, "`LIMIT` order with special `timeInForce`: the
+            // final status result of the order(FILLED or EXPIRED) will be returned directly". The default ACK
+            // answers NEW for a post-only order that then expires because it would cross (live mainnet 2026-10-05).
+            if (tif === "IOC" || tif === "GTX")
+                params.newOrderRespType = "RESULT";
+            if (clientOrderId !== null)
+                params.newClientOrderId = clientOrderId;
+            if (opts?.reduceOnly)
+                params.reduceOnly = "true";
+            Object.assign(params, await this._builderParams());
+        }
+        catch (e) {
+            throw orderNotSent("aster", `limit ${side} ${size} ${symbol} @ ${price}`, e);
+        }
         return this._signedPostEip712("/fapi/v3/order", params, r);
     }
+    /**
+     * 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 = 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) {
-        // Aster has no atomic edit — cancel + replace
-        const openOrders = await this.getOpenOrders();
-        const existing = openOrders.find(o => o.orderId === orderId);
-        const side = existing?.side ?? "buy";
-        await this.cancelOrder(symbol, orderId);
-        return this.limitOrder(symbol, side, price, size);
+        const r = this._resolveSigner();
+        const apiSymbol = this._toApi(symbol);
+        const rawOrders = await this._signedGetEip712("/fapi/v3/openOrders", {}, r);
+        const existing = (rawOrders ?? []).find(o => String(o.orderId ?? "") === orderId);
+        if (!existing) {
+            // Rule #2: never guess the order — fail honestly if it is no longer open.
+            throw new PerpError("ORDER_NOT_FOUND", `Aster order ${orderId} is not among the open orders; refusing to edit (cannot guess its side).`, { exchange: "aster" });
+        }
+        const type = String(existing.type ?? "").toUpperCase();
+        if (type !== "LIMIT") {
+            // Venue modify supports LIMIT only; a STOP/TP must be cancelled and re-placed explicitly.
+            throw new PerpError("INVALID_PARAMS", `Aster editOrder only supports plain LIMIT orders (order ${orderId} is ${type || "unknown"}). Cancel and re-place it explicitly.`, { exchange: "aster" });
+        }
+        const executed = plainQty(existing.executedQty);
+        if (executed === null) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster order ${orderId}: openOrders row has no readable executedQty (${String(existing.executedQty)})`, { exchange: "aster" });
+        }
+        requirePositive(size, "size");
+        const px = requireOnTick(price, (await this._symbolPriceFilters(apiSymbol)).tickSize);
+        return this._perpWrite("PUT /fapi/v3/order", () => this._signedPostTo(this._baseUrl, "/fapi/v3/order", {
+            symbol: apiSymbol,
+            orderId,
+            side: String(existing.side ?? "").toUpperCase(),
+            quantity: subDecimal(size, `-${executed}`),
+            price: px,
+        }, r, "PUT"), true);
     }
     async cancelOrder(symbol, orderId) {
+        return this._cancelOne(symbol, { orderId }, orderId);
+    }
+    /**
+     * Cancel one order by client order id — V3 futures "Cancel Order" (DELETE /fapi/v3/order):
+     * "Either `orderId` or `origClientOrderId` must be sent."
+     */
+    async cancelOrderByClientId(symbol, clientOrderId) {
+        const id = requireAsterClientOrderId(clientOrderId);
+        return this._cancelOne(symbol, { origClientOrderId: id }, `c:${id}`);
+    }
+    /**
+     * One order's row — V3 futures "Query Order" (GET /fapi/v3/order, symbol + orderId or
+     * origClientOrderId). Docs: CANCELED / EXPIRED orders with no fill older than 7 days "will not
+     * be found". -2013 NO_SUCH_ORDER → ORDER_NOT_FOUND; any other failure throws as is.
+     */
+    async queryOrderRow(symbol, ref) {
+        const key = ref.kind === "orderId" ? { orderId: ref.value } : { origClientOrderId: requireAsterClientOrderId(ref.value) };
+        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());
+        }
+        catch (e) {
+            if (e instanceof PerpError && e.structured.details?.venueCode === -2013) {
+                throw new PerpError("ORDER_NOT_FOUND", `Aster has no order ${label} on ${symbol.toUpperCase()} (-2013 NO_SUCH_ORDER)`, {
+                    exchange: "aster", venueCode: -2013, remediation: "List orders: perp account orders -e aster / perp history orders -e aster",
+                });
+            }
+            throw e;
+        }
+        if (row === null || typeof row !== "object" || Array.isArray(row)) {
+            throw new PerpError("EXCHANGE_ERROR", `Aster GET /fapi/v3/order ${label}: unexpected response shape`, { exchange: "aster" });
+        }
+        return row;
+    }
+    async _cancelOne(symbol, key, orderId) {
         const r = this._resolveSigner();
-        return this._signedDeleteEip712("/fapi/v3/order", {
-            symbol: this._toApi(symbol),
-            orderId,
-        }, r);
+        try {
+            return await this._signedDeleteEip712("/fapi/v3/order", {
+                symbol: this._toApi(symbol),
+                ...key,
+            }, r);
+        }
+        catch (e) {
+            // Docs (futures V3 error codes): "-2011 CANCEL_REJECTED" — the venue refused the cancel; the
+            // order is not open (already filled / cancelled, or unknown). Live mainnet 2026-10-05, cancel of
+            // a filled order: 400 {"code":-2011,"msg":"Unknown order sent."}. Definite: nothing was cancelled.
+            if (e instanceof PerpError && e.structured.details?.venueCode === -2011) {
+                throw new PerpError("ORDER_REJECTED", `Aster refused to cancel order ${orderId} on ${symbol} (-2011 CANCEL_REJECTED): it is not an open order`, {
+                    exchange: "aster", orderId, venueCode: -2011,
+                    remediation: `Check its final state: perp trade status ${orderId} --symbol ${symbol} -e aster`,
+                });
+            }
+            throw e;
+        }
     }
     async cancelAllOrders(symbol) {
         const r = this._resolveSigner();
@@ -473,39 +1132,229 @@ export class AsterAdapter {
                     marginType: marginMode === "cross" ? "CROSSED" : "ISOLATED",
                 }, r);
             }
-            catch { /* may fail if already set */ }
+            catch (e) {
+                // Rule #2: only -4046 NO_NEED_TO_CHANGE_MARGIN_TYPE ("No need to change
+                // margin type") is a benign no-op. Every other rejection — notably a
+                // refusal because the symbol has an open position or open orders —
+                // means the account is STILL on the previous margin mode. Swallowing
+                // those left the user believing they had switched to isolated while the
+                // position stayed cross, and the leverage change below then applied to
+                // a cross position.
+                const msg = e instanceof Error ? e.message : String(e);
+                const benign = msg.includes("-4046") || /no need to change margin type/i.test(msg);
+                if (benign) { /* already on the requested margin type */ }
+                else if (e instanceof PerpError && typeof e.structured.details?.venueCode === "number" && [-4047, -4048, -4050, -4051].includes(e.structured.details.venueCode)) {
+                    // The venue refused the margin-type change; the leverage request below is NOT sent, so
+                    // nothing changed. Docs ("Error Codes"): -4047 "Margin type cannot be changed if there
+                    // exists open orders." · -4048 "Margin type cannot be changed if there exists position."
+                    // · -4050 "Cross balance insufficient." · -4051 "Isolated balance insufficient." The
+                    // "Change Margin Type" section states no balance or Multi-Assets-mode condition, so
+                    // for -4050 / -4051 the venue's own text is reported as is (live mainnet 2026-10-05:
+                    // ISOLATED on a flat SOL → 400 -4050) with the two account facts to check.
+                    const code = e.structured.details.venueCode;
+                    const why = {
+                        [-4047]: ["THERE_EXISTS_OPEN_ORDERS", `Cancel the ${symbol} open orders first: perp trade cancel ${symbol} -e aster`],
+                        [-4048]: ["THERE_EXISTS_QUANTITY", `Close the ${symbol} position first: perp trade close ${symbol} -e aster`],
+                        [-4050]: ["CROSS_BALANCE_INSUFFICIENT", `The venue docs do not state the condition. Check the account's margin-asset balance (perp account balance -e aster) and whether it is in Multi-Assets mode (GET /fapi/v3/multiAssetsMargin; set in the Aster app) — or keep cross: perp trade leverage ${symbol} ${leverage} -e aster`],
+                        [-4051]: ["ISOLATED_BALANCE_INSUFFICIENT", `The venue docs do not state the condition. Check the account's margin-asset balance: perp account balance -e aster`],
+                    };
+                    throw new PerpError("ACTION_REJECTED", `Aster refused to switch ${symbol} to ${marginMode} margin (${code} ${why[code][0]}: ${msg}) — margin mode and leverage are unchanged`, {
+                        exchange: "aster", venueCode: code, httpStatus: e.structured.details.httpStatus, remediation: why[code][1],
+                    });
+                }
+                else
+                    throw e;
+            }
         }
         return this._signedPostEip712("/fapi/v3/leverage", {
             symbol: this._toApi(symbol),
             leverage: String(leverage),
         }, r);
     }
+    /**
+     * Trigger order. Type follows the venue trigger rules (V3 docs, "Condition orders"):
+     * STOP*: BUY fires at price >= stopPrice, SELL at <= ; TAKE_PROFIT*: the reverse. So the
+     * type is chosen from the trigger vs the current trigger-source price and the order side
+     * (the side closing a long is SELL): BUY above / SELL below → STOP, otherwise
+     * TAKE_PROFIT. (Always STOP_MARKET made every TP fail with -2021.)
+     * Trigger source: workingType MARK_PRICE compared with the premiumIndex mark (default),
+     * or CONTRACT_PRICE with the last price when triggerType is "last".
+     * size "0" = whole position → closePosition=true (STOP_MARKET / TAKE_PROFIT_MARKET only;
+     * the venue forbids quantity and reduceOnly with it).
+     * `opts.kind` (TP/SL legs): sl → STOP(_MARKET), tp → TAKE_PROFIT(_MARKET) as given, with
+     * no price read; a trigger already crossed is rejected by the venue (-2021).
+     */
     async stopOrder(symbol, side, size, triggerPrice, opts) {
         const r = this._resolveSigner();
-        const params = {
-            symbol: this._toApi(symbol),
-            side: side.toUpperCase(),
-            quantity: size,
-            stopPrice: triggerPrice,
-            type: opts?.limitPrice ? "STOP" : "STOP_MARKET",
-        };
-        if (opts?.limitPrice) {
-            params.price = opts.limitPrice;
-            params.timeInForce = "GTC";
+        const apiSymbol = this._toApi(symbol);
+        const what = `stop ${side} ${size} ${symbol} @ ${triggerPrice}`;
+        let params;
+        try {
+            if (opts?.triggerType === "mid") {
+                throw unsupported("Aster", "triggerType", "stop orders trigger on MARK_PRICE or CONTRACT_PRICE only", "Use triggerType mark or last");
+            }
+            const f = await this._symbolPriceFilters(apiSymbol);
+            const stopPrice = requireOnTick(triggerPrice, f.tickSize);
+            const useLast = opts?.triggerType === "last";
+            let isStop;
+            if (opts?.kind !== undefined) {
+                isStop = opts.kind === "sl";
+            }
+            else {
+                const ref = useLast ? await this._lastPrice(apiSymbol) : await this.referencePrice(symbol);
+                const t = Number(stopPrice), p = Number(ref);
+                if (t === p) {
+                    throw new PerpError("INVALID_PARAMS", `Aster ${apiSymbol}: trigger ${stopPrice} equals the current ${useLast ? "last" : "mark"} price — it would trigger immediately`, { exchange: "aster" });
+                }
+                isStop = side === "buy" ? t > p : t < p;
+            }
+            const closeAll = Number(size) === 0;
+            if (!closeAll)
+                requirePositive(size, "size");
+            params = {
+                symbol: apiSymbol,
+                side: side.toUpperCase(),
+                stopPrice,
+                workingType: useLast ? "CONTRACT_PRICE" : "MARK_PRICE",
+            };
+            if (opts?.limitPrice) {
+                if (closeAll) {
+                    throw new PerpError("INVALID_PARAMS", "Aster closePosition (whole-position trigger) only exists for market triggers — pass an explicit size with a limit price", { exchange: "aster" });
+                }
+                params.type = isStop ? "STOP" : "TAKE_PROFIT";
+                params.price = requireOnTick(opts.limitPrice, f.tickSize);
+                params.timeInForce = "GTC";
+            }
+            else {
+                params.type = isStop ? "STOP_MARKET" : "TAKE_PROFIT_MARKET";
+            }
+            if (closeAll) {
+                params.closePosition = "true";
+            }
+            else {
+                params.quantity = size;
+                if (opts?.reduceOnly)
+                    params.reduceOnly = "true";
+            }
+            Object.assign(params, await this._builderParams());
+        }
+        catch (e) {
+            throw orderNotSent("aster", what, e);
         }
-        if (opts?.reduceOnly)
-            params.reduceOnly = "true";
         return this._signedPostEip712("/fapi/v3/order", params, r);
     }
-    // ── Withdraw (master-only: never delegates to agent or PK) ──
-    async withdraw(amount, _destination, _opts) {
-        if (!this._masterSigner) {
-            throw new PerpError("NO_SIGNER_AVAILABLE", "Aster withdrawal requires OWS master wallet (--ows). Agent and PK signers cannot authorize withdrawals.", {
-                remediation: "Use: perp -e aster --ows <walletName> funds withdraw",
+    /** Last traded price (GET /fapi/v3/ticker/price) — the CONTRACT_PRICE trigger source. */
+    async _lastPrice(apiSymbol) {
+        let price;
+        try {
+            price = (await this._publicGet("/fapi/v3/ticker/price", { symbol: apiSymbol }))?.price;
+        }
+        catch (e) {
+            throw new PerpError("PRICE_STALE", `Aster ${apiSymbol} last price unavailable: ${e instanceof Error ? e.message : String(e)}`, { exchange: "aster" });
+        }
+        const str = typeof price === "number" ? String(price) : price;
+        if (typeof str !== "string" || !(Number(str) > 0) || !Number.isFinite(Number(str))) {
+            throw new PerpError("PRICE_STALE", `Aster ${apiSymbol} ticker/price returned no usable price (${String(price)})`, { exchange: "aster" });
+        }
+        return str;
+    }
+    // ── Withdraw (mainnet only): POST /fapi/v3/aster/user-withdraw ──
+    /** Asset withdrawn by `withdraw`: `requested` (must be in capabilities.withdrawAssets), else withdrawAssets[0]. */
+    _withdrawAsset(requested) {
+        const assets = asterVenue.capabilities?.withdrawAssets;
+        if (assets === null || assets === undefined || assets.length === 0)
+            throw new Error("aster venue definition declares no withdrawAssets");
+        if (requested === undefined)
+            return assets[0];
+        const a = requested.toUpperCase();
+        if (!assets.includes(a)) {
+            throw new PerpError("INVALID_PARAMS", `Aster withdraws ${assets.join(" / ")} only (got "${requested}")`, { exchange: "aster", remediation: `Use --asset ${assets.join(" or --asset ")}` });
+        }
+        return a;
+    }
+    /**
+     * Withdrawable perp balance + fee for the withdraw asset on `chain`
+     * (POST /fapi/v3/aster/user-withdraw-info, signed by the API wallet). Read-only.
+     */
+    async withdrawLimits(chain, asset) {
+        requireAsterFundsNetwork(this._testnet ? "testnet" : "mainnet", "withdraw");
+        const raw = await this.signedRequest(this._baseUrl, "POST", "/fapi/v3/aster/user-withdraw-info", {});
+        return parseAsterWithdrawLimits(raw, this._withdrawAsset(asset), ASTER_FUNDS_CHAINS[chain].chainId);
+    }
+    /** Deposit / withdraw history (POST /fapi/v3/aster/deposit-withdraw-history, signed by the API wallet). Read-only. */
+    async depositWithdrawHistory() {
+        return this.signedRequest(this._baseUrl, "POST", "/fapi/v3/aster/deposit-withdraw-history", {});
+    }
+    /**
+     * Withdraw the venue collateral (USDT) from the perp account to the account owner's OWN address
+     * on BNB Chain (default) or Arbitrum. Two signatures (asterdex/api-docs
+     * demo/aster-deposit-withdrawal.md, API-demo futures-v3-demo/58_withdrawEvm.js):
+     *   1. `userSignature` — the master wallet's EIP-712 "Aster" Action over receiver / chain / token /
+     *      amount / fee / nonce, recovered locally and compared to the account owner before sending;
+     *   2. the V3 envelope signed by the API wallet, which must have canWithdraw (and an IP whitelist).
+     * The fee and the maximum come from user-withdraw-info; the identical amount / fee strings go
+     * into the signature and the request. Once the request left, an unreadable result is
+     * ORDER_PENDING (never resubmit).
+     */
+    async withdraw(amount, destination, opts) {
+        requireAsterFundsNetwork(this._testnet ? "testnet" : "mainnet", "withdraw");
+        if (opts?.assetId !== undefined || opts?.routeType !== undefined) {
+            throw new PerpError("INVALID_PARAMS", "Aster withdraw takes no assetId/routeType (use --asset USDT|USDC and --chain bsc|arbitrum)");
+        }
+        const chain = opts?.chain === undefined ? "bsc" : opts.chain;
+        const pins = ASTER_FUNDS_CHAINS[chain];
+        const asset = this._withdrawAsset(opts?.asset);
+        const r = this._resolveSigner();
+        if (this._agentMeta === undefined || this._agentMeta.permissions.canWithdraw !== true) {
+            throw new PerpError("POLICY_DENIED", "The active Aster API wallet was approved without the withdraw permission", {
+                exchange: "aster",
+                remediation: "Re-approve it with withdraw + a mandatory IP whitelist: perp wallet agent approve aster --can-withdraw --ip-whitelist <your public ip> --rotate — or withdraw in the Aster web app",
             });
         }
-        // Aster withdrawal via spot/wallet API (not futures API) — not yet implemented.
-        throw new Error("Aster withdrawal requires the spot API (not available in futures mode). Use the Aster web UI to withdraw.");
+        const user = r.userAddress;
+        if (!/^0x[0-9a-fA-F]{40}$/.test(destination) || destination.toLowerCase() !== user.toLowerCase()) {
+            throw new PerpError("INVALID_PARAMS", `Aster only withdraws to the account's own address ${user} (got "${destination}")`, {
+                exchange: "aster", remediation: `Omit --to (defaults to ${user})`,
+            });
+        }
+        const master = this._masterSigner ?? this._pkSigner;
+        if (master === undefined) {
+            throw new PerpError("NO_SIGNER_AVAILABLE", "Aster withdraw needs the master wallet to sign the withdraw message; only the API wallet is loaded", {
+                exchange: "aster", remediation: "Run with the master wallet: perp --ows <wallet> funds withdraw aster <amount> — or withdraw in the Aster web app",
+            });
+        }
+        if (master.getAddress().toLowerCase() !== user.toLowerCase()) {
+            throw new PerpError("INVALID_PARAMS", `The loaded master wallet ${master.getAddress()} is not the Aster account owner ${user}`, {
+                exchange: "aster", remediation: "Select the wallet that owns the Aster account (--ows <wallet>)",
+            });
+        }
+        const limits = await this.withdrawLimits(chain, asset);
+        assertAsterWithdrawAmount(amount, limits, asset);
+        const userNonce = (BigInt(Date.now()) * 1000n).toString();
+        const typed = buildWithdrawTypedData({
+            chainId: pins.chainId, chainName: pins.withdrawChainName, receiver: user, asset, amount, fee: limits.fee, userNonce,
+        });
+        let userSignature;
+        try {
+            userSignature = await master.signTypedData(typed.domain, typed.types, typed.message);
+        }
+        catch (e) {
+            throw orderNotSent("aster", "withdraw", e);
+        }
+        assertAsterWithdrawSignature(typed, userSignature, user);
+        const path = "/fapi/v3/aster/user-withdraw";
+        const raw = await this._perpWrite(`POST ${path}`, () => this._signedPostTo(this._baseUrl, path, {
+            chainId: String(pins.chainId), asset, amount, fee: limits.fee, receiver: user, userNonce, userSignature,
+        }, r));
+        const res = (raw !== null && typeof raw === "object" ? raw : {});
+        if (typeof res.withdrawId !== "string" && typeof res.withdrawId !== "number") {
+            // 2xx without the documented withdrawId: the request was accepted on the wire — outcome unknown.
+            throw orderOutcomeUnknown("aster", `POST ${path}`, new Error(`unrecognized response ${JSON.stringify(raw).slice(0, 160)}`), "Do NOT resubmit — the withdrawal may have been accepted. Check the Aster app → Assets → History");
+        }
+        return {
+            withdrawId: String(res.withdrawId), hash: typeof res.hash === "string" ? res.hash : "",
+            chain, chainId: pins.chainId, asset, amount, fee: limits.fee, receiver: user,
+        };
     }
     // ── Private: signer resolution ────────────────────────────────────────────
     /**
@@ -517,23 +1366,20 @@ export class AsterAdapter {
     _resolveSigner() {
         // Tier 1: agent (when registered, not expired, --no-agent NOT set)
         if (!this._useNoAgent && this._agentSigner && this._agentMeta) {
+            // An expired agent record is an explicit error — never a fall-through to the master tier
+            // (as on Hyperliquid / Pacifica; the master cannot sign Aster requests anyway).
             if (isExpired(this._agentMeta)) {
-                // Skip Tier 1 only if Tier 2/3 available; otherwise throw AGENT_EXPIRED
-                if (!this._masterSigner && !this._pkSigner) {
-                    throw new PerpError("AGENT_EXPIRED", "Agent wallet has expired", {
-                        remediation: "perp wallet agent approve aster --rotate",
-                    });
-                }
-                // fall through to Tier 2/3
-            }
-            else {
-                return {
-                    tier: "agent",
-                    signer: this._agentSigner,
-                    signerAddress: this._agentMeta.agentEvmAddress,
-                    userAddress: this._agentMeta.userEvmAddress,
-                };
+                throw new PerpError("AGENT_EXPIRED", `Aster agent wallet ${this._agentMeta.agentEvmAddress} expired at ${this._agentMeta.expiresAt}`, {
+                    exchange: "aster",
+                    remediation: "perp wallet agent approve aster --rotate",
+                });
             }
+            return {
+                tier: "agent",
+                signer: this._agentSigner,
+                signerAddress: this._agentMeta.agentEvmAddress,
+                userAddress: this._agentMeta.userEvmAddress,
+            };
         }
         // Tier 2/3: master self-signing is not supported by the venue. Per Aster
         // V3 spec the `signer` field MUST be a registered API_WALLET (agent);
@@ -555,9 +1401,9 @@ export class AsterAdapter {
         });
     }
     // ── Private: nonce ────────────────────────────────────────────────────────
-    _nextNonce() {
-        const ms = Date.now() * 1000 + (++this._nonceCounter % 1000);
-        return String(ms);
+    /** Monotonic µs nonce per signer, persisted across processes (aster-nonce.ts). */
+    _nextNonce(signer) {
+        return nextAsterNonce(signer);
     }
     // ── Private: EIP-712 signed HTTP helpers ─────────────────────────────────
     /**
@@ -586,7 +1432,7 @@ export class AsterAdapter {
         // Insertion order (matches Python reference: nonce, user, signer last).
         const fullParams = {
             ...params,
-            nonce: this._nextNonce(),
+            nonce: this._nextNonce(resolved.signerAddress),
             user: resolved.userAddress,
             signer: resolved.signerAddress,
         };
@@ -603,14 +1449,54 @@ export class AsterAdapter {
      * Sign and POST to a path using EIP-712 Domain B.
      */
     async _signedPostEip712(path, params, resolved) {
-        const qs = await this._buildSignedQueryString(params, resolved);
-        const url = `${this._baseUrl}${path}?${qs}`;
-        const res = await fetch(url, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded" },
-            body: "",
-        });
-        return this._handleAsterResponse(res, "POST", path);
+        return this._perpWrite(`POST ${path}`, () => this._signedPostTo(this._baseUrl, path, params, resolved), path === "/fapi/v3/order");
+    }
+    /**
+     * A perp account WRITE (order / modify / cancel / margin type / leverage). Once the request is
+     * on the wire, a transport failure, an HTTP 5xx or an unreadable 2xx body leaves the outcome
+     * unknown → ORDER_PENDING (never the retryable EXCHANGE_ERROR / EXCHANGE_UNREACHABLE); no
+     * connection at all → not sent. Venue refusals (4xx, error envelopes) pass through unchanged.
+     */
+    async _perpWrite(what, send, orderPlacement = false) {
+        try {
+            return await send();
+        }
+        catch (e) {
+            if (e instanceof PerpError) {
+                const d = e.structured.details;
+                const http = typeof d?.httpStatus === "number" ? d.httpStatus : null;
+                if (d?.responseUnreadable === true || (http !== null && http >= 500))
+                    throw orderOutcomeUnknown("aster", what, e);
+                // Order placement / modify: a documented 4xx business code is a definite refusal (asterOrderRejection).
+                throw orderPlacement ? asterOrderRejection(e) : e;
+            }
+            throw isTransportFailure(e) ? sendFailure("aster", what, e) : e;
+        }
+    }
+    /** Sign and POST (or PUT) to `host + path` (perp `fapi` or spot `sapi` — same Domain B signing). */
+    async _signedPostTo(host, path, params, resolved, method = "POST") {
+        let qs;
+        try {
+            qs = await this._buildSignedQueryString(params, resolved);
+        }
+        catch (e) {
+            // Signing failed before the request was sent: definitely not placed (never ORDER_PENDING).
+            throw orderNotSent("aster", `${method} ${path}`, e);
+        }
+        const url = `${host}${path}?${qs}`;
+        // Any order write (place / modify) makes the open-orders snapshot stale — before and after the request.
+        this.invalidateOpenOrdersCache();
+        try {
+            const res = await fetch(url, {
+                method,
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: "",
+            });
+            return await this._handleAsterResponse(res, method, path);
+        }
+        finally {
+            this.invalidateOpenOrdersCache();
+        }
     }
     /**
      * Sign and GET from a path using EIP-712 Domain B.
@@ -625,27 +1511,40 @@ export class AsterAdapter {
      * one would itself be rejected. Non-429 venue errors throw immediately.
      */
     async _signedGetEip712(path, params, resolved) {
-        return this._signedRequestWithRetry("GET", path, params, resolved);
+        return this._signedRequestWithRetry(this._baseUrl, "GET", path, params, resolved);
     }
     /**
      * Sign and DELETE from a path using EIP-712 Domain B.
      * Same retry behavior as _signedGetEip712.
      */
     async _signedDeleteEip712(path, params, resolved) {
-        return this._signedRequestWithRetry("DELETE", path, params, resolved);
+        return this._perpWrite(`DELETE ${path}`, () => this._signedRequestWithRetry(this._baseUrl, "DELETE", path, params, resolved));
     }
     /** Shared GET/DELETE retry loop with fresh-nonce per attempt.
      *
      *  Total 4 attempts: initial + 3 retries with backoffs 2s, 4s, 8s.
      *  Codex v0.12.12 final QA #3: previously MAX_ATTEMPTS = 3 truncated the
      *  documented curve so the 8s backoff was never reachable in practice. */
-    async _signedRequestWithRetry(method, path, params, resolved) {
+    async _signedRequestWithRetry(host, method, path, params, resolved) {
+        if (method === "DELETE") {
+            // A cancel makes the open-orders snapshot stale — before and after the request.
+            this.invalidateOpenOrdersCache();
+            try {
+                return await this._signedRequestLoop(host, method, path, params, resolved);
+            }
+            finally {
+                this.invalidateOpenOrdersCache();
+            }
+        }
+        return this._signedRequestLoop(host, method, path, params, resolved);
+    }
+    async _signedRequestLoop(host, method, path, params, resolved) {
         const MAX_ATTEMPTS = 4;
         let lastErr;
         for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
             // Rebuild signed query string with fresh nonce on each attempt.
             const qs = await this._buildSignedQueryString(params, resolved);
-            const url = `${this._baseUrl}${path}?${qs}`;
+            const url = `${host}${path}?${qs}`;
             const res = await fetch(url, method === "DELETE" ? { method: "DELETE" } : undefined);
             // 429 → backoff + retry. All other paths (including non-429 venue
             // errors wrapped in HTTP 200 with code≠0) throw immediately via
@@ -685,32 +1584,77 @@ export class AsterAdapter {
      */
     async _handleAsterResponse(res, method, path) {
         if (res.status === 429) {
-            const retryAfter = parseInt(res.headers.get("Retry-After") || "5", 10);
-            await new Promise(r => setTimeout(r, Math.min(retryAfter * 1000, 30000)));
-            throw new Error(`${method} ${path} rate limited`);
+            // HTTP 429 = refused before processing: the request was definitely NOT executed
+            // (details.sent === false → isDefiniteOrderFailure), and RATE_LIMITED stays retryable —
+            // after Retry-After (carried as retryAfterMs when the venue sends it).
+            const retryAfterSec = Number(res.headers.get("Retry-After"));
+            throw new PerpError("RATE_LIMITED", `Aster ${method} ${path} rate limited (HTTP 429); nothing was executed`, {
+                exchange: "aster", httpStatus: 429, sent: false,
+                ...(Number.isFinite(retryAfterSec) && retryAfterSec > 0 ? { retryAfterMs: retryAfterSec * 1000 } : {}),
+                remediation: "Nothing was sent to the book. Wait and retry, or reduce request frequency",
+            });
         }
         if (!res.ok) {
-            const text = await res.text().catch(() => "");
+            const text = await res.text();
+            // Aster returns non-2xx with a JSON {code, msg} body for venue errors (e.g. HTTP 401
+            // -2015 / -1002). Carry the venue code so callers (spot permission mapping) can key on it.
+            let venueCode = null;
+            try {
+                const j = JSON.parse(text);
+                if (typeof j.code === "string" || typeof j.code === "number")
+                    venueCode = j.code;
+            }
+            catch {
+                // Non-JSON body (HTML error page): no venue code — the HTTP status + text are reported.
+            }
             const s = classifyError(new Error(`${method} ${path} failed (${res.status}): ${text.slice(0, 200)}`), "aster");
-            throw new PerpError(s.code, s.message, { exchange: s.exchange });
+            if (res.status >= 500) {
+                // A 5xx can arrive after the venue accepted the request: never a definite code
+                // (substring classification could otherwise yield e.g. SIGNATURE_FAILED / INSUFFICIENT_BALANCE).
+                throw new PerpError("EXCHANGE_ERROR", s.message, {
+                    exchange: "aster",
+                    httpStatus: res.status,
+                    ...(venueCode !== null ? { venueCode } : {}),
+                });
+            }
+            throw new PerpError(s.code, s.message, {
+                exchange: s.exchange,
+                httpStatus: res.status,
+                ...(venueCode !== null ? { venueCode } : {}),
+                ...(s.remediation ? { remediation: s.remediation } : {}),
+            });
         }
-        // Parse JSON, then validate venue error envelope. Aster success returns
-        // either an object whose `code` is "000000"/200 (or absent) or an array
-        // (e.g., GET /fapi/v3/openOrders, GET /fapi/v3/userTrades).
+        // Parse JSON, then validate venue error envelope. Aster success returns an array
+        // (e.g., GET /fapi/v3/openOrders, GET /fapi/v3/userTrades) or an object whose `code`
+        // is absent or one of the documented success values (asterdex/api-docs):
+        //   200      — futures/spot V3, e.g. Change Margin Type: {"code": 200, "msg": "success"}
+        //   "200"    — futures V3 "Cancel All Open Orders (TRADE)":
+        //              {"code": "200", "msg": "The operation of cancel all open order is done."}
+        //   "000000" — bapi envelope (bapi/aster-bapi-en.md): {"code": "000000", "message": null, ...}
+        // Anything else (incl. 0, which the docs only list as a WebSocket error code) is an error.
         const text = await res.text();
         let parsed;
         try {
             parsed = JSON.parse(text);
         }
         catch {
-            throw new PerpError("EXCHANGE_ERROR", `${method} ${path}: malformed JSON: ${text.slice(0, 200)}`, { exchange: "aster" });
+            // httpStatus + responseUnreadable: the request WAS accepted (2xx) — order callers map this to "pending".
+            throw new PerpError("EXCHANGE_ERROR", `${method} ${path}: malformed JSON: ${text.slice(0, 200)}`, { exchange: "aster", httpStatus: res.status, responseUnreadable: true });
         }
         if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
             const json = parsed;
-            if (json.code !== undefined && json.code !== "000000" && json.code !== 200 && json.code !== 0) {
+            if (json.code !== undefined && json.code !== 200 && json.code !== "200" && json.code !== "000000") {
                 const rawMsg = typeof json.msg === "string" ? json.msg : JSON.stringify(json);
-                const s = classifyError(new Error(rawMsg), "aster");
-                throw new PerpError(s.code, s.message, { exchange: s.exchange });
+                // Classify on the venue code AND the message: Aster's terse messages
+                // ("This function can only be used after deposit.") are the only signal
+                // for some codes, but the numeric code is the stable key — feed both so
+                // a message reword upstream does not silently drop the mapping.
+                const s = classifyError(new Error(`[${json.code}] ${rawMsg}`), "aster");
+                throw new PerpError(s.code, rawMsg, {
+                    exchange: s.exchange,
+                    venueCode: json.code,
+                    ...(s.remediation ? { remediation: s.remediation } : {}),
+                });
             }
         }
         return parsed;