@reefclaw/openclaw-plugin 0.1.5 → 0.1.7

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;

package/venues/hyperliquid/hl-precision.js

@@ -0,0 +1,176 @@
+// Hyperliquid price/size precision — the rule, implemented HERE, on strings.
+//
+// ★ WHY NOT CCXT: `priceToPrecision` has a known rounding bug in the [1,10)
+// range (ccxt#26132) and the whole point of a safety floor is that the stop
+// price we compute is the stop price the exchange gets. Plan §5.5: own the math.
+//
+// ★ WHY NOT decimal.js: it would become a runtime dependency of the PUBLISHED
+// plugin package. The rule below only needs exact DECIMAL-STRING manipulation
+// (truncate / count significant figures) — no arithmetic on values — so strings
+// are both exact and dependency-free. Every function takes and returns numbers at
+// the boundary but never rounds through binary floating point.
+//
+// THE RULE (docs, verified 2026-07-11; re-verified live 2026-07-12):
+//   PRICE is valid iff
+//     - it is an INTEGER (always allowed, regardless of sig figs), OR
+//     - it has ≤ 5 significant figures AND ≤ (MAX_DECIMALS − szDecimals) decimals
+//       where MAX_DECIMALS = 6 for perps.
+//   SIZE is rounded DOWN to szDecimals (from `meta.universe`).
+//   MIN NOTIONAL is $10 (observed live: "Order must have minimum value of $10").
+//
+// Rounding direction is explicit at every call site — never "nearest" by default
+// on a protective leg. `passive` semantics: a BUY rounds DOWN, a SELL rounds UP,
+// so a rounded limit never crosses further into the book than intended.
+const MAX_DECIMALS_PERP = 6;
+/** HL minimum order value in USDC. Observed live 2026-07-12 (a $6 order was
+ *  rejected: "Order must have minimum value of $10"). */
+export const HL_MIN_NOTIONAL_USD = 10;
+/** Split a finite number into its exact decimal string parts, expanding any
+ *  exponent form ("1e-7") that JS produces for small/large magnitudes — the
+ *  string rule below must never see an "e". */
+function toPlainDecimalString(value) {
+    if (!Number.isFinite(value))
+        throw new Error(`not finite: ${value}`);
+    // toPrecision(17) is lossless for a double, and never yields exponent form for
+    // the magnitudes we trade; Number() re-parses to drop trailing zeros.
+    const s = String(value);
+    if (!s.includes('e') && !s.includes('E'))
+        return s;
+    // Exponent form → expand via toFixed with enough decimals (bounded: HL prices
+    // never need more than 20 decimals, and sizes are capped by szDecimals).
+    return value.toFixed(20).replace(/0+$/, '').replace(/\.$/, '');
+}
+/** 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 function countSignificantFigures(value) {
+    const s = toPlainDecimalString(Math.abs(value));
+    const digits = s.replace('.', '').replace(/^0+/, '').replace(/0+$/, '');
+    // An integer like 1200 has 2 sig figs by this measure — which is the
+    // conservative reading, and integers are unconditionally allowed anyway.
+    return digits.length === 0 ? 1 : digits.length;
+}
+/** Decimal places of a value (0 for integers). */
+export function decimalPlaces(value) {
+    const s = toPlainDecimalString(Math.abs(value));
+    const dot = s.indexOf('.');
+    return dot === -1 ? 0 : s.length - dot - 1;
+}
+/** Truncate a decimal string to N decimals, rounding in the requested direction.
+ *  Exact — no binary float rounding anywhere. */
+function roundDecimals(value, decimals, dir) {
+    if (decimals < 0)
+        decimals = 0;
+    const factor = 10 ** decimals;
+    // Work in an integer domain scaled by `factor`; the +/- 1e-9 nudge absorbs the
+    // classic 0.1*3 = 0.30000000000000004 representation error WITHOUT changing a
+    // value that is genuinely on the boundary.
+    const scaled = value * factor;
+    const eps = 1e-9;
+    const out = dir === 'down' ? Math.floor(scaled + eps) : Math.ceil(scaled - eps);
+    return out / factor;
+}
+/** Round a value to at most `sig` significant figures, in the given direction. */
+function roundToSignificantFigures(value, sig, dir) {
+    if (value === 0)
+        return 0;
+    const magnitude = Math.floor(Math.log10(Math.abs(value)));
+    // decimals needed so that the value carries exactly `sig` significant figures
+    const decimals = sig - 1 - magnitude;
+    return roundDecimals(value, Math.max(decimals, 0), dir);
+}
+/** 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 function isValidHlPrice(price, szDecimals) {
+    if (!Number.isFinite(price) || price <= 0)
+        return false;
+    if (Number.isInteger(price))
+        return true; // integers always allowed
+    const maxDecimals = MAX_DECIMALS_PERP - szDecimals;
+    return countSignificantFigures(price) <= 5 && decimalPlaces(price) <= maxDecimals;
+}
+/** 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 function roundHlPrice(price, szDecimals, dir) {
+    if (!Number.isFinite(price) || price <= 0) {
+        throw new Error(`Invalid HL price: ${price}`);
+    }
+    const maxDecimals = Math.max(MAX_DECIMALS_PERP - szDecimals, 0);
+    // 1) cap significant figures
+    let out = roundToSignificantFigures(price, 5, dir);
+    // 2) cap decimals (may reduce sig figs further — that stays legal)
+    if (decimalPlaces(out) > maxDecimals) {
+        out = roundDecimals(out, maxDecimals, dir);
+    }
+    // A rounded-to-zero price is never legal — fall back to the smallest legal tick.
+    if (out <= 0)
+        out = 1 / 10 ** maxDecimals;
+    return out;
+}
+/** 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 function roundHlSize(size, szDecimals) {
+    if (!Number.isFinite(size) || size < 0) {
+        throw new Error(`Invalid HL size: ${size}`);
+    }
+    return roundDecimals(size, szDecimals, 'down');
+}
+/** 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 function validateHlOrder(args) {
+    const { amount, price, referencePrice, rules, side } = args;
+    const { szDecimals } = rules;
+    const roundedAmount = roundHlSize(amount, szDecimals);
+    if (roundedAmount <= 0) {
+        return {
+            valid: false,
+            error: `Amount ${amount} rounds to zero at ${szDecimals} decimals — increase the size`,
+            roundedAmount: 0,
+        };
+    }
+    let roundedPrice;
+    if (price !== undefined) {
+        roundedPrice = roundHlPrice(price, szDecimals, side === 'buy' ? 'down' : 'up');
+    }
+    const notionalPrice = roundedPrice ?? referencePrice;
+    if (notionalPrice !== undefined && notionalPrice > 0) {
+        const notional = roundedAmount * notionalPrice;
+        if (notional < HL_MIN_NOTIONAL_USD) {
+            const minAmount = HL_MIN_NOTIONAL_USD / notionalPrice;
+            return {
+                valid: false,
+                // Same dollar-hint shape the Binance path uses — the agent gets an
+                // actionable number, not a rule citation.
+                error: `Order value $${notional.toFixed(2)} is below Hyperliquid's $${HL_MIN_NOTIONAL_USD} minimum. ` +
+                    `Increase size to at least ${minAmount.toFixed(szDecimals + 1)} (≈$${HL_MIN_NOTIONAL_USD}).`,
+                roundedAmount,
+                roundedPrice,
+            };
+        }
+    }
+    return { valid: true, roundedAmount, roundedPrice };
+}
+/** 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 function marketIocPrice(args) {
+    const { referencePrice, side, slippagePct, szDecimals } = args;
+    if (!Number.isFinite(referencePrice) || referencePrice <= 0) {
+        throw new Error(`marketIocPrice needs a positive reference price, got ${referencePrice}`);
+    }
+    const slip = Math.min(Math.max(slippagePct, 0), 0.02); // hard clamp ≤2%
+    const raw = side === 'buy' ? referencePrice * (1 + slip) : referencePrice * (1 - slip);
+    // Round the bound OUTWARD (buy up / sell down) so rounding never makes the
+    // order less marketable than intended.
+    return roundHlPrice(raw, szDecimals, side === 'buy' ? 'up' : 'down');
+}

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

@@ -0,0 +1,88 @@
+import type { CcxtOrder, CcxtPosition, CcxtBalance } from '../../types.js';
+export interface HlCredentials {
+    /** MASTER account address (0x…). Queries always use this — an agent wallet
+     *  holds no balance and no positions (learned the hard way 2026-07-12). */
+    walletAddress: string;
+    /** AGENT (API) wallet private key — signs, never holds funds. */
+    agentPrivateKey: string;
+    testnet?: boolean;
+}
+/** The CCXT options that MUST be present on every authed HL client. Exported so
+ *  `hl-private.test.ts` can assert them — if a future ccxt bump changes the
+ *  option names, the test fails rather than the users paying a silent 1bp. */
+export declare const HL_REQUIRED_OPTIONS: {
+    readonly builderFee: false;
+    readonly refSet: true;
+};
+export interface HlTriggerParams {
+    /** Trigger price (fires on MARK — HL has no workingType choice). */
+    triggerPrice: number;
+    /** 'sl' | 'tp' — HL's own naming. */
+    tpsl: 'sl' | 'tp';
+    reduceOnly: true;
+    cloid?: string;
+}
+export interface HlOrderRequest {
+    symbol: string;
+    side: 'buy' | 'sell';
+    /** 'market' is emulated: an IOC limit at `price` (the caller must have applied
+     *  the slippage bound via hl-precision.marketIocPrice). */
+    type: 'market' | 'limit';
+    amount: number;
+    price: number;
+    reduceOnly?: boolean;
+    postOnly?: boolean;
+    cloid?: string;
+    trigger?: {
+        triggerPrice: number;
+        tpsl: 'sl' | 'tp';
+    };
+}
+export declare class HyperliquidPrivateApi {
+    private readonly creds;
+    private readonly exchange;
+    private readonly mutex;
+    private marketsLoaded;
+    constructor(creds: HlCredentials);
+    /** Exposed for the options-pin test + diagnostics. */
+    getExchange(): any;
+    loadMarkets(): Promise<boolean>;
+    /** Positions for the MASTER account. `null` = fetch failed (state unknown);
+     *  `[]` = the exchange confirmed flat. */
+    fetchPositions(symbol?: string): Promise<CcxtPosition[] | null>;
+    /** Open orders INCLUDING trigger/TPSL legs. CCXT's HL `fetchOpenOrders`
+     *  defaults to `frontendOpenOrders`, which is the only endpoint that returns
+     *  trigger orders (plan §3.6) — the analog of Binance's merged algo endpoints. */
+    fetchOpenOrders(symbol?: string): Promise<CcxtOrder[] | null>;
+    fetchBalance(): Promise<CcxtBalance | null>;
+    /** Per-order status — the liveness resolver's REST tier (Tier 2 of the
+     *  3-tier rule). Weight 2. `null` = lookup FAILED (unknown), which callers
+     *  must treat as "do not act", NOT as "gone". */
+    fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    /** Own fills. WS is the authoritative ingress (plan + the audit-trail rule);
+     *  this is the gap-fill/truth-check path. NOTE: only the 10,000 most recent
+     *  fills exist server-side — deep history is NOT queryable on HL, which is why
+     *  the `trades` table must be WS-first. */
+    fetchMyTrades(symbol?: string, since?: number, limit?: number): Promise<unknown[] | null>;
+    /** Refresh the ADDRESS action budget (the starvation guard). Weight 20 — call
+     *  every ~5 min, never per-heartbeat. */
+    refreshAddressBudget(): Promise<void>;
+    /** Raw `POST /info` — for the handful of reads CCXT doesn't expose
+     *  (userRateLimit, userNonFundingLedgerUpdates, portfolio). Never used for
+     *  signed actions. */
+    rawInfo(body: Record<string, unknown>): Promise<any>;
+    /** Submit one order. Market orders are IOC-limit emulated — `price` is
+     *  MANDATORY (ccxt throws without it) and the caller must already have applied
+     *  the slippage bound + HL rounding (hl-precision). */
+    submitOrder(req: HlOrderRequest): Promise<CcxtOrder | null>;
+    /** Submit N orders as ONE signed action (one nonce, one `/exchange` call).
+     *  This is how a bracket pair (SL+TP) is placed: atomic-ish, and it costs 1 IP
+     *  weight unit but N address actions. */
+    submitOrders(reqs: HlOrderRequest[]): Promise<CcxtOrder[] | null>;
+    cancelOrder(orderId: string, symbol: string): Promise<CcxtOrder | null>;
+    /** Cancel by cloid — the bracket path's cancel (we always know our own cloid,
+     *  and it survives a restart because it is derived, not stored). */
+    cancelOrderByCloid(cloid: string, symbol: string): Promise<CcxtOrder | null>;
+    private buildParams;
+    get isMarketsLoaded(): boolean;
+}