perp-cli 0.11.0 → 0.12.0

package/dist/errors.d.ts

@@ -50,6 +50,62 @@ export declare const ERROR_CODES: {
         readonly status: 409;
         readonly retryable: false;
     };
+    readonly NO_SIGNER_AVAILABLE: {
+        readonly code: "NO_SIGNER_AVAILABLE";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly AGENT_NOT_REGISTERED: {
+        readonly code: "AGENT_NOT_REGISTERED";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly AGENT_EXPIRED: {
+        readonly code: "AGENT_EXPIRED";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly POLICY_DENIED: {
+        readonly code: "POLICY_DENIED";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly KEY_NOT_FOUND: {
+        readonly code: "KEY_NOT_FOUND";
+        readonly status: 404;
+        readonly retryable: false;
+    };
+    readonly WALLET_LOCKED: {
+        readonly code: "WALLET_LOCKED";
+        readonly status: 423;
+        readonly retryable: false;
+    };
+    readonly APPROVE_PARTIAL: {
+        readonly code: "APPROVE_PARTIAL";
+        readonly status: 500;
+        readonly retryable: false;
+    };
+    readonly APPROVE_FAILED: {
+        readonly code: "APPROVE_FAILED";
+        readonly status: 500;
+        readonly retryable: false;
+    };
+    readonly LOCK_HELD: {
+        readonly code: "LOCK_HELD";
+        readonly status: 423;
+        readonly retryable: true;
+        readonly retryAfterMs: 5000;
+    };
+    readonly PASSPHRASE_REQUIRED: {
+        readonly code: "PASSPHRASE_REQUIRED";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly NOT_IMPLEMENTED: {
+        readonly code: "NOT_IMPLEMENTED";
+        readonly status: 501;
+        readonly retryable: false;
+    };
     readonly EXCHANGE_UNREACHABLE: {
         readonly code: "EXCHANGE_UNREACHABLE";
         readonly status: 503;
@@ -96,7 +152,15 @@ export interface StructuredError {
     retryAfterMs?: number;
     exchange?: string;
     details?: Record<string, unknown>;
+    /** Actionable hint for automated callers (AC-19) */
+    remediation?: string;
 }
+/**
+ * Extract a human-readable message from any thrown value.
+ * Handles Error instances, plain objects with a `.message` field (string OR object),
+ * and circular-safe stringification fallback.
+ */
+export declare function extractErrorMessage(err: unknown): string;
 /**
  * Classify an error from any exchange into a structured error code.
  * Pattern-matches on error messages to detect known error types.

package/dist/errors.js

@@ -11,6 +11,18 @@ export const ERROR_CODES = {
     SIZE_TOO_LARGE: { code: "SIZE_TOO_LARGE", status: 400, retryable: false },
     RISK_VIOLATION: { code: "RISK_VIOLATION", status: 403, retryable: false },
     DUPLICATE_ORDER: { code: "DUPLICATE_ORDER", status: 409, retryable: false },
+    // Agent-wallet error codes (OWS / Phase 2a)
+    NO_SIGNER_AVAILABLE: { code: "NO_SIGNER_AVAILABLE", status: 401, retryable: false },
+    AGENT_NOT_REGISTERED: { code: "AGENT_NOT_REGISTERED", status: 401, retryable: false },
+    AGENT_EXPIRED: { code: "AGENT_EXPIRED", status: 401, retryable: false },
+    POLICY_DENIED: { code: "POLICY_DENIED", status: 403, retryable: false },
+    KEY_NOT_FOUND: { code: "KEY_NOT_FOUND", status: 404, retryable: false },
+    WALLET_LOCKED: { code: "WALLET_LOCKED", status: 423, retryable: false },
+    APPROVE_PARTIAL: { code: "APPROVE_PARTIAL", status: 500, retryable: false },
+    APPROVE_FAILED: { code: "APPROVE_FAILED", status: 500, retryable: false },
+    LOCK_HELD: { code: "LOCK_HELD", status: 423, retryable: true, retryAfterMs: 5000 },
+    PASSPHRASE_REQUIRED: { code: "PASSPHRASE_REQUIRED", status: 401, retryable: false },
+    NOT_IMPLEMENTED: { code: "NOT_IMPLEMENTED", status: 501, retryable: false },
     // 5xx - System / transient errors
     EXCHANGE_UNREACHABLE: { code: "EXCHANGE_UNREACHABLE", status: 503, retryable: true },
     RATE_LIMITED: { code: "RATE_LIMITED", status: 429, retryable: true, retryAfterMs: 1000 },
@@ -20,12 +32,37 @@ export const ERROR_CODES = {
     TIMEOUT: { code: "TIMEOUT", status: 504, retryable: true },
     UNKNOWN: { code: "UNKNOWN", status: 500, retryable: false },
 };
+/**
+ * Extract a human-readable message from any thrown value.
+ * Handles Error instances, plain objects with a `.message` field (string OR object),
+ * and circular-safe stringification fallback.
+ */
+export function extractErrorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    if (err && typeof err === "object") {
+        const m = err.message;
+        if (typeof m === "string")
+            return m;
+        if (m !== undefined) {
+            try {
+                return JSON.stringify(m);
+            }
+            catch { /* circular */ }
+        }
+        try {
+            return JSON.stringify(err);
+        }
+        catch { /* circular */ }
+    }
+    return String(err);
+}
 /**
  * Classify an error from any exchange into a structured error code.
  * Pattern-matches on error messages to detect known error types.
  */
 export function classifyError(err, exchange) {
-    const message = err instanceof Error ? err.message : String(err);
+    const message = extractErrorMessage(err);
     const lower = message.toLowerCase();
     // Margin-specific checks first (before generic "insufficient" catch)
     if (lower.includes("margin") && (lower.includes("insufficient") || lower.includes("not enough"))) {
@@ -43,6 +80,39 @@ export function classifyError(err, exchange) {
     if (lower.includes("timeout") || lower.includes("timed out") || lower.includes("etimedout")) {
         return { ...ERROR_CODES.TIMEOUT, message, exchange };
     }
+    // OWS / agent-wallet specific matchers — MUST precede generic "sign" / "not found" blocks
+    // so "wallet is locked, cannot sign" → WALLET_LOCKED (not SIGNATURE_FAILED)
+    // and "key not found" → KEY_NOT_FOUND (not SYMBOL_NOT_FOUND / default)
+    if (lower.includes("policy denied") || (lower.includes("policy") && lower.includes("denied"))) {
+        return { ...ERROR_CODES.POLICY_DENIED, message, exchange };
+    }
+    if (lower.includes("wallet is locked") || lower.includes("wallet locked")) {
+        return { ...ERROR_CODES.WALLET_LOCKED, message, exchange };
+    }
+    if (lower.includes("key not found") || lower.includes("api key not found")) {
+        return { ...ERROR_CODES.KEY_NOT_FOUND, message, exchange };
+    }
+    if (lower.includes("no signer") || lower.includes("signer unavailable") || lower.includes("no auth")) {
+        return { ...ERROR_CODES.NO_SIGNER_AVAILABLE, message, exchange };
+    }
+    if (lower.includes("agent not registered")) {
+        return { ...ERROR_CODES.AGENT_NOT_REGISTERED, message, exchange };
+    }
+    if (lower.includes("agent expired") || lower.includes("agent has expired")) {
+        return { ...ERROR_CODES.AGENT_EXPIRED, message, exchange };
+    }
+    if (lower.includes("lock held") || lower.includes("lockfile held")) {
+        return { ...ERROR_CODES.LOCK_HELD, message, exchange };
+    }
+    if (lower.includes("passphrase required") || lower.includes("passphrase missing")) {
+        return { ...ERROR_CODES.PASSPHRASE_REQUIRED, message, exchange };
+    }
+    if (lower.includes("partial") && (lower.includes("approve") || lower.includes("approval"))) {
+        return { ...ERROR_CODES.APPROVE_PARTIAL, message, exchange };
+    }
+    if (lower.includes("approve_failed") || (lower.includes("approve failed") && lower.includes("clean"))) {
+        return { ...ERROR_CODES.APPROVE_FAILED, message, exchange };
+    }
     if (lower.includes("not found") && (lower.includes("symbol") || lower.includes("market") || lower.includes("asset"))) {
         return { ...ERROR_CODES.SYMBOL_NOT_FOUND, message, exchange };
     }
@@ -79,6 +149,16 @@ export class PerpError extends Error {
     constructor(code, message, details) {
         super(message);
         this.name = "PerpError";
-        this.structured = { ...ERROR_CODES[code], message, details };
+        // Lift `remediation` from details to top-level StructuredError field (AC-19)
+        const remediation = details?.remediation;
+        const strippedDetails = details ? { ...details } : undefined;
+        if (strippedDetails)
+            delete strippedDetails.remediation;
+        this.structured = {
+            ...ERROR_CODES[code],
+            message,
+            ...(remediation !== undefined ? { remediation } : {}),
+            ...(strippedDetails && Object.keys(strippedDetails).length > 0 ? { details: strippedDetails } : {}),
+        };
     }
 }

package/dist/event-stream.js

@@ -48,9 +48,20 @@ export async function startEventStream(adapter, opts) {
                 }
             }
             // Closed positions
+            // SSOT rule #2: emit realizedPnl explicitly so position-history can
+            // require the field. We can't reach back into the exchange to fetch the
+            // true realized P&L from a polling stream — but the last unrealized
+            // snapshot before the position disappears is the closest proxy and
+            // becomes realized at close. Surfacing it under realizedPnl makes the
+            // contract explicit.
             for (const [sym, prev] of prevPositions) {
                 if (!currentPositions.has(sym)) {
-                    emit({ type: "position_closed", exchange: adapter.name, timestamp: ts, data: { ...prev } });
+                    emit({
+                        type: "position_closed",
+                        exchange: adapter.name,
+                        timestamp: ts,
+                        data: { ...prev, realizedPnl: prev.unrealizedPnl },
+                    });
                 }
             }
             // ── Liquidation warnings ──

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

@@ -0,0 +1,156 @@
+/**
+ * Aster V3 EIP-712 typed-data builders.
+ *
+ * Pure functions — no side effects, no fs/fetch/env reads.
+ * All field ordering and serialization matches the HypurrQuant_FE mainnet
+ * production reference: AsterPerpAdapter.ts:456-700.
+ *
+ * Key conventions:
+ *   - Domain A (chainId=56)  — master-signed ops: approveAgent, delAgent, approveBuilder
+ *   - Domain B (chainId=1666) — agent-signed per-order ops
+ *   - uint256 fields serialized as decimal strings (never BigInt) to survive JSON.stringify
+ *   - EIP-712 message keys are PascalCase; HTTP query-string keys are camelCase
+ */
+/** Domain A: used for master-signed ops (ApproveAgent, DelAgent, ApproveBuilder). */
+export declare const ASTER_DOMAIN_A: {
+    readonly name: "AsterSignTransaction";
+    readonly version: "1";
+    readonly chainId: 56;
+    readonly verifyingContract: "0x0000000000000000000000000000000000000000";
+};
+/** Domain B: used for agent-signed per-request ops (order, cancel, leverage). */
+export declare const ASTER_DOMAIN_B: {
+    readonly chainId: 1666;
+    readonly name: "AsterSignTransaction";
+    readonly version: "1";
+    readonly verifyingContract: "0x0000000000000000000000000000000000000000";
+};
+/** EIP-712 types for Domain B order signing — single msg string (URL-encoded query string). */
+export declare const ORDER_TYPES: {
+    readonly Message: readonly [{
+        readonly name: "msg";
+        readonly type: "string";
+    }];
+};
+type Eip712Field = {
+    name: string;
+    type: string;
+};
+type AsterChain = "Mainnet" | "Testnet";
+export interface ApproveAgentParams {
+    user: `0x${string}`;
+    agentAddress: `0x${string}`;
+    agentName: string;
+    /** Unix milliseconds timestamp when the agent expires. Serialized as decimal string. */
+    expiredMs: number | string;
+    canPerpTrade: boolean;
+    canSpotTrade: boolean;
+    canWithdraw: boolean;
+    /**
+     * Optional IP whitelist. Include (even as "") when defined and non-null.
+     * Undefined/null = field omitted from EIP-712 struct.
+     */
+    ipWhitelist?: string;
+    /** Optional builder address. When present, Builder + MaxFeeRate are included. */
+    builder?: string;
+    /** Required when builder is set. */
+    maxFeeRate?: string;
+    /** Optional builder name. Independently gated by its own undefined-check. */
+    builderName?: string;
+    /** Microsecond-precision nonce (Date.now() * 1000 + counter). Serialized as decimal string. */
+    nonceMicros: number | string;
+    asterChain?: AsterChain;
+}
+/**
+ * Build the EIP-712 typed-data payload for `POST /fapi/v3/approveAgent`.
+ *
+ * Field order in types array and message object matches HypurrQuant_FE
+ * AsterPerpAdapter.ts:481-533 exactly:
+ *   AgentName, AgentAddress, [IpWhitelist?,] Expired, CanSpotTrade, CanPerpTrade,
+ *   CanWithdraw, [Builder?, MaxFeeRate?, BuilderName?,] AsterChain, User, Nonce
+ */
+export declare function buildApproveAgentTypedData(params: ApproveAgentParams): {
+    domain: typeof ASTER_DOMAIN_A;
+    types: {
+        ApproveAgent: Eip712Field[];
+    };
+    primaryType: "ApproveAgent";
+    message: Record<string, unknown>;
+};
+export interface DelAgentParams {
+    user: `0x${string}`;
+    agentAddress: `0x${string}`;
+    nonceMicros: number | string;
+    asterChain?: AsterChain;
+}
+/**
+ * Build the EIP-712 typed-data payload for `DELETE /fapi/v3/agent`.
+ *
+ * TODO: confirm DelAgent struct vs Aster docs at Step 0b spike.
+ * HypurrQuant_FE does not implement a revoke/delAgent method — this is a
+ * best-effort field set mirroring the ApproveAgent terminal fields (AgentAddress,
+ * AsterChain, User, Nonce) without the permission booleans.
+ */
+export declare function buildDelAgentTypedData(params: DelAgentParams): {
+    domain: typeof ASTER_DOMAIN_A;
+    types: {
+        DelAgent: Eip712Field[];
+    };
+    primaryType: "DelAgent";
+    message: Record<string, unknown>;
+};
+/**
+ * Encode order parameters as a URL-encoded query string.
+ *
+ * Deterministic key order = insertion order of `orderParams` (JS object property
+ * iteration order). Caller must pre-populate `user` and `nonce` (microseconds)
+ * in the dict; this function does NOT inject defaults.
+ *
+ * Uses `URLSearchParams` for encoding consistency with Python
+ * `urllib.parse.urlencode`.
+ */
+export declare function buildOrderQueryStringMsg(orderParams: Record<string, string | number | boolean>): string;
+/**
+ * Build the EIP-712 typed-data payload for agent-signed order requests.
+ *
+ * Domain B (chainId=1666), primaryType="Message", single `msg` field containing
+ * the URL-encoded query string produced by buildOrderQueryStringMsg.
+ */
+export declare function buildOrderTypedData(orderParams: Record<string, string | number | boolean>): {
+    domain: typeof ASTER_DOMAIN_B;
+    types: typeof ORDER_TYPES;
+    primaryType: "Message";
+    message: {
+        msg: string;
+    };
+};
+export interface ApproveBuilderParams {
+    builder: string;
+    maxFeeRate: string;
+    builderName?: string;
+    user: `0x${string}`;
+    nonceMicros: number | string;
+    asterChain?: AsterChain;
+}
+/**
+ * Build the EIP-712 typed-data payload for `POST /fapi/v3/approveBuilder`.
+ *
+ * Domain A (chainId=56), primaryType="ApproveBuilder".
+ * Default-path field order from HypurrQuant_FE AsterPerpAdapter.ts:630-651:
+ *   Builder, MaxFeeRate, AsterChain, User, Nonce
+ * `BuilderName` is a forward-compatible extension (HQ_FE omits it); included
+ * only when explicitly provided so the default path stays byte-equivalent to
+ * the production reference.
+ *
+ * Must be called BEFORE approveAgent so Aster fee attribution is set up
+ * before the first order.
+ */
+export declare function buildApproveBuilderTypedData(params: ApproveBuilderParams): {
+    domain: typeof ASTER_DOMAIN_A;
+    types: {
+        ApproveBuilder: Eip712Field[];
+    };
+    primaryType: "ApproveBuilder";
+    message: Record<string, unknown>;
+};
+export {};

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

@@ -0,0 +1,189 @@
+/**
+ * Aster V3 EIP-712 typed-data builders.
+ *
+ * Pure functions — no side effects, no fs/fetch/env reads.
+ * All field ordering and serialization matches the HypurrQuant_FE mainnet
+ * production reference: AsterPerpAdapter.ts:456-700.
+ *
+ * Key conventions:
+ *   - Domain A (chainId=56)  — master-signed ops: approveAgent, delAgent, approveBuilder
+ *   - Domain B (chainId=1666) — agent-signed per-order ops
+ *   - uint256 fields serialized as decimal strings (never BigInt) to survive JSON.stringify
+ *   - EIP-712 message keys are PascalCase; HTTP query-string keys are camelCase
+ */
+// ── Domain constants ──────────────────────────────────────────────────────────
+/** Domain A: used for master-signed ops (ApproveAgent, DelAgent, ApproveBuilder). */
+export const ASTER_DOMAIN_A = {
+    name: "AsterSignTransaction",
+    version: "1",
+    chainId: 56,
+    verifyingContract: "0x0000000000000000000000000000000000000000",
+};
+/** Domain B: used for agent-signed per-request ops (order, cancel, leverage). */
+export const ASTER_DOMAIN_B = {
+    ...ASTER_DOMAIN_A,
+    chainId: 1666,
+};
+/** EIP-712 types for Domain B order signing — single msg string (URL-encoded query string). */
+export const ORDER_TYPES = {
+    Message: [{ name: "msg", type: "string" }],
+};
+/**
+ * Build the EIP-712 typed-data payload for `POST /fapi/v3/approveAgent`.
+ *
+ * Field order in types array and message object matches HypurrQuant_FE
+ * AsterPerpAdapter.ts:481-533 exactly:
+ *   AgentName, AgentAddress, [IpWhitelist?,] Expired, CanSpotTrade, CanPerpTrade,
+ *   CanWithdraw, [Builder?, MaxFeeRate?, BuilderName?,] AsterChain, User, Nonce
+ */
+export function buildApproveAgentTypedData(params) {
+    const ipWhitelistIncluded = params.ipWhitelist !== undefined && params.ipWhitelist !== null;
+    const builderIncluded = params.builder !== undefined && params.builder !== null;
+    // Build types array — insertion order must match message object order.
+    const agentTypes = [
+        { name: "AgentName", type: "string" },
+        { name: "AgentAddress", type: "string" },
+    ];
+    if (ipWhitelistIncluded) {
+        agentTypes.push({ name: "IpWhitelist", type: "string" });
+    }
+    agentTypes.push({ name: "Expired", type: "uint256" }, { name: "CanSpotTrade", type: "bool" }, { name: "CanPerpTrade", type: "bool" }, { name: "CanWithdraw", type: "bool" });
+    if (builderIncluded) {
+        agentTypes.push({ name: "Builder", type: "string" });
+        agentTypes.push({ name: "MaxFeeRate", type: "string" });
+        if (params.builderName !== undefined) {
+            agentTypes.push({ name: "BuilderName", type: "string" });
+        }
+    }
+    agentTypes.push({ name: "AsterChain", type: "string" }, { name: "User", type: "string" }, { name: "Nonce", type: "uint256" });
+    // Build message object — same insertion order as types array.
+    const message = {
+        AgentName: params.agentName,
+        AgentAddress: params.agentAddress,
+    };
+    if (ipWhitelistIncluded) {
+        message["IpWhitelist"] = params.ipWhitelist;
+    }
+    // uint256 → decimal string (BigInt throws in JSON.stringify inside providers)
+    message["Expired"] = String(params.expiredMs);
+    message["CanSpotTrade"] = params.canSpotTrade;
+    message["CanPerpTrade"] = params.canPerpTrade;
+    message["CanWithdraw"] = params.canWithdraw;
+    if (builderIncluded) {
+        message["Builder"] = params.builder;
+        message["MaxFeeRate"] = params.maxFeeRate;
+        if (params.builderName !== undefined) {
+            message["BuilderName"] = params.builderName;
+        }
+    }
+    message["AsterChain"] = params.asterChain ?? "Mainnet";
+    message["User"] = params.user;
+    message["Nonce"] = String(params.nonceMicros);
+    return {
+        domain: ASTER_DOMAIN_A,
+        types: { ApproveAgent: agentTypes },
+        primaryType: "ApproveAgent",
+        message,
+    };
+}
+/**
+ * Build the EIP-712 typed-data payload for `DELETE /fapi/v3/agent`.
+ *
+ * TODO: confirm DelAgent struct vs Aster docs at Step 0b spike.
+ * HypurrQuant_FE does not implement a revoke/delAgent method — this is a
+ * best-effort field set mirroring the ApproveAgent terminal fields (AgentAddress,
+ * AsterChain, User, Nonce) without the permission booleans.
+ */
+export function buildDelAgentTypedData(params) {
+    const delTypes = [
+        { name: "AgentAddress", type: "string" },
+        { name: "AsterChain", type: "string" },
+        { name: "User", type: "string" },
+        { name: "Nonce", type: "uint256" },
+    ];
+    const message = {
+        AgentAddress: params.agentAddress,
+        AsterChain: params.asterChain ?? "Mainnet",
+        User: params.user,
+        Nonce: String(params.nonceMicros),
+    };
+    return {
+        domain: ASTER_DOMAIN_A,
+        types: { DelAgent: delTypes },
+        primaryType: "DelAgent",
+        message,
+    };
+}
+// ── buildOrderQueryStringMsg ──────────────────────────────────────────────────
+/**
+ * Encode order parameters as a URL-encoded query string.
+ *
+ * Deterministic key order = insertion order of `orderParams` (JS object property
+ * iteration order). Caller must pre-populate `user` and `nonce` (microseconds)
+ * in the dict; this function does NOT inject defaults.
+ *
+ * Uses `URLSearchParams` for encoding consistency with Python
+ * `urllib.parse.urlencode`.
+ */
+export function buildOrderQueryStringMsg(orderParams) {
+    const sp = new URLSearchParams();
+    for (const [key, value] of Object.entries(orderParams)) {
+        sp.append(key, String(value));
+    }
+    return sp.toString();
+}
+// ── buildOrderTypedData ───────────────────────────────────────────────────────
+/**
+ * Build the EIP-712 typed-data payload for agent-signed order requests.
+ *
+ * Domain B (chainId=1666), primaryType="Message", single `msg` field containing
+ * the URL-encoded query string produced by buildOrderQueryStringMsg.
+ */
+export function buildOrderTypedData(orderParams) {
+    const msg = buildOrderQueryStringMsg(orderParams);
+    return {
+        domain: ASTER_DOMAIN_B,
+        types: ORDER_TYPES,
+        primaryType: "Message",
+        message: { msg },
+    };
+}
+/**
+ * Build the EIP-712 typed-data payload for `POST /fapi/v3/approveBuilder`.
+ *
+ * Domain A (chainId=56), primaryType="ApproveBuilder".
+ * Default-path field order from HypurrQuant_FE AsterPerpAdapter.ts:630-651:
+ *   Builder, MaxFeeRate, AsterChain, User, Nonce
+ * `BuilderName` is a forward-compatible extension (HQ_FE omits it); included
+ * only when explicitly provided so the default path stays byte-equivalent to
+ * the production reference.
+ *
+ * Must be called BEFORE approveAgent so Aster fee attribution is set up
+ * before the first order.
+ */
+export function buildApproveBuilderTypedData(params) {
+    const builderTypes = [
+        { name: "Builder", type: "string" },
+        { name: "MaxFeeRate", type: "string" },
+    ];
+    if (params.builderName !== undefined) {
+        builderTypes.push({ name: "BuilderName", type: "string" });
+    }
+    builderTypes.push({ name: "AsterChain", type: "string" }, { name: "User", type: "string" }, { name: "Nonce", type: "uint256" });
+    const message = {
+        Builder: params.builder,
+        MaxFeeRate: params.maxFeeRate,
+    };
+    if (params.builderName !== undefined) {
+        message["BuilderName"] = params.builderName;
+    }
+    message["AsterChain"] = params.asterChain ?? "Mainnet";
+    message["User"] = params.user;
+    message["Nonce"] = String(params.nonceMicros);
+    return {
+        domain: ASTER_DOMAIN_A,
+        types: { ApproveBuilder: builderTypes },
+        primaryType: "ApproveBuilder",
+        message,
+    };
+}

package/dist/exchanges/aster.d.ts

@@ -1,17 +1,33 @@
 /**
- * Aster DEX adapter — Binance Futures API compatible REST wrapper.
+ * Aster DEX adapter — EIP-712 three-tier signer routing (v3.2).
+ *
+ * Signer priority:
+ *   Tier 1 — Agent OWS wallet  (registered + not expired + no --no-agent)
+ *   Tier 2 — OWS master wallet (--ows / owsActiveWallet)
+ *   Tier 3 — PK direct         (--private-key / PRIVATE_KEY / ASTER_PRIVATE_KEY)
+ *
+ * HMAC paths fully removed (see Step 3 plan — all Binance-compat HMAC code deleted).
+ *
  * Docs: https://docs.asterdex.com/product/aster-perpetuals/api/api-documentation
  * Base: https://fapi.asterdex.com
  */
 import type { ExchangeAdapter, ExchangeMarketInfo, ExchangePosition, ExchangeOrder, ExchangeBalance, ExchangeTrade, ExchangeFundingPayment, ExchangeKline } from "./interface.js";
+import type { EvmSigner } from "../signer/interface.js";
+import type { AgentMeta } from "../settings.js";
+import type { AgentSigningStrategy } from "../agent-wallet/signing-strategy.js";
 export declare class AsterAdapter implements ExchangeAdapter {
     readonly name = "aster";
     readonly chain = "bnb";
     readonly aliases: readonly ["ast"];
-    private _apiKey;
-    private _apiSecret;
     private _baseUrl;
     private _testnet;
+    private _agentMeta?;
+    private _agentSigner?;
+    private _masterSigner?;
+    private _pkSigner?;
+    private _useNoAgent;
+    /** PK held between ctor and init() since LocalEvmSigner.create() is async */
+    private _pendingPk?;
     private _marketsCache;
     private _marketsCacheTime;
     private _fundingHoursCache;
@@ -20,14 +36,20 @@ export declare class AsterAdapter implements ExchangeAdapter {
     private _ordersCache;
     private static readonly CACHE_TTL;
     private static readonly ACCOUNT_CACHE_TTL;
-    constructor(apiKey?: string, apiSecret?: string, testnet?: boolean);
+    private _nonceCounter;
+    constructor(privateKey?: string, testnet?: boolean);
+    init(): Promise<void>;
+    setAgent(meta: AgentMeta, strategy: AgentSigningStrategy): void;
+    setMasterSigner(signer: EvmSigner): void;
+    setPkSigner(signer: EvmSigner): void;
+    setNoAgent(noAgent: boolean): void;
     get isReadOnly(): boolean;
+    get activeSignerTier(): "agent" | "master" | "pk" | null;
     /** CLI symbol → Aster API symbol (ETH → ETHUSDT) */
     private _toApi;
     /** Aster API symbol → CLI symbol (ETHUSDT → ETH) */
     private _fromApi;
-    init(): Promise<void>;
-    /** Get funding interval for a symbol (lazy bootstrap — queries on first access, cached permanently). */
+    /** Get funding interval for a symbol (lazy bootstrap). */
     getFundingHours(symbol: string): Promise<number | undefined>;
     getMarkets(): Promise<ExchangeMarketInfo[]>;
     getOrderbook(symbol: string): Promise<{
@@ -66,11 +88,38 @@ export declare class AsterAdapter implements ExchangeAdapter {
         assetId?: number;
         routeType?: number;
     }): Promise<unknown>;
-    private _sign;
-    /** Handle 429 rate limit with retry */
+    private _resolveSigner;
+    private _nextNonce;
+    /**
+     * Build the canonical signed-request URL per Aster v3 spec.
+     *
+     * Reference: https://github.com/asterdex/api-docs (V3, EN, send_by_url).
+     * The Python reference adds keys to the dict in this exact order:
+     *   nonce, user, signer
+     * then URL-encodes the dict to form the EIP-712 `msg`. After signing,
+     * `&signature=` is appended to the same query string. Authority verification
+     * reconstructs `msg` from the URL query params minus `signature`, so the
+     * signed dict and the URL query string must be byte-identical except for
+     * the appended signature.
+     *
+     * `signatureChainId` is NOT a v3 parameter — it's an artifact of an older
+     * scheme; including it breaks signature verification on every call.
+     */
+    private _buildSignedQueryString;
+    /**
+     * Sign and POST to a path using EIP-712 Domain B.
+     */
+    private _signedPostEip712;
+    /**
+     * Sign and GET from a path using EIP-712 Domain B.
+     */
+    private _signedGetEip712;
+    /**
+     * Sign and DELETE from a path using EIP-712 Domain B.
+     */
+    private _signedDeleteEip712;
+    private _handleEip712Response;
+    /** Handle 429 rate limit with retry — used by GET/DELETE multi-attempt loops */
     private _handleResponse;
     private _publicGet;
-    private _signedGet;
-    private _signedPost;
-    private _signedDelete;
 }