perp-cli 0.12.17 → 0.14.0

package/dist/exchanges/builder-fee.js

@@ -0,0 +1,421 @@
+/**
+ * Builder fees — one uniform, default-OFF mechanism for every venue.
+ *
+ * A builder fee is an extra per-order fee the venue pays to a third-party "builder"
+ * (Hyperliquid builder codes, Pacifica builder program, Aster builder, Ondo builder
+ * codes). It is charged to the USER, so perp-cli never attaches one unless:
+ *   1. `settings.builder.<venue>` is set explicitly by the user (absent = off — there
+ *      is no shipped default and no env var), and
+ *   2. the venue approval the fee needs is CONFIRMED (venue status read, cached per
+ *      process for BUILDER_APPROVAL_TTL_MS; a builder-related order rejection drops the
+ *      cached read). Approval-free venues (Ondo) are confirmed by (1) alone.
+ * A builder-related order rejection is returned to the caller with remediation
+ * (--no-builder / re-approve) and is NEVER retried — re-sending is a new order.
+ * An order whose approval is missing / unknown is sent WITHOUT the fee and says so in
+ * `execution.notes` (and once on stderr) — the fee is the builder's, never a reason to
+ * fail or silently change the user's order. `--no-builder` disables it per command.
+ *
+ * Per-venue facts (official docs, checked 2026-10-02):
+ * - hyperliquid  https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes
+ *     ApproveBuilderFee signed by the MAIN wallet (an agent cannot sign it); order action
+ *     `builder: { b: <address>, f: <tenths of a bp> }`; max 0.1% perps / 1% spot; status
+ *     info `{ type: "maxBuilderFee", user, builder }`. HIP-3 dexes are not covered by the
+ *     docs → never attached there.
+ * - pacifica     https://pacifica.gitbook.io/docs/programs/builder-program.md
+ *     approve_builder_code { builder_code, max_fee_rate } signed by the account; per-order
+ *     `builder_code` on create_market / create / stop/create / positions/tpsl. TWAP
+ *     (create_twap_order) does not document builder_code → never sent there.
+ *     The builder sets its own fee_rate; the user's approved max_fee_rate caps it, so the
+ *     code is attached only while the approved max_fee_rate ≤ the configured feeBps (the
+ *     user's consent). The venue documents no ceiling → perp-cli caps the consent at 10
+ *     bps. Spot rejects it (err 108).
+ * - aster        https://asterdex.github.io/aster-api-website/asterCode/integration-flow/
+ *     + asterdex/api-docs demo/aster-code.py: approveBuilder { builder, maxFeeRate ≤ 0.001 }
+ *     master-signed; orders carry `builder` + `feeRate` (decimal) signed by the API wallet;
+ *     list GET /fapi/v3/builder, revoke DELETE /fapi/v3/builder (DelBuilder). The testnet
+ *     API documents no approveBuilder → testnet off.
+ * - ondo         https://docs.ondoperps.xyz/api-reference/integration_guide (+ rest-spec)
+ *     no user approval; per-order `builderCode: { code, feeRateBpsFractional }` on
+ *     POST /v1/perps/orders and POST /v1/perps/stop_order (stops do NOT inherit it); cap
+ *     10 bps; sandbox uses the same API.
+ * - qfex         https://docs.qfex.com/qfex/builder-code
+ *     fee SHARE, not an extra fee: the trader pays the normal venue fee and the venue credits
+ *     part of it to the builder (feeKind "share", feeBps null). No user approval. The code
+ *     (UUID) rides on the Trade WebSocket auth (`params.builder_code`) for the life of the
+ *     connection — never per order; an unknown code is not an error, so attribution is not
+ *     confirmable from the trader side. Prod codes mean nothing on UAT → testnet off.
+ * - lighter / lighter-rh: unsupported — see UNSUPPORTED below.
+ * - arcus: unsupported — see UNSUPPORTED below.
+ */
+import { PerpError, classifyError, isDefiniteOrderFailure, isTransportFailure, isUnknownOutcomeServerError } from "../errors.js";
+import { isVenueId } from "./venue-types.js";
+export const BUILDER_FEE_CAPABILITIES = {
+    hyperliquid: {
+        approval: "master", identity: "address", perpCapBps: 10, spotCapBps: 100, hip3: false, testnet: true,
+        feeStepBps: 0.1, feeKind: "exact", docs: "https://hyperliquid.gitbook.io/hyperliquid-docs/trading/builder-codes",
+    },
+    pacifica: {
+        approval: "master", identity: "code", perpCapBps: 10, spotCapBps: null, hip3: null, testnet: true,
+        feeStepBps: 0.01, feeKind: "max", docs: "https://pacifica.gitbook.io/docs/programs/builder-program.md",
+    },
+    aster: {
+        approval: "master", identity: "address", perpCapBps: 10, spotCapBps: null, hip3: null, testnet: false,
+        feeStepBps: 0.01, feeKind: "exact", docs: "https://asterdex.github.io/aster-api-website/asterCode/integration-flow/",
+    },
+    ondo: {
+        approval: "none", identity: "code", perpCapBps: 10, spotCapBps: null, hip3: null, testnet: true,
+        feeStepBps: 0.01, feeKind: "exact", docs: "https://docs.ondoperps.xyz/api-reference/integration_guide",
+    },
+    qfex: {
+        approval: "none", identity: "code", perpCapBps: null, spotCapBps: null, hip3: null, testnet: false,
+        feeStepBps: null, feeKind: "share", docs: "https://docs.qfex.com/qfex/builder-code",
+    },
+    lighter: null,
+    "lighter-rh": null,
+    arcus: null,
+};
+/** Why a venue has no builder-fee support (shown in CAPABILITY_UNSUPPORTED). */
+export const BUILDER_FEE_UNSUPPORTED = {
+    lighter: "not yet implemented in perp-cli — the official lighter-go signer can sign ApproveIntegrator and the per-order integrator fields, but perp-cli sends them as 0 (https://apidocs.lighter.xyz/docs/partner-integration)",
+    "lighter-rh": "not yet implemented in perp-cli — Lighter RH uses the same official lighter-go signer; partner-attribution fields are sent as 0 (https://apidocs.rh.lighter.xyz/docs/partner-attribution.md)",
+    arcus: "Arcus has no perps builder fee; its integrator fee applies to the spot router only and needs a partner key from Arcus (https://docs.arcus.xyz/concepts/spot-router)",
+};
+export function builderFeeUnsupported(venue) {
+    return new PerpError("CAPABILITY_UNSUPPORTED", `${venue} does not support builderFee — ${BUILDER_FEE_UNSUPPORTED[venue] ?? "no builder-fee mechanism"}`, {
+        venue, feature: "builderFee", reason: BUILDER_FEE_UNSUPPORTED[venue] ?? "no builder-fee mechanism",
+        remediation: `Builder fees are available on: ${builderFeeVenues().join(", ")}`,
+    });
+}
+export function builderFeeVenues() {
+    return Object.keys(BUILDER_FEE_CAPABILITIES).filter(v => BUILDER_FEE_CAPABILITIES[v] !== null);
+}
+/** Capability of a venue, or CAPABILITY_UNSUPPORTED. */
+export function requireBuilderCapability(venue) {
+    const cap = BUILDER_FEE_CAPABILITIES[venue];
+    if (cap === null)
+        throw builderFeeUnsupported(venue);
+    return cap;
+}
+/** The configured user-paid fee of an "exact" / "max" venue. A "share" target has none. */
+export function requireFeeBps(t) {
+    if (t.feeBps === null)
+        throw new PerpError("INVALID_PARAMS", `${t.venue} builder attribution carries no fee (fee share)`);
+    return t.feeBps;
+}
+const ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+/** Pacifica: "alphanumeric, max 16 characters" (builder-program docs). */
+const PACIFICA_CODE_RE = /^[A-Za-z0-9]{1,16}$/;
+/** Ondo documents no format; refuse whitespace / control characters and absurd lengths. */
+const ONDO_CODE_RE = /^[A-Za-z0-9_-]{1,64}$/;
+/** QFEX builder codes are UUIDs (docs builder-code / authenticate). */
+const QFEX_CODE_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Validate one settings.builder.<venue> entry. Throws `invalid(problem)` — never clamps
+ * or rewrites a value. Returns the normalized target.
+ */
+export function parseBuilderEntry(venue, raw, invalid) {
+    if (!isVenueId(venue))
+        throw invalid(`builder: unknown venue "${venue}"`);
+    const cap = BUILDER_FEE_CAPABILITIES[venue];
+    if (cap === null)
+        throw invalid(`builder.${venue}: ${venue} does not support builder fees — ${BUILDER_FEE_UNSUPPORTED[venue] ?? ""}`);
+    if (cap.feeKind === "share") {
+        // Fee share: the code only. A feeBps key is refused — there is no user-paid fee to configure.
+        if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+            throw invalid(`builder.${venue} must be { code: <uuid> } (fee share — no feeBps)`);
+        }
+        const s = raw;
+        for (const k of Object.keys(s)) {
+            if (k !== "code")
+                throw invalid(`builder.${venue}: unknown key "${k}" (expected code only — ${venue} builder codes share the venue fee, the user pays nothing extra)`);
+        }
+        if (typeof s.code !== "string" || !QFEX_CODE_RE.test(s.code)) {
+            throw invalid(`builder.${venue}.code must be a UUID (got ${JSON.stringify(s.code)})`);
+        }
+        return { venue, identity: s.code.toLowerCase(), feeBps: null };
+    }
+    if (cap.perpCapBps === null || cap.feeStepBps === null) {
+        throw invalid(`builder.${venue}: capability declares no fee cap / increment`);
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw invalid(`builder.${venue} must be { ${cap.identity}: <${cap.identity}>, feeBps: <number> }`);
+    }
+    const e = raw;
+    for (const k of Object.keys(e)) {
+        if (k !== cap.identity && k !== "feeBps")
+            throw invalid(`builder.${venue}: unknown key "${k}" (expected ${cap.identity}, feeBps)`);
+    }
+    const id = e[cap.identity];
+    let identity;
+    if (cap.identity === "address") {
+        if (typeof id !== "string" || !ADDRESS_RE.test(id))
+            throw invalid(`builder.${venue}.address must be a 0x-prefixed 20-byte EVM address (got ${JSON.stringify(id)})`);
+        identity = id.toLowerCase();
+    }
+    else {
+        const re = venue === "pacifica" ? PACIFICA_CODE_RE : ONDO_CODE_RE;
+        if (typeof id !== "string" || !re.test(id)) {
+            throw invalid(`builder.${venue}.code must match ${re.source} (got ${JSON.stringify(id)})`);
+        }
+        identity = id;
+    }
+    const fee = e.feeBps;
+    if (typeof fee !== "number" || !Number.isFinite(fee) || fee <= 0) {
+        throw invalid(`builder.${venue}.feeBps must be a number of basis points > 0 (got ${JSON.stringify(fee)})`);
+    }
+    if (fee > cap.perpCapBps) {
+        throw invalid(`builder.${venue}.feeBps ${fee} exceeds the ${venue} cap of ${cap.perpCapBps} bps`);
+    }
+    const steps = fee / cap.feeStepBps;
+    if (Math.abs(steps - Math.round(steps)) > 1e-9) {
+        throw invalid(`builder.${venue}.feeBps ${fee} is not a multiple of the venue's ${cap.feeStepBps} bps increment`);
+    }
+    return { venue, identity, feeBps: fee };
+}
+/** Validate the whole settings.builder object (absent / null = nothing configured). */
+export function parseBuilderSettings(raw, invalid) {
+    const out = {};
+    if (raw === undefined || raw === null)
+        return out;
+    if (typeof raw !== "object" || Array.isArray(raw))
+        throw invalid("builder must be an object of { venue: { address|code, feeBps } }");
+    for (const [venue, entry] of Object.entries(raw)) {
+        const t = parseBuilderEntry(venue, entry, invalid);
+        const cap = BUILDER_FEE_CAPABILITIES[t.venue];
+        const stored = entry;
+        out[venue] = cap.feeKind === "share"
+            ? { code: stored.code }
+            : cap.identity === "address"
+                ? { address: stored.address, feeBps: t.feeBps }
+                : { code: stored.code, feeBps: t.feeBps };
+    }
+    return out;
+}
+/** "2.5 bps", or "fee share (no extra fee)" for a share target. */
+export function feeText(t) {
+    return t.feeBps === null ? "fee share (no extra fee)" : `${t.feeBps} bps`;
+}
+/** The configured target for a venue, or null (off). */
+export function builderTargetOf(builder, venue) {
+    const entry = builder[venue];
+    if (entry === undefined)
+        return null;
+    return parseBuilderEntry(venue, entry, p => new PerpError("INVALID_PARAMS", p));
+}
+export const NO_BUILDER = { applied: null, note: null };
+/** How long a venue approval read is reused before it is read again. */
+export const BUILDER_APPROVAL_TTL_MS = 5 * 60_000;
+/** Process-wide approval cache: `${venue}:${network}:${account}:${identity}` → status read + read time. */
+const _approvalCache = new Map();
+const _warned = new Set();
+/** Forget cached approval reads and stderr warnings (after approve / revoke; test hook). */
+export function resetBuilderApprovalCache() {
+    _approvalCache.clear();
+    _warned.clear();
+}
+/** Drop the cached approval reads of one venue + network (the next order re-reads the venue). */
+export function invalidateBuilderApproval(venue, network) {
+    const prefix = `${venue}:${network}:`;
+    for (const k of [..._approvalCache.keys()])
+        if (k.startsWith(prefix))
+            _approvalCache.delete(k);
+}
+/**
+ * Per-adapter builder-fee gate. Built only when settings.builder.<venue> is set
+ * (resolveBuilderGate) — an unconfigured venue has no gate and no notes at all.
+ */
+export class BuilderFeeGate {
+    target;
+    network;
+    skipReason;
+    readApproval;
+    accountOf;
+    constructor(target, network, 
+    /** Static reason the configured fee is never attached by this adapter (--no-builder, testnet). */
+    skipReason, 
+    /** Reads the venue approval for the active account; null when the venue has no approval step. */
+    readApproval, 
+    /** Account the approval belongs to (master address) — part of the cache key. */
+    accountOf) {
+        this.target = target;
+        this.network = network;
+        this.skipReason = skipReason;
+        this.readApproval = readApproval;
+        this.accountOf = accountOf;
+    }
+    get capability() {
+        return requireBuilderCapability(this.target.venue);
+    }
+    /** Venue approval for the configured builder (cached for BUILDER_APPROVAL_TTL_MS). Failures → "unknown". */
+    async approval() {
+        if (this.readApproval === null)
+            return { status: "approved", maxFeeBps: null };
+        const key = `${this.target.venue}:${this.network}:${this.accountOf().toLowerCase()}:${this.target.identity}`;
+        const cached = _approvalCache.get(key);
+        if (cached !== undefined && Date.now() - cached.at < BUILDER_APPROVAL_TTL_MS)
+            return cached.read;
+        const read = this.readApproval(this.target).then(a => a, 
+        // Recorded, not hidden: the decision carries the reason and the order goes out without the fee.
+        (e) => ({ status: "unknown", reason: e instanceof Error ? e.message : String(e) }));
+        _approvalCache.set(key, { read, at: Date.now() });
+        return read;
+    }
+    /**
+     * Whether the next perp order carries the fee. `hip3` = the order is on a Hyperliquid
+     * HIP-3 dex. Never throws: a fee that cannot be attached becomes a note.
+     */
+    async decide(opts) {
+        const t = this.target;
+        const cap = this.capability;
+        const skip = (why) => this.warnOnce({ applied: null, note: `builder fee not attached: ${why}` });
+        if (this.skipReason !== null)
+            return { applied: null, note: `builder fee not attached: ${this.skipReason}` };
+        if (opts.hip3 && cap.hip3 === false)
+            return skip("HIP-3 dex orders do not carry builder fees (not covered by the venue docs)");
+        const a = await this.approval();
+        if (a.status === "unknown") {
+            return skip(`${t.venue} approval for ${t.identity} could not be confirmed (${a.reason}) — check: perp${this.network === "testnet" ? " -n testnet" : ""} wallet builder status ${t.venue}`);
+        }
+        if (a.status === "notApproved") {
+            const have = a.maxFeeBps === null ? "none" : `${a.maxFeeBps} bps`;
+            return skip(`${t.venue} approval for ${t.identity} missing (approved max: ${have}, configured: ${feeText(t)}) — approve with: perp${this.network === "testnet" ? " -n testnet" : ""} wallet builder approve ${t.venue}`);
+        }
+        if (a.status === "aboveConsent") {
+            return skip(`${t.venue} approved max for ${t.identity} is ${a.maxFeeBps} bps, above the configured ${feeText(t)} — the builder could charge more than you configured; re-approve exactly ${feeText(t)}: perp${this.network === "testnet" ? " -n testnet" : ""} wallet builder approve ${t.venue}`);
+        }
+        return { applied: { venue: t.venue, identity: t.identity, feeBps: t.feeBps, feeKind: cap.feeKind, approvedMaxBps: a.maxFeeBps }, note: null };
+    }
+    warnOnce(d) {
+        const key = `${this.target.venue}:${this.network}:${d.note}`;
+        if (d.note !== null && !_warned.has(key)) {
+            _warned.add(key);
+            process.stderr.write(`[warn] ${d.note}\n`);
+        }
+        return d;
+    }
+}
+/**
+ * The gate for an adapter being created, or null when settings.builder.<venue> is not
+ * set (default) or the context is read-only. The single place builder settings are
+ * resolved (adapters never read settings).
+ */
+export function resolveBuilderGate(venue, ctx, builder, readApproval, accountOf) {
+    if (ctx.readOnly)
+        return null;
+    const target = builderTargetOf(builder, venue);
+    if (target === null)
+        return null;
+    const cap = requireBuilderCapability(venue);
+    let skipReason = null;
+    if (ctx.noBuilder)
+        skipReason = "disabled by --no-builder";
+    else if (ctx.network === "testnet" && !cap.testnet)
+        skipReason = `${venue} testnet has no builder-fee flow`;
+    return new BuilderFeeGate(target, ctx.network, skipReason, cap.approval === "none" ? null : readApproval, accountOf);
+}
+/** Gate held by an adapter (public `builderFee` field), or null. */
+export function builderGateOf(adapter) {
+    const g = adapter?.builderFee;
+    return g instanceof BuilderFeeGate ? g : null;
+}
+/** Decision for an adapter's next perp order (no gate = not configured = NO_BUILDER). */
+export async function builderDecisionOf(adapter, opts) {
+    const g = builderGateOf(adapter);
+    return g === null ? NO_BUILDER : g.decide(opts);
+}
+// ── Unit conversions (one place) ──
+/** Fee rate as a decimal fraction string: 2.5 bps → "0.00025". */
+export function bpsToRate(bps) {
+    const s = (bps / 10_000).toFixed(10).replace(/0+$/, "").replace(/\.$/, "");
+    return s === "" ? "0" : s;
+}
+/** Decimal fraction (string | number) → bps, or null when unreadable. */
+export function rateToBps(rate) {
+    const n = typeof rate === "number" ? rate : typeof rate === "string" && rate.trim() !== "" ? Number(rate) : NaN;
+    return Number.isFinite(n) && n >= 0 ? Math.round(n * 10_000 * 1e6) / 1e6 : null;
+}
+/** Hyperliquid `f` (tenths of a basis point). */
+export function hlFeeTenthsBps(bps) {
+    return Math.round(bps * 10);
+}
+/** Hyperliquid ApproveBuilderFee maxFeeRate: a percent string ("0.01%" = 1 bp). */
+export function hlMaxFeeRatePercent(bps) {
+    return `${bpsToRate(bps * 100)}%`;
+}
+/** feeKind "exact": approval verdict from the venue's approved ceiling (bps; null = no approval on record). */
+export function approvalFromMax(maxFeeBps, feeBps) {
+    // 1e-9 absorbs decimal-string → float conversion; never rounds a smaller approval up.
+    if (maxFeeBps !== null && maxFeeBps + 1e-9 >= feeBps)
+        return { status: "approved", maxFeeBps };
+    return { status: "notApproved", maxFeeBps };
+}
+/**
+ * feeKind "max" (Pacifica): the builder picks its own rate up to the approved ceiling, so the
+ * configured feeBps is the user's consent and the approved ceiling must not exceed it.
+ * null = no approval on record.
+ */
+export function approvalFromCeiling(maxFeeBps, feeBps) {
+    if (maxFeeBps === null)
+        return { status: "notApproved", maxFeeBps: null };
+    if (maxFeeBps - 1e-9 <= feeBps)
+        return { status: "approved", maxFeeBps };
+    return { status: "aboveConsent", maxFeeBps };
+}
+/**
+ * An order the venue rejected for a builder-related reason (the error text names the builder):
+ * the cached approval of that venue is dropped (the next order re-reads it) and the rejection is
+ * returned with remediation. The order is NOT retried — re-sending is a new order, so that stays
+ * the user's explicit choice. Any other error (or no gate) is returned unchanged.
+ */
+export function builderRejectionOf(adapter, err) {
+    const g = builderGateOf(adapter);
+    if (g === null)
+        return err;
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!/builder/i.test(msg))
+        return err;
+    // Only a DEFINITE venue rejection is re-described: an unknown outcome (ORDER_PENDING /
+    // ORDER_PARTIAL, a transport failure, a 5xx, any non-definite PerpError) keeps its own
+    // "do NOT resubmit" remediation — "re-send it without the fee" could double the order.
+    if (!isDefiniteBuilderRejection(err))
+        return err;
+    const venue = g.target.venue;
+    invalidateBuilderApproval(venue, g.network);
+    const n = g.network === "testnet" ? " -n testnet" : "";
+    const remediation = `The venue rejected the order over the builder fee; it was NOT retried. Re-send it without the fee (--no-builder), or re-approve: perp${n} wallet builder approve ${venue} (check: perp${n} wallet builder status ${venue})`;
+    const e = classifyError(err, venue);
+    return new PerpError(e.code, e.message, { ...(e.details ?? {}), exchange: venue, remediation });
+}
+/**
+ * true when `err` proves the order was refused (nothing placed): a PerpError with a definite code
+ * (isDefiniteOrderFailure), or a venue 4xx answer (details.httpStatus 4xx, not 429) whose code is
+ * not an unknown-outcome code; a plain Error that is neither a transport failure nor a 5xx
+ * unknown-outcome message (adapter-level venue refusal text).
+ */
+function isDefiniteBuilderRejection(err) {
+    if (err instanceof PerpError) {
+        const code = err.structured.code;
+        if (code === "ORDER_PENDING" || code === "ORDER_PARTIAL")
+            return false;
+        if (isDefiniteOrderFailure(err))
+            return true;
+        const http = err.structured.details?.httpStatus;
+        return typeof http === "number" && http >= 400 && http < 500 && http !== 429;
+    }
+    return !isTransportFailure(err) && !isUnknownOutcomeServerError(err);
+}
+/**
+ * Builder decision for a planned perp order on `symbol` (dry-run / preview): the same
+ * cached gate decision a live order would use. Hyperliquid resolves the asset id so a
+ * HIP-3 market reports "not attached".
+ */
+export async function builderPlanFor(adapter, symbol) {
+    if (builderGateOf(adapter) === null)
+        return NO_BUILDER;
+    const hl = adapter;
+    if (hl.name === "hyperliquid" && typeof hl.builderDecision === "function" && typeof hl.getAssetIndex === "function") {
+        const idx = symbol === null ? null : await hl.getAssetIndex.call(adapter, symbol.toUpperCase());
+        return hl.builderDecision.call(adapter, idx);
+    }
+    return builderDecisionOf(adapter, { hip3: false });
+}

package/dist/exchanges/canonical-symbols.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cross-venue canonical symbols — the single mapping source used to decide
+ * that two markets on different venues are the same underlying
+ * (design §4 L4, §10.9).
+ *
+ * Rules by asset class:
+ * - crypto:  ticker identity after the adapter strips its quote suffix, plus
+ *            DENOMINATION_ALIASES (kPEPE ≡ 1000PEPE, UBTC ≡ BTC ...).
+ * - equity / etf: exchange-listed ticker identity (TSLA on Ondo ≡ TSLA on
+ *            Arcus ≡ TSLA on Lighter RH ≡ xyz:TSLA on HIP-3). Adapters must
+ *            pass the plain ticker (e.g. strip Ondo's "-USD.P").
+ * - index / commodity / fx / preIpo: EXPLICIT table only. Same-looking names
+ *            are frequently different products (US500 vs USA500, USOIL vs CL),
+ *            so an unmapped market returns null and is excluded from matching.
+ */
+import type { AssetClass, VenueId } from "./venue-types.js";
+/** Denomination / wrapper aliases → canonical crypto ticker. */
+export declare const DENOMINATION_ALIASES: Readonly<Record<string, string>>;
+/**
+ * Explicit mapping for index / commodity / fx / preIpo markets.
+ * Key: `${venue}|${symbol}` (symbol as the adapter reports it; for HIP-3 use `hl:<dex>` as venue).
+ */
+export declare const EXPLICIT_CANONICAL: Readonly<Record<string, string>>;
+/** Pairs verified to be DIFFERENT products despite similar names. Never match. */
+export declare const NEVER_MATCH: ReadonlySet<string>;
+export declare function isNeverMatch(a: string, b: string): boolean;
+/**
+ * Canonical key for a market, or null when it must not be matched across venues.
+ * @param venueKey venue id, or `hl:<dex>` for HIP-3 dex markets
+ * @param symbol   plain symbol as reported by the adapter (no quote suffix, no dex prefix)
+ */
+export declare function canonicalFor(venueKey: VenueId | `hl:${string}`, symbol: string, assetClass: AssetClass): string | null;

package/dist/exchanges/canonical-symbols.js

@@ -0,0 +1,96 @@
+/**
+ * Cross-venue canonical symbols — the single mapping source used to decide
+ * that two markets on different venues are the same underlying
+ * (design §4 L4, §10.9).
+ *
+ * Rules by asset class:
+ * - crypto:  ticker identity after the adapter strips its quote suffix, plus
+ *            DENOMINATION_ALIASES (kPEPE ≡ 1000PEPE, UBTC ≡ BTC ...).
+ * - equity / etf: exchange-listed ticker identity (TSLA on Ondo ≡ TSLA on
+ *            Arcus ≡ TSLA on Lighter RH ≡ xyz:TSLA on HIP-3). Adapters must
+ *            pass the plain ticker (e.g. strip Ondo's "-USD.P").
+ * - index / commodity / fx / preIpo: EXPLICIT table only. Same-looking names
+ *            are frequently different products (US500 vs USA500, USOIL vs CL),
+ *            so an unmapped market returns null and is excluded from matching.
+ */
+/** Denomination / wrapper aliases → canonical crypto ticker. */
+export const DENOMINATION_ALIASES = {
+    KPEPE: "1000PEPE",
+    "1000PEPE": "1000PEPE",
+    KSHIB: "1000SHIB",
+    KBONK: "1000BONK",
+    KFLOKI: "1000FLOKI",
+    KLUNC: "1000LUNC",
+    KNEIRO: "1000NEIRO",
+    KDOGS: "1000DOGS",
+    // Hyperliquid spot wrapper tokens (was SPOT_PERP_TOKEN_MAP)
+    UBTC: "BTC",
+    UETH: "ETH",
+    USOL: "SOL",
+    UFART: "FARTCOIN",
+    UPUMP: "PUMP",
+    LINK0: "LINK",
+    AVAX0: "AVAX",
+    AAVE0: "AAVE",
+};
+/**
+ * Explicit mapping for index / commodity / fx / preIpo markets.
+ * Key: `${venue}|${symbol}` (symbol as the adapter reports it; for HIP-3 use `hl:<dex>` as venue).
+ */
+export const EXPLICIT_CANONICAL = {
+    // Gold / silver spot-referenced perps
+    "ondo|XAU": "GOLD",
+    "ondo|XAG": "SILVER",
+    "lighter-rh|XAU": "GOLD",
+    "lighter-rh|XAG": "SILVER",
+    "hl:xyz|GOLD": "GOLD",
+    "hl:xyz|SILVER": "SILVER",
+    "qfex|GOLD": "GOLD",
+    "qfex|SILVER": "SILVER",
+    // Crude oil (WTI)
+    "ondo|WTI": "CRUDE_OIL_WTI",
+    "hl:xyz|CL": "CRUDE_OIL_WTI",
+    "hl:flx|OIL": "CRUDE_OIL_WTI",
+    // QFEX CL blends expiring futures; roll-week gaps are caught by the cross-venue price filter.
+    "qfex|CL": "CRUDE_OIL_WTI",
+    // US equity indices
+    "ondo|US500": "SPX",
+    "ondo|US100": "NDX",
+    "qfex|US500": "SPX",
+    "qfex|US100": "NDX",
+    // FX
+    "ondo|USDJPY": "USDJPY",
+};
+/** Pairs verified to be DIFFERENT products despite similar names. Never match. */
+export const NEVER_MATCH = new Set([
+    "USAR:US500", "USAR:USA500", "US500:USA500",
+    "SEMI:SEMIS",
+    "USOIL:CL", "USOIL:OIL",
+    "GOLDJM:GOLD", "GLDMINE:GOLD",
+    "SILVERJM:SILVER",
+    "URNM:URANIUM",
+    "NUCLEAR:ENERGY", "NUCLEAR:USENERGY",
+]);
+export function isNeverMatch(a, b) {
+    return NEVER_MATCH.has(`${a}:${b}`) || NEVER_MATCH.has(`${b}:${a}`);
+}
+/**
+ * Canonical key for a market, or null when it must not be matched across venues.
+ * @param venueKey venue id, or `hl:<dex>` for HIP-3 dex markets
+ * @param symbol   plain symbol as reported by the adapter (no quote suffix, no dex prefix)
+ */
+export function canonicalFor(venueKey, symbol, assetClass) {
+    const up = symbol.toUpperCase();
+    switch (assetClass) {
+        case "crypto":
+            return DENOMINATION_ALIASES[up] ?? up; // ticker identity is the rule for crypto; the alias table overrides it
+        case "equity":
+        case "etf":
+            return up;
+        case "index":
+        case "commodity":
+        case "fx":
+        case "preIpo":
+            return EXPLICIT_CANONICAL[`${venueKey}|${up}`] ?? null;
+    }
+}

package/dist/exchanges/capabilities.d.ts

@@ -56,7 +56,8 @@ export interface EvmAddressCapable {
     readonly address: string;
 }
 export interface QueryOrderCapable {
-    queryOrder(orderId: number): Promise<unknown>;
+    /** Order id (u64) or, on Hyperliquid, a client order id (cloid) string. */
+    queryOrder(orderId: number | string): Promise<unknown>;
 }
 export interface UsdTransferCapable {
     usdTransfer(amount: number, destination: string): Promise<unknown>;
@@ -72,3 +73,8 @@ export declare function hasLighterAccount(adapter: ExchangeAdapter): adapter is
 export declare function hasEvmAddress(adapter: ExchangeAdapter): adapter is ExchangeAdapter & EvmAddressCapable;
 export declare function isQueryOrderCapable(adapter: ExchangeAdapter): adapter is ExchangeAdapter & QueryOrderCapable;
 export declare function isUsdTransferCapable(adapter: ExchangeAdapter): adapter is ExchangeAdapter & UsdTransferCapable;
+/**
+ * true when the venue's kline endpoint needs account credentials (Ondo GET /v1/perps/candles):
+ * `market kline` then uses the credentialed adapter instead of the keyless public one.
+ */
+export declare function klinesNeedAuth(adapter: ExchangeAdapter): boolean;

package/dist/exchanges/capabilities.js

@@ -42,3 +42,10 @@ export function isQueryOrderCapable(adapter) {
 export function isUsdTransferCapable(adapter) {
     return typeof adapter.usdTransfer === "function";
 }
+/**
+ * true when the venue's kline endpoint needs account credentials (Ondo GET /v1/perps/candles):
+ * `market kline` then uses the credentialed adapter instead of the keyless public one.
+ */
+export function klinesNeedAuth(adapter) {
+    return adapter.klinesRequireAuth === true;
+}