perp-cli 0.15.0 → 0.16.0

package/dist/exchanges/public-balances.d.ts

@@ -0,0 +1,25 @@
+import { type Network, type PublicBalanceResult, type PublicPositionsOptions } from "./venue.js";
+import type { LighterVenueId } from "./venues/lighter-family.js";
+/**
+ * Hyperliquid: info `clearinghouseState` (native perp dex), `userAbstraction` (the mode decides
+ * the equity source, exactly as the keyed getBalance) and `spotClearinghouseState` (spot rows;
+ * in unified / portfolio mode also the collateral), plus `meta.collateralToken` when the mode needs
+ * it. HIP-3: `clearinghouseState {dex}` for every dex of `perpDexs` (paced: hlDexFanOut); a dex
+ * balance is that dex's own perp clearinghouse, listed when its account value is non-zero. A dex
+ * (or the dex list) that fails is an `errors` entry ("hip3:<dex>") — unknown, never zero; the
+ * native, mode or spot read failing fails the venue.
+ */
+export declare function hyperliquidBalanceByAddress(net: Network, address: string): Promise<PublicBalanceResult>;
+/**
+ * Lighter / Lighter RH: `GET /account?by=l1_address` lists every account of the address; each
+ * account's balance (lighterBalanceOf) and spot assets (lighterSpotBalanceRows) are one
+ * `accounts` row. `accountIndex` narrows to one account (not one of the address's →
+ * INVALID_PARAMS); no account → empty `accounts` + note.
+ */
+export declare function lighterBalanceByAddress(venue: LighterVenueId, net: Network, address: string, opts: PublicPositionsOptions): Promise<PublicBalanceResult>;
+/**
+ * Pacifica: `GET /account?account=` (balance + spot_balances), `/positions?account=` and
+ * `/info/prices` — pacificaBalanceOf with the keyed extras (usdcBalance, borrowedUsdc,
+ * pendingInterest, availableToWithdraw). The address is validated as base58 32 bytes by the caller.
+ */
+export declare function pacificaBalanceByAddress(net: Network, address: string): Promise<PublicBalanceResult>;

package/dist/exchanges/public-balances.js

@@ -0,0 +1,158 @@
+/**
+ * Balances of ANY account by its public address, keyless (`perp account balance --address`, MCP
+ * get_balance_by_address). Wired into the registry through VenuePublicData.fetchBalanceByAddress;
+ * the balance comes from the same functions as the keyed adapters' getBalance (hlBalanceOf /
+ * lighterBalanceOf / pacificaBalanceOf) and the spot rows from the keyed spot mappers
+ * (hlSpotBalanceRows / lighterSpotBalanceRows / pacificaSpotBalanceRows). Read-only GETs / info
+ * POSTs; nothing is signed, no key is loaded.
+ */
+import { classifyError, PerpError } from "../errors.js";
+import { getVenue, networkConfig } from "./venue.js";
+import { chooseLighterAccounts, hlDexFanOut, hlDexNamesOf, lighterAccountIndexOf } from "./public-positions.js";
+function errorOf(e, venue) {
+    const s = classifyError(e, venue);
+    return { code: s.code, message: s.message };
+}
+/** A venue read failure as a typed error (the public HTTP helpers throw plain Errors on HTTP status). */
+async function typed(venue, read) {
+    try {
+        return await read();
+    }
+    catch (e) {
+        if (e instanceof PerpError)
+            throw e;
+        const s = classifyError(e, venue);
+        throw new PerpError(s.code === "UNKNOWN" ? "EXCHANGE_ERROR" : s.code, s.message, { exchange: venue });
+    }
+}
+const EMPTY = { balance: null, spot: null, accounts: null, dexes: null, accountMode: null };
+/** spotClearinghouseState `balances`, every row with a coin and numeric total / hold (unreadable → EXCHANGE_ERROR, never "0"). */
+function hlSpotBalancesOf(state) {
+    const balances = state?.balances;
+    if (!Array.isArray(balances))
+        throw new PerpError("EXCHANGE_ERROR", "hyperliquid spotClearinghouseState: no balances array", { exchange: "hyperliquid" });
+    for (const b of balances) {
+        const num = (v) => typeof v === "string" && v !== "" && Number.isFinite(Number(v));
+        if (typeof b?.coin !== "string" || !num(b.total) || !num(b.hold)) {
+            throw new PerpError("EXCHANGE_ERROR", `hyperliquid spotClearinghouseState: unreadable balance row ${JSON.stringify(b).slice(0, 160)}`, { exchange: "hyperliquid" });
+        }
+    }
+    return balances;
+}
+/**
+ * Hyperliquid: info `clearinghouseState` (native perp dex), `userAbstraction` (the mode decides
+ * the equity source, exactly as the keyed getBalance) and `spotClearinghouseState` (spot rows;
+ * in unified / portfolio mode also the collateral), plus `meta.collateralToken` when the mode needs
+ * it. HIP-3: `clearinghouseState {dex}` for every dex of `perpDexs` (paced: hlDexFanOut); a dex
+ * balance is that dex's own perp clearinghouse, listed when its account value is non-zero. A dex
+ * (or the dex list) that fails is an `errors` entry ("hip3:<dex>") — unknown, never zero; the
+ * native, mode or spot read failing fails the venue.
+ */
+export async function hyperliquidBalanceByAddress(net, address) {
+    const { legacyPublicJson } = await import("../funding/legacy-public.js");
+    const { legacyPublicBaseUrl } = await import("../api/public/urls.js");
+    const { hlAbstractionModeOf, hlBalanceOf, hlSpotUsdPricesOf } = await import("./hyperliquid.js");
+    const { hlSpotBalanceRows } = await import("./hyperliquid-spot.js");
+    const url = `${legacyPublicBaseUrl("hyperliquid", net)}/info`;
+    const post = (body, label) => legacyPublicJson("hyperliquid", url, label, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+    });
+    const errors = {};
+    const [native, modeRaw, spotState, dexList] = await Promise.all([
+        typed("hyperliquid", () => post({ type: "clearinghouseState", user: address }, "info clearinghouseState")),
+        typed("hyperliquid", () => post({ type: "userAbstraction", user: address }, "info userAbstraction")),
+        typed("hyperliquid", () => post({ type: "spotClearinghouseState", user: address }, "info spotClearinghouseState")),
+        post({ type: "perpDexs" }, "info perpDexs").then(hlDexNamesOf, (e) => { errors.hip3 = errorOf(e, "hyperliquid"); return []; }),
+    ]);
+    const mode = hlAbstractionModeOf(modeRaw);
+    const balances = hlSpotBalancesOf(spotState);
+    let token = null;
+    const collateralToken = () => (token ??= typed("hyperliquid", () => post({ type: "meta" }, "info meta")).then((meta) => {
+        const idx = meta?.collateralToken;
+        if (typeof idx !== "number" || !Number.isInteger(idx) || idx < 0) {
+            throw new PerpError("EXCHANGE_ERROR", `Hyperliquid meta has no collateralToken (got ${JSON.stringify(idx)})`, { exchange: "hyperliquid" });
+        }
+        return idx;
+    }));
+    const nativeState = native;
+    const { balance, notes } = await hlBalanceOf(nativeState, mode, "", {
+        collateralToken,
+        spotCollateralRow: async () => {
+            const t = await collateralToken();
+            return { row: balances.find(b => Number(b.token) === t) ?? null, balances, token: t, portfolioMarginRatio: spotState.portfolioMarginRatio };
+        },
+        spotUsdPrices: async () => hlSpotUsdPricesOf(await typed("hyperliquid", () => post({ type: "spotMetaAndAssetCtxs" }, "info spotMetaAndAssetCtxs"))),
+    });
+    const unified = mode === "unified" || mode === "portfolio";
+    const out = notes.map(n => n.trim());
+    if (unified) {
+        const av = nativeState.marginSummary?.accountValue;
+        const wd = nativeState.withdrawable;
+        const perp = [typeof av === "string" ? `accountValue ${av}` : null, typeof wd === "string" ? `withdrawable ${wd}` : null].filter(x => x !== null).join(", ");
+        out.push(`account mode ${mode}: equity / available come from the spot clearinghouse (the collateral balance already moves with perp PnL), as in the keyed balance; the native perp clearinghouse${perp !== "" ? ` (${perp})` : ""} is a per-dex view and is not added`);
+    }
+    // HIP-3 dex balances: the dex's own perp clearinghouse (standard semantics — the mode-dependent
+    // spot collateral is the top-level balance, never repeated per dex).
+    const dexes = {};
+    const noSpotRead = () => { throw new PerpError("EXCHANGE_ERROR", "internal: a HIP-3 dex balance read asked for spot state", { exchange: "hyperliquid" }); };
+    const perDex = await hlDexFanOut(net, dexList, dex => post({ type: "clearinghouseState", user: address, dex }, `info clearinghouseState dex ${dex}`));
+    for (const [i, res] of perDex.entries()) {
+        const dex = dexList[i];
+        if (res.status === "rejected") {
+            errors[`hip3:${dex}`] = errorOf(res.reason, "hyperliquid");
+            continue;
+        }
+        try {
+            const b = (await hlBalanceOf(res.value, "standard", dex, { collateralToken: noSpotRead, spotCollateralRow: noSpotRead, spotUsdPrices: noSpotRead })).balance;
+            if (Number(b.equity) !== 0)
+                dexes[dex] = b;
+        }
+        catch (e) {
+            errors[`hip3:${dex}`] = errorOf(e, "hyperliquid");
+        }
+    }
+    return { balance, spot: hlSpotBalanceRows({ balances }, mode), accounts: null, dexes, accountMode: mode, errors, notes: out };
+}
+/**
+ * Lighter / Lighter RH: `GET /account?by=l1_address` lists every account of the address; each
+ * account's balance (lighterBalanceOf) and spot assets (lighterSpotBalanceRows) are one
+ * `accounts` row. `accountIndex` narrows to one account (not one of the address's →
+ * INVALID_PARAMS); no account → empty `accounts` + note.
+ */
+export async function lighterBalanceByAddress(venue, net, address, opts) {
+    const { fetchLighterAccountsByL1 } = await import("./lighter-public.js");
+    const { lighterBalanceOf } = await import("./lighter.js");
+    const { lighterSpotBalanceRows } = await import("./lighter-spot.js");
+    const collateral = networkConfig(getVenue(venue), net).collateral[0];
+    if (collateral === undefined)
+        throw new PerpError("INVALID_PARAMS", `${venue} network config has no collateral`);
+    const accounts = await fetchLighterAccountsByL1(venue, net, address);
+    if (accounts === null || accounts.length === 0) {
+        return { ...EMPTY, accounts: [], errors: {}, notes: [`no ${venue === "lighter" ? "Lighter" : "Lighter RH"} account for this address`] };
+    }
+    const rows = chooseLighterAccounts(venue, accounts, opts.accountIndex).map(a => ({
+        accountIndex: lighterAccountIndexOf(a),
+        balance: lighterBalanceOf(a, venue, collateral),
+        spot: lighterSpotBalanceRows(a, venue, collateral),
+    }));
+    return { ...EMPTY, accounts: rows, errors: {}, notes: [] };
+}
+/**
+ * Pacifica: `GET /account?account=` (balance + spot_balances), `/positions?account=` and
+ * `/info/prices` — pacificaBalanceOf with the keyed extras (usdcBalance, borrowedUsdc,
+ * pendingInterest, availableToWithdraw). The address is validated as base58 32 bytes by the caller.
+ */
+export async function pacificaBalanceByAddress(net, address) {
+    const { PacificaClient } = await import("../pacifica/client.js");
+    const { pacificaBalanceOf } = await import("./pacifica.js");
+    const { pacificaSpotBalanceRows } = await import("./pacifica-spot.js");
+    const client = new PacificaClient({ network: net });
+    const [info, positions, prices] = await typed("pacifica", () => Promise.all([client.getAccount(address), client.getPositions(address), client.getPrices()]));
+    return {
+        ...EMPTY,
+        balance: pacificaBalanceOf(info, positions, prices),
+        spot: pacificaSpotBalanceRows(info),
+        errors: {},
+        notes: [],
+    };
+}

package/dist/exchanges/public-positions.d.ts

@@ -0,0 +1,43 @@
+import { type Network, type PublicPositionsOptions, type PublicPositionsResult } from "./venue.js";
+import type { LighterVenueId } from "./venues/lighter-family.js";
+/** Requests of a HIP-3 per-dex fan-out in flight at once. */
+export declare const HL_DEX_FANOUT_CONCURRENCY = 4;
+/** Burst of the fan-out's token bucket, in HL weight units (clearinghouseState weighs 2 → 10 requests). */
+export declare const HL_DEX_FANOUT_BURST = 20;
+/**
+ * One `read` per HIP-3 dex, paced: at most HL_DEX_FANOUT_CONCURRENCY in flight, and every request
+ * takes its weight from a token bucket refilled at the venue's documented rate
+ * (hyperliquidVenue.rateLimit: 1200 weight / min = 20 / s; clearinghouseState weight 2) with a
+ * small burst (HL_DEX_FANOUT_BURST) instead of the full minute's budget. HL mainnet lists ~10
+ * dexes (no wait); testnet ~272, where an unpaced burst got HTTP 429 on 62 of 272 reads at
+ * concurrency 4 — paced, the fan-out takes ~25 s instead. A failed read stays that dex's
+ * (settled per dex); nothing is retried.
+ */
+export declare function hlDexFanOut<T>(net: Network, dexes: readonly string[], read: (dex: string) => Promise<T>): Promise<PromiseSettledResult<T>[]>;
+/** Hyperliquid `perpDexs` → HIP-3 dex names (the first entry, null, is the native dex). */
+export declare function hlDexNamesOf(j: unknown): string[];
+/** Account index of a Lighter account object. */
+export declare function lighterAccountIndexOf(a: Record<string, unknown>): number;
+/** The accounts of an address a read covers: every one, or the one of `accountIndex` (not one of the address's → INVALID_PARAMS). */
+export declare function chooseLighterAccounts(venue: LighterVenueId, accounts: Array<Record<string, unknown>>, accountIndex: number | undefined): Array<Record<string, unknown>>;
+/**
+ * Hyperliquid: info `clearinghouseState` {user} for the native perp dex plus {user, dex} for every
+ * HIP-3 dex of `perpDexs` (one request each, paced: hlDexFanOut). Native rows carry `dex: null`, HIP-3 rows their dex
+ * and the prefixed coin ("xyz:GOLD"), as the HIP-3 market rows. A dex (or the dex list) that
+ * fails is an `errors` entry ("hip3:<dex>") — its rows are unknown, never silently dropped; the
+ * native read failing fails the venue.
+ */
+export declare function hyperliquidPositionsByAddress(net: Network, address: string): Promise<PublicPositionsResult>;
+/**
+ * Lighter / Lighter RH: `GET /account?by=l1_address` lists every account of the address
+ * (sub-accounts); each account's rows are tagged with its `accountIndex`. The venue keeps a
+ * zero-size row for every market an account ever touched: those are dropped by the mapper.
+ * `accountIndex` narrows to one account (not one of the address's → INVALID_PARAMS).
+ */
+export declare function lighterPositionsByAddress(venue: LighterVenueId, net: Network, address: string, opts: PublicPositionsOptions): Promise<PublicPositionsResult>;
+/**
+ * Pacifica: `GET /positions?account=` marked with `/info/prices`; unresolved leverage from the
+ * account's public `/account/settings`, then the market max (`/info`). The address is validated
+ * as base58 32 bytes by the caller (an EVM address would be answered `success: true, []`).
+ */
+export declare function pacificaPositionsByAddress(net: Network, address: string): Promise<PublicPositionsResult>;

package/dist/exchanges/public-positions.js

@@ -0,0 +1,154 @@
+/**
+ * Open positions of ANY account by its public address, keyless (`perp account positions
+ * --address`, MCP get_positions_by_address). Wired into the registry through
+ * VenuePublicData.fetchPositionsByAddress (+ addressKind); the rows come from the same mappers as
+ * the keyed adapters' getPositions (hlPositionRows / lighterPositionRows / pacificaPositionRows),
+ * with plain symbols. Read-only GETs / info POSTs; nothing is signed, no key is loaded.
+ */
+import { classifyError, PerpError } from "../errors.js";
+import { getVenue } from "./venue.js";
+import { acquireRate } from "./rate-limiter.js";
+function errorOf(e, venue) {
+    const s = classifyError(e, venue);
+    return { code: s.code, message: s.message };
+}
+/** A venue read failure as a typed error (the public HTTP helpers throw plain Errors on HTTP status). */
+async function typed(venue, read) {
+    try {
+        return await read();
+    }
+    catch (e) {
+        if (e instanceof PerpError)
+            throw e;
+        const s = classifyError(e, venue);
+        throw new PerpError(s.code === "UNKNOWN" ? "EXCHANGE_ERROR" : s.code, s.message, { exchange: venue });
+    }
+}
+/** Requests of a HIP-3 per-dex fan-out in flight at once. */
+export const HL_DEX_FANOUT_CONCURRENCY = 4;
+/** Burst of the fan-out's token bucket, in HL weight units (clearinghouseState weighs 2 → 10 requests). */
+export const HL_DEX_FANOUT_BURST = 20;
+/**
+ * One `read` per HIP-3 dex, paced: at most HL_DEX_FANOUT_CONCURRENCY in flight, and every request
+ * takes its weight from a token bucket refilled at the venue's documented rate
+ * (hyperliquidVenue.rateLimit: 1200 weight / min = 20 / s; clearinghouseState weight 2) with a
+ * small burst (HL_DEX_FANOUT_BURST) instead of the full minute's budget. HL mainnet lists ~10
+ * dexes (no wait); testnet ~272, where an unpaced burst got HTTP 429 on 62 of 272 reads at
+ * concurrency 4 — paced, the fan-out takes ~25 s instead. A failed read stays that dex's
+ * (settled per dex); nothing is retried.
+ */
+export async function hlDexFanOut(net, dexes, read) {
+    const venuePolicy = getVenue("hyperliquid").rateLimit;
+    const policy = { capacity: HL_DEX_FANOUT_BURST, refillPerSec: venuePolicy.refillPerSec, weights: venuePolicy.weights };
+    const out = new Array(dexes.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < dexes.length) {
+            const i = next++;
+            try {
+                await acquireRate(`hyperliquid:hip3-fanout:${net}`, policy, "clearinghouseState");
+                out[i] = { status: "fulfilled", value: await read(dexes[i]) };
+            }
+            catch (e) {
+                out[i] = { status: "rejected", reason: e };
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(HL_DEX_FANOUT_CONCURRENCY, dexes.length) }, worker));
+    return out;
+}
+/** Hyperliquid `perpDexs` → HIP-3 dex names (the first entry, null, is the native dex). */
+export function hlDexNamesOf(j) {
+    if (!Array.isArray(j))
+        throw new PerpError("EXCHANGE_ERROR", "hyperliquid perpDexs: expected an array", { exchange: "hyperliquid" });
+    return j.flatMap(d => (d !== null && typeof d === "object" && typeof d.name === "string" ? [d.name] : []));
+}
+/** Account index of a Lighter account object. */
+export function lighterAccountIndexOf(a) {
+    return Number(a.account_index ?? a.index);
+}
+/** The accounts of an address a read covers: every one, or the one of `accountIndex` (not one of the address's → INVALID_PARAMS). */
+export function chooseLighterAccounts(venue, accounts, accountIndex) {
+    if (accountIndex === undefined)
+        return accounts;
+    const chosen = accounts.filter(a => lighterAccountIndexOf(a) === accountIndex);
+    if (chosen.length === 0) {
+        throw new PerpError("INVALID_PARAMS", `${venue}: account index ${accountIndex} is not an account of this address (accounts: ${accounts.map(lighterAccountIndexOf).join(", ")})`, {
+            exchange: venue, remediation: `Use one of: ${accounts.map(lighterAccountIndexOf).join(", ")} — or drop --account-index for every account`,
+        });
+    }
+    return chosen;
+}
+/**
+ * Hyperliquid: info `clearinghouseState` {user} for the native perp dex plus {user, dex} for every
+ * HIP-3 dex of `perpDexs` (one request each, paced: hlDexFanOut). Native rows carry `dex: null`, HIP-3 rows their dex
+ * and the prefixed coin ("xyz:GOLD"), as the HIP-3 market rows. A dex (or the dex list) that
+ * fails is an `errors` entry ("hip3:<dex>") — its rows are unknown, never silently dropped; the
+ * native read failing fails the venue.
+ */
+export async function hyperliquidPositionsByAddress(net, address) {
+    const { legacyPublicJson } = await import("../funding/legacy-public.js");
+    const { legacyPublicBaseUrl } = await import("../api/public/urls.js");
+    const { hlPositionRows } = await import("./hyperliquid.js");
+    const url = `${legacyPublicBaseUrl("hyperliquid", net)}/info`;
+    const post = (body, label) => legacyPublicJson("hyperliquid", url, label, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body),
+    });
+    const errors = {};
+    const [native, dexList] = await Promise.all([
+        typed("hyperliquid", () => post({ type: "clearinghouseState", user: address }, "info clearinghouseState")),
+        post({ type: "perpDexs" }, "info perpDexs").then(hlDexNamesOf, (e) => { errors.hip3 = errorOf(e, "hyperliquid"); return []; }),
+    ]);
+    const positions = hlPositionRows(native, coin => coin).map(r => ({ ...r, dex: null }));
+    const perDex = await hlDexFanOut(net, dexList, dex => post({ type: "clearinghouseState", user: address, dex }, `info clearinghouseState dex ${dex}`));
+    perDex.forEach((res, i) => {
+        const dex = dexList[i];
+        if (res.status === "rejected") {
+            errors[`hip3:${dex}`] = errorOf(res.reason, "hyperliquid");
+            return;
+        }
+        try {
+            positions.push(...hlPositionRows(res.value, coin => (coin.includes(":") ? coin : `${dex}:${coin}`)).map(r => ({ ...r, dex })));
+        }
+        catch (e) {
+            errors[`hip3:${dex}`] = errorOf(e, "hyperliquid");
+        }
+    });
+    return { positions, errors, notes: [] };
+}
+/**
+ * Lighter / Lighter RH: `GET /account?by=l1_address` lists every account of the address
+ * (sub-accounts); each account's rows are tagged with its `accountIndex`. The venue keeps a
+ * zero-size row for every market an account ever touched: those are dropped by the mapper.
+ * `accountIndex` narrows to one account (not one of the address's → INVALID_PARAMS).
+ */
+export async function lighterPositionsByAddress(venue, net, address, opts) {
+    const { fetchLighterAccountsByL1, fetchLighterPriceDecimals } = await import("./lighter-public.js");
+    const { lighterPositionRows } = await import("./lighter.js");
+    const accounts = await fetchLighterAccountsByL1(venue, net, address);
+    if (accounts === null || accounts.length === 0)
+        return { positions: [], errors: {}, notes: [`no ${venue === "lighter" ? "Lighter" : "Lighter RH"} account for this address`] };
+    const chosen = chooseLighterAccounts(venue, accounts, opts.accountIndex);
+    const open = (a) => (Array.isArray(a.positions) ? a.positions : []).some(p => Number(p.position) !== 0);
+    // Price decimals only when there is a mark to format (an account without positions costs one read).
+    const decimals = chosen.some(open) ? await fetchLighterPriceDecimals(venue, net) : new Map();
+    const positions = chosen.flatMap(a => lighterPositionRows(a.positions, venue, sym => decimals.get(sym.toUpperCase())).map(r => ({ ...r, accountIndex: lighterAccountIndexOf(a) })));
+    return { positions, errors: {}, notes: [] };
+}
+/**
+ * Pacifica: `GET /positions?account=` marked with `/info/prices`; unresolved leverage from the
+ * account's public `/account/settings`, then the market max (`/info`). The address is validated
+ * as base58 32 bytes by the caller (an EVM address would be answered `success: true, []`).
+ */
+export async function pacificaPositionsByAddress(net, address) {
+    const { PacificaClient } = await import("../pacifica/client.js");
+    const { pacificaPositionRows } = await import("./pacifica.js");
+    const { legacyPublicData } = await import("../funding/legacy-public.js");
+    const client = new PacificaClient({ network: net });
+    const [rows, prices] = await typed("pacifica", () => Promise.all([client.getPositions(address), client.getPrices()]));
+    const positions = await pacificaPositionRows(rows, prices, {
+        accountSettings: () => client.getAccountSettings(address),
+        maxLeverage: async () => new Map((await legacyPublicData("pacifica").fetchMarkets(net)).map(m => [m.symbol, m.maxLeverage])),
+    });
+    return { positions, errors: {}, notes: [] };
+}

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

@@ -41,7 +41,7 @@
 import { PerpError } from "../../errors.js";
 import type { WithdrawGate } from "../../settings.js";
 import { type BuilderFeeGate } from "../builder-fee.js";
-import type { ExchangeAdapter, ExchangeBalance, ExchangeFundingPayment, ExchangeKline, ExchangeMarketInfo, ExchangeOrder, ExchangePosition, ExchangeTrade, ExchangePublicTrade } from "../interface.js";
+import type { ExchangeAdapter, ExchangeBalance, ExchangeFundingPayment, ExchangeKline, ExchangeMarketInfo, ExchangeOrder, ExchangePosition, ExchangeTrade, ExchangePublicTrade, FundingHistoryRow } from "../interface.js";
 import type { IocOutcome } from "../ioc-outcome.js";
 import type { ResolvedSlippage } from "../slippage.js";
 import type { TradingV2 } from "../trading-v2.js";
@@ -77,6 +77,22 @@ export declare function qfexClientOrderId(): string;
  * quantity) are quantized to the instrument tick / lot instead (fromWireNumber).
  */
 export declare function plainNumber(n: unknown, what: string): string;
+/**
+ * A QFEX `market list` / `market info` row: the legacy shape plus listing state and quote currency.
+ * Prices are in `quoteAsset`; `volume24h` is USD (null for a non-USD quote — no FX rate published),
+ * `volume24hQuote` the venue's 24h notional in `quoteAsset`.
+ */
+export type QfexMarketRow = ExchangeMarketInfo & {
+    tradable: boolean;
+    status: QfexListedStatus;
+    quoteAsset: string;
+    volume24hQuote: string | null;
+};
+/**
+ * Why a LISTED (ACTIVE) market is or is not tradable through perp-cli: "active" = tradable;
+ * "nonUsdQuote" = quoted in KRW / JPY / CNY / SEK / HKD — readable, never ordered (USD sizing).
+ */
+export type QfexListedStatus = "active" | "nonUsdQuote";
 export interface QfexAddOrderWire {
     symbol: string;
     side: "BUY" | "SELL";
@@ -143,6 +159,12 @@ export declare class QfexAdapter implements ExchangeAdapter, TradingV2 {
     private session;
     private instrumentMap;
     private instrumentOf;
+    /**
+     * Instrument of a per-symbol read (book / funding / kline / info). Unknown → SYMBOL_NOT_FOUND; a
+     * listed market whose /refdata status is not ACTIVE (DELISTED, INACTIVE) → SYMBOL_NOT_FOUND with
+     * that status: it is not a live market. A non-USD ACTIVE market is readable (only orders refuse it).
+     */
+    private readableInstrument;
     /** Refuse a market perp-cli must not send orders to, and an order type / TIF the symbol does not list. */
     private requireOrderable;
     /** Mark of ONE symbol from a single-symbol MDS subscription; PRICE_STALE when absent or older than QFEX_MARK_MAX_AGE_MS. */
@@ -261,19 +283,40 @@ export declare class QfexAdapter implements ExchangeAdapter, TradingV2 {
     private settleUnknownStopCancel;
     private settledByHistory;
     applyLeverage(symbol: string, leverage: number, marginMode: "cross" | "isolated" | null): Promise<LeverageResult>;
-    getMarkets(): Promise<ExchangeMarketInfo[]>;
+    /**
+     * Legacy rows plus `tradable` (ACTIVE and USD-quoted, qfexTradable), the /refdata `status`
+     * (ACTIVE / INACTIVE / DELISTED) and `quoteAsset` (prices of KRW / JPY / CNY / SEK / HKD markets
+     * are in that currency, not USD).
+     */
+    getMarkets(): Promise<QfexMarketRow[]>;
+    private marketRow;
+    /**
+     * `market info` of one ACTIVE market. fundingRate is the CURRENT /md/contracts `funding_rate`
+     * (the rate `market funding` / `arb scan --rates --include-unverified` show), labelled fundingVerified false: QFEX funding
+     * is unverified (Q4, display only). Market lists keep fundingRate null so no scan / bot reads it.
+     */
+    getMarketInfo(symbol: string): Promise<QfexMarketRow & {
+        fundingVerified: false;
+        fundingNote: string;
+        marketClosed: boolean | null;
+    }>;
+    /** `quoteAsset`: level prices are in the market's quote currency (KRW for SAMSUNG-KRW). */
     getOrderbook(symbol: string): Promise<{
         bids: [string, string][];
         asks: [string, string][];
+        quoteAsset: string;
     }>;
     getRecentTrades(): Promise<ExchangePublicTrade[]>;
-    /** Hourly funding windows (GET /funding/{symbol}, intervalMinutes 60). `limit` = hours back (default 24). */
-    getFundingHistory(symbol: string, limit?: number): Promise<{
-        time: number;
-        rate: string;
-        price: string | null;
-    }[]>;
-    getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<ExchangeKline[]>;
+    /**
+     * Hourly funding windows (GET /funding/{symbol}, intervalMinutes 60). `limit` = hours back (default 24).
+     * A window outside the market's funding hours (qfexFundingWindowClosed) is `rate: null,
+     * marketClosed: true` — the venue prints 0 there, which is "no funding", not a 0 rate.
+     */
+    getFundingHistory(symbol: string, limit?: number): Promise<FundingHistoryRow[]>;
+    /** Rows carry `quoteAsset`: OHLC prices are in the market's quote currency (KRW for SAMSUNG-KRW). */
+    getKlines(symbol: string, interval: string, startTime: number, endTime: number): Promise<Array<ExchangeKline & {
+        quoteAsset: string;
+    }>>;
     private userPositions;
     /** Equity is the venue's own figure (GET /user/subaccounts/equity) — never recomputed from balance fields. */
     getBalance(): Promise<ExchangeBalance>;

package/dist/exchanges/qfex/adapter.js

@@ -50,7 +50,7 @@ import { QFEX_BANKER_NETWORK, QFEX_ENDPOINTS, QFEX_WITHDRAW_DISABLED, QFEX_WITHD
 import { loadQfexCredentials, QFEX_IMPORT_REMEDIATION } from "./agent.js";
 import { QfexClient } from "./client.js";
 import { qfexStatusClass } from "./errors.js";
-import { fetchQfexInstruments, qfexPlainSymbol, qfexPublicData, qfexTradable, qfexVenueSymbol, } from "./public.js";
+import { buildQfexFundingRates, buildQfexMarkets, fetchQfexInstruments, fetchQfexMarketsWithInstruments, qfexFundingWindowClosed, qfexIndexPrices, qfexListedStatus, qfexPlainSymbol, qfexPublicData, qfexTradable, qfexVenueSymbol, } from "./public.js";
 import { QFEX_AUTOMATION_VERIFIED, QFEX_MODIFY_KEEPS_CLIENT_ID, QFEX_REDUCE_ONLY_WIRE, QFEX_STOP_CLIENT_ID_ECHO, decimalsEqual, fromWireNumber, isZeroDecimal, qfexAutomationGate, qfexReduceOnlyGate, reduceOnlyWireValue, subDecimals, sumDecimals, toWireNumber, weightedAveragePrice, } from "./signing.js";
 import { QFEX_IDLE_CLOSE_MS, QFEX_MDS_TIMEOUT_MS, QFEX_TIMEOUTS, fetchQfexMarketStats, qfexPendingRemediation, qfexTradeSession, } from "./ws-transport.js";
 /** A mark price entry older than this (its own venue `time`) is not used as an order reference. */
@@ -283,6 +283,20 @@ export class QfexAdapter {
         }
         return i;
     }
+    /**
+     * Instrument of a per-symbol read (book / funding / kline / info). Unknown → SYMBOL_NOT_FOUND; a
+     * listed market whose /refdata status is not ACTIVE (DELISTED, INACTIVE) → SYMBOL_NOT_FOUND with
+     * that status: it is not a live market. A non-USD ACTIVE market is readable (only orders refuse it).
+     */
+    async readableInstrument(symbol) {
+        const i = await this.instrumentOf(symbol);
+        if (i.status !== "ACTIVE") {
+            throw new PerpError("SYMBOL_NOT_FOUND", `QFEX ${i.venueSymbol} is ${i.status.toLowerCase()} (status ${i.status}) — not a live market`, {
+                exchange: "qfex", status: i.status, remediation: "List tradable markets with: perp market list -e qfex",
+            });
+        }
+        return i;
+    }
     /** Refuse a market perp-cli must not send orders to, and an order type / TIF the symbol does not list. */
     requireOrderable(i, orderType, tif) {
         if (i.status !== "ACTIVE") {
@@ -1111,26 +1125,70 @@ export class QfexAdapter {
         return { venue: "qfex", symbol: i.symbol, leverage: raw.leverage, marginMode: "cross", venueRaw: raw };
     }
     // ── Legacy ExchangeAdapter: market data ──
+    /**
+     * Legacy rows plus `tradable` (ACTIVE and USD-quoted, qfexTradable), the /refdata `status`
+     * (ACTIVE / INACTIVE / DELISTED) and `quoteAsset` (prices of KRW / JPY / CNY / SEK / HKD markets
+     * are in that currency, not USD).
+     */
     async getMarkets() {
-        return (await this.getVenueMarkets()).map(toLegacyMarketInfo);
+        const { markets, instruments, volumeNotional } = await fetchQfexMarketsWithInstruments(this.network);
+        const bySymbol = new Map(instruments.map(i => [i.venueSymbol, i]));
+        return markets.map(m => this.marketRow(m, bySymbol.get(m.venueSymbol), volumeNotional));
     }
+    marketRow(m, i, volumeNotional) {
+        if (i === undefined)
+            throw new PerpError("EXCHANGE_ERROR", `QFEX ${m.venueSymbol} is missing from /refdata`, { exchange: "qfex" });
+        return {
+            ...toLegacyMarketInfo(m), tradable: m.tradable, status: qfexListedStatus(i), quoteAsset: i.quoteAsset,
+            volume24hQuote: volumeNotional.get(i.venueSymbol) ?? null,
+        };
+    }
+    /**
+     * `market info` of one ACTIVE market. fundingRate is the CURRENT /md/contracts `funding_rate`
+     * (the rate `market funding` / `arb scan --rates --include-unverified` show), labelled fundingVerified false: QFEX funding
+     * is unverified (Q4, display only). Market lists keep fundingRate null so no scan / bot reads it.
+     */
+    async getMarketInfo(symbol) {
+        const i = await this.readableInstrument(symbol);
+        const snap = await fetchQfexMarketStats(QFEX_ENDPOINTS[this.network].mdsWs, i.venueSymbol, QFEX_MDS_TIMEOUT_MS);
+        const contracts = await this.client.publicGet("/md/contracts", null);
+        const { markets } = buildQfexMarkets([i], snap, Date.now(), qfexIndexPrices(listOf(contracts.data, "/md/contracts data")));
+        if (markets.length === 0)
+            throw new PerpError("PRICE_STALE", `QFEX ${i.venueSymbol}: no mark price in the market_stats snapshot`, { exchange: "qfex" });
+        const { rates } = buildQfexFundingRates([i], listOf(contracts.data, "/md/contracts data").filter(c => c.ticker_id === i.venueSymbol), snap.marks, Date.now());
+        return {
+            ...this.marketRow(markets[0], i, snap.volumeNotional),
+            fundingRate: rates.length === 0 ? null : rates[0].rate,
+            // true = the window in progress is outside the market's funding hours (fundingRate null).
+            marketClosed: rates.length === 0 ? null : rates[0].marketClosed === true,
+            fundingVerified: false,
+            fundingNote: "QFEX funding rate UNVERIFIED (not confirmed against settled payments) — display only, never a basis for trading",
+        };
+    }
+    /** `quoteAsset`: level prices are in the market's quote currency (KRW for SAMSUNG-KRW). */
     async getOrderbook(symbol) {
         // Resolved against refdata first: an unknown symbol is SYMBOL_NOT_FOUND, not the venue's
         // HTTP 404 surfacing as a retryable EXCHANGE_ERROR.
-        const venueSymbol = (await this.instrumentOf(symbol)).venueSymbol;
+        const instrument = await this.readableInstrument(symbol);
+        const venueSymbol = instrument.venueSymbol;
         const book = await this.client.publicGet(`/md/orderbook/${encodeURIComponent(venueSymbol)}`, null);
         // The venue lists empty price levels (quantity "0"); they are not part of the book.
         const side = (v, what) => listOf(v, what)
             .filter(l => Array.isArray(l) && typeof l[0] === "string" && typeof l[1] === "string" && Number(l[1]) > 0)
             .map(l => [l[0], l[1]]);
-        return { bids: side(book.bids, "orderbook bids"), asks: side(book.asks, "orderbook asks") };
+        return { bids: side(book.bids, "orderbook bids"), asks: side(book.asks, "orderbook asks"), quoteAsset: instrument.quoteAsset };
     }
     async getRecentTrades() {
         throw unsupported("qfex", "recentTrades", "the documented public trade endpoint (GET /public/trades) answers 404", "Use the order book: perp market book <symbol> -e qfex");
     }
-    /** Hourly funding windows (GET /funding/{symbol}, intervalMinutes 60). `limit` = hours back (default 24). */
+    /**
+     * Hourly funding windows (GET /funding/{symbol}, intervalMinutes 60). `limit` = hours back (default 24).
+     * A window outside the market's funding hours (qfexFundingWindowClosed) is `rate: null,
+     * marketClosed: true` — the venue prints 0 there, which is "no funding", not a 0 rate.
+     */
     async getFundingHistory(symbol, limit) {
-        const venueSymbol = (await this.instrumentOf(symbol)).venueSymbol;
+        const instrument = await this.readableInstrument(symbol);
+        const venueSymbol = instrument.venueSymbol;
         const hours = limit === undefined ? 24 : limit;
         if (!Number.isInteger(hours) || hours < 1)
             throw new PerpError("INVALID_PARAMS", `funding history limit must be a positive integer of hours (got ${hours})`);
@@ -1145,16 +1203,20 @@ export class QfexAdapter {
             const time = typeof r.windowStart === "string" ? Date.parse(r.windowStart) : NaN;
             if (!Number.isFinite(time))
                 throw new PerpError("EXCHANGE_ERROR", `QFEX funding history: invalid windowStart ${JSON.stringify(r.windowStart)}`);
-            out.push({ time, rate: plainNumber(r.rate, "funding rate"), price: null });
+            const rate = plainNumber(r.rate, "funding rate");
+            const marketClosed = qfexFundingWindowClosed(instrument.marketHours, time, Number(rate));
+            out.push({ time, rate: marketClosed ? null : rate, price: null, intervalHours: 1, rateKind: marketClosed ? null : "lastSettled", marketClosed });
         }
         return out.sort((a, b) => a.time - b.time);
     }
+    /** Rows carry `quoteAsset`: OHLC prices are in the market's quote currency (KRW for SAMSUNG-KRW). */
     async getKlines(symbol, interval, startTime, endTime) {
         const resolution = KLINE_RESOLUTION[interval.trim()];
         if (resolution === undefined) {
             throw new PerpError("INVALID_PARAMS", `Unsupported kline interval "${interval}" on QFEX`, { remediation: `Use one of: ${Object.keys(KLINE_RESOLUTION).join(", ")}` });
         }
-        const venueSymbol = (await this.instrumentOf(symbol)).venueSymbol;
+        const instrument = await this.readableInstrument(symbol);
+        const venueSymbol = instrument.venueSymbol;
         const body = await this.client.publicGet(`/candles/${encodeURIComponent(venueSymbol)}`, {
             resolution, fromISO: new Date(startTime).toISOString(), toISO: new Date(endTime).toISOString(),
         });
@@ -1162,7 +1224,10 @@ export class QfexAdapter {
             const time = Date.parse(c.startedAt);
             if (!Number.isFinite(time))
                 throw new PerpError("EXCHANGE_ERROR", `QFEX candles: invalid startedAt "${c.startedAt}"`);
-            return { time, open: c.open, high: c.high, low: c.low, close: c.close, ...qfexCandleVolumes(c), trades: null };
+            const v = qfexCandleVolumes(c);
+            // `usdVolume` is Σ price × qty in the QUOTE currency (live 2026-10-19: SAMSUNG-KRW 1m candles
+            // equal the KRW trade tape exactly); quoteVolume is USD → null for a non-USD quote.
+            return { time, open: c.open, high: c.high, low: c.low, close: c.close, ...v, quoteVolume: instrument.quoteAsset === "USD" ? v.quoteVolume : null, trades: null, quoteAsset: instrument.quoteAsset };
         }).sort((a, b) => a.time - b.time);
     }
     // ── Legacy ExchangeAdapter: account ──