perp-cli 0.12.17 → 0.14.1

package/dist/config.d.ts

@@ -1,19 +1,70 @@
 import { Keypair } from "@solana/web3.js";
-export type Exchange = "pacifica" | "hyperliquid" | "lighter" | "aster";
+import type { Network, VenueId } from "./exchanges/venue-types.js";
+import type { VenueCredentials } from "./exchanges/venue.js";
+/** @deprecated alias — every venue id is an exchange id (design §10.3). */
+export type Exchange = VenueId;
+/** CLI (and MCP) inputs that select credentials. Absent flag = null. */
+export interface CliCredentialOpts {
+    privateKey: string | null;
+    /** --wallet <name>: OWS wallet, else local wallets.json entry */
+    wallet: string | null;
+    /** --ows <name> */
+    ows: string | null;
+    /** --ows-key <token> (or OWS_API_KEY env) */
+    owsKey: string | null;
+    /** --passphrase <pp> */
+    passphrase: string | null;
+}
+export declare const NO_CLI_CREDENTIAL_OPTS: CliCredentialOpts;
+/** True when the OWS vault holds a wallet with this name (no catch: a broken OWS install throws). */
+export declare function owsWalletExists(walletName: string): boolean;
 /**
- * Try to load a private key without throwing if none is found.
- * Returns null if no key is configured.
- */
-export declare function tryLoadPrivateKey(exchange: Exchange, pkOverride?: string, walletName?: string): Promise<string | null>;
-/**
- * Resolve an OWS wallet name to a signer-ready marker.
- * Returns the OWS wallet name prefixed with "ows:" so callers can detect OWS mode.
+ * Resolve an OWS wallet name to a signer-ready marker ("ows:<name>"), or null
+ * when the vault has no such wallet.
  */
 export declare function resolveOwsWallet(walletName: string): string | null;
 /** Check if a key string represents an OWS wallet reference. */
 export declare function isOwsKey(key: string): boolean;
 /** Extract OWS wallet name from an ows: prefixed key string. */
 export declare function getOwsWalletName(key: string): string;
-export declare function loadPrivateKey(exchange: Exchange, pkOverride?: string, walletName?: string): Promise<string>;
+/** CLI/MCP-shared credential resolution (design §10.2). */
+export declare function resolveCredentials(venue: VenueId, opts: CliCredentialOpts, network: Network): Promise<VenueCredentials>;
+/**
+ * Whether any credential source is configured for the venue (explicit checks,
+ * no catch). true does not mean the source is valid — creating the adapter
+ * surfaces that error.
+ */
+export declare function hasCredentials(venue: VenueId, opts: CliCredentialOpts): Promise<boolean>;
+/**
+ * Account-role venues (registry order) with a configured credential source —
+ * the default set for "all exchanges" aggregate views. Market-data-only venues
+ * never qualify.
+ */
+export declare function listConfiguredAccountVenues(opts?: CliCredentialOpts): Promise<VenueId[]>;
+/**
+ * Master key for a venue as a string: "ows:<name>" for OWS wallets, else the raw key.
+ * Throws NO_ENV_TIER for venues without an env/PK tier when nothing else is configured,
+ * and a setup hint when no source exists.
+ */
+export declare function loadPrivateKey(exchange: VenueId, pkOverride?: string, walletName?: string): Promise<string>;
+/** Root-program option values → credential selectors (shared by the CLI adapter factory and master-only commands). */
+export declare function cliCredentialOptsFrom(rootOpts: Record<string, unknown>): CliCredentialOpts;
+/**
+ * Commands that only the account owner can sign (deposit, withdraw, transfer, bridge, referral
+ * set, agent approve/revoke): refuse up front with NO_SIGNER_AVAILABLE when no master wallet is
+ * configured on this machine — e.g. only an agent / API key imported from the exchange website.
+ * Never falls back to the agent key (it cannot sign these). A configured-but-missing master
+ * (active wallet not in the vault) throws KEY_NOT_FOUND from resolveMasterKey.
+ */
+export declare function requireMasterWallet(venue: VenueId, opts: CliCredentialOpts, action: string): Promise<void>;
+/**
+ * The OWS master wallet selected by the CLI flags / active wallet, with the passphrase that opens
+ * it — for on-chain transactions the master signs itself (deposits, bridges). null when the
+ * master source is not an OWS wallet (none configured, or a raw private key).
+ */
+export declare function resolveOwsMaster(venue: VenueId, opts: CliCredentialOpts): Promise<{
+    wallet: string;
+    passphrase: string;
+} | null>;
 export declare function parseSolanaKeypair(input: string): Keypair;
 export declare function isEvmPrivateKey(input: string): boolean;

package/dist/config.js

@@ -4,32 +4,34 @@ import chalk from "chalk";
 import { resolve } from "path";
 import { existsSync, readFileSync } from "fs";
 import { createRequire } from "node:module";
+import { PerpError } from "./errors.js";
+import { isLegacyVenueId } from "./exchanges/venue-types.js";
 const _require = createRequire(import.meta.url);
 /**
- * Try to load a private key without throwing if none is found.
- * Returns null if no key is configured.
+ * Legacy env private-key variables (design §10.3). New venues have no env tier:
+ * loadPrivateKey()/resolveCredentials() never read env keys for them.
+ * v0.12.10 restored ASTER_PRIVATE_KEY so Aster Tier 3 env-PK loading works.
  */
-export async function tryLoadPrivateKey(exchange, pkOverride, walletName) {
-    try {
-        return await loadPrivateKey(exchange, pkOverride, walletName);
-    }
-    catch {
-        return null;
-    }
+const envMap = {
+    pacifica: ["PACIFICA_PRIVATE_KEY", "pk"],
+    hyperliquid: ["HYPERLIQUID_PRIVATE_KEY", "HL_PRIVATE_KEY"],
+    lighter: ["LIGHTER_PRIVATE_KEY"],
+    aster: ["ASTER_PRIVATE_KEY"],
+};
+export const NO_CLI_CREDENTIAL_OPTS = {
+    privateKey: null, wallet: null, ows: null, owsKey: null, passphrase: null,
+};
+/** True when the OWS vault holds a wallet with this name (no catch: a broken OWS install throws). */
+export function owsWalletExists(walletName) {
+    const { listWallets } = _require("@open-wallet-standard/core");
+    return listWallets().some((w) => w.name === walletName);
 }
 /**
- * Resolve an OWS wallet name to a signer-ready marker.
- * Returns the OWS wallet name prefixed with "ows:" so callers can detect OWS mode.
+ * Resolve an OWS wallet name to a signer-ready marker ("ows:<name>"), or null
+ * when the vault has no such wallet.
  */
 export function resolveOwsWallet(walletName) {
-    try {
-        const { getWallet } = _require("@open-wallet-standard/core");
-        getWallet(walletName); // throws if not found
-        return `ows:${walletName}`;
-    }
-    catch {
-        return null;
-    }
+    return owsWalletExists(walletName) ? `ows:${walletName}` : null;
 }
 /** Check if a key string represents an OWS wallet reference. */
 export function isOwsKey(key) {
@@ -39,80 +41,248 @@ export function isOwsKey(key) {
 export function getOwsWalletName(key) {
     return key.slice(4);
 }
-export async function loadPrivateKey(exchange, pkOverride, walletName) {
-    // 0a. OWS wallet (--ows flag sets walletName with "ows:" prefix)
-    if (walletName?.startsWith("ows:")) {
-        return walletName; // pass through — adapters detect the ows: prefix
+function legacyKeyFile(venue) {
+    return resolve(process.env.HOME || "~", ".perp", `${venue}.key`);
+}
+function envKeyOf(venue) {
+    for (const envVar of envMap[venue] ?? []) {
+        const v = process.env[envVar];
+        if (v)
+            return v;
     }
-    // 0b. Wallet name override (--wallet flag) — check OWS first, then local
-    if (walletName) {
-        // Try OWS vault
-        const owsKey = resolveOwsWallet(walletName);
-        if (owsKey)
-            return owsKey;
-        // Fall back to local wallets
+    // config.ts generic PRIVATE_KEY — recorded as out of scope in §10.11, legacy venues only.
+    const generic = process.env.PRIVATE_KEY;
+    return generic ? generic : null;
+}
+/**
+ * The master key source for a venue, in precedence order:
+ *   --ows → --wallet (OWS, else local wallets.json) → --private-key →
+ *   settings.owsActiveWallet → [legacy venues only] env → wallets.json active → ~/.perp/<venue>.key
+ * Returns null only when no source is configured. A configured source that
+ * cannot be resolved throws (SSOT Rule #2).
+ */
+async function resolveMasterKey(venue, opts) {
+    if (opts.ows !== null)
+        return { kind: "ows", wallet: opts.ows };
+    if (opts.wallet !== null) {
+        if (owsWalletExists(opts.wallet))
+            return { kind: "ows", wallet: opts.wallet };
         const { getWalletKeyByName } = await import("./commands/wallet.js");
-        const key = getWalletKeyByName(walletName);
+        const key = getWalletKeyByName(opts.wallet);
         if (!key)
-            throw new Error(`Wallet "${walletName}" not found. Run: perp wallet list`);
-        return key;
+            throw new PerpError("KEY_NOT_FOUND", `Wallet "${opts.wallet}" not found`, { remediation: "Run: perp wallet list" });
+        return { kind: "pk", key };
     }
-    // 1. CLI flag
-    if (pkOverride)
-        return pkOverride;
-    // 2. OWS active wallet (highest priority after explicit flags)
-    try {
-        const { loadSettings } = await import("./settings.js");
-        const settings = loadSettings();
-        if (settings.owsActiveWallet) {
-            const owsKey = resolveOwsWallet(settings.owsActiveWallet);
-            if (owsKey)
-                return owsKey;
+    if (opts.privateKey !== null)
+        return { kind: "pk", key: opts.privateKey };
+    const { loadSettings } = await import("./settings.js");
+    const active = loadSettings().owsActiveWallet;
+    if (active) {
+        if (!owsWalletExists(active)) {
+            throw new PerpError("KEY_NOT_FOUND", `Active OWS wallet "${active}" is not in the OWS vault`, {
+                remediation: "Run: perp wallet list, then select an existing wallet (perp wallet use <name>)",
+            });
         }
+        return { kind: "ows", wallet: active };
     }
-    catch {
-        // settings module not available, skip
-    }
-    // 3. Exchange-specific env vars
-    // v0.12.4 retired the legacy HMAC ASTER_API_KEY/SECRET path.
-    // v0.12.6 restored Aster as a normal EVM exchange in EXCHANGE_ENV_MAP
-    // (setup wizard / wallet show), but missed this map — leaving Tier 3
-    // env-PK loading broken. v0.12.10 restores ASTER_PRIVATE_KEY here so
-    // `tryLoadPrivateKey("aster")` finds the env value, mirroring HL/LT.
-    const envMap = {
-        pacifica: ["PACIFICA_PRIVATE_KEY", "pk"],
-        hyperliquid: ["HYPERLIQUID_PRIVATE_KEY", "HL_PRIVATE_KEY"],
-        lighter: ["LIGHTER_PRIVATE_KEY"],
-        aster: ["ASTER_PRIVATE_KEY"],
-    };
-    for (const envVar of envMap[exchange]) {
-        if (process.env[envVar])
-            return process.env[envVar];
-    }
-    // 4. Generic fallback
-    if (process.env.PRIVATE_KEY)
-        return process.env.PRIVATE_KEY;
-    // 5. Legacy: Active wallet from wallets.json
-    try {
-        const { getActiveWalletKey } = await import("./commands/wallet.js");
-        const walletKey = getActiveWalletKey(exchange);
-        if (walletKey)
-            return walletKey;
+    if (!isLegacyVenueId(venue))
+        return null;
+    const envKey = envKeyOf(venue);
+    if (envKey !== null)
+        return { kind: "pk", key: envKey };
+    const { getActiveWalletKey } = await import("./commands/wallet.js");
+    const walletKey = getActiveWalletKey(venue);
+    if (walletKey)
+        return { kind: "pk", key: walletKey };
+    const keyFile = legacyKeyFile(venue);
+    if (existsSync(keyFile))
+        return { kind: "pk", key: readFileSync(keyFile, "utf-8").trim() };
+    return null;
+}
+/** Registered agent meta for a venue (any network), or null — presence check only. */
+async function agentOf(venue) {
+    const store = await import("./agent-wallet/store.js");
+    switch (venue) {
+        case "ondo": return store.getVenueAgent("ondo");
+        case "arcus": return store.getVenueAgent("arcus");
+        case "qfex": return store.getVenueAgent("qfex");
+        case "pacifica":
+        case "hyperliquid":
+        case "lighter":
+        case "lighter-rh":
+        case "aster":
+            return store.getAgent(venue);
     }
-    catch {
-        // wallet module not available, skip
+}
+/**
+ * Agent meta to sign with on `network`. Legacy-shaped agents are selected by
+ * their recorded network (a mainnet agent is never handed to a testnet adapter).
+ * Ondo / Arcus metas are selected by their `network` field the same way.
+ */
+async function agentForNetwork(venue, network) {
+    const store = await import("./agent-wallet/store.js");
+    switch (venue) {
+        case "ondo": return store.getVenueAgentForNetwork("ondo", network);
+        case "arcus": return store.getVenueAgentForNetwork("arcus", network);
+        case "qfex": return store.getVenueAgentForNetwork("qfex", network);
+        case "pacifica":
+        case "hyperliquid":
+        case "lighter":
+        case "lighter-rh":
+        case "aster":
+            return store.getAgentForNetwork(venue, network);
     }
-    // 6. Legacy key file (~/.perp/<exchange>.key)
-    const keyFile = resolve(process.env.HOME || "~", ".perp", `${exchange}.key`);
-    if (existsSync(keyFile)) {
-        return readFileSync(keyFile, "utf-8").trim();
+}
+/**
+ * Passphrase that opens an OWS master wallet. Precedence between explicit
+ * user inputs: --ows-key token (routes through the OWS policy engine) →
+ * --passphrase → OWS_PASSPHRASE env. None given → "" (the OWS empty
+ * passphrase; this is what the pre-venue OWS path always used).
+ */
+function owsPassphraseOf(opts) {
+    if (opts.owsKey !== null)
+        return opts.owsKey;
+    if (opts.passphrase !== null)
+        return opts.passphrase;
+    if ("OWS_PASSPHRASE" in process.env)
+        return process.env.OWS_PASSPHRASE ?? "";
+    return "";
+}
+function owsKeyTokenOf(opts) {
+    if (opts.owsKey !== null)
+        return opts.owsKey;
+    // OWS_API_KEY env: recorded as out of scope in §10.11 (kept as before).
+    const env = process.env.OWS_API_KEY;
+    return env ? env : null;
+}
+/** CLI/MCP-shared credential resolution (design §10.2). */
+export async function resolveCredentials(venue, opts, network) {
+    const withToken = { ...opts, owsKey: owsKeyTokenOf(opts) };
+    // Custodial venues (masterKeyKind "none": qfex) have no master key to resolve.
+    const { ensureVenuesRegistered } = await import("./exchanges/venues/index.js");
+    const { getVenue } = await import("./exchanges/venue.js");
+    ensureVenuesRegistered();
+    const master = getVenue(venue).masterKeyKind === "none" ? null : await resolveMasterKey(venue, withToken);
+    return {
+        pk: master?.kind === "pk" ? master.key : null,
+        owsWallet: master?.kind === "ows" ? master.wallet : null,
+        owsPassphrase: master?.kind === "ows" ? owsPassphraseOf(withToken) : null,
+        owsKeyToken: withToken.owsKey,
+        agent: await agentForNetwork(venue, network),
+    };
+}
+/**
+ * Whether any credential source is configured for the venue (explicit checks,
+ * no catch). true does not mean the source is valid — creating the adapter
+ * surfaces that error.
+ */
+export async function hasCredentials(venue, opts) {
+    // A venue without any owner-wallet signing path (qfex: custodial, API key only) is configured
+    // only by an imported key — a master wallet / private key is not a credential for it.
+    const { ensureVenuesRegistered } = await import("./exchanges/venues/index.js");
+    const { getVenue } = await import("./exchanges/venue.js");
+    ensureVenuesRegistered();
+    if (getVenue(venue).masterKeyKind === "none")
+        return (await agentOf(venue)) !== null;
+    if (opts.ows !== null || opts.wallet !== null || opts.privateKey !== null)
+        return true;
+    if ((await agentOf(venue)) !== null)
+        return true;
+    const { loadSettings } = await import("./settings.js");
+    if (loadSettings().owsActiveWallet)
+        return true;
+    if (!isLegacyVenueId(venue))
+        return false;
+    if (envKeyOf(venue) !== null)
+        return true;
+    const { getActiveWalletKey } = await import("./commands/wallet.js");
+    if (getActiveWalletKey(venue))
+        return true;
+    return existsSync(legacyKeyFile(venue));
+}
+/**
+ * Account-role venues (registry order) with a configured credential source —
+ * the default set for "all exchanges" aggregate views. Market-data-only venues
+ * never qualify.
+ */
+export async function listConfiguredAccountVenues(opts = NO_CLI_CREDENTIAL_OPTS) {
+    const { ensureVenuesRegistered } = await import("./exchanges/venues/index.js");
+    const { listVenuesWithRole } = await import("./exchanges/venue.js");
+    ensureVenuesRegistered();
+    const venues = listVenuesWithRole("account").map(v => v.id);
+    const configured = await Promise.all(venues.map(v => hasCredentials(v, opts)));
+    return venues.filter((_, i) => configured[i]);
+}
+/**
+ * Master key for a venue as a string: "ows:<name>" for OWS wallets, else the raw key.
+ * Throws NO_ENV_TIER for venues without an env/PK tier when nothing else is configured,
+ * and a setup hint when no source exists.
+ */
+export async function loadPrivateKey(exchange, pkOverride, walletName) {
+    const opts = {
+        ...NO_CLI_CREDENTIAL_OPTS,
+        privateKey: pkOverride ?? null,
+        ows: walletName?.startsWith("ows:") ? walletName.slice(4) : null,
+        wallet: walletName && !walletName.startsWith("ows:") ? walletName : null,
+    };
+    const master = await resolveMasterKey(exchange, opts);
+    if (master?.kind === "ows")
+        return `ows:${master.wallet}`;
+    if (master?.kind === "pk")
+        return master.key;
+    if (!isLegacyVenueId(exchange)) {
+        throw new PerpError("NO_ENV_TIER", `${exchange} has no env/private-key tier`, {
+            remediation: `Use an OWS wallet (perp wallet generate, then --ows <name>) or register an agent: perp wallet agent approve ${exchange}`,
+        });
     }
-    throw new Error(`No wallet configured for ${exchange}.\n\n` +
+    throw new PerpError("NO_SIGNER_AVAILABLE", `No wallet configured for ${exchange}.\n\n` +
         `  Quick start:  ${chalk.cyan("perp wallet generate")}\n\n` +
         `  Or manually:\n` +
-        `    perp wallet import <key>     Import key to OWS vault\n` +
-        `    perp wallet set ${exchange} <key>  Legacy: set env var\n` +
-        `    --private-key <key>          Per-command override`);
+        `    perp wallet import           Import key to OWS vault (hidden prompt / stdin)\n` +
+        `    perp wallet set ${exchange}     Import key (hidden prompt / stdin) to OWS vault`, { exchange, remediation: masterMissingRemediation(exchange) });
+}
+/** Root-program option values → credential selectors (shared by the CLI adapter factory and master-only commands). */
+export function cliCredentialOptsFrom(rootOpts) {
+    const str = (v) => (typeof v === "string" ? v : null);
+    return {
+        privateKey: str(rootOpts.privateKey),
+        wallet: str(rootOpts.wallet),
+        ows: str(rootOpts.ows),
+        owsKey: str(rootOpts.owsKey),
+        passphrase: str(rootOpts.passphrase),
+    };
+}
+function masterMissingRemediation(venue) {
+    const chain = venue === "pacifica" ? "solana" : "evm";
+    return `Do this on the exchange website, or add the master wallet to this computer: perp wallet import --name <name> --chain ${chain} (hidden prompt / stdin), then perp wallet use <name> (or pass --ows <name>). An imported agent / API key can trade but cannot move funds.`;
+}
+/**
+ * Commands that only the account owner can sign (deposit, withdraw, transfer, bridge, referral
+ * set, agent approve/revoke): refuse up front with NO_SIGNER_AVAILABLE when no master wallet is
+ * configured on this machine — e.g. only an agent / API key imported from the exchange website.
+ * Never falls back to the agent key (it cannot sign these). A configured-but-missing master
+ * (active wallet not in the vault) throws KEY_NOT_FOUND from resolveMasterKey.
+ */
+export async function requireMasterWallet(venue, opts, action) {
+    const master = await resolveMasterKey(venue, { ...opts, owsKey: owsKeyTokenOf(opts) });
+    if (master !== null)
+        return;
+    throw new PerpError("NO_SIGNER_AVAILABLE", `${action} needs the ${venue} master wallet, which is not on this computer`, {
+        exchange: venue,
+        remediation: masterMissingRemediation(venue),
+    });
+}
+/**
+ * The OWS master wallet selected by the CLI flags / active wallet, with the passphrase that opens
+ * it — for on-chain transactions the master signs itself (deposits, bridges). null when the
+ * master source is not an OWS wallet (none configured, or a raw private key).
+ */
+export async function resolveOwsMaster(venue, opts) {
+    const withToken = { ...opts, owsKey: owsKeyTokenOf(opts) };
+    const master = await resolveMasterKey(venue, withToken);
+    if (master === null || master.kind !== "ows")
+        return null;
+    return { wallet: master.wallet, passphrase: owsPassphraseOf(withToken) };
 }
 export function parseSolanaKeypair(input) {
     // Try base58 first

package/dist/constants.d.ts

@@ -1,11 +1,36 @@
 /**
  * Shared constants for perp-cli.
  */
-/** Default taker fee per exchange (as fraction, e.g. 0.00035 = 0.035%) */
+/**
+ * Published taker fee per venue (fraction, e.g. 0.00035 = 0.035%) — configuration, not a
+ * fallback (SSOT Rule #2 shipped defaults): used when settings.fees has no entry for the venue.
+ */
 export declare const TAKER_FEES: Record<string, number>;
-/** Get taker fee for an exchange. Uses settings if available, falls back to defaults. */
+/**
+ * Published maker fee per venue (fraction; negative = rebate). Only venues whose base-tier
+ * maker rate is published and verified are listed; others resolve to 0 in getMakerFee().
+ */
+export declare const MAKER_FEES: Record<string, number>;
+/**
+ * Taker fee for a venue: settings.fees[venue].taker → TAKER_FEES[venue] → DEFAULT_TAKER_FEE
+ * (estimate for venues without a published entry). loadSettings() errors (malformed
+ * settings.json) propagate — never replaced by the built-in fees.
+ */
 export declare function getTakerFee(exchange: string): number;
-/** Get maker fee for an exchange. Uses settings if available. */
+/**
+ * Maker fee for a venue: settings.fees[venue].maker → MAKER_FEES[venue] → 0 (no maker fee
+ * published/configured). loadSettings() errors propagate.
+ */
 export declare function getMakerFee(exchange: string): number;
-/** Default taker fee for single-exchange use (when exchange is unknown). */
+/**
+ * Taker-fee estimate for an id with no TAKER_FEES entry. Every venue id in VENUE_IDS has
+ * a published entry above, so this applies only to genuinely unknown ids — e.g. arb-auto's
+ * getTakerFee("default") and trade-validator's venue-agnostic notional fee estimate.
+ */
 export declare const DEFAULT_TAKER_FEE = 0.00035;
+/**
+ * Hyperliquid's minimum order value, venue-wide (native perps and HIP-3 dexes): the venue refuses
+ * smaller orders with "Order must have minimum value of $10". It is a documented constant, not a
+ * field of `meta` / `metaAndAssetCtxs`, so it is the one order minimum that lives in code.
+ */
+export declare const HL_MIN_ORDER_VALUE_USD = "10";

package/dist/constants.js

@@ -2,36 +2,78 @@
  * Shared constants for perp-cli.
  */
 import { loadSettings } from "./settings.js";
-/** Default taker fee per exchange (as fraction, e.g. 0.00035 = 0.035%) */
+/**
+ * Published taker fee per venue (fraction, e.g. 0.00035 = 0.035%) — configuration, not a
+ * fallback (SSOT Rule #2 shipped defaults): used when settings.fees has no entry for the venue.
+ */
 export const TAKER_FEES = {
     hyperliquid: 0.00035,
     pacifica: 0.00035,
     lighter: 0,
     aster: 0.0004, // 0.04% taker fee
+    // Ondo Perps base rate (docs.ondoperps.xyz/fees, 2026-10-02): taker 5 bps. A limited-time
+    // 50% promotion (2.5 bps) is NOT assumed — it can end without notice; set
+    // settings.fees.ondo to use the promotional or a volume-tier rate.
+    ondo: 0.0005,
+    // Arcus mainnet tier 0 "Base" (GET https://api.arcus.xyz/v1/feetiers, read 2026-10-02):
+    // taker_fee_ppm 225. The docs publish no rates ("read fees from the API"); higher-volume
+    // tiers are cheaper (Bronze 190 … Max 95 ppm). Testnet Base differs (450 ppm).
+    arcus: 0.000225,
+    // Lighter RH "Standard" (default) account tier: 0% / 0% (apidocs.lighter.xyz lighter-rh).
+    // "Plus" is 0.005%/0.005%; "Premium" is 0.0120%/0.0350% (maker/taker) down to
+    // 0.0084%/0.0245% by 14-day volume — Premium accounts must set settings.fees["lighter-rh"].
+    "lighter-rh": 0,
+    // QFEX entry tier ("Tier 5", < $2m 30-day effective volume; docs.qfex.com/qfex/fees, read
+    // 2026-10-04): taker 0.10% on single stocks — the HIGHEST class rate, so index / commodity
+    // orders (0.05%) are never under-estimated. Lower tiers / the lifetime-tier promotion: set
+    // settings.fees.qfex.
+    qfex: 0.001,
 };
-/** Get taker fee for an exchange. Uses settings if available, falls back to defaults. */
+/**
+ * Published maker fee per venue (fraction; negative = rebate). Only venues whose base-tier
+ * maker rate is published and verified are listed; others resolve to 0 in getMakerFee().
+ */
+export const MAKER_FEES = {
+    ondo: 0.0002, // base 2 bps; promotional 1 bp not assumed (see TAKER_FEES.ondo)
+    arcus: 0, // mainnet Base tier maker_fee_ppm 0
+    // Aster perpetuals, Crypto — General (docs.asterdex.com trading/perpetuals/fees-and-specs/fees,
+    // read 2026-10-02): maker 0%, taker 0.04% (TAKER_FEES.aster). RWA markets: maker 0 bps.
+    aster: 0,
+    "lighter-rh": 0, // Standard tier (Premium: 0.012% under $1M 14-day volume)
+    qfex: 0.0005, // Tier 5 single stocks 0.05% (indices / commodities 0.02%); see TAKER_FEES.qfex
+};
+/**
+ * Taker fee for a venue: settings.fees[venue].taker → TAKER_FEES[venue] → DEFAULT_TAKER_FEE
+ * (estimate for venues without a published entry). loadSettings() errors (malformed
+ * settings.json) propagate — never replaced by the built-in fees.
+ */
 export function getTakerFee(exchange) {
     const key = exchange.toLowerCase();
-    try {
-        const settings = loadSettings();
-        if (settings.fees[key]?.taker !== undefined) {
-            return settings.fees[key].taker;
-        }
-    }
-    catch { /* fallback to hardcoded */ }
-    return TAKER_FEES[key] ?? 0.00035;
+    const configured = loadSettings().fees[key]?.taker;
+    if (configured !== undefined)
+        return configured;
+    return TAKER_FEES[key] ?? DEFAULT_TAKER_FEE;
 }
-/** Get maker fee for an exchange. Uses settings if available. */
+/**
+ * Maker fee for a venue: settings.fees[venue].maker → MAKER_FEES[venue] → 0 (no maker fee
+ * published/configured). loadSettings() errors propagate.
+ */
 export function getMakerFee(exchange) {
     const key = exchange.toLowerCase();
-    try {
-        const settings = loadSettings();
-        if (settings.fees[key]?.maker !== undefined) {
-            return settings.fees[key].maker;
-        }
-    }
-    catch { /* fallback */ }
-    return 0;
+    const configured = loadSettings().fees[key]?.maker;
+    if (configured !== undefined)
+        return configured;
+    return MAKER_FEES[key] ?? 0;
 }
-/** Default taker fee for single-exchange use (when exchange is unknown). */
+/**
+ * Taker-fee estimate for an id with no TAKER_FEES entry. Every venue id in VENUE_IDS has
+ * a published entry above, so this applies only to genuinely unknown ids — e.g. arb-auto's
+ * getTakerFee("default") and trade-validator's venue-agnostic notional fee estimate.
+ */
 export const DEFAULT_TAKER_FEE = 0.00035;
+/**
+ * Hyperliquid's minimum order value, venue-wide (native perps and HIP-3 dexes): the venue refuses
+ * smaller orders with "Order must have minimum value of $10". It is a documented constant, not a
+ * field of `meta` / `metaAndAssetCtxs`, so it is the one order minimum that lives in code.
+ */
+export const HL_MIN_ORDER_VALUE_USD = "10";

package/dist/dashboard/server.d.ts

@@ -63,6 +63,8 @@ export interface DashboardSnapshot {
         dexAssets: DexAssetRow[];
         dexNames: string[];
         exchangeStatus: Record<string, string>;
+        /** Error message per venue (or "funding" when the whole fetch failed). */
+        exchangeErrors: Record<string, string>;
     };
 }
 export interface DashboardOpts {

package/dist/dashboard/server.js

@@ -9,7 +9,7 @@ import { WebSocketServer, WebSocket } from "ws";
 import { getUI } from "./ui.js";
 import { WsFeedManager } from "./ws-feeds.js";
 // Cached arb data (polled less frequently)
-let cachedArb = { opportunities: [], dexArb: [], dexAssets: [], dexNames: [], exchangeStatus: {} };
+let cachedArb = { opportunities: [], dexArb: [], dexAssets: [], dexNames: [], exchangeStatus: {}, exchangeErrors: {} };
 // Cached market data (polled with arb cycle — market metadata rarely changes)
 const cachedMarkets = new Map();
 /**
@@ -40,10 +40,12 @@ async function pollArbData() {
     const opportunities = [];
     const dexArb = [];
     let exchangeStatus = {};
+    let exchangeErrors = {};
     try {
         const { fetchAllFundingRates } = await import("../funding/rates.js");
         const snapshot = await fetchAllFundingRates({ minSpread: 5 });
         exchangeStatus = snapshot.exchangeStatus;
+        exchangeErrors = snapshot.exchangeErrors;
         for (const sym of snapshot.symbols.slice(0, 20)) {
             opportunities.push({
                 symbol: sym.symbol,
@@ -60,8 +62,9 @@ async function pollArbData() {
             });
         }
     }
-    catch {
-        // funding rates unavailable
+    catch (e) {
+        exchangeStatus = { funding: "error" };
+        exchangeErrors = { funding: e instanceof Error ? e.message : String(e) };
     }
     const dexAssets = [];
     const dexNamesSet = new Set();
@@ -95,8 +98,8 @@ async function pollArbData() {
             const row = {
                 base,
                 dexes: assets.map((a) => {
-                    // All dex funding rates are already per-hour, same as hyperliquid
-                    const ann = annualizeRate(a.fundingRate, "hyperliquid");
+                    // Venue ref: "hyperliquid" for native, "hl:<dex>" for HIP-3 (same basis, §10.1)
+                    const ann = annualizeRate(a.fundingRate, a.dex === "hl" ? "hyperliquid" : `hl:${a.dex}`);
                     return { dex: a.dex, rate: a.fundingRate, annualizedPct: ann, markPrice: a.markPrice, oi: a.openInterest };
                 }),
             };
@@ -113,7 +116,7 @@ async function pollArbData() {
         // dex arb unavailable
     }
     const dexNames = [...dexNamesSet].sort();
-    return { opportunities, dexArb, dexAssets: dexAssets.slice(0, 30), dexNames, exchangeStatus };
+    return { opportunities, dexArb, dexAssets: dexAssets.slice(0, 30), dexNames, exchangeStatus, exchangeErrors };
 }
 /**
  * Poll all exchanges and return a unified snapshot.