@reefclaw/openclaw-plugin 0.1.5 → 0.1.6

package/venues/hyperliquid/hl-balance.d.ts

@@ -0,0 +1,116 @@
+import type { CcxtBalance } from '../../types.js';
+import type { CloseReason } from '../../simulator/types.js';
+export interface HlClearinghouseState {
+    marginSummary?: {
+        accountValue?: string | number;
+        totalMarginUsed?: string | number;
+        totalNtlPos?: string | number;
+    };
+    withdrawable?: string | number;
+    assetPositions?: Array<{
+        position?: {
+            coin?: string;
+            szi?: string | number;
+            entryPx?: string | number;
+            unrealizedPnl?: string | number;
+            positionValue?: string | number;
+            liquidationPx?: string | number;
+            marginUsed?: string | number;
+        };
+    }>;
+}
+export interface HlNav {
+    /** accountValue — what the HL app's portfolio panel shows. */
+    equity: number;
+    /** equity − Σ uPnl. The Binance "wallet"/margin-balance analog. */
+    wallet: number;
+    totalUnrealizedPnl: number;
+    /** Free collateral (HL `withdrawable`). */
+    available: number;
+}
+/** Derive NAV/wallet from a clearinghouseState payload.
+ *
+ *  ★ Returns null when the payload is UNREADABLE — never a zeroed NAV. A phantom
+ *  "$0 equity" would trip risk limits and look like a catastrophic loss; null
+ *  means "unknown", which the caller must refuse to act on (null ≠ empty). */
+export declare function deriveHlNav(state: HlClearinghouseState | null | undefined): HlNav | null;
+/** CcxtBalance shape the rest of the plugin (KPI strip, sizing, LiveBalanceEnricher)
+ *  already consumes. USDC is HL's settlement asset. */
+export declare function toCcxtBalance(nav: HlNav): CcxtBalance;
+export interface HlFillForAnchor {
+    time: number;
+    closedPnl?: string | number;
+    fee?: string | number;
+    builderFee?: string | number;
+}
+export interface HlFundingForAnchor {
+    time: number;
+    /** HL funding deltas are signed USDC (negative = paid). */
+    usdc?: string | number;
+    delta?: {
+        usdc?: string | number;
+    };
+}
+/** Σ(closedPnl − fee − builderFee) + Σ funding, over rows at/after `sinceMs`.
+ *
+ *  This is the exact analog of Binance's `netNonTransfer` (REALIZED_PNL +
+ *  COMMISSION + FUNDING_FEE), and — critically — it is NET of fees. The Binance
+ *  lesson (the ledger was systematically gross, causing a visible KPI gap) applies
+ *  verbatim: a gross anchor WILL disagree with the HL app. */
+export declare function computeNetNonTransfer(args: {
+    fills: HlFillForAnchor[];
+    fundings: HlFundingForAnchor[];
+    sinceMs: number;
+}): {
+    netNonTransfer: number;
+    realizedPnlGross: number;
+    fees: number;
+    funding: number;
+};
+/** UTC-midnight epoch ms for a given instant (the Day-P&L boundary). */
+export declare function utcMidnightMs(now?: number): number;
+/** sessionStartNav = wallet_now − netNonTransfer_since_midnight.
+ *  dayPnl = NAV − sessionStartNav (computed by the caller each tick). */
+export declare function deriveSessionStartNav(args: {
+    walletNow: number;
+    netNonTransfer: number;
+}): number;
+/** A capital flow (deposit / withdraw / internal transfer) changes the wallet
+ *  WITHOUT being trading P&L — bump the anchor by the same signed amount so it
+ *  never shows up as Day-P&L (the DepositTracker rule).
+ *
+ *  T-3 note: the `delta.type` enum is OPEN (docs incomplete; only
+ *  `internalTransfer` observed so far). We therefore treat any ledger row that
+ *  carries a usdc delta as a capital flow rather than switch on a closed set — an
+ *  UNKNOWN type must never be silently dropped, or the anchor drifts. */
+export declare function applyLedgerDelta(args: {
+    sessionStartNav: number;
+    ledgerRows: Array<{
+        time: number;
+        delta?: {
+            usdc?: string | number;
+            type?: string;
+        };
+    }>;
+    sinceMs: number;
+    seenHashes?: Set<string>;
+}): {
+    sessionStartNav: number;
+    applied: number;
+};
+/** ★ Close-bypass mapping (§5.9) — HL signals → journal close reasons.
+ *
+ *  A position can leave our control without our close path running: a bracket
+ *  triggering, a LIQUIDATION, an ADL, or a delisting. Each must land in the
+ *  journal honestly (the KPI and the learning loop both read these), never as a
+ *  silent disappearance. */
+export declare function mapHlCloseReason(signal: {
+    /** Fill-level liquidation object (authoritative). */
+    liquidation?: {
+        method?: string;
+    } | null;
+    /** Order status from `orderUpdates`. */
+    orderStatus?: string;
+    /** Our own cloid role, when the closing order was one of our legs. */
+    bracketRole?: 'stop' | 'target';
+}): CloseReason | 'liquidated' | 'adl' | 'venue_delisted' | null;

package/venues/hyperliquid/hl-balance.js

@@ -0,0 +1,145 @@
+// Hyperliquid balance / NAV / Day-P&L anchor (plan §5.8) + close-bypass mapping
+// (§5.9). Pure functions — the adapter feeds them raw HL payloads.
+//
+// ★ THE INVARIANT THIS FILE EXISTS TO KEEP: "KPI must equal the exchange app to
+//   the cent." On Binance that meant anchoring Day-P&L to the UTC-midnight income
+//   endpoint (a multi-dollar gap there was ALWAYS a bug, never a formula quirk).
+//   HL has no income endpoint, so the anchor is RECONSTRUCTED:
+//
+//     wallet      = accountValue − Σ unrealizedPnl      (accountValue INCLUDES uPnl)
+//     NAV/equity  = accountValue                        (so equity = wallet + Σ uPnl
+//                                                        stays literally true)
+//     netNonTransfer(since UTC midnight)
+//                 = Σ closedPnl − Σ fee − Σ builderFee   (fills)
+//                   + Σ funding                          (userFunding)
+//     sessionStartNav = wallet_now − netNonTransfer
+//     dayPnl      = NAV − sessionStartNav
+//
+//   Deposits/withdrawals/transfers are NOT trading P&L: they bump the anchor
+//   instead (the DepositTracker rule), via `applyLedgerDelta`.
+//
+// ★ FILL-HISTORY SHALLOWNESS: only the 10,000 most recent fills exist server-side
+//   on HL (deep history is NOT queryable). The anchor must therefore be able to
+//   run off WS-captured fills persisted in our own `trades` table — which is why
+//   the WS-first audit-trail rule is a hard prerequisite here, not hygiene.
+const num = (v) => {
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) ? n : 0;
+};
+/** Derive NAV/wallet from a clearinghouseState payload.
+ *
+ *  ★ Returns null when the payload is UNREADABLE — never a zeroed NAV. A phantom
+ *  "$0 equity" would trip risk limits and look like a catastrophic loss; null
+ *  means "unknown", which the caller must refuse to act on (null ≠ empty). */
+export function deriveHlNav(state) {
+    if (!state || typeof state !== 'object')
+        return null;
+    const accountValueRaw = state.marginSummary?.accountValue;
+    if (accountValueRaw === undefined || accountValueRaw === null)
+        return null;
+    const equity = num(accountValueRaw);
+    const totalUnrealizedPnl = (state.assetPositions ?? []).reduce((sum, ap) => sum + num(ap?.position?.unrealizedPnl), 0);
+    return {
+        equity,
+        wallet: equity - totalUnrealizedPnl,
+        totalUnrealizedPnl,
+        available: num(state.withdrawable),
+    };
+}
+/** CcxtBalance shape the rest of the plugin (KPI strip, sizing, LiveBalanceEnricher)
+ *  already consumes. USDC is HL's settlement asset. */
+export function toCcxtBalance(nav) {
+    const free = { USDC: nav.available };
+    const used = { USDC: Math.max(0, nav.wallet - nav.available) };
+    const total = { USDC: nav.wallet };
+    return {
+        free,
+        used,
+        total,
+        USDC: { free: nav.available, used: used.USDC, total: nav.wallet },
+    };
+}
+/** Σ(closedPnl − fee − builderFee) + Σ funding, over rows at/after `sinceMs`.
+ *
+ *  This is the exact analog of Binance's `netNonTransfer` (REALIZED_PNL +
+ *  COMMISSION + FUNDING_FEE), and — critically — it is NET of fees. The Binance
+ *  lesson (the ledger was systematically gross, causing a visible KPI gap) applies
+ *  verbatim: a gross anchor WILL disagree with the HL app. */
+export function computeNetNonTransfer(args) {
+    let realizedPnlGross = 0;
+    let fees = 0;
+    for (const f of args.fills) {
+        if (!Number.isFinite(f.time) || f.time < args.sinceMs)
+            continue;
+        realizedPnlGross += num(f.closedPnl);
+        fees += num(f.fee) + num(f.builderFee);
+    }
+    let funding = 0;
+    for (const f of args.fundings) {
+        if (!Number.isFinite(f.time) || f.time < args.sinceMs)
+            continue;
+        funding += num(f.usdc ?? f.delta?.usdc);
+    }
+    return {
+        netNonTransfer: realizedPnlGross - fees + funding,
+        realizedPnlGross,
+        fees,
+        funding,
+    };
+}
+/** UTC-midnight epoch ms for a given instant (the Day-P&L boundary). */
+export function utcMidnightMs(now = Date.now()) {
+    const d = new Date(now);
+    return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+}
+/** sessionStartNav = wallet_now − netNonTransfer_since_midnight.
+ *  dayPnl = NAV − sessionStartNav (computed by the caller each tick). */
+export function deriveSessionStartNav(args) {
+    return args.walletNow - args.netNonTransfer;
+}
+/** A capital flow (deposit / withdraw / internal transfer) changes the wallet
+ *  WITHOUT being trading P&L — bump the anchor by the same signed amount so it
+ *  never shows up as Day-P&L (the DepositTracker rule).
+ *
+ *  T-3 note: the `delta.type` enum is OPEN (docs incomplete; only
+ *  `internalTransfer` observed so far). We therefore treat any ledger row that
+ *  carries a usdc delta as a capital flow rather than switch on a closed set — an
+ *  UNKNOWN type must never be silently dropped, or the anchor drifts. */
+export function applyLedgerDelta(args) {
+    let bump = 0;
+    let applied = 0;
+    for (const row of args.ledgerRows) {
+        if (!Number.isFinite(row.time) || row.time < args.sinceMs)
+            continue;
+        const usdc = num(row.delta?.usdc);
+        if (usdc === 0)
+            continue;
+        bump += usdc;
+        applied += 1;
+    }
+    return { sessionStartNav: args.sessionStartNav + bump, applied };
+}
+/** ★ Close-bypass mapping (§5.9) — HL signals → journal close reasons.
+ *
+ *  A position can leave our control without our close path running: a bracket
+ *  triggering, a LIQUIDATION, an ADL, or a delisting. Each must land in the
+ *  journal honestly (the KPI and the learning loop both read these), never as a
+ *  silent disappearance. */
+export function mapHlCloseReason(signal) {
+    if (signal.liquidation) {
+        // HL marks backstop (HLP vault) liquidations distinctly from market ones; ADL
+        // arrives as a liquidation of the OPPOSITE side hitting us.
+        const method = (signal.liquidation.method ?? '').toLowerCase();
+        return method.includes('adl') ? 'adl' : 'liquidated';
+    }
+    const status = (signal.orderStatus ?? '').toLowerCase();
+    if (status === 'liquidatedcanceled')
+        return 'liquidated';
+    if (status === 'delistedcanceled')
+        return 'venue_delisted';
+    if (signal.bracketRole === 'stop')
+        return 'exchange_stop';
+    if (signal.bracketRole === 'target')
+        return 'exchange_target';
+    return null;
+}

package/venues/hyperliquid/hl-brackets.d.ts

@@ -0,0 +1,102 @@
+import type { BracketId, BracketRole } from '../../live/bracket-types.js';
+import type { HlOrderRequest } from './hl-private.js';
+export type ProtectiveRole = Extract<BracketRole, 'stop' | 'target'>;
+export interface HlBracketLeg {
+    role: ProtectiveRole;
+    triggerPrice: number;
+    /** HL legs are FIXED SIZE (T-2) — this is why resizing exists. */
+    size: number;
+    cloid: string;
+}
+export interface HlBracketPlan {
+    bracketId: BracketId;
+    symbol: string;
+    /** Side of the CLOSING orders (opposite the position). */
+    closeSide: 'buy' | 'sell';
+    legs: HlBracketLeg[];
+}
+/** A leg as it currently exists ON the exchange (from `frontendOpenOrders`). */
+export interface LiveLeg {
+    role: ProtectiveRole;
+    cloid: string;
+    size: number;
+    triggerPrice: number;
+}
+/** Plan a fresh bracket for a filled entry. */
+export declare function planBracket(args: {
+    bracketId: BracketId;
+    symbol: string;
+    positionSide: 'long' | 'short';
+    positionSize: number;
+    stopPrice?: number;
+    targetPrice?: number;
+}): HlBracketPlan;
+/** Build the submit-requests for a plan.
+ *
+ *  Both legs go out as ONE `createOrders` batch: one signed action, one nonce (a
+ *  same-ms nonce collision is a real HL failure mode), costing 1 IP weight unit
+ *  but 2 ADDRESS actions (the rate gate counts both).
+ *
+ *  Legs are reduce-only trigger-market orders. HL triggers fire on MARK price only
+ *  — stop-distance validation upstream must therefore use mark, never last. */
+export declare function buildBracketOrders(plan: HlBracketPlan): HlOrderRequest[];
+export interface CoverageResult {
+    covered: boolean;
+    /** Un-protected contracts per role. > 0 ⇒ that much of the position is NAKED. */
+    shortfall: Record<ProtectiveRole, number>;
+    /** A role with NO live leg at all — a protection gap, not a sizing gap. */
+    missing: ProtectiveRole[];
+}
+/** ★ THE T-2 INVARIANT — do the live legs cover the whole position?
+ *
+ *  On HL a protective leg is a FIXED SIZE, so a scale-in silently leaves the added
+ *  contracts unprotected unless the legs are resized. A `covered:false` result is
+ *  a safety-floor breach (naked size), not cosmetic drift. */
+export declare function bracketCoversPosition(args: {
+    positionSize: number;
+    liveLegs: LiveLeg[];
+}): CoverageResult;
+export interface ResizePlan {
+    /** Cloids to cancel (the stale, wrongly-sized legs). */
+    cancelCloids: string[];
+    /** Fresh legs to submit at the correct size. */
+    submit: HlOrderRequest[];
+    /** Empty when nothing needs doing — the caller must treat this as a no-op and
+     *  NOT churn the exchange (idempotent-tool contract). */
+    noop: boolean;
+}
+/** ★ Resize protective legs after a scale-in (or any position-size change).
+ *
+ *  HL gives us no in-place resize primitive we can trust (`modify` carries an
+ *  `always_place` footgun the plan forbids, and positionTpsl auto-sizing is
+ *  unreachable via ccxt — T-2). So the honest sequence is CANCEL + REPLACE, and
+ *  the order matters:
+ *
+ *    Cancel-then-place opens a brief unprotected window; place-then-cancel would
+ *    double-protect (two reduce-only legs summing to 2× the position — the excess
+ *    is harmless because reduce-only can never flip a position, and HL cancels the
+ *    stragglers when flat). We therefore SUBMIT FIRST, then cancel the stale legs:
+ *    over-protection for a few hundred ms beats a naked window. The caller is
+ *    expected to execute `submit` before `cancelCloids`.
+ *
+ *  Fresh cloids are generated for the new legs (a cloid is single-use), which is
+ *  also why the ledger keys on `bracketId`, not on a specific cloid. */
+export declare function planResize(args: {
+    bracketId: BracketId;
+    symbol: string;
+    positionSide: 'long' | 'short';
+    positionSize: number;
+    liveLegs: LiveLeg[];
+}): ResizePlan;
+/** Is this exchange order one of OUR protective legs?
+ *
+ *  The kill-switch's second layer (`OrderData.protective`) maps from this. It is
+ *  deliberately BROADER than "has one of our cloids": an externally-placed stop
+ *  must also survive a Kill. Mirrors the Binance rule (`reduceOnly || closePosition
+ *  || STOP/TAKE_PROFIT type`), translated to HL's fields. */
+export declare function isProtectiveHlOrder(order: {
+    reduceOnly?: boolean;
+    isTrigger?: boolean;
+    isPositionTpsl?: boolean;
+    orderType?: string;
+}): boolean;

package/venues/hyperliquid/hl-brackets.js

@@ -0,0 +1,172 @@
+// Hyperliquid bracket mechanics (plan §5.7) — written against MEASURED behavior,
+// not assumptions. The testnet run of 2026-07-12 (docs/CLAUDE/hyperliquid.md
+// §"Testnet verification results") settled the two questions this file turns on:
+//
+//   ★ T-1 — GOOD NEWS. Standalone (grouping `na`) reduce-only trigger legs
+//     AUTO-CANCEL when the position goes flat (~2.7s, zero residuals), and when
+//     ONE leg triggers the SIBLING SELF-CANCELS (OCO-like, ≤5.6s). HL cleans up
+//     after itself like Binance's algo orders, so BracketManager needs NO bespoke
+//     sibling-canceller. A defensive cancel stays harmless (idempotent) but is not
+//     load-bearing.
+//
+//   ★ T-2 — THE HAZARD. `grouping:'positionTpsl'` is NOT reachable through ccxt's
+//     params passthrough (it silently produced an ordinary `isPositionTpsl:false`
+//     leg), and leg sizes DO NOT follow a scale-in: after doubling a position the
+//     stop stayed at the ORIGINAL size. Binance legs use `closePosition:true`
+//     (inherently whole-position); HL legs are FIXED SIZE. Therefore:
+//
+//       ⇒ EVERY scale-in MUST resize the protective legs, or the added size is
+//         NAKED. `planResize()` is that requirement in code and
+//         `bracketCoversPosition()` is the invariant the auditor enforces.
+//
+// Everything here is PURE — it computes plans (what to submit, what to cancel);
+// the adapter executes them. Safety logic stays unit-testable without a network.
+import { buildHlBracketCloid } from './hl-cloid.js';
+/** HL sizes are rounded to szDecimals, so an exact float compare would false-flag
+ *  a correctly-sized leg. Below this, a gap is rounding dust, not exposure. */
+const COVERAGE_EPSILON = 1e-8;
+/** Plan a fresh bracket for a filled entry. */
+export function planBracket(args) {
+    const closeSide = args.positionSide === 'long' ? 'sell' : 'buy';
+    const legs = [];
+    if (args.stopPrice !== undefined) {
+        legs.push({
+            role: 'stop',
+            triggerPrice: args.stopPrice,
+            size: args.positionSize,
+            cloid: buildHlBracketCloid(args.bracketId, 'stop'),
+        });
+    }
+    if (args.targetPrice !== undefined) {
+        legs.push({
+            role: 'target',
+            triggerPrice: args.targetPrice,
+            size: args.positionSize,
+            cloid: buildHlBracketCloid(args.bracketId, 'target'),
+        });
+    }
+    return { bracketId: args.bracketId, symbol: args.symbol, closeSide, legs };
+}
+/** Build the submit-requests for a plan.
+ *
+ *  Both legs go out as ONE `createOrders` batch: one signed action, one nonce (a
+ *  same-ms nonce collision is a real HL failure mode), costing 1 IP weight unit
+ *  but 2 ADDRESS actions (the rate gate counts both).
+ *
+ *  Legs are reduce-only trigger-market orders. HL triggers fire on MARK price only
+ *  — stop-distance validation upstream must therefore use mark, never last. */
+export function buildBracketOrders(plan) {
+    return plan.legs.map((leg) => ({
+        symbol: plan.symbol,
+        side: plan.closeSide,
+        type: 'market',
+        amount: leg.size,
+        // A trigger-market leg still needs a price for ccxt's slippage bound; the
+        // trigger price is the natural reference (the leg only executes there).
+        price: leg.triggerPrice,
+        reduceOnly: true,
+        cloid: leg.cloid,
+        trigger: {
+            triggerPrice: leg.triggerPrice,
+            tpsl: leg.role === 'stop' ? 'sl' : 'tp',
+        },
+    }));
+}
+/** ★ THE T-2 INVARIANT — do the live legs cover the whole position?
+ *
+ *  On HL a protective leg is a FIXED SIZE, so a scale-in silently leaves the added
+ *  contracts unprotected unless the legs are resized. A `covered:false` result is
+ *  a safety-floor breach (naked size), not cosmetic drift. */
+export function bracketCoversPosition(args) {
+    const shortfall = { stop: 0, target: 0 };
+    const missing = [];
+    for (const role of ['stop', 'target']) {
+        const legs = args.liveLegs.filter((l) => l.role === role);
+        if (legs.length === 0) {
+            missing.push(role);
+            continue;
+        }
+        const coveredSize = legs.reduce((sum, l) => sum + l.size, 0);
+        const gap = args.positionSize - coveredSize;
+        if (gap > COVERAGE_EPSILON)
+            shortfall[role] = gap;
+    }
+    const covered = shortfall.stop <= COVERAGE_EPSILON &&
+        shortfall.target <= COVERAGE_EPSILON &&
+        // A missing STOP is never "covered" — that is the naked-position case. A
+        // missing TARGET is a policy choice (requireTakeProfit can be off), so it is
+        // reported in `missing` but does not by itself fail coverage.
+        !missing.includes('stop');
+    return { covered, shortfall, missing };
+}
+/** ★ Resize protective legs after a scale-in (or any position-size change).
+ *
+ *  HL gives us no in-place resize primitive we can trust (`modify` carries an
+ *  `always_place` footgun the plan forbids, and positionTpsl auto-sizing is
+ *  unreachable via ccxt — T-2). So the honest sequence is CANCEL + REPLACE, and
+ *  the order matters:
+ *
+ *    Cancel-then-place opens a brief unprotected window; place-then-cancel would
+ *    double-protect (two reduce-only legs summing to 2× the position — the excess
+ *    is harmless because reduce-only can never flip a position, and HL cancels the
+ *    stragglers when flat). We therefore SUBMIT FIRST, then cancel the stale legs:
+ *    over-protection for a few hundred ms beats a naked window. The caller is
+ *    expected to execute `submit` before `cancelCloids`.
+ *
+ *  Fresh cloids are generated for the new legs (a cloid is single-use), which is
+ *  also why the ledger keys on `bracketId`, not on a specific cloid. */
+export function planResize(args) {
+    const coverage = bracketCoversPosition({
+        positionSize: args.positionSize,
+        liveLegs: args.liveLegs,
+    });
+    // Nothing to do when every present leg already covers the position exactly.
+    const oversized = args.liveLegs.some((l) => l.size - args.positionSize > COVERAGE_EPSILON);
+    if (coverage.shortfall.stop <= COVERAGE_EPSILON &&
+        coverage.shortfall.target <= COVERAGE_EPSILON &&
+        !oversized) {
+        return { cancelCloids: [], submit: [], noop: true };
+    }
+    // Rebuild every PRESENT role at the correct size, preserving its trigger price.
+    const legs = [];
+    const cancelCloids = [];
+    for (const role of ['stop', 'target']) {
+        const existing = args.liveLegs.filter((l) => l.role === role);
+        if (existing.length === 0)
+            continue; // absent leg = attach path's job, not resize's
+        // Trigger price is preserved from the live leg (the agent's pinned plan) —
+        // resizing must NEVER silently move a stop.
+        const triggerPrice = existing[0].triggerPrice;
+        legs.push({
+            role,
+            triggerPrice,
+            size: args.positionSize,
+            cloid: buildHlBracketCloid(args.bracketId, role),
+        });
+        cancelCloids.push(...existing.map((l) => l.cloid));
+    }
+    const closeSide = args.positionSide === 'long' ? 'sell' : 'buy';
+    const submit = buildBracketOrders({
+        bracketId: args.bracketId,
+        symbol: args.symbol,
+        closeSide,
+        legs,
+    });
+    return { cancelCloids, submit, noop: submit.length === 0 };
+}
+/** Is this exchange order one of OUR protective legs?
+ *
+ *  The kill-switch's second layer (`OrderData.protective`) maps from this. It is
+ *  deliberately BROADER than "has one of our cloids": an externally-placed stop
+ *  must also survive a Kill. Mirrors the Binance rule (`reduceOnly || closePosition
+ *  || STOP/TAKE_PROFIT type`), translated to HL's fields. */
+export function isProtectiveHlOrder(order) {
+    if (order.reduceOnly === true)
+        return true;
+    if (order.isTrigger === true)
+        return true;
+    if (order.isPositionTpsl === true)
+        return true;
+    const t = (order.orderType ?? '').toLowerCase();
+    return t.includes('stop') || t.includes('take profit') || t.includes('tp');
+}

package/venues/hyperliquid/hl-cloid.d.ts

@@ -0,0 +1,22 @@
+import type { BracketId, BracketRole } from '../../live/bracket-types.js';
+/** Build the HL cloid for a bracket leg. Reuses the venue-neutral 16-hex
+ *  bracketId (same value the Binance cid carries) so the BracketLedger,
+ *  reconciler and journal stay venue-agnostic. */
+export declare function buildHlBracketCloid(bracketId: BracketId, role: BracketRole): string;
+/** Parse an HL cloid. Returns null for any non-bracket cloid — this is called on
+ *  EVERY order HL returns during reconciliation, so a null result is normal and
+ *  must never throw. */
+export declare function parseHlBracketCloid(cloid: string): {
+    bracketId: BracketId;
+    role: BracketRole;
+} | null;
+/** Cheap type-guard: is this one of OUR bracket cloids? */
+export declare function isHlBracketCloid(cloid: string): boolean;
+/** Is this a syntactically valid HL cloid at all (128-bit hex)? Used to reject
+ *  a Binance-shaped cid before it reaches the wire (HL returns a cryptic error
+ *  for malformed cloids). */
+export declare function isValidHlCloid(cloid: string): boolean;
+/** Non-bracket cloid for a plain (entry/close) order — lets every HL order carry
+ *  an idempotency key, exactly like the Binance path's clientOrderId. Distinct
+ *  magic ("ord") so it never parses as a bracket leg. */
+export declare function buildHlOrderCloid(): string;

package/venues/hyperliquid/hl-cloid.js

@@ -0,0 +1,82 @@
+// Hyperliquid bracket cloid scheme (plan §5.7).
+//
+// HL client order ids are **128-bit hex** (`0x` + exactly 32 hex chars) — NOT
+// free-form ASCII like Binance's `newClientOrderId`. So the Binance `bkt<16hex><role>`
+// scheme cannot be reused verbatim; it is RE-ENCODED into the 128-bit space:
+//
+//   0x  bc7  <role>  <16hex bracketId>  <12hex random>
+//   └┬┘ └┬┘  └──┬─┘  └──────┬────────┘  └─────┬──────┘
+//    │   │      │           │                 └── entropy (collision + opacity)
+//    │   │      │           └── the SAME bracketId the Binance scheme uses, so the
+//    │   │      │              ledger/reconciler stay venue-agnostic
+//    │   │      └── role nibble: e=entry, 5=stop, 7=target (hex-legal; 's'/'t' are not)
+//    │   └── magic "bc7" (bracket) — short on purpose, see below
+//    └── 0x prefix
+//
+//   3 + 1 + 16 + 12 = 32 hex chars. Exactly a valid cloid.
+//
+// ★ WHY THE MAGIC IS SHORT AND THE ENTROPY IS LONG. On Binance an EXTERNAL actor
+// with API access pattern-matched our `rc-` cids and auto-cancelled every order
+// carrying them (docs/BRACKET_CANCEL_ROOT_CAUSE_2026-05-16.md). The lesson carries
+// to any venue: a long, guessable, human-obvious prefix is an attack surface. Keep
+// the recognizable part minimal (we still need to reassemble brackets from the
+// exchange after a restart, with zero reliance on local state) and let the rest be
+// random.
+//
+// ★ RECOGNITION STAYS CENTRALIZED. docs/CLAUDE/brackets.md forbids a second
+// bracket-cid regex anywhere else in the codebase. This module is the HL half of
+// that rule; `live/bracket-id.ts:parseBracketClientId(venue, cid)` dispatches here.
+// Never inline `/^0xbc7/` in a caller.
+import { randomBytes } from 'node:crypto';
+/** 0x + bc7 + role-nibble + 16-hex bracketId + 12-hex entropy = 34 chars total. */
+const HL_CLOID_REGEX = /^0xbc7([e57])([0-9a-f]{16})([0-9a-f]{12})$/;
+/** Any well-formed HL cloid (128-bit hex), bracket or not. */
+const HL_CLOID_SHAPE = /^0x[0-9a-f]{32}$/;
+const ROLE_TO_NIBBLE = {
+    entry: 'e',
+    stop: '5',
+    target: '7',
+};
+const NIBBLE_TO_ROLE = {
+    e: 'entry',
+    '5': 'stop',
+    '7': 'target',
+};
+/** Build the HL cloid for a bracket leg. Reuses the venue-neutral 16-hex
+ *  bracketId (same value the Binance cid carries) so the BracketLedger,
+ *  reconciler and journal stay venue-agnostic. */
+export function buildHlBracketCloid(bracketId, role) {
+    if (!/^[0-9a-f]{16}$/.test(bracketId)) {
+        throw new Error(`Invalid bracketId: ${bracketId} — expected 16 hex chars`);
+    }
+    const entropy = randomBytes(6).toString('hex'); // 12 hex chars
+    return `0xbc7${ROLE_TO_NIBBLE[role]}${bracketId}${entropy}`;
+}
+/** Parse an HL cloid. Returns null for any non-bracket cloid — this is called on
+ *  EVERY order HL returns during reconciliation, so a null result is normal and
+ *  must never throw. */
+export function parseHlBracketCloid(cloid) {
+    if (typeof cloid !== 'string')
+        return null;
+    const m = HL_CLOID_REGEX.exec(cloid.toLowerCase());
+    if (!m)
+        return null;
+    return { bracketId: m[2], role: NIBBLE_TO_ROLE[m[1]] };
+}
+/** Cheap type-guard: is this one of OUR bracket cloids? */
+export function isHlBracketCloid(cloid) {
+    return typeof cloid === 'string' && HL_CLOID_REGEX.test(cloid.toLowerCase());
+}
+/** Is this a syntactically valid HL cloid at all (128-bit hex)? Used to reject
+ *  a Binance-shaped cid before it reaches the wire (HL returns a cryptic error
+ *  for malformed cloids). */
+export function isValidHlCloid(cloid) {
+    return typeof cloid === 'string' && HL_CLOID_SHAPE.test(cloid.toLowerCase());
+}
+/** Non-bracket cloid for a plain (entry/close) order — lets every HL order carry
+ *  an idempotency key, exactly like the Binance path's clientOrderId. Distinct
+ *  magic ("ord") so it never parses as a bracket leg. */
+export function buildHlOrderCloid() {
+    // 0x + "0d" (order) + 30 hex random = 32 hex chars.
+    return `0x0d${randomBytes(15).toString('hex')}`;
+}