perp-cli 0.12.17 → 0.14.1

package/dist/exchanges/qfex/agent.d.ts

@@ -0,0 +1,58 @@
+/**
+ * QFEX API key import (design §14.5 as amended by §14.12 #9).
+ *
+ * Keys are created on the QFEX website (Developer Settings, 2FA) — there is no programmatic
+ * approval. The public key + secret are entered via hidden prompt / stdin only (never flags,
+ * never env). The secret is stored only in ~/.perp/qfex-agents/<publicKey>.json (AES-256-GCM,
+ * 0600; SSOT Rule #3); settings keep the QfexAgentMeta pointer.
+ *
+ * The import BINDS the key to one concrete account UUID (the primary account's id, or the
+ * given subaccount) — never "whatever the venue defaults to" — shows it, and stores nothing
+ * until the caller confirms it. Every check is a read; no order, no subscription to act on,
+ * and the banker (funding) host is not called (its GET /address issues an address).
+ */
+import type { QfexAgentMeta } from "../../settings.js";
+import type { Network } from "../venue-types.js";
+import type { QfexCredentials } from "./signing.js";
+import type { RateLimitPolicy } from "../venue.js";
+export declare const QFEX_AGENTS_DIR = "qfex-agents";
+export declare const QFEX_IMPORT_REMEDIATION = "perp wallet agent import qfex";
+/** Read + decrypt the stored key. Throws KEY_NOT_FOUND / SIGNATURE_FAILED. */
+export declare function loadQfexCredentials(publicKey: string): QfexCredentials;
+export interface QfexAccountBinding {
+    accountId: string;
+    isPrimaryAccount: boolean;
+    /** How the account was established (shown to the user and recorded as the verification method). */
+    method: string;
+}
+/** QFEX's answer for an account with no balance record yet (never funded). */
+export declare function isUnfundedAccountError(e: unknown): boolean;
+export interface QfexImportOptions {
+    agentName: string;
+    publicKey: string;
+    secret: string;
+    network: Network;
+    /** --account-id; null = the user's primary account. */
+    accountId: string | null;
+    endpoints: {
+        rest: string;
+        tradeWs: string;
+        banker: string;
+    };
+    rateLimit: RateLimitPolicy;
+    /** Shown the resolved account; returning false stores nothing. */
+    confirmAccount(binding: QfexAccountBinding): Promise<boolean>;
+}
+/**
+ * Verify a key against the venue with reads only, bind it to one account, get that binding
+ * confirmed, then store it. Nothing is written if any step fails or the confirmation is declined.
+ */
+export declare function importQfexAgent(opts: QfexImportOptions): Promise<{
+    meta: QfexAgentMeta;
+    binding: QfexAccountBinding;
+}>;
+/**
+ * Delete the local keystore for `publicKey`. Returns true if a file was removed. The key stays
+ * valid on the venue — revoke it in QFEX Developer Settings.
+ */
+export declare function revokeQfexAgentLocal(publicKey: string): boolean;

package/dist/exchanges/qfex/agent.js

@@ -0,0 +1,188 @@
+/**
+ * QFEX API key import (design §14.5 as amended by §14.12 #9).
+ *
+ * Keys are created on the QFEX website (Developer Settings, 2FA) — there is no programmatic
+ * approval. The public key + secret are entered via hidden prompt / stdin only (never flags,
+ * never env). The secret is stored only in ~/.perp/qfex-agents/<publicKey>.json (AES-256-GCM,
+ * 0600; SSOT Rule #3); settings keep the QfexAgentMeta pointer.
+ *
+ * The import BINDS the key to one concrete account UUID (the primary account's id, or the
+ * given subaccount) — never "whatever the venue defaults to" — shows it, and stores nothing
+ * until the caller confirms it. Every check is a read; no order, no subscription to act on,
+ * and the banker (funding) host is not called (its GET /address issues an address).
+ */
+import { deleteVenueSecret, loadVenueSecret, saveVenueSecret } from "../../agent-wallet/venue-keystore.js";
+import { PerpError } from "../../errors.js";
+import { QfexClient } from "./client.js";
+import { QFEX_IDLE_CLOSE_MS, QFEX_TIMEOUTS, QfexTradeSession } from "./ws-transport.js";
+export const QFEX_AGENTS_DIR = "qfex-agents";
+export const QFEX_IMPORT_REMEDIATION = "perp wallet agent import qfex";
+/** The key is also the keystore file name and a URL query value → a conservative charset. */
+const PUBLIC_KEY_RE = /^[A-Za-z0-9._-]{1,200}$/;
+const SECRET_RE = /^\S{1,200}$/;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function assertCredentialFormat(publicKey, secret) {
+    // The qfex_pub_… / qfex_secret_… prefixes in the docs are examples; they are not enforced.
+    if (!PUBLIC_KEY_RE.test(publicKey)) {
+        throw new PerpError("INVALID_PARAMS", "QFEX public key must be 1-200 characters of letters, digits, '.', '_' or '-'", {
+            remediation: "Copy the public key exactly as shown in QFEX Developer Settings",
+        });
+    }
+    if (!SECRET_RE.test(secret)) {
+        throw new PerpError("INVALID_PARAMS", "QFEX secret must be 1-200 characters without whitespace — input not shown", {
+            remediation: "Copy the secret exactly as shown when the key was created (it is displayed once)",
+        });
+    }
+}
+/** Read + decrypt the stored key. Throws KEY_NOT_FOUND / SIGNATURE_FAILED. */
+export function loadQfexCredentials(publicKey) {
+    const plaintext = loadVenueSecret(QFEX_AGENTS_DIR, publicKey, "", QFEX_IMPORT_REMEDIATION);
+    let parsed;
+    try {
+        parsed = JSON.parse(plaintext);
+    }
+    catch (e) {
+        throw new PerpError("SIGNATURE_FAILED", `QFEX keystore for ${publicKey} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`, {
+            remediation: QFEX_IMPORT_REMEDIATION,
+        });
+    }
+    const r = parsed;
+    if (r === null || typeof r !== "object" || typeof r.publicKey !== "string" || typeof r.secret !== "string") {
+        throw new PerpError("SIGNATURE_FAILED", `QFEX keystore for ${publicKey} is missing publicKey/secret`, { remediation: QFEX_IMPORT_REMEDIATION });
+    }
+    if (r.publicKey !== publicKey) {
+        throw new PerpError("SIGNATURE_FAILED", `QFEX keystore for ${publicKey} holds a different public key`, { remediation: QFEX_IMPORT_REMEDIATION });
+    }
+    return { publicKey: r.publicKey, secret: r.secret };
+}
+function codeOf(e) {
+    return e instanceof PerpError ? e.structured.code : null;
+}
+/**
+ * Permission-probing read; any failure other than the two below aborts the import.
+ * true = the read succeeded, false = the venue denied it (403), null = the permission cannot be
+ * told: an account that has never been funded answers GET /user/positions with HTTP 500
+ * "position balance not found" (live production 2026-10-05) — the key authenticated, but there
+ * is no balance record to read yet.
+ */
+async function probe(read) {
+    try {
+        await read();
+        return true;
+    }
+    catch (e) {
+        if (codeOf(e) === "POLICY_DENIED")
+            return false;
+        if (isUnfundedAccountError(e))
+            return null;
+        throw e;
+    }
+}
+/** QFEX's answer for an account with no balance record yet (never funded). */
+export function isUnfundedAccountError(e) {
+    return e instanceof PerpError && /position balance not found/i.test(e.message);
+}
+/**
+ * Verify a key against the venue with reads only, bind it to one account, get that binding
+ * confirmed, then store it. Nothing is written if any step fails or the confirmation is declined.
+ */
+export async function importQfexAgent(opts) {
+    const publicKey = opts.publicKey.trim();
+    const secret = opts.secret.trim();
+    assertCredentialFormat(publicKey, secret);
+    if (opts.accountId !== null && !UUID_RE.test(opts.accountId)) {
+        throw new PerpError("INVALID_PARAMS", `--account-id "${opts.accountId}" is not a UUID`, {
+            remediation: "Use the account id shown in the QFEX web app (Subaccounts)",
+        });
+    }
+    const credentials = { publicKey, secret };
+    const client = new QfexClient({ restUrl: opts.endpoints.rest, bankerUrl: opts.endpoints.banker, network: opts.network, credentials, accountId: null });
+    // 1. Which account? GET /user/subaccounts/balance lists the user's accounts with is_master.
+    let binding;
+    let rows;
+    try {
+        const body = await client.getAs("/user/subaccounts/balance", null, null);
+        if (!Array.isArray(body.accounts))
+            throw new PerpError("EXCHANGE_ERROR", "QFEX /user/subaccounts/balance: response has no accounts list");
+        rows = body.accounts;
+    }
+    catch (e) {
+        if (codeOf(e) !== "POLICY_DENIED")
+            throw e;
+        rows = null; // the key may not list accounts (e.g. scoped to one account)
+    }
+    if (rows !== null) {
+        const ids = rows.filter(r => typeof r.account_id === "string").map(r => ({ id: r.account_id.toLowerCase(), master: r.is_master === true }));
+        if (opts.accountId !== null) {
+            const hit = ids.find(r => r.id === opts.accountId.toLowerCase());
+            if (hit === undefined) {
+                throw new PerpError("AGENT_NOT_REGISTERED", `QFEX ${opts.network} lists no account ${opts.accountId} for this key`, {
+                    remediation: `Accounts visible to the key: ${ids.map(r => `${r.id}${r.master ? " (primary)" : ""}`).join(", ") || "none"}`,
+                });
+            }
+            binding = { accountId: hit.id, isPrimaryAccount: hit.master, method: "GET /user/subaccounts/balance lists the account" };
+        }
+        else {
+            const masters = ids.filter(r => r.master);
+            if (masters.length !== 1) {
+                throw new PerpError("EXCHANGE_ERROR", `QFEX /user/subaccounts/balance lists ${masters.length} primary accounts; cannot tell which account the key trades`, {
+                    remediation: "Pass the account explicitly: perp wallet agent import qfex --account-id <uuid>",
+                });
+            }
+            binding = { accountId: masters[0].id, isPrimaryAccount: true, method: "GET /user/subaccounts/balance: the is_master account" };
+        }
+    }
+    else {
+        if (opts.accountId === null) {
+            throw new PerpError("POLICY_DENIED", "This QFEX key cannot list accounts, so the account it trades cannot be resolved", {
+                remediation: "Pass the account the key is scoped to: perp wallet agent import qfex --account-id <uuid> (shown in the QFEX web app)",
+            });
+        }
+        binding = { accountId: opts.accountId.toLowerCase(), isPrimaryAccount: false, method: "given --account-id; a signed read as that account succeeded (the key cannot list accounts, so primary/sub is unknown — treated as a subaccount)" };
+    }
+    // 2. Reads AS that account. 401 aborts (SIGNATURE_FAILED); 403 = that permission is missing.
+    const viewPositions = await probe(() => client.getAs("/user/positions", null, binding.accountId));
+    const viewOrders = await probe(() => client.getAs("/user/trade", { limit: 1 }, binding.accountId));
+    if (rows === null && viewPositions !== true) {
+        const positions = viewPositions === false ? "was denied positions" : "could not read positions (unknown: the account is not funded yet)";
+        throw new PerpError("POLICY_DENIED", `The key could not list accounts and ${positions} as ${binding.accountId}; nothing proves it can act on that account`, {
+            remediation: viewPositions === false
+                ? "Check the account id and the key's scope / View permissions in QFEX Developer Settings"
+                : "Fund the account first (a never-funded account has no balance record to read), or import a key with All accounts access",
+        });
+    }
+    // 3. Trade WebSocket authentication with the account named explicitly. No command is sent.
+    const session = new QfexTradeSession({
+        url: opts.endpoints.tradeWs, network: opts.network, credentials, accountId: binding.accountId, builderCode: null,
+        rateLimit: opts.rateLimit, timeouts: QFEX_TIMEOUTS, idleCloseMs: QFEX_IDLE_CLOSE_MS,
+    });
+    await session.verifyAuth();
+    // 4. The user confirms the account BEFORE anything is stored.
+    if (!(await opts.confirmAccount(binding))) {
+        throw new PerpError("INVALID_PARAMS", `QFEX import cancelled — account ${binding.accountId} was not confirmed; nothing was stored`, {
+            remediation: "Re-run and confirm the account, or pass the intended one: perp wallet agent import qfex --account-id <uuid>",
+        });
+    }
+    const keystorePath = saveVenueSecret(QFEX_AGENTS_DIR, publicKey, JSON.stringify({ publicKey, secret }), "");
+    const meta = {
+        kind: "qfex",
+        agentName: opts.agentName,
+        publicKey,
+        keystorePath,
+        accountId: binding.accountId,
+        isPrimaryAccount: binding.isPrimaryAccount,
+        // Positions and balance come from the same endpoint. Execute / withdraw cannot be checked without acting.
+        permissions: { viewPositions, viewBalance: viewPositions, viewOrders, executeOrders: null, depositWithdraw: null },
+        network: opts.network,
+        approvedAt: new Date().toISOString(),
+        source: "imported",
+    };
+    return { meta, binding };
+}
+/**
+ * Delete the local keystore for `publicKey`. Returns true if a file was removed. The key stays
+ * valid on the venue — revoke it in QFEX Developer Settings.
+ */
+export function revokeQfexAgentLocal(publicKey) {
+    return deleteVenueSecret(QFEX_AGENTS_DIR, publicKey);
+}

package/dist/exchanges/qfex/client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * QFEX raw REST client (design §14.1, §14.4, §14.6): raw fetch + node:crypto HMAC, no SDK.
+ *
+ * Two hosts: the API (`api.qfex.*` — market data, account reads, leverage, subaccount
+ * transfer) and the banker (`banker.qfex.*` — deposit address, withdraw). Both take the same
+ * four auth headers (signing.ts). Errors are RFC 7807 problem+json.
+ *
+ * No retries, no fallbacks (SSOT Rule #2). A GET failure is definite (nothing changed). A POST
+ * that may have reached the venue (transport failure, timeout, 5xx) is an UNKNOWN outcome:
+ * ORDER_PENDING, never re-sent.
+ *
+ * Rate limit: QFEX documents only the WebSocket budget ("HTTP endpoints … may be subject to
+ * separate controls"). UNVERIFIED — a conservative 5 requests/s per process is applied here.
+ */
+import type { RateLimitPolicy } from "../venue.js";
+import type { Network } from "../venue-types.js";
+import { type QfexCredentials } from "./signing.js";
+/** UNVERIFIED: no published REST limit — 5 req/s (see module header). */
+export declare const QFEX_REST_RATE_LIMIT: RateLimitPolicy;
+/** Per-request timeout (fetch + body read). */
+export declare const QFEX_REQUEST_TIMEOUT_MS = 15000;
+export type QfexQuery = Record<string, string | number | null>;
+export interface QfexClientOptions {
+    restUrl: string;
+    bankerUrl: string;
+    network: Network;
+    /** null → public endpoints only. */
+    credentials: QfexCredentials | null;
+    /** Account the signed requests act as (x-qfex-requested-account-id); null only while a key is being imported. */
+    accountId: string | null;
+}
+export declare class QfexClient {
+    private readonly opts;
+    private readonly restUrl;
+    private readonly bankerUrl;
+    private readonly rateKey;
+    constructor(opts: QfexClientOptions);
+    get hasCredentials(): boolean;
+    /** Public GET (no auth headers). */
+    publicGet<T>(path: string, query: QfexQuery | null): Promise<T>;
+    /** Signed GET as the configured account. */
+    get<T>(path: string, query: QfexQuery | null): Promise<T>;
+    /** Signed GET as an explicit account (`null` = no account header: the key's primary account). Import-time checks only. */
+    getAs<T>(path: string, query: QfexQuery | null, accountId: string | null): Promise<T>;
+    /** Signed POST; returns the parsed body, or null for an empty one (204 / empty 200). */
+    post<T>(path: string, query: QfexQuery | null, body: unknown): Promise<T | null>;
+    bankerGet<T>(path: string, query: QfexQuery | null): Promise<T>;
+    /** Banker POST acts on the primary account (deposits / withdrawals are primary-only): no account header. */
+    bankerPost<T>(path: string, body: unknown): Promise<T | null>;
+    private request;
+    private unknownOutcome;
+}
+/** A required GET body: QFEX GET endpoints always answer with a JSON object. */
+export declare function requireBody<T>(body: T | null, what: string): T;

package/dist/exchanges/qfex/client.js

@@ -0,0 +1,138 @@
+/**
+ * QFEX raw REST client (design §14.1, §14.4, §14.6): raw fetch + node:crypto HMAC, no SDK.
+ *
+ * Two hosts: the API (`api.qfex.*` — market data, account reads, leverage, subaccount
+ * transfer) and the banker (`banker.qfex.*` — deposit address, withdraw). Both take the same
+ * four auth headers (signing.ts). Errors are RFC 7807 problem+json.
+ *
+ * No retries, no fallbacks (SSOT Rule #2). A GET failure is definite (nothing changed). A POST
+ * that may have reached the venue (transport failure, timeout, 5xx) is an UNKNOWN outcome:
+ * ORDER_PENDING, never re-sent.
+ *
+ * Rate limit: QFEX documents only the WebSocket budget ("HTTP endpoints … may be subject to
+ * separate controls"). UNVERIFIED — a conservative 5 requests/s per process is applied here.
+ */
+import { PerpError, orderOutcomeUnknown } from "../../errors.js";
+import { acquireRate } from "../rate-limiter.js";
+import { qfexBankerError, qfexRestError } from "./errors.js";
+import { qfexNonce, qfexRestHeaders } from "./signing.js";
+/** UNVERIFIED: no published REST limit — 5 req/s (see module header). */
+export const QFEX_REST_RATE_LIMIT = { capacity: 5, refillPerSec: 5, weights: null };
+/** Per-request timeout (fetch + body read). */
+export const QFEX_REQUEST_TIMEOUT_MS = 15_000;
+export class QfexClient {
+    opts;
+    restUrl;
+    bankerUrl;
+    rateKey;
+    constructor(opts) {
+        this.opts = opts;
+        this.restUrl = opts.restUrl.replace(/\/+$/, "");
+        this.bankerUrl = opts.bankerUrl.replace(/\/+$/, "");
+        this.rateKey = `qfex:${opts.network}:rest`;
+    }
+    get hasCredentials() {
+        return this.opts.credentials !== null;
+    }
+    /** Public GET (no auth headers). */
+    async publicGet(path, query) {
+        return requireBody(await this.request("api", "GET", path, query, null, false, this.opts.accountId), `GET ${path}`);
+    }
+    /** Signed GET as the configured account. */
+    async get(path, query) {
+        return requireBody(await this.request("api", "GET", path, query, null, true, this.opts.accountId), `GET ${path}`);
+    }
+    /** Signed GET as an explicit account (`null` = no account header: the key's primary account). Import-time checks only. */
+    async getAs(path, query, accountId) {
+        return requireBody(await this.request("api", "GET", path, query, null, true, accountId), `GET ${path}`);
+    }
+    /** Signed POST; returns the parsed body, or null for an empty one (204 / empty 200). */
+    async post(path, query, body) {
+        return this.request("api", "POST", path, query, body, true, this.opts.accountId);
+    }
+    async bankerGet(path, query) {
+        return requireBody(await this.request("banker", "GET", path, query, null, true, null), `GET ${path}`);
+    }
+    /** Banker POST acts on the primary account (deposits / withdrawals are primary-only): no account header. */
+    async bankerPost(path, body) {
+        return this.request("banker", "POST", path, null, body, true, null);
+    }
+    async request(host, method, path, query, body, auth, accountId) {
+        let pathWithQuery = path;
+        if (query !== null) {
+            const qs = new URLSearchParams();
+            for (const [k, v] of Object.entries(query))
+                if (v !== null)
+                    qs.append(k, String(v));
+            const s = qs.toString();
+            if (s !== "")
+                pathWithQuery = `${path}?${s}`;
+        }
+        const base = host === "api" ? this.restUrl : this.bankerUrl;
+        const bodyStr = body === null ? "" : JSON.stringify(body);
+        // The rate-limit wait happens BEFORE the timestamp is taken (±5 min window, and a queued
+        // request must not go out with a stale one).
+        await acquireRate(this.rateKey, QFEX_REST_RATE_LIMIT, path);
+        const headers = { Accept: "application/json" };
+        if (bodyStr !== "")
+            headers["Content-Type"] = "application/json";
+        if (auth) {
+            const creds = this.opts.credentials;
+            if (creds === null) {
+                throw new PerpError("NO_SIGNER_AVAILABLE", `QFEX: ${method} ${path} requires an API key`, {
+                    remediation: "Import a QFEX API key: perp wallet agent import qfex",
+                });
+            }
+            Object.assign(headers, qfexRestHeaders(creds, accountId, Date.now(), qfexNonce()));
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), QFEX_REQUEST_TIMEOUT_MS);
+        let res;
+        let text;
+        try {
+            res = await fetch(`${base}${pathWithQuery}`, { method, headers, ...(bodyStr !== "" ? { body: bodyStr } : {}), signal: controller.signal });
+            text = await res.text();
+        }
+        catch (e) {
+            const aborted = controller.signal.aborted;
+            const reason = aborted ? `timed out after ${QFEX_REQUEST_TIMEOUT_MS}ms` : `failed: ${e instanceof Error ? e.message : String(e)}`;
+            if (method === "POST")
+                throw this.unknownOutcome(host, path, `request ${reason}`);
+            throw new PerpError(aborted ? "TIMEOUT" : "EXCHANGE_UNREACHABLE", `QFEX: ${method} ${path} ${reason}`, {
+                exchange: "qfex", remediation: `Check network connectivity to ${base}`,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            // A 5xx on a POST does not say whether the venue applied it.
+            if (method === "POST" && res.status >= 500)
+                throw this.unknownOutcome(host, path, `HTTP ${res.status}: ${text.slice(0, 200)}`);
+            throw host === "banker" ? qfexBankerError(method, path, res.status, text) : qfexRestError(method, path, res.status, text);
+        }
+        if (text.trim() === "")
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            if (method === "POST")
+                throw this.unknownOutcome(host, path, `HTTP ${res.status} with a non-JSON body`);
+            throw new PerpError("EXCHANGE_ERROR", `QFEX: ${method} ${path} returned non-JSON (HTTP ${res.status})`, {
+                exchange: "qfex", httpStatus: res.status, body: text.slice(0, 300),
+            });
+        }
+    }
+    unknownOutcome(host, path, reason) {
+        return orderOutcomeUnknown("qfex", `POST ${path}`, new Error(reason), host === "banker"
+            ? "Do NOT resubmit — POST /withdraw is not idempotent and may have been applied. Check the QFEX funding history (web app) and: perp account balance -e qfex"
+            : "Do NOT resubmit — the request may have been applied. Check: perp account balance -e qfex / perp account positions -e qfex");
+    }
+}
+/** A required GET body: QFEX GET endpoints always answer with a JSON object. */
+export function requireBody(body, what) {
+    if (body === null)
+        throw new PerpError("EXCHANGE_ERROR", `QFEX: ${what} returned an empty body`, { exchange: "qfex" });
+    return body;
+}

package/dist/exchanges/qfex/errors.d.ts

@@ -0,0 +1,70 @@
+/**
+ * QFEX venue status / error → PerpError (design §14.3 error table, §14.12 #3, #8, #11).
+ *
+ * Three sources:
+ *  - order_response.status   engine verdict on one order (definite once correlated);
+ *  - error frames            `{err:{…}}`, `{type:"Err",…}`, `{type:"error",…}` (all documented);
+ *  - REST problem+json       api.qfex.* and banker.qfex.*.
+ * Nothing here retries. A RATE_LIMITED on a cancel is surfaced, never re-sent.
+ */
+import { PerpError } from "../../errors.js";
+/** order_response.status values (AsyncAPI OrderResponse.status enum). */
+export declare const QFEX_ORDER_STATUSES: readonly ["ACK", "EXPIRED", "IOC_CANCELLED", "INVALID_PRICE", "INVALID_QUANTITY", "NOT_FOUND", "IOC_PARTIALLY_FILLED", "USER_NOT_FOUND", "PERMISSION_DENIED", "FILLED", "MODIFIED", "CANCELLED", "CANCELLED_STP", "REJECTED", "NO_SUCH_ORDER", "INVALID_ORDER_TYPE", "BAD_SYMBOL", "PRICE_LESS_THAN_MIN_PRICE", "PRICE_GREATER_THAN_MAX_PRICE", "CANNOT_MODIFY_PARTIAL_FILL", "CANNOT_MODIFY_ALO_WOULD_CROSS", "FAILED_MARGIN_CHECK", "REJECTED_MUST_CHANGE_VALUE_MODIFY", "NO_CHANGE_NO_UPDATE", "INVALID_TICK_SIZE_PRECISION_PRICE", "INVALID_TICK_SIZE_PRECISION_QUANTITY", "QUANTITY_LESS_THAN_MIN_QUANTITY", "QUANTITY_GREATER_THAN_MAX_QUANTITY", "REJECTED_GREATER_THAN_MAX_PRICE_BAND", "REJECTED_LESS_THAN_MIN_PRICE_BAND", "INVALID_TIME_IN_FORCE", "REJECTED_WOULD_BREACH_MAX_POSITION", "REJECTED_WOULD_BREACH_MAX_NOTIONAL", "CANNOT_MODIFY_NO_SUCH_ORDER", "REJECTED_MARKET_CLOSED", "USER_IN_LIQUIDATION", "REJECTED_FAILED_TO_PROCESS", "INVALID_TAKE_PROFIT_PRICE", "INVALID_STOP_LOSS_PRICE", "INVALID_CLIENT_ORDER_ID", "RATE_LIMITED", "REJECTED_TOO_MANY_OPEN_ORDERS", "REJECTED_OPEN_INTEREST_LIMIT", "REJECTED_TOTAL_OPEN_INTEREST_LIMIT", "REJECTED_LESS_THAN_MIN_NOTIONAL"];
+export type QfexStatusClass = 
+/** Received by the gateway; not yet proven resting or filled. */
+"ack"
+/** FILLED — full when quantity_remaining is 0, otherwise a partial fill. */
+ | "fill"
+/** MODIFIED — the order now lives under a new order_id. */
+ | "modified"
+/** The order is gone from the book: IOC_PARTIALLY_FILLED, IOC_CANCELLED, CANCELLED, CANCELLED_STP, EXPIRED. */
+ | "terminal"
+/** The engine refused the request. */
+ | "reject"
+/** A status this build does not know — never interpreted. */
+ | "unknown";
+export declare function qfexStatusClass(status: string): QfexStatusClass;
+/** "… retry after 200ms" / "… retry after 2 seconds" → ms; null when the message carries no hint. */
+export declare function parseRetryAfterMs(message: string | null): number | null;
+export interface QfexOrderContext {
+    /** What was being done, for the message ("add_order AAPL-USD"). */
+    what: string;
+    /** Price band of the market at validation time (attached to band rejections). */
+    band: {
+        lower: string;
+        upper: string;
+    } | null;
+}
+/** Error for a correlated order_response whose status is an engine rejection. */
+export declare function qfexOrderStatusError(status: string, ctx: QfexOrderContext, frame: unknown): PerpError;
+export declare const QFEX_ERR_CODES: readonly ["RateLimited", "InvalidJSONFormat", "AlreadyAuthenticated", "InvalidParameter", "PermissionDenied", "ServerError", "InvalidOrder", "InvalidOrderId", "KycRequired", "TncRequired"];
+export interface QfexErrFrame {
+    errorCode: string;
+    message: string | null;
+    /** Echo of the request (`{type, params}`); null when absent or empty (`{}`), which carries no evidence. */
+    echo: {
+        type: string;
+        params: Record<string, unknown>;
+    } | null;
+}
+/**
+ * Is an error frame, received after a MUTATING request was sent, proof that the request was
+ * NOT applied? Only when the venue echoed that very request AND the code is a refusal.
+ * `ServerError` ("safe to retry" in the docs) says nothing about whether the engine saw the
+ * order, and an error without an echo — including the documented `RateLimited` with
+ * `incoming_message: {}` — cannot be attributed to this request: both are unknown outcomes.
+ */
+export declare function qfexErrIsDefiniteRefusal(err: QfexErrFrame, echoMatches: boolean): boolean;
+/** PerpError for an error frame that is a definite answer (reads, or a refusal per qfexErrIsDefiniteRefusal). */
+export declare function qfexErrFrameError(err: QfexErrFrame, what: string): PerpError;
+/** api.qfex.* (trading / account REST): 401 → SIGNATURE_FAILED, 403 → POLICY_DENIED, 429 → RATE_LIMITED, 5xx → EXCHANGE_ERROR. */
+export declare function qfexRestError(method: string, path: string, httpStatus: number, body: string): PerpError;
+/**
+ * banker.qfex.* (deposit address / withdraw), docs programmatic-funding "Errors":
+ *   400 invalid amount / address / network, or insufficient withdrawable balance → definite refusal;
+ *   401 missing / invalid authentication OR terms not accepted → by body;
+ *   403 key lacks "Deposit and withdraw", or the account cannot use funding;
+ * The official CLI README adds that withdrawals need 2FA and cannot be started from a CLI, so a
+ * refusal here is expected for many accounts.
+ */
+export declare function qfexBankerError(method: string, path: string, httpStatus: number, body: string): PerpError;