perp-cli 0.9.8 → 0.12.0

package/dist/config.d.ts

@@ -5,6 +5,15 @@ export type Exchange = "pacifica" | "hyperliquid" | "lighter" | "aster";
  * Returns null if no key is configured.
  */
 export declare function tryLoadPrivateKey(exchange: Exchange, pkOverride?: string, walletName?: string): Promise<string | null>;
+/**
+ * Resolve an OWS wallet name to a signer-ready marker.
+ * Returns the OWS wallet name prefixed with "ows:" so callers can detect OWS mode.
+ */
+export declare function resolveOwsWallet(walletName: string): string | null;
+/** Check if a key string represents an OWS wallet reference. */
+export declare function isOwsKey(key: string): boolean;
+/** Extract OWS wallet name from an ows: prefixed key string. */
+export declare function getOwsWalletName(key: string): string;
 export declare function loadPrivateKey(exchange: Exchange, pkOverride?: string, walletName?: string): Promise<string>;
 export declare function parseSolanaKeypair(input: string): Keypair;
 export declare function isEvmPrivateKey(input: string): boolean;

package/dist/config.js

@@ -3,6 +3,8 @@ import bs58 from "bs58";
 import chalk from "chalk";
 import { resolve } from "path";
 import { existsSync, readFileSync } from "fs";
+import { createRequire } from "node:module";
+const _require = createRequire(import.meta.url);
 /**
  * Try to load a private key without throwing if none is found.
  * Returns null if no key is configured.
@@ -15,9 +17,40 @@ export async function tryLoadPrivateKey(exchange, pkOverride, walletName) {
         return null;
     }
 }
+/**
+ * Resolve an OWS wallet name to a signer-ready marker.
+ * Returns the OWS wallet name prefixed with "ows:" so callers can detect OWS mode.
+ */
+export function resolveOwsWallet(walletName) {
+    try {
+        const { getWallet } = _require("@open-wallet-standard/core");
+        getWallet(walletName); // throws if not found
+        return `ows:${walletName}`;
+    }
+    catch {
+        return null;
+    }
+}
+/** Check if a key string represents an OWS wallet reference. */
+export function isOwsKey(key) {
+    return key.startsWith("ows:");
+}
+/** Extract OWS wallet name from an ows: prefixed key string. */
+export function getOwsWalletName(key) {
+    return key.slice(4);
+}
 export async function loadPrivateKey(exchange, pkOverride, walletName) {
-    // 0. Wallet name override (--wallet flag)
+    // 0a. OWS wallet (--ows flag sets walletName with "ows:" prefix)
+    if (walletName?.startsWith("ows:")) {
+        return walletName; // pass through — adapters detect the ows: prefix
+    }
+    // 0b. Wallet name override (--wallet flag) — check OWS first, then local
     if (walletName) {
+        // Try OWS vault
+        const owsKey = resolveOwsWallet(walletName);
+        if (owsKey)
+            return owsKey;
+        // Fall back to local wallets
         const { getWalletKeyByName } = await import("./commands/wallet.js");
         const key = getWalletKeyByName(walletName);
         if (!key)
@@ -27,7 +60,20 @@ export async function loadPrivateKey(exchange, pkOverride, walletName) {
     // 1. CLI flag
     if (pkOverride)
         return pkOverride;
-    // 2. Exchange-specific env vars
+    // 2. OWS active wallet (highest priority after explicit flags)
+    try {
+        const { loadSettings } = await import("./settings.js");
+        const settings = loadSettings();
+        if (settings.owsActiveWallet) {
+            const owsKey = resolveOwsWallet(settings.owsActiveWallet);
+            if (owsKey)
+                return owsKey;
+        }
+    }
+    catch {
+        // settings module not available, skip
+    }
+    // 3. Exchange-specific env vars
     const envMap = {
         pacifica: ["PACIFICA_PRIVATE_KEY", "pk"],
         hyperliquid: ["HYPERLIQUID_PRIVATE_KEY", "HL_PRIVATE_KEY"],
@@ -38,10 +84,10 @@ export async function loadPrivateKey(exchange, pkOverride, walletName) {
         if (process.env[envVar])
             return process.env[envVar];
     }
-    // 3. Generic fallback
+    // 4. Generic fallback
     if (process.env.PRIVATE_KEY)
         return process.env.PRIVATE_KEY;
-    // 4. Active wallet from wallets.json
+    // 5. Legacy: Active wallet from wallets.json
     try {
         const { getActiveWalletKey } = await import("./commands/wallet.js");
         const walletKey = getActiveWalletKey(exchange);
@@ -56,12 +102,12 @@ export async function loadPrivateKey(exchange, pkOverride, walletName) {
     if (existsSync(keyFile)) {
         return readFileSync(keyFile, "utf-8").trim();
     }
-    throw new Error(`No private key configured for ${exchange}.\n\n` +
-        `  Quick start:  ${chalk.cyan("perp setup")}\n\n` +
+    throw new Error(`No wallet configured for ${exchange}.\n\n` +
+        `  Quick start:  ${chalk.cyan("perp wallet generate")}\n\n` +
         `  Or manually:\n` +
-        `    perp wallet set ${exchange} <key>\n` +
-        `    ${envMap[exchange][0]}=<key> (env var)\n` +
-        `    --private-key <key> (per-command)`);
+        `    perp wallet import <key>     Import key to OWS vault\n` +
+        `    perp wallet set ${exchange} <key>  Legacy: set env var\n` +
+        `    --private-key <key>          Per-command override`);
 }
 export function parseSolanaKeypair(input) {
     // Try base58 first

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,
+    };
+}