perp-cli 0.14.3 → 0.16.0

package/dist/exchanges/precision.d.ts

@@ -1,5 +1,5 @@
 /**
- * Decimal-string precision helpers for order entry (design §10.10).
+ * Decimal-string precision helpers for order entry.
  *
  * All math is done on scaled BigInt to avoid float drift. Rules:
  * - limit prices that are not on tick are REJECTED (INVALID_TICK), never rounded;
@@ -24,6 +24,8 @@ export declare function requirePositive(value: string, what: string): void;
 export declare function requireOnTick(price: string, tickSize: string): string;
 /** Exact (a + b) / 2 of two plain decimal strings (no float arithmetic: 0.1 and 0.2 → "0.15"). */
 export declare function midDecimal(a: string, b: string): string;
+/** Exact decimal a + b (plain decimal strings). */
+export declare function addDecimal(a: string, b: string): string;
 /** Exact decimal a − b (plain decimal strings). */
 export declare function subDecimal(a: string, b: string): string;
 /** Exact decimal a × b (plain decimal strings). */

package/dist/exchanges/precision.js

@@ -1,5 +1,5 @@
 /**
- * Decimal-string precision helpers for order entry (design §10.10).
+ * Decimal-string precision helpers for order entry.
  *
  * All math is done on scaled BigInt to avoid float drift. Rules:
  * - limit prices that are not on tick are REJECTED (INVALID_TICK), never rounded;
@@ -119,6 +119,13 @@ export function midDecimal(a, b) {
     const scale = Math.max(x.scale, y.scale) + 1; // one more digit holds the possible ".5"
     return format((rescale(x, scale) + rescale(y, scale)) / 2n, scale);
 }
+/** Exact decimal a + b (plain decimal strings). */
+export function addDecimal(a, b) {
+    const x = parseDecimal(a);
+    const y = parseDecimal(b);
+    const scale = Math.max(x.scale, y.scale);
+    return format(rescale(x, scale) + rescale(y, scale), scale);
+}
 /** Exact decimal a − b (plain decimal strings). */
 export function subDecimal(a, b) {
     const x = parseDecimal(a);
@@ -195,7 +202,7 @@ export async function lotStepOf(adapter, symbol) {
         m = bare[0];
     }
     if (m === undefined) {
-        throw new PerpError("SYMBOL_NOT_FOUND", `${adapter.name}: market ${symbol} not found — lot step unknown`, { exchange: adapter.name });
+        throw new PerpError("SYMBOL_NOT_FOUND", `${adapter.name}: market ${symbol} not found — lot step unknown`, { exchange: adapter.name, remediation: `List markets: perp -e ${adapter.name} market list` });
     }
     if (m.stepSize !== null)
         return m.stepSize;

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

@@ -1,6 +1,5 @@
 /**
  * QFEX adapter — native TradingV2 + legacy ExchangeAdapter shim
- * (design §14.3–§14.6 as amended by §14.12; §10.7, §10.10, §13).
  *
  * Signer: imported HMAC API key only (QfexAgentMeta → ~/.perp/qfex-agents/<publicKey>.json).
  * Orders go over the Trade WebSocket (ws-transport.ts); account reads, leverage and transfers
@@ -42,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 } 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";
@@ -52,6 +51,20 @@ import { type QfexReduceOnlyWire } from "./signing.js";
 import { qfexPendingRemediation, type QfexOrderResponse } from "./ws-transport.js";
 /** A mark price entry older than this (its own venue `time`) is not used as an order reference. */
 export declare const QFEX_MARK_MAX_AGE_MS = 10000;
+/**
+ * Candle volumes. GET /candles returns `usdVolume` (populated) and `baseTokenVolume`, which the
+ * venue leaves "0" on traded candles (live 2026-10-14, CL-USD 1HOUR: baseTokenVolume "0" with
+ * usdVolume "52534.48506" on every row; startingOpenInterest / orderbookMidPrice* are "0" too).
+ * A base "0" next to a non-zero USD volume is a placeholder → null (unknown), never 0; when
+ * both are zero the candle really had no volume.
+ */
+export declare function qfexCandleVolumes(c: {
+    baseTokenVolume: unknown;
+    usdVolume: unknown;
+}): {
+    volume: string | null;
+    quoteVolume: string;
+};
 /** Client order id sent to the venue: a fresh UUID (the format the venue itself generates). */
 export declare function qfexClientOrderId(): string;
 /**
@@ -64,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";
@@ -130,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. */
@@ -215,7 +250,7 @@ export declare class QfexAdapter implements ExchangeAdapter, TradingV2 {
     /**
      * A reduce-only order the venue did not confirm as reduce-only (`reduce_only` false or absent
      * on an order frame — reduceOnlyUnconfirmedFrame — or on a read-back row of THIS order). The order may be live as a normal order, so the outcome is
-     * unknown (ORDER_PENDING, design §14.12 #4e: never re-sent). It is NOT cancelled here: a cancel
+     * unknown (ORDER_PENDING, never re-sent). It is NOT cancelled here: a cancel
      * is a second mutating command with its own unknown outcome and cannot undo a fill.
      */
     private reduceOnlyEchoError;
@@ -225,7 +260,7 @@ export declare class QfexAdapter implements ExchangeAdapter, TradingV2 {
     private orderResultOf;
     /**
      * Final filled size of an order placed through the legacy shim — non-null ONLY when a venue
-     * terminal frame was received (design §14.12 #3). A pending result is never an outcome.
+     * terminal frame was received. A pending result is never an outcome.
      */
     iocOutcomeOf(raw: unknown): IocOutcome | null;
     amendOrder(req: AmendRequest): Promise<OrderResult>;
@@ -248,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<ExchangeTrade[]>;
-    /** 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[]>;
+    getRecentTrades(): Promise<ExchangePublicTrade[]>;
+    /**
+     * 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>;