perp-cli 0.12.15 → 0.14.0

package/dist/exchanges/qfex/errors.js

@@ -0,0 +1,236 @@
+/**
+ * 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 const QFEX_ORDER_STATUSES = [
+    "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",
+];
+const TERMINAL = new Set(["IOC_PARTIALLY_FILLED", "IOC_CANCELLED", "CANCELLED", "CANCELLED_STP", "EXPIRED"]);
+const KNOWN = new Set(QFEX_ORDER_STATUSES);
+export function qfexStatusClass(status) {
+    if (status === "ACK")
+        return "ack";
+    if (status === "FILLED")
+        return "fill";
+    if (status === "MODIFIED")
+        return "modified";
+    if (TERMINAL.has(status))
+        return "terminal";
+    return KNOWN.has(status) ? "reject" : "unknown";
+}
+const STATUS_CODE = {
+    INVALID_PRICE: "INVALID_PARAMS",
+    INVALID_QUANTITY: "INVALID_PARAMS",
+    INVALID_ORDER_TYPE: "INVALID_PARAMS",
+    INVALID_TIME_IN_FORCE: "INVALID_PARAMS",
+    INVALID_TAKE_PROFIT_PRICE: "INVALID_PARAMS",
+    INVALID_STOP_LOSS_PRICE: "INVALID_PARAMS",
+    INVALID_CLIENT_ORDER_ID: "INVALID_PARAMS",
+    INVALID_TICK_SIZE_PRECISION_QUANTITY: "INVALID_PARAMS",
+    REJECTED_MUST_CHANGE_VALUE_MODIFY: "INVALID_PARAMS",
+    NO_CHANGE_NO_UPDATE: "INVALID_PARAMS",
+    INVALID_TICK_SIZE_PRECISION_PRICE: "INVALID_TICK",
+    PRICE_LESS_THAN_MIN_PRICE: "INVALID_PARAMS",
+    PRICE_GREATER_THAN_MAX_PRICE: "INVALID_PARAMS",
+    REJECTED_GREATER_THAN_MAX_PRICE_BAND: "INVALID_PARAMS",
+    REJECTED_LESS_THAN_MIN_PRICE_BAND: "INVALID_PARAMS",
+    QUANTITY_LESS_THAN_MIN_QUANTITY: "SIZE_TOO_SMALL",
+    REJECTED_LESS_THAN_MIN_NOTIONAL: "SIZE_TOO_SMALL",
+    QUANTITY_GREATER_THAN_MAX_QUANTITY: "SIZE_TOO_LARGE",
+    BAD_SYMBOL: "SYMBOL_NOT_FOUND",
+    NOT_FOUND: "ORDER_NOT_FOUND",
+    NO_SUCH_ORDER: "ORDER_NOT_FOUND",
+    CANNOT_MODIFY_NO_SUCH_ORDER: "ORDER_NOT_FOUND",
+    CANNOT_MODIFY_PARTIAL_FILL: "ORDER_REJECTED",
+    CANNOT_MODIFY_ALO_WOULD_CROSS: "ORDER_REJECTED",
+    REJECTED: "ORDER_REJECTED",
+    REJECTED_FAILED_TO_PROCESS: "ORDER_REJECTED",
+    REJECTED_MARKET_CLOSED: "ORDER_REJECTED",
+    FAILED_MARGIN_CHECK: "MARGIN_INSUFFICIENT",
+    REJECTED_WOULD_BREACH_MAX_POSITION: "RISK_VIOLATION",
+    REJECTED_WOULD_BREACH_MAX_NOTIONAL: "RISK_VIOLATION",
+    REJECTED_OPEN_INTEREST_LIMIT: "RISK_VIOLATION",
+    REJECTED_TOTAL_OPEN_INTEREST_LIMIT: "RISK_VIOLATION",
+    REJECTED_TOO_MANY_OPEN_ORDERS: "RISK_VIOLATION",
+    USER_IN_LIQUIDATION: "RISK_VIOLATION",
+    PERMISSION_DENIED: "POLICY_DENIED",
+    USER_NOT_FOUND: "AGENT_NOT_REGISTERED",
+    RATE_LIMITED: "RATE_LIMITED",
+};
+const KEY_PERMISSION_REMEDIATION = "Check the API key's permissions and account scope in QFEX Developer Settings (website, 2FA). The denial can also be KYC, terms or region — perp-cli does not cache it";
+const CODE_REMEDIATION = {
+    INVALID_TICK: "Align the price with the market tick: perp market info <symbol> -e qfex",
+    SIZE_TOO_SMALL: "Increase the size above the market minimum: perp market info <symbol> -e qfex",
+    SIZE_TOO_LARGE: "Reduce the size below the market maximum: perp market info <symbol> -e qfex",
+    SYMBOL_NOT_FOUND: "List markets with: perp market list -e qfex",
+    MARGIN_INSUFFICIENT: "Reduce size / leverage or deposit more USDC (perp funds deposit qfex)",
+    RISK_VIOLATION: "The venue's position / notional / open-interest / open-order limit was hit — reduce the size or close positions",
+    POLICY_DENIED: KEY_PERMISSION_REMEDIATION,
+    AGENT_NOT_REGISTERED: "The venue does not know this user / account — re-import the key: perp wallet agent import qfex",
+    RATE_LIMITED: "Wait for the retry-after hint, then run the command again yourself (perp-cli never re-sends an order or a cancel)",
+};
+const STATUS_REMEDIATION = {
+    CANNOT_MODIFY_PARTIAL_FILL: "A partially filled order cannot be modified — cancel it and place a new order",
+    CANNOT_MODIFY_ALO_WOULD_CROSS: "The new price would cross the book — choose a passive price, or cancel and place a LIMIT order",
+    REJECTED_MARKET_CLOSED: "The market is closed for this order right now — check the session: perp market info <symbol> -e qfex",
+    INVALID_CLIENT_ORDER_ID: "The venue refused the generated client order id — report it (docs/TEST-PLAN.md QFEX Q18)",
+};
+/** "… retry after 200ms" / "… retry after 2 seconds" → ms; null when the message carries no hint. */
+export function parseRetryAfterMs(message) {
+    if (message === null)
+        return null;
+    const m = /retry after\s+(\d+(?:\.\d+)?)\s*(ms|milliseconds?|s|sec|seconds?)\b/i.exec(message);
+    if (m === null)
+        return null;
+    const n = Number(m[1]);
+    return /^ms|^milli/i.test(m[2]) ? n : n * 1000;
+}
+/** Error for a correlated order_response whose status is an engine rejection. */
+export function qfexOrderStatusError(status, ctx, frame) {
+    const code = STATUS_CODE[status] ?? "ORDER_REJECTED";
+    const remediation = STATUS_REMEDIATION[status] ?? CODE_REMEDIATION[code];
+    const details = { exchange: "qfex", venueStatus: status, venueRaw: frame };
+    if (status === "REJECTED_MARKET_CLOSED")
+        details.reason = "marketClosed";
+    if (ctx.band !== null && /PRICE|BAND/.test(status))
+        details.band = ctx.band;
+    if (remediation !== undefined)
+        details.remediation = remediation;
+    return new PerpError(code, `QFEX rejected ${ctx.what}: ${status}`, details);
+}
+// ── Error frames ──
+export const QFEX_ERR_CODES = [
+    "RateLimited", "InvalidJSONFormat", "AlreadyAuthenticated", "InvalidParameter", "PermissionDenied",
+    "ServerError", "InvalidOrder", "InvalidOrderId", "KycRequired", "TncRequired",
+];
+const ERR_CODE = {
+    RateLimited: "RATE_LIMITED",
+    InvalidJSONFormat: "INVALID_PARAMS",
+    InvalidParameter: "INVALID_PARAMS",
+    InvalidOrder: "INVALID_PARAMS",
+    InvalidOrderId: "INVALID_PARAMS",
+    PermissionDenied: "POLICY_DENIED",
+    KycRequired: "POLICY_DENIED",
+    TncRequired: "POLICY_DENIED",
+    AlreadyAuthenticated: "EXCHANGE_ERROR",
+    ServerError: "EXCHANGE_ERROR",
+};
+const ERR_REMEDIATION = {
+    KycRequired: "Complete KYC on the QFEX website, then retry",
+    TncRequired: "Accept the latest QFEX Terms and Conditions on the website, then retry",
+    PermissionDenied: KEY_PERMISSION_REMEDIATION,
+    RateLimited: CODE_REMEDIATION.RATE_LIMITED,
+};
+/**
+ * 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 function qfexErrIsDefiniteRefusal(err, echoMatches) {
+    if (!echoMatches)
+        return false;
+    return err.errorCode !== "ServerError" && err.errorCode in ERR_CODE;
+}
+/** PerpError for an error frame that is a definite answer (reads, or a refusal per qfexErrIsDefiniteRefusal). */
+export function qfexErrFrameError(err, what) {
+    const code = ERR_CODE[err.errorCode] ?? "EXCHANGE_ERROR";
+    const details = { exchange: "qfex", venueCode: err.errorCode };
+    const retryAfterMs = err.errorCode === "RateLimited" ? parseRetryAfterMs(err.message) : null;
+    if (retryAfterMs !== null)
+        details.retryAfterMs = retryAfterMs;
+    const remediation = ERR_REMEDIATION[err.errorCode] ?? CODE_REMEDIATION[code];
+    if (remediation !== undefined)
+        details.remediation = remediation;
+    return new PerpError(code, `QFEX ${what}: ${err.errorCode}${err.message !== null ? ` — ${err.message}` : ""}`, details);
+}
+function problemText(body) {
+    try {
+        const p = JSON.parse(body);
+        if (p !== null && typeof p === "object") {
+            const parts = [p.title, p.detail].filter((x) => typeof x === "string" && x !== "");
+            if (parts.length > 0)
+                return parts.join(": ");
+        }
+    }
+    catch { /* not JSON — the raw text is used */ }
+    return body.slice(0, 300);
+}
+/** api.qfex.* (trading / account REST): 401 → SIGNATURE_FAILED, 403 → POLICY_DENIED, 429 → RATE_LIMITED, 5xx → EXCHANGE_ERROR. */
+export function qfexRestError(method, path, httpStatus, body) {
+    const text = problemText(body);
+    const at = `[${method} ${path}, HTTP ${httpStatus}]`;
+    const base = { exchange: "qfex", httpStatus };
+    if (httpStatus === 401) {
+        return new PerpError("SIGNATURE_FAILED", `QFEX: ${text} ${at}`, {
+            ...base, remediation: "Check the system clock (QFEX accepts ±5 minutes) and that the key was not revoked; re-import: perp wallet agent import qfex --replace",
+        });
+    }
+    if (httpStatus === 403)
+        return new PerpError("POLICY_DENIED", `QFEX: ${text} ${at}`, { ...base, remediation: KEY_PERMISSION_REMEDIATION });
+    if (httpStatus === 404)
+        return new PerpError("EXCHANGE_ERROR", `QFEX: ${text} ${at}`, base);
+    if (httpStatus === 429)
+        return new PerpError("RATE_LIMITED", `QFEX: ${text} ${at}`, { ...base, remediation: CODE_REMEDIATION.RATE_LIMITED });
+    if (httpStatus >= 400 && httpStatus < 500)
+        return new PerpError("INVALID_PARAMS", `QFEX: ${text} ${at}`, base);
+    return new PerpError("EXCHANGE_ERROR", `QFEX: ${text} ${at}`, base);
+}
+/**
+ * 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 function qfexBankerError(method, path, httpStatus, body) {
+    const text = problemText(body);
+    const at = `[${method} ${path}, HTTP ${httpStatus}]`;
+    const base = { exchange: "qfex", httpStatus };
+    const website = "QFEX documents that withdrawals need two-factor authentication on the web app; if the API refuses, withdraw there";
+    if (httpStatus === 400) {
+        const insufficient = /insufficient|withdrawable|balance/i.test(text);
+        return new PerpError(insufficient ? "INSUFFICIENT_BALANCE" : "ACTION_REJECTED", `QFEX funding refused: ${text} ${at}`, {
+            ...base, remediation: insufficient
+                ? "The amount exceeds the Withdrawable Balance (cash + realised PnL + min(unrealised PnL, 0) − 1.05 × margin) — lower it or free margin"
+                : `Nothing was executed. Check the amount, address and network (ARBITRUM_ONE). ${website}`,
+        });
+    }
+    if (httpStatus === 401) {
+        const terms = /terms|t&c|tnc|agreement|conditions/i.test(text);
+        return new PerpError(terms ? "POLICY_DENIED" : "SIGNATURE_FAILED", `QFEX funding: ${text} ${at}`, {
+            ...base, remediation: terms
+                ? "Accept the latest QFEX terms on the website, then retry"
+                : "Authentication was refused: check the system clock and the key (perp wallet agent import qfex --replace). Nothing was executed",
+        });
+    }
+    if (httpStatus === 403) {
+        return new PerpError("POLICY_DENIED", `QFEX funding: ${text} ${at}`, {
+            ...base, remediation: `The key needs the "Deposit and withdraw" permission (only "All accounts" keys can have it), or the account cannot use funding. ${website}`,
+        });
+    }
+    if (httpStatus === 429)
+        return new PerpError("RATE_LIMITED", `QFEX funding: ${text} ${at}`, { ...base, remediation: CODE_REMEDIATION.RATE_LIMITED });
+    if (httpStatus >= 400 && httpStatus < 500)
+        return new PerpError("ACTION_REJECTED", `QFEX funding refused: ${text} ${at}`, base);
+    return new PerpError("EXCHANGE_ERROR", `QFEX funding: ${text} ${at}`, base);
+}

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

@@ -0,0 +1,122 @@
+/**
+ * QFEX public market data (design §14.8 as amended by §14.12 #6, #7, #10).
+ *
+ * Sources (all public):
+ *   GET /refdata                 instruments: tick, lot, min/max quantity, price band, status,
+ *                                quote / margin asset, allowed order types + TIFs, market hours
+ *   MDS market_stats snapshot    mark price (each entry with its own `time`), open interest,
+ *                                24h notional volume
+ *   GET /md/contracts            funding_rate / next_funding_rate_timestamp (funding reads only)
+ *
+ * Coupling (§14.12 #10): order-entry precision comes from /refdata ALONE (fetchQfexInstruments).
+ * Markets need /refdata + the MDS snapshot. Only funding reads need /md/contracts — its failure
+ * fails fetchFundingRates, never market listing or order entry.
+ *
+ * Funding is UNVERIFIED (venue flag fundingVerified: false, Q4): the rate's unit is not
+ * confirmed against settled payments and `funding_rate` vs `next_funding_rate` is undecided.
+ * Markets therefore carry fundingRate null; fetchFundingRates returns the raw `funding_rate`
+ * for the explicit, flagged reads only (`perp funding`, `arb scan --include-unverified`).
+ *
+ * Symbols: "AAPL-USD" → CLI symbol "AAPL". Non-USD quotes keep the suffix ("SKHYNIX-KRW"),
+ * have no canonical symbol and are NOT tradable through perp-cli (USD-assuming sizing / risk).
+ */
+import type { VenuePublicData } from "../venue.js";
+import type { AssetClass, FundingRateBasis, Network, VenueFundingRate, VenueMarket } from "../venue-types.js";
+import { QfexClient } from "./client.js";
+export declare const QFEX_FUNDING_BASIS: FundingRateBasis;
+export declare const QFEX_SETTLEMENT_HOURS = 1;
+export declare const QFEX_USD_SUFFIX = "-USD";
+/**
+ * Pre-IPO perps (docs /qfex/pre-ipo-stocks). /refdata does not mark them (they are listed as
+ * EQUITY), so the list is explicit; its completeness is Q12. Their price convention (implied
+ * valuation per notional share count) is venue-specific → never matched across venues.
+ */
+export declare const QFEX_PRE_IPO: ReadonlySet<string>;
+export interface QfexSessionWindow {
+    session: string;
+    open: string;
+    close: string;
+}
+export interface QfexRefdataRow {
+    symbol: string;
+    status: string;
+    product_category: string;
+    tick_size: string;
+    lot_size: string;
+    min_price: string;
+    max_price: string;
+    min_quantity: string;
+    max_quantity: string;
+    default_max_leverage: number;
+    base_asset: string;
+    quote_asset: string;
+    margin_asset: string;
+    order_types: string[];
+    order_time_in_force: string[];
+    market_hours: Record<string, unknown> | null;
+}
+export interface QfexContractRow {
+    ticker_id: string;
+    funding_rate: string;
+    next_funding_rate: string;
+    next_funding_rate_timestamp: number;
+}
+/** One instrument, as order entry needs it — from /refdata only. */
+export interface QfexInstrument {
+    venueSymbol: string;
+    symbol: string;
+    status: string;
+    assetClass: AssetClass;
+    tickSize: string;
+    lotSize: string;
+    minQuantity: string;
+    maxQuantity: string;
+    /** Current price band (orders outside it are rejected before the engine). */
+    band: {
+        lower: string;
+        upper: string;
+    };
+    maxLeverage: number;
+    quoteAsset: string;
+    marginAsset: string;
+    orderTypes: readonly string[];
+    timeInForce: readonly string[];
+    marketHours: Record<string, unknown> | null;
+}
+/** "AAPL-USD" → "AAPL"; a non-USD quote keeps its suffix ("SKHYNIX-KRW"). */
+export declare function qfexPlainSymbol(venueSymbol: string): string;
+/** CLI symbol ("aapl", "AAPL", "AAPL-USD", "SKHYNIX-KRW") → venue symbol. A bare ticker is the USD market. */
+export declare function qfexVenueSymbol(symbol: string): string;
+export declare function qfexAssetClass(row: Pick<QfexRefdataRow, "symbol" | "product_category" | "base_asset">): AssetClass;
+export declare function toQfexInstrument(raw: unknown): QfexInstrument;
+/** Is the market one perp-cli may send orders to? USD-quoted and ACTIVE (§14.12 #7). */
+export declare function qfexTradable(i: Pick<QfexInstrument, "status" | "quoteAsset">): boolean;
+/**
+ * Whether `nowMs` falls inside a `session: "open"` window of the instrument's market_hours
+ * (weekday + local time in its `tz`). null = the venue published no usable schedule.
+ * This is the underlying's regular session only — it is NOT used to infer whether funding
+ * accrues (the schedule and the documented funding hours do not map 1:1, Q9).
+ */
+export declare function qfexUnderlyingOpen(marketHours: Record<string, unknown> | null, nowMs: number): boolean | null;
+export declare function qfexPublicClient(net: Network): QfexClient;
+/** Every instrument of /refdata (all statuses). The only input of order-entry validation. */
+export declare function fetchQfexInstruments(client: QfexClient): Promise<QfexInstrument[]>;
+export declare function buildQfexMarkets(instruments: readonly QfexInstrument[], snap: {
+    marks: ReadonlyMap<string, {
+        price: string;
+        time: number;
+    }>;
+    openInterest: ReadonlyMap<string, string>;
+    volumeNotional: ReadonlyMap<string, string>;
+}, nowMs: number): {
+    markets: VenueMarket[];
+    activeWithoutMark: string[];
+};
+export declare function buildQfexFundingRates(instruments: readonly QfexInstrument[], contracts: readonly QfexContractRow[], marks: ReadonlyMap<string, {
+    price: string;
+    time: number;
+}>, nowMs: number): {
+    rates: VenueFundingRate[];
+    unlisted: string[];
+};
+export declare const qfexPublicData: VenuePublicData;

package/dist/exchanges/qfex/public.js

@@ -0,0 +1,268 @@
+/**
+ * QFEX public market data (design §14.8 as amended by §14.12 #6, #7, #10).
+ *
+ * Sources (all public):
+ *   GET /refdata                 instruments: tick, lot, min/max quantity, price band, status,
+ *                                quote / margin asset, allowed order types + TIFs, market hours
+ *   MDS market_stats snapshot    mark price (each entry with its own `time`), open interest,
+ *                                24h notional volume
+ *   GET /md/contracts            funding_rate / next_funding_rate_timestamp (funding reads only)
+ *
+ * Coupling (§14.12 #10): order-entry precision comes from /refdata ALONE (fetchQfexInstruments).
+ * Markets need /refdata + the MDS snapshot. Only funding reads need /md/contracts — its failure
+ * fails fetchFundingRates, never market listing or order entry.
+ *
+ * Funding is UNVERIFIED (venue flag fundingVerified: false, Q4): the rate's unit is not
+ * confirmed against settled payments and `funding_rate` vs `next_funding_rate` is undecided.
+ * Markets therefore carry fundingRate null; fetchFundingRates returns the raw `funding_rate`
+ * for the explicit, flagged reads only (`perp funding`, `arb scan --include-unverified`).
+ *
+ * Symbols: "AAPL-USD" → CLI symbol "AAPL". Non-USD quotes keep the suffix ("SKHYNIX-KRW"),
+ * have no canonical symbol and are NOT tradable through perp-cli (USD-assuming sizing / risk).
+ */
+import { PerpError } from "../../errors.js";
+import { canonicalFor } from "../canonical-symbols.js";
+import { QFEX_ENDPOINTS } from "../venues/qfex.js";
+import { QfexClient } from "./client.js";
+import { fetchQfexMarketStats, QFEX_MDS_TIMEOUT_MS } from "./ws-transport.js";
+export const QFEX_FUNDING_BASIS = { kind: "perHours", hours: 1 };
+export const QFEX_SETTLEMENT_HOURS = 1;
+export const QFEX_USD_SUFFIX = "-USD";
+/**
+ * Pre-IPO perps (docs /qfex/pre-ipo-stocks). /refdata does not mark them (they are listed as
+ * EQUITY), so the list is explicit; its completeness is Q12. Their price convention (implied
+ * valuation per notional share count) is venue-specific → never matched across venues.
+ */
+export const QFEX_PRE_IPO = new Set(["ANTHROPIC", "OPENAI"]);
+// ── Symbols ──
+/** "AAPL-USD" → "AAPL"; a non-USD quote keeps its suffix ("SKHYNIX-KRW"). */
+export function qfexPlainSymbol(venueSymbol) {
+    return venueSymbol.endsWith(QFEX_USD_SUFFIX) ? venueSymbol.slice(0, -QFEX_USD_SUFFIX.length) : venueSymbol;
+}
+/** CLI symbol ("aapl", "AAPL", "AAPL-USD", "SKHYNIX-KRW") → venue symbol. A bare ticker is the USD market. */
+export function qfexVenueSymbol(symbol) {
+    const up = symbol.trim().toUpperCase().replace(/-PERP$/, "");
+    if (up.length === 0)
+        throw new PerpError("INVALID_PARAMS", "symbol is empty");
+    return up.includes("-") ? up : `${up}${QFEX_USD_SUFFIX}`;
+}
+const CATEGORY_TO_ASSET_CLASS = {
+    EQUITY: "equity",
+    INDEX: "index",
+    COMMODITY: "commodity",
+    FX: "fx",
+};
+export function qfexAssetClass(row) {
+    const c = CATEGORY_TO_ASSET_CLASS[row.product_category];
+    if (c === undefined) {
+        throw new PerpError("EXCHANGE_ERROR", `QFEX: cannot classify ${row.symbol} (product_category ${JSON.stringify(row.product_category)})`, {
+            remediation: "Update CATEGORY_TO_ASSET_CLASS in src/exchanges/qfex/public.ts for the new venue category",
+        });
+    }
+    return c === "equity" && QFEX_PRE_IPO.has(row.base_asset) ? "preIpo" : c;
+}
+function requireString(row, key) {
+    const v = row[key];
+    if (typeof v !== "string" || v === "")
+        throw new PerpError("EXCHANGE_ERROR", `QFEX /refdata: ${String(row.symbol)} has no ${key}`);
+    return v;
+}
+function stringList(row, key) {
+    const v = row[key];
+    if (!Array.isArray(v) || v.some(x => typeof x !== "string"))
+        throw new PerpError("EXCHANGE_ERROR", `QFEX /refdata: ${String(row.symbol)} has no ${key} list`);
+    return v;
+}
+export function toQfexInstrument(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        throw new PerpError("EXCHANGE_ERROR", "QFEX /refdata: instrument row is not an object");
+    const row = raw;
+    const venueSymbol = requireString(row, "symbol");
+    const lev = row.default_max_leverage;
+    if (typeof lev !== "number" || !Number.isFinite(lev) || lev <= 0) {
+        throw new PerpError("EXCHANGE_ERROR", `QFEX /refdata: ${venueSymbol} has no default_max_leverage`);
+    }
+    const hours = row.market_hours;
+    const base = requireString(row, "base_asset");
+    const category = requireString(row, "product_category");
+    return {
+        venueSymbol,
+        symbol: qfexPlainSymbol(venueSymbol),
+        status: requireString(row, "status"),
+        assetClass: qfexAssetClass({ symbol: venueSymbol, product_category: category, base_asset: base }),
+        tickSize: requireString(row, "tick_size"),
+        lotSize: requireString(row, "lot_size"),
+        minQuantity: requireString(row, "min_quantity"),
+        maxQuantity: requireString(row, "max_quantity"),
+        band: { lower: requireString(row, "min_price"), upper: requireString(row, "max_price") },
+        maxLeverage: lev,
+        quoteAsset: requireString(row, "quote_asset"),
+        marginAsset: requireString(row, "margin_asset"),
+        orderTypes: stringList(row, "order_types"),
+        timeInForce: stringList(row, "order_time_in_force"),
+        marketHours: hours !== null && typeof hours === "object" && !Array.isArray(hours) ? hours : null,
+    };
+}
+/** Is the market one perp-cli may send orders to? USD-quoted and ACTIVE (§14.12 #7). */
+export function qfexTradable(i) {
+    return i.status === "ACTIVE" && i.quoteAsset === "USD";
+}
+// ── Market hours → session ──
+const WEEKDAYS = ["sunday", "monday", "tuesday", "wednesday", "thursday", "friday", "saturday"];
+/**
+ * Whether `nowMs` falls inside a `session: "open"` window of the instrument's market_hours
+ * (weekday + local time in its `tz`). null = the venue published no usable schedule.
+ * This is the underlying's regular session only — it is NOT used to infer whether funding
+ * accrues (the schedule and the documented funding hours do not map 1:1, Q9).
+ */
+export function qfexUnderlyingOpen(marketHours, nowMs) {
+    if (marketHours === null || typeof marketHours.tz !== "string")
+        return null;
+    let parts;
+    try {
+        parts = new Intl.DateTimeFormat("en-US", {
+            timeZone: marketHours.tz, weekday: "long", hour: "2-digit", minute: "2-digit", second: "2-digit", hourCycle: "h23",
+        }).formatToParts(new Date(nowMs));
+    }
+    catch {
+        return null; // an unknown IANA zone name is "no usable schedule", not a closed market
+    }
+    const get = (t) => parts.find(p => p.type === t)?.value;
+    const weekday = get("weekday")?.toLowerCase();
+    const h = get("hour"), m = get("minute"), s = get("second");
+    if (weekday === undefined || !WEEKDAYS.includes(weekday) || h === undefined || m === undefined || s === undefined)
+        return null;
+    const now = `${h}:${m}:${s}`;
+    const day = marketHours[weekday];
+    if (day === undefined)
+        return false; // no window listed for this weekday
+    if (!Array.isArray(day))
+        return null;
+    for (const w of day) {
+        if (w === null || typeof w !== "object")
+            return null;
+        const win = w;
+        if (typeof win.session !== "string" || typeof win.open !== "string" || typeof win.close !== "string")
+            return null;
+        if (win.session === "open" && now >= win.open && now <= win.close)
+            return true;
+    }
+    return false;
+}
+function sessionOf(i, nowMs) {
+    const open = qfexUnderlyingOpen(i.marketHours, nowMs);
+    if (open === null)
+        return null;
+    return { underlyingOpen: open, priceBand: i.band, marginMultiplier: null };
+}
+// ── Fetchers ──
+export function qfexPublicClient(net) {
+    const ep = QFEX_ENDPOINTS[net];
+    return new QfexClient({ restUrl: ep.rest, bankerUrl: ep.banker, network: net, credentials: null, accountId: null });
+}
+/** Every instrument of /refdata (all statuses). The only input of order-entry validation. */
+export async function fetchQfexInstruments(client) {
+    const body = await client.publicGet("/refdata", null);
+    if (!Array.isArray(body.data))
+        throw new PerpError("EXCHANGE_ERROR", "QFEX /refdata: response has no data list");
+    return body.data.map(toQfexInstrument);
+}
+function canonicalOf(i) {
+    // A local-currency quote is a different contract from the USD one (ZHIPU-HKD vs ZHIPU-USD).
+    if (i.quoteAsset !== "USD")
+        return null;
+    return canonicalFor("qfex", i.symbol, i.assetClass);
+}
+export function buildQfexMarkets(instruments, snap, nowMs) {
+    const markets = [];
+    const activeWithoutMark = [];
+    for (const i of instruments) {
+        const mark = snap.marks.get(i.venueSymbol);
+        if (mark === undefined) {
+            if (i.status === "ACTIVE")
+                activeWithoutMark.push(i.venueSymbol);
+            continue; // no price feed → cannot be priced; never given a made-up mark
+        }
+        const oi = snap.openInterest.get(i.venueSymbol);
+        const vol = snap.volumeNotional.get(i.venueSymbol);
+        markets.push({
+            venue: "qfex",
+            venueSymbol: i.venueSymbol,
+            symbol: i.symbol,
+            canonical: canonicalOf(i),
+            assetClass: i.assetClass,
+            settle: i.marginAsset,
+            quoteAsset: i.quoteAsset,
+            markPrice: mark.price,
+            indexPrice: null,
+            fundingRate: null, // unverified (Q4) — see module header
+            fundingRateBasis: QFEX_FUNDING_BASIS,
+            settlementIntervalHours: QFEX_SETTLEMENT_HOURS,
+            openInterest: oi === undefined ? null : oi,
+            volume24h: vol === undefined ? null : vol,
+            tickSize: i.tickSize,
+            stepSize: i.lotSize,
+            minSize: i.minQuantity,
+            minNotional: null, // REJECTED_LESS_THAN_MIN_NOTIONAL exists but the threshold is unpublished
+            maxLeverage: i.maxLeverage,
+            marginTiers: null,
+            session: sessionOf(i, nowMs),
+            tradable: qfexTradable(i),
+        });
+    }
+    return { markets, activeWithoutMark };
+}
+async function fetchMarkets(net) {
+    const instruments = await fetchQfexInstruments(qfexPublicClient(net));
+    const snap = await fetchQfexMarketStats(QFEX_ENDPOINTS[net].mdsWs, "*", QFEX_MDS_TIMEOUT_MS);
+    const { markets, activeWithoutMark } = buildQfexMarkets(instruments, snap, Date.now());
+    if (activeWithoutMark.length > 0) {
+        console.warn(`[qfex] excluded ${activeWithoutMark.length} active market(s) without a mark price: ${activeWithoutMark.join(", ")}`);
+    }
+    return markets;
+}
+export function buildQfexFundingRates(instruments, contracts, marks, nowMs) {
+    const byVenueSymbol = new Map(instruments.map(i => [i.venueSymbol, i]));
+    const rates = [];
+    const unlisted = [];
+    for (const c of contracts) {
+        const i = byVenueSymbol.get(c.ticker_id);
+        if (i === undefined) {
+            unlisted.push(c.ticker_id);
+            continue;
+        }
+        if (i.status !== "ACTIVE")
+            continue;
+        if (typeof c.funding_rate !== "string" || c.funding_rate === "") {
+            throw new PerpError("EXCHANGE_ERROR", `QFEX /md/contracts: ${c.ticker_id} has no funding_rate`);
+        }
+        const mark = marks.get(c.ticker_id);
+        const nextMs = typeof c.next_funding_rate_timestamp === "number" ? c.next_funding_rate_timestamp * 1000 : null;
+        rates.push({
+            venue: "qfex",
+            venueSymbol: c.ticker_id,
+            symbol: i.symbol,
+            canonical: canonicalOf(i),
+            rate: c.funding_rate,
+            basis: QFEX_FUNDING_BASIS,
+            markPrice: mark === undefined ? null : mark.price,
+            // A timestamp in the past is not a "next" funding time (seen on closed markets).
+            nextFundingTime: nextMs !== null && nextMs > nowMs ? nextMs : null,
+        });
+    }
+    return { rates, unlisted };
+}
+async function fetchFundingRates(net) {
+    const client = qfexPublicClient(net);
+    const instruments = await fetchQfexInstruments(client);
+    const body = await client.publicGet("/md/contracts", null);
+    if (!Array.isArray(body.data))
+        throw new PerpError("EXCHANGE_ERROR", "QFEX /md/contracts: response has no data list");
+    const snap = await fetchQfexMarketStats(QFEX_ENDPOINTS[net].mdsWs, "*", QFEX_MDS_TIMEOUT_MS);
+    const { rates, unlisted } = buildQfexFundingRates(instruments, body.data, snap.marks, Date.now());
+    if (unlisted.length > 0) {
+        console.warn(`[qfex] excluded ${unlisted.length} contract(s) missing from /refdata: ${unlisted.join(", ")}`);
+    }
+    return rates;
+}
+export const qfexPublicData = { fetchMarkets, fetchFundingRates };