@reefclaw/openclaw-plugin 0.1.4 → 0.1.6

package/venues/hyperliquid/hl-info-cache.d.ts

@@ -0,0 +1,46 @@
+import { type HlAssetRules, type HlValidationResult, type RoundDirection } from './hl-precision.js';
+interface MetaUniverseEntry {
+    name: string;
+    szDecimals: number;
+    maxLeverage?: number;
+    isDelisted?: boolean;
+}
+export declare class HyperliquidInfoCache {
+    private readonly fetchMeta;
+    private rules;
+    private loadedAt;
+    constructor(fetchMeta: () => Promise<{
+        universe?: MetaUniverseEntry[];
+    } | null>);
+    /** Load `meta.universe` → per-coin rules. Returns false on failure and KEEPS the
+     *  previous rules (a transient failure must not zero out the cache and start
+     *  rejecting every order). */
+    load(): Promise<boolean>;
+    get isStale(): boolean;
+    get size(): number;
+    /** Rules for a canonical symbol (BTC/USDC) or a bare coin (BTC). Coin names are
+     *  CASE-SENSITIVE on HL (kPEPE) — never uppercase the lookup key. */
+    getRules(symbolOrCoin: string): HlAssetRules | null;
+    /** Same contract as ExchangeInfoCache.validate — round, then check, and return
+     *  the rounded values the caller must actually submit. */
+    validate(args: {
+        symbol: string;
+        amount: number;
+        side: 'buy' | 'sell';
+        price?: number;
+        referencePrice?: number;
+    }): HlValidationResult;
+    /** Round a price for a symbol (direction explicit — a protective leg never
+     *  rounds "nearest"). Throws when the asset is unknown: a stop we cannot round
+     *  correctly must NOT be silently submitted at an unrounded price. */
+    roundPrice(symbol: string, price: number, dir: RoundDirection): number;
+    roundSize(symbol: string, size: number): number;
+    /** The IOC bound that emulates a market order. */
+    marketPrice(args: {
+        symbol: string;
+        side: 'buy' | 'sell';
+        referencePrice: number;
+        slippagePct: number;
+    }): number;
+}
+export {};

package/venues/hyperliquid/hl-info-cache.js

@@ -0,0 +1,125 @@
+// Hyperliquid asset-rules cache — the HL analog of `live/exchange-info-cache.ts`.
+//
+// Holds `szDecimals` + `assetIndex` + `maxLeverage` per coin, refreshed from
+// `meta` (weight 20) at boot and daily thereafter, and exposes the SAME
+// `validate()` contract the Binance cache exposes so the two adapters' call sites
+// stay symmetric (the shared contract suite depends on that symmetry).
+//
+// ★ NEVER hardcode an assetIndex. Indices are positional in `meta.universe` and
+//   DIFFER between mainnet and testnet ([asset-ids]). A hardcoded index is an
+//   order on the wrong coin.
+// ★ The rounding rule itself lives in `hl-precision.ts` — this module only
+//   supplies the per-asset inputs and caches them.
+import { logger } from '../../logger.js';
+import { toHyperliquidCoin } from '../symbols.js';
+import { validateHlOrder, roundHlPrice, roundHlSize, marketIocPrice, } from './hl-precision.js';
+const TAG = 'hl-info-cache';
+/** Refresh cadence — HL adds/removes perps and can change szDecimals on a
+ *  listing; daily matches the Binance exchangeInfo refresh. */
+const REFRESH_MS = 24 * 60 * 60 * 1000;
+export class HyperliquidInfoCache {
+    fetchMeta;
+    rules = new Map(); // keyed by COIN (case-sensitive)
+    loadedAt = 0;
+    constructor(fetchMeta) {
+        this.fetchMeta = fetchMeta;
+    }
+    /** Load `meta.universe` → per-coin rules. Returns false on failure and KEEPS the
+     *  previous rules (a transient failure must not zero out the cache and start
+     *  rejecting every order). */
+    async load() {
+        try {
+            const meta = await this.fetchMeta();
+            const universe = meta?.universe;
+            if (!Array.isArray(universe) || universe.length === 0) {
+                logger.error(TAG, 'meta.universe empty or unreadable — keeping previous rules');
+                return false;
+            }
+            const next = new Map();
+            universe.forEach((entry, index) => {
+                if (!entry?.name || typeof entry.szDecimals !== 'number')
+                    return;
+                if (entry.isDelisted)
+                    return; // never trade a delisted asset
+                next.set(entry.name, {
+                    szDecimals: entry.szDecimals,
+                    assetIndex: index, // ★ positional — this is the ONLY correct source
+                    maxLeverage: entry.maxLeverage,
+                });
+            });
+            if (next.size === 0) {
+                logger.error(TAG, 'meta.universe parsed to zero assets — keeping previous rules');
+                return false;
+            }
+            this.rules = next;
+            this.loadedAt = Date.now();
+            logger.info(TAG, `Loaded HL asset rules: ${next.size} coins`);
+            return true;
+        }
+        catch (err) {
+            logger.error(TAG, `load failed: ${err instanceof Error ? err.message : String(err)}`);
+            return false;
+        }
+    }
+    get isStale() {
+        return this.loadedAt === 0 || Date.now() - this.loadedAt > REFRESH_MS;
+    }
+    get size() {
+        return this.rules.size;
+    }
+    /** Rules for a canonical symbol (BTC/USDC) or a bare coin (BTC). Coin names are
+     *  CASE-SENSITIVE on HL (kPEPE) — never uppercase the lookup key. */
+    getRules(symbolOrCoin) {
+        const coin = symbolOrCoin.includes('/')
+            ? toHyperliquidCoin(symbolOrCoin)
+            : symbolOrCoin;
+        return this.rules.get(coin) ?? null;
+    }
+    /** Same contract as ExchangeInfoCache.validate — round, then check, and return
+     *  the rounded values the caller must actually submit. */
+    validate(args) {
+        const rules = this.getRules(args.symbol);
+        if (!rules) {
+            return {
+                valid: false,
+                error: `Unknown Hyperliquid asset for ${args.symbol} — not in meta.universe ` +
+                    '(delisted, wrong network, or coin-name case mismatch).',
+                roundedAmount: 0,
+            };
+        }
+        return validateHlOrder({
+            amount: args.amount,
+            price: args.price,
+            referencePrice: args.referencePrice,
+            rules,
+            side: args.side,
+        });
+    }
+    /** Round a price for a symbol (direction explicit — a protective leg never
+     *  rounds "nearest"). Throws when the asset is unknown: a stop we cannot round
+     *  correctly must NOT be silently submitted at an unrounded price. */
+    roundPrice(symbol, price, dir) {
+        const rules = this.getRules(symbol);
+        if (!rules)
+            throw new Error(`Cannot round price for unknown HL asset ${symbol}`);
+        return roundHlPrice(price, rules.szDecimals, dir);
+    }
+    roundSize(symbol, size) {
+        const rules = this.getRules(symbol);
+        if (!rules)
+            throw new Error(`Cannot round size for unknown HL asset ${symbol}`);
+        return roundHlSize(size, rules.szDecimals);
+    }
+    /** The IOC bound that emulates a market order. */
+    marketPrice(args) {
+        const rules = this.getRules(args.symbol);
+        if (!rules)
+            throw new Error(`Cannot price market order for unknown HL asset ${args.symbol}`);
+        return marketIocPrice({
+            referencePrice: args.referencePrice,
+            side: args.side,
+            slippagePct: args.slippagePct,
+            szDecimals: rules.szDecimals,
+        });
+    }
+}

package/venues/hyperliquid/hl-live-adapter.d.ts

@@ -0,0 +1,88 @@
+import { EventEmitter } from 'node:events';
+import type { IExchangeAdapter, AdapterReadiness, OrderOptions } from '../../exchange-adapter.js';
+import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode } from '../../types.js';
+import type { PositionMetadata, CloseReason } from '../../simulator/types.js';
+import { type HlCredentials } from './hl-private.js';
+import type { BracketId } from '../../live/bracket-types.js';
+export interface HlLiveAdapterOptions {
+    credentials: HlCredentials;
+    mode: TradingMode;
+    marketSlippagePct?: number;
+}
+export declare class HyperliquidLiveAdapter extends EventEmitter implements IExchangeAdapter {
+    private readonly opts;
+    private readonly api;
+    private readonly publicApi;
+    private readonly infoCache;
+    private readonly slippagePct;
+    private _readiness;
+    private openOrdersUnavailableUntil;
+    constructor(opts: HlLiveAdapterOptions);
+    /** Boot: load markets + asset rules. Readiness gates `create_order` ONLY —
+     *  emergency paths never consult it. */
+    initialize(): Promise<void>;
+    get readiness(): AdapterReadiness;
+    get mode(): TradingMode;
+    get isLive(): boolean;
+    createOrder(symbol: string, side: 'buy' | 'sell', type: 'market' | 'limit', amount: number, price?: number, _metadata?: PositionMetadata, options?: OrderOptions): Promise<CcxtOrder>;
+    /** Emergency-safe: never pre-gated, never readiness-gated. */
+    cancelOrder(orderId: string, symbol?: string): Promise<CcxtOrder>;
+    /**
+     * Cancel WORKING orders — protective legs are PRESERVED.
+     *
+     * This is the plugin-side half of the kill-preserve rule (the skill has its own,
+     * broader layer). A Kill must never strip the stop off a live position.
+     */
+    cancelAllOrders(symbol?: string): Promise<CcxtOrder[]>;
+    /**
+     * Close a position at market (reduce-only IOC).
+     *
+     * ★ null ≠ empty: a FAILED position fetch throws (state unknown — closing
+     * against an unknown book could open a NEW position in the opposite direction);
+     * a CONFIRMED-flat account is a benign no-op.
+     */
+    closePosition(symbol: string, _closeReason?: CloseReason): Promise<CcxtOrder>;
+    getBalance(): Promise<CcxtBalance>;
+    /** Display contract (`?? []`) — the 20+ KPI/display callers. */
+    getPositions(symbol?: string): Promise<CcxtPosition[]>;
+    /** ★ Decision contract — null means UNKNOWN, and destructive paths must not act. */
+    getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
+    /**
+     * ★ THROWS on a failed fetch — never returns [].
+     *
+     * An empty list is positive information ("the exchange has no orders"); a failed
+     * fetch is not. Collapsing the two is what drove the ATOM naked-bracket loop on
+     * Binance. A sticky cooldown then prevents a retry loop from pinning the budget.
+     */
+    getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
+    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    getLastPrice(symbol: string): Promise<number | null>;
+    /** Attach protective legs to a filled position — ONE signed action for both. */
+    attachBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+        stopPrice?: number;
+        targetPrice?: number;
+    }): Promise<CcxtOrder[]>;
+    /**
+     * ★ T-2 REQUIREMENT: resize protective legs after a scale-in.
+     *
+     * HL legs are FIXED SIZE and do not follow the position (measured). Without this
+     * the added contracts are NAKED. Submit-then-cancel: a moment of over-protection
+     * (harmless — reduce-only cannot flip a position) beats a naked window.
+     */
+    resizeBrackets(args: {
+        bracketId: BracketId;
+        symbol: string;
+        positionSide: 'long' | 'short';
+        positionSize: number;
+    }): Promise<{
+        resized: boolean;
+    }>;
+    /** Coverage audit — `covered:false` means part of the position is NAKED. */
+    auditBracketCoverage(symbol: string, positionSize: number): Promise<import("./hl-brackets.js").CoverageResult>;
+    /** Our protective legs currently on the exchange. Throws on unknown (never []). */
+    private readLiveLegs;
+}

package/venues/hyperliquid/hl-live-adapter.js

@@ -0,0 +1,353 @@
+// HyperliquidLiveAdapter — IExchangeAdapter over Hyperliquid (plan §5.1).
+//
+// A SIBLING of Binance's LiveAdapter, not a refactor of it: ~1800 lines of
+// incident-hardened live-money logic stay untouched, and the invariants are held
+// by the SHARED CONTRACT SUITE that runs against both adapters (plan §9.1).
+//
+// THE INHERITED CONTRACTS (each one is an incident, not a preference):
+//   ★ null ≠ empty. `getPositionsOrNull()` returns null when the fetch FAILED;
+//     `getOpenOrders()` THROWS rather than return `[]` on a failed fetch (a
+//     phantom-empty order list once drove ~17 cycles of re-attach against real
+//     protective orders — the 2026-05-14 ATOM naked-bracket loop).
+//   ★ `closePosition()` distinguishes null (unknown) from [] (confirmed flat).
+//   ★ Emergency paths (cancel/close) are NEVER gated by our own pacer or by
+//     readiness — an exit must always be attemptable.
+//   ★ A sticky cooldown after a failed order-list fetch, so a tight agent retry
+//     loop cannot pin the rate budget and blind the whole agent.
+//
+// THE HL-SPECIFIC RULES (all measured on testnet 2026-07-12):
+//   ★ No native market order → IOC limit at a slippage-bounded price, and ccxt
+//     REQUIRES that reference price (it throws without one).
+//   ★ Reduce-only trigger legs auto-cancel on flat and behave OCO (T-1) → no
+//     sibling-canceller needed.
+//   ★ Legs are FIXED SIZE and do NOT follow a scale-in (T-2) → `resizeBrackets()`
+//     exists and the auditor treats an under-sized leg as NAKED size.
+//   ★ Positions/balance are queried on the MASTER address; the agent wallet only
+//     signs (it holds nothing).
+import { EventEmitter } from 'node:events';
+import { logger } from '../../logger.js';
+import { HyperliquidPrivateApi } from './hl-private.js';
+import { HyperliquidInfoCache } from './hl-info-cache.js';
+import { HyperliquidPublicApi } from './hl-public.js';
+import { planBracket, planResize, buildBracketOrders, bracketCoversPosition, } from './hl-brackets.js';
+import { deriveHlNav, toCcxtBalance } from './hl-balance.js';
+import { buildHlOrderCloid, parseHlBracketCloid } from './hl-cloid.js';
+const TAG = 'hl-live-adapter';
+/** Default IOC slippage bound for an emulated market order. 0.5% — NOT ccxt's
+ *  5% default, which would be a silent execution-quality disaster. */
+const DEFAULT_MARKET_SLIPPAGE = 0.005;
+/** Sticky cooldown after a failed open-orders fetch (the Binance lesson: the
+ *  SKILL.md audit→attach loop re-calls every ~3s and would pin the budget). */
+const OPEN_ORDERS_COOLDOWN_MS = 45_000;
+export class HyperliquidLiveAdapter extends EventEmitter {
+    opts;
+    api;
+    publicApi;
+    infoCache;
+    slippagePct;
+    _readiness = 'INIT_PENDING';
+    openOrdersUnavailableUntil = 0;
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        this.api = new HyperliquidPrivateApi(opts.credentials);
+        this.publicApi = new HyperliquidPublicApi({ testnet: opts.credentials.testnet });
+        this.slippagePct = clampSlippage(opts.marketSlippagePct ?? DEFAULT_MARKET_SLIPPAGE);
+        this.infoCache = new HyperliquidInfoCache(async () => {
+            // `meta` is a keyless info read — the public client owns it.
+            return this.publicApi.fetchMeta();
+        });
+    }
+    // ---- Lifecycle ----
+    /** Boot: load markets + asset rules. Readiness gates `create_order` ONLY —
+     *  emergency paths never consult it. */
+    async initialize() {
+        const markets = await this.api.loadMarkets();
+        const rules = await this.infoCache.load();
+        if (markets && rules && this.infoCache.size > 0) {
+            this._readiness = 'READY';
+            logger.info(TAG, `HL live adapter READY (${this.infoCache.size} assets, mode=${this.opts.mode})`);
+        }
+        else {
+            // DEGRADED, not BLOCKED: reads/exits still work; entries are refused
+            // upstream by the readiness gate.
+            this._readiness = 'DEGRADED';
+            logger.error(TAG, 'HL live adapter DEGRADED — markets/asset rules unavailable; entries blocked, exits still work');
+        }
+        // Prime the ADDRESS action budget (the starvation guard, §5.6).
+        await this.api.refreshAddressBudget();
+    }
+    get readiness() {
+        return this._readiness;
+    }
+    get mode() {
+        return this.opts.mode;
+    }
+    get isLive() {
+        return true;
+    }
+    // ---- Core trading ----
+    async createOrder(symbol, side, type, amount, price, _metadata, options) {
+        // A market order NEEDS a reference price on HL (no native market order; ccxt
+        // derives the slippage cap from it and THROWS without one — verified live).
+        let referencePrice = price;
+        if (type === 'market' || referencePrice === undefined) {
+            const mark = await this.publicApi.fetchMarkPrice(symbol);
+            if (mark === null || !(mark > 0)) {
+                throw new Error(`Cannot price a ${type} order on ${symbol}: mark price unavailable. ` +
+                    'Hyperliquid has no native market order — an IOC bound needs a reference price.');
+            }
+            referencePrice = mark;
+        }
+        const submitPrice = type === 'market'
+            ? this.infoCache.marketPrice({
+                symbol,
+                side,
+                referencePrice,
+                slippagePct: this.slippagePct,
+            })
+            : this.infoCache.roundPrice(symbol, referencePrice, side === 'buy' ? 'down' : 'up');
+        const check = this.infoCache.validate({
+            symbol,
+            amount,
+            side,
+            price: type === 'limit' ? submitPrice : undefined,
+            referencePrice,
+        });
+        if (!check.valid)
+            throw new Error(check.error ?? 'Hyperliquid order validation failed');
+        const cloid = options?.clientOrderId ?? buildHlOrderCloid();
+        const order = await this.api.submitOrder({
+            symbol,
+            side,
+            type,
+            amount: check.roundedAmount,
+            price: submitPrice,
+            reduceOnly: options?.reduceOnly,
+            cloid,
+        });
+        if (!order)
+            throw new Error(`Hyperliquid order submission returned no order for ${symbol}`);
+        return order;
+    }
+    /** Emergency-safe: never pre-gated, never readiness-gated. */
+    async cancelOrder(orderId, symbol) {
+        if (!symbol)
+            throw new Error('Hyperliquid cancelOrder requires a symbol');
+        const res = await this.api.cancelOrder(orderId, symbol);
+        if (!res)
+            throw new Error(`Cancel returned no result for ${orderId}`);
+        return res;
+    }
+    /**
+     * Cancel WORKING orders — protective legs are PRESERVED.
+     *
+     * This is the plugin-side half of the kill-preserve rule (the skill has its own,
+     * broader layer). A Kill must never strip the stop off a live position.
+     */
+    async cancelAllOrders(symbol) {
+        const open = await this.api.fetchOpenOrders(symbol);
+        if (open === null) {
+            // Unknown ≠ nothing. Refuse to "cancel all" against an unknown book.
+            throw new Error('cancelAllOrders: could not read open orders (fetch failed) — refusing to act on an unknown order book');
+        }
+        const cancelled = [];
+        for (const o of open) {
+            const cloid = (o.clientOrderId ?? '');
+            // Preserve OUR bracket legs…
+            if (cloid && parseHlBracketCloid(cloid))
+                continue;
+            // …and any other protective order (externally placed stops included).
+            const raw = o.info ?? {};
+            if (raw.reduceOnly === true ||
+                raw.isTrigger === true ||
+                raw.isPositionTpsl === true) {
+                continue;
+            }
+            try {
+                const res = await this.api.cancelOrder(String(o.id), o.symbol ?? symbol ?? '');
+                if (res)
+                    cancelled.push(res);
+            }
+            catch (err) {
+                logger.warn(TAG, `cancelAllOrders: cancel ${o.id} failed: ${msg(err)}`);
+            }
+        }
+        return cancelled;
+    }
+    /**
+     * Close a position at market (reduce-only IOC).
+     *
+     * ★ null ≠ empty: a FAILED position fetch throws (state unknown — closing
+     * against an unknown book could open a NEW position in the opposite direction);
+     * a CONFIRMED-flat account is a benign no-op.
+     */
+    async closePosition(symbol, _closeReason) {
+        const positions = await this.api.fetchPositions(symbol);
+        if (positions === null) {
+            throw new Error(`closePosition(${symbol}): position state UNKNOWN (fetch failed) — refusing to submit a ` +
+                'close that could open an opposite position. Retry once the exchange responds.');
+        }
+        const pos = positions.find((p) => p.symbol?.startsWith(symbol.split(':')[0]));
+        if (!pos || Math.abs(Number(pos.contracts ?? 0)) === 0) {
+            throw new Error(`closePosition(${symbol}): no open position (exchange confirmed flat)`);
+        }
+        const size = Math.abs(Number(pos.contracts));
+        const side = pos.side === 'long' ? 'sell' : 'buy';
+        const mark = await this.publicApi.fetchMarkPrice(symbol);
+        if (mark === null || !(mark > 0)) {
+            throw new Error(`closePosition(${symbol}): mark price unavailable — cannot bound the IOC close`);
+        }
+        const price = this.infoCache.marketPrice({
+            symbol,
+            side,
+            referencePrice: mark,
+            // A CLOSE is not the place to be precious about slippage — use a wider
+            // bound than an entry so an exit does not silently fail to fill.
+            slippagePct: Math.min(this.slippagePct * 2, 0.02),
+        });
+        const order = await this.api.submitOrder({
+            symbol,
+            side,
+            type: 'market',
+            amount: this.infoCache.roundSize(symbol, size),
+            price,
+            reduceOnly: true,
+            cloid: buildHlOrderCloid(),
+        });
+        if (!order)
+            throw new Error(`closePosition(${symbol}) returned no order`);
+        return order;
+    }
+    // ---- State queries ----
+    async getBalance() {
+        const state = await this.api.rawInfo({
+            type: 'clearinghouseState',
+            user: this.opts.credentials.walletAddress,
+        }).catch(() => null);
+        const nav = deriveHlNav(state);
+        if (!nav) {
+            throw new Error('getBalance: clearinghouseState unreadable — balance UNKNOWN (never reported as $0)');
+        }
+        return toCcxtBalance(nav);
+    }
+    /** Display contract (`?? []`) — the 20+ KPI/display callers. */
+    async getPositions(symbol) {
+        return (await this.api.fetchPositions(symbol)) ?? [];
+    }
+    /** ★ Decision contract — null means UNKNOWN, and destructive paths must not act. */
+    async getPositionsOrNull(symbol) {
+        return this.api.fetchPositions(symbol);
+    }
+    /**
+     * ★ THROWS on a failed fetch — never returns [].
+     *
+     * An empty list is positive information ("the exchange has no orders"); a failed
+     * fetch is not. Collapsing the two is what drove the ATOM naked-bracket loop on
+     * Binance. A sticky cooldown then prevents a retry loop from pinning the budget.
+     */
+    async getOpenOrders(symbol) {
+        const now = Date.now();
+        if (now < this.openOrdersUnavailableUntil) {
+            const waitS = Math.ceil((this.openOrdersUnavailableUntil - now) / 1000);
+            throw new Error(`getOpenOrders: Hyperliquid unavailable — sticky cooldown active (~${waitS}s left, no call made). ` +
+                'Caller must NOT proceed as if the exchange has zero orders.');
+        }
+        const orders = await this.api.fetchOpenOrders(symbol);
+        if (orders === null) {
+            this.openOrdersUnavailableUntil = Date.now() + OPEN_ORDERS_COOLDOWN_MS;
+            throw new Error('getOpenOrders: fetch FAILED (rate limit / transient) — order state UNKNOWN. ' +
+                'This is NOT "zero orders": a caller that treats it as empty would re-attach or cancel ' +
+                'against real protective orders.');
+        }
+        this.openOrdersUnavailableUntil = 0;
+        return orders;
+    }
+    async fetchOrder(orderId, symbol) {
+        return this.api.fetchOrder(orderId, symbol);
+    }
+    async getLastPrice(symbol) {
+        return this.publicApi.fetchMarkPrice(symbol);
+    }
+    // ---- Brackets (the safety floor) ----
+    /** Attach protective legs to a filled position — ONE signed action for both. */
+    async attachBrackets(args) {
+        const plan = planBracket({
+            ...args,
+            positionSize: this.infoCache.roundSize(args.symbol, args.positionSize),
+            // Round each trigger to the PROTECTIVE side: a long's stop rounds DOWN
+            // (never tighter than the agent asked), its target rounds UP.
+            stopPrice: args.stopPrice === undefined
+                ? undefined
+                : this.infoCache.roundPrice(args.symbol, args.stopPrice, args.positionSide === 'long' ? 'down' : 'up'),
+            targetPrice: args.targetPrice === undefined
+                ? undefined
+                : this.infoCache.roundPrice(args.symbol, args.targetPrice, args.positionSide === 'long' ? 'up' : 'down'),
+        });
+        const orders = await this.api.submitOrders(buildBracketOrders(plan));
+        if (!orders)
+            throw new Error(`attachBrackets(${args.symbol}): submission returned nothing`);
+        return orders;
+    }
+    /**
+     * ★ T-2 REQUIREMENT: resize protective legs after a scale-in.
+     *
+     * HL legs are FIXED SIZE and do not follow the position (measured). Without this
+     * the added contracts are NAKED. Submit-then-cancel: a moment of over-protection
+     * (harmless — reduce-only cannot flip a position) beats a naked window.
+     */
+    async resizeBrackets(args) {
+        const live = await this.readLiveLegs(args.symbol);
+        const plan = planResize({
+            ...args,
+            positionSize: this.infoCache.roundSize(args.symbol, args.positionSize),
+            liveLegs: live,
+        });
+        if (plan.noop)
+            return { resized: false };
+        await this.api.submitOrders(plan.submit); // protect FIRST
+        for (const cloid of plan.cancelCloids) {
+            try {
+                await this.api.cancelOrderByCloid(cloid, args.symbol);
+            }
+            catch (err) {
+                // A stale leg that refuses to cancel is over-protection, not risk.
+                logger.warn(TAG, `resizeBrackets: stale leg ${cloid} cancel failed: ${msg(err)}`);
+            }
+        }
+        logger.info(TAG, `resized brackets on ${args.symbol} to ${args.positionSize} (T-2: HL legs do not auto-resize)`);
+        return { resized: true };
+    }
+    /** Coverage audit — `covered:false` means part of the position is NAKED. */
+    async auditBracketCoverage(symbol, positionSize) {
+        const live = await this.readLiveLegs(symbol);
+        return bracketCoversPosition({ positionSize, liveLegs: live });
+    }
+    /** Our protective legs currently on the exchange. Throws on unknown (never []). */
+    async readLiveLegs(symbol) {
+        const orders = await this.getOpenOrders(symbol); // throws on failed fetch
+        const legs = [];
+        for (const o of orders) {
+            const cloid = (o.clientOrderId ?? '');
+            const parsed = cloid ? parseHlBracketCloid(cloid) : null;
+            if (!parsed || parsed.role === 'entry')
+                continue;
+            const raw = o.info ?? {};
+            legs.push({
+                role: parsed.role,
+                cloid,
+                size: Number(o.remaining ?? o.amount ?? raw.sz ?? 0),
+                triggerPrice: Number(raw.triggerPx ?? o.price ?? 0),
+            });
+        }
+        return legs;
+    }
+}
+function clampSlippage(pct) {
+    if (!Number.isFinite(pct) || pct <= 0)
+        return DEFAULT_MARKET_SLIPPAGE;
+    return Math.min(pct, 0.02); // hard ceiling 2%
+}
+function msg(err) {
+    return err instanceof Error ? err.message : String(err);
+}

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

@@ -0,0 +1,61 @@
+/** HL minimum order value in USDC. Observed live 2026-07-12 (a $6 order was
+ *  rejected: "Order must have minimum value of $10"). */
+export declare const HL_MIN_NOTIONAL_USD = 10;
+export type RoundDirection = 'down' | 'up';
+/** Count significant figures of a decimal string (leading zeros are not
+ *  significant; trailing zeros AFTER a decimal point are, but we always emit
+ *  trimmed strings so they never appear). */
+export declare function countSignificantFigures(value: number): number;
+/** Decimal places of a value (0 for integers). */
+export declare function decimalPlaces(value: number): number;
+export interface HlAssetRules {
+    /** Size decimals from `meta.universe[].szDecimals`. */
+    szDecimals: number;
+    /** Asset index — the `a` field of an order. NEVER hardcode: mainnet and
+     *  testnet indices differ ([asset-ids]). */
+    assetIndex: number;
+    maxLeverage?: number;
+}
+/** Is this price acceptable to Hyperliquid as-is? (The exact documented rule —
+ *  used by tests and as a post-round assertion, never as a substitute for
+ *  rounding.) */
+export declare function isValidHlPrice(price: number, szDecimals: number): boolean;
+/** Round a price to the nearest HL-legal value in the requested direction.
+ *
+ *  Applies BOTH constraints (≤5 sig figs AND ≤ MAX_DECIMALS−szDecimals decimals),
+ *  tightest-wins. An integer result is always legal, so the decimal cap can never
+ *  push a price to an illegal value. */
+export declare function roundHlPrice(price: number, szDecimals: number, dir: RoundDirection): number;
+/** Round an order size DOWN to szDecimals. Always DOWN: rounding a size up can
+ *  overshoot the position (a reduce-only leg sized above the position is rejected)
+ *  or exceed the intended risk. */
+export declare function roundHlSize(size: number, szDecimals: number): number;
+export interface HlValidationResult {
+    valid: boolean;
+    error?: string;
+    roundedAmount: number;
+    roundedPrice?: number;
+}
+/** Pre-flight validation mirroring `ExchangeInfoCache.validate`'s contract
+ *  (same shape, same "round then check" order, same dollar-hint error copy) so
+ *  the adapter's call sites are venue-symmetric.
+ *
+ *  @param side  drives passive rounding of a limit price (buy → down, sell → up).
+ *  @param referencePrice mark/mid — used for the notional check when no limit
+ *    price is given (market orders). */
+export declare function validateHlOrder(args: {
+    amount: number;
+    price?: number;
+    referencePrice?: number;
+    rules: HlAssetRules;
+    side: 'buy' | 'sell';
+}): HlValidationResult;
+/** The IOC price bound that emulates a market order (HL has no native market
+ *  order — plan §3.4). Explicit slippage ALWAYS — ccxt's `defaultSlippage: 0.05`
+ *  (5%!) is never relied upon. */
+export declare function marketIocPrice(args: {
+    referencePrice: number;
+    side: 'buy' | 'sell';
+    slippagePct: number;
+    szDecimals: number;
+}): number;