@oracle-agent/oracle 0.1.0

package/src/data/providers/hl-markets.mjs

@@ -0,0 +1,210 @@
+// Hyperliquid market datapoints for the Hyperliquid agent.
+//
+// The raw /info endpoints return parallel arrays and stringly-typed numbers
+// that every consumer ends up re-deriving: universe[i] pairs with assetCtxs[i],
+// funding is an 8-hour decimal that people want annualized, open interest is
+// denominated in the coin rather than USD. Doing that join once, here, keeps
+// every chart and card consistent instead of each one inventing its own math.
+//
+// Reads only. No keys, no signing.
+
+import { hlMetaAndAssetCtxs, hlAllMids, hlCandleSnapshot, hlL2Book, hlSpotMeta } from "./hl-info.mjs";
+
+/** Liveness: the media lane is healthy when the underlying info plane answers. */
+export async function hlMarketsHealth(opts = {}) {
+  const t0 = Date.now();
+  try {
+    const mids = await hlAllMids(opts);
+    return {
+      provider: "hl-markets",
+      ok: true,
+      venue: "hyperliquid",
+      symbols: Object.keys(mids || {}).length,
+      latencyMs: Date.now() - t0,
+    };
+  } catch (e) {
+    return { provider: "hl-markets", ok: false, error: String(e?.message || e), latencyMs: Date.now() - t0 };
+  }
+}
+
+const HOURS_PER_YEAR = 24 * 365;
+const FUNDING_INTERVAL_HOURS = 8;
+
+function num(value) {
+  if (value == null) return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+function pct(a, b) {
+  if (a == null || b == null || b === 0) return null;
+  return ((a - b) / b) * 100;
+}
+
+/**
+ * Join the perp universe with its asset contexts into one flat row per market.
+ *
+ * This is THE datapoint set for an Hyperliquid agent board: price, 24h change, volume,
+ * open interest in both coin and USD, funding (interval + annualized), and the
+ * leverage/decimals metadata needed to render or size an order.
+ */
+export async function hlMarketDatapoints(args = {}, opts = {}) {
+  const [meta, mids] = await Promise.all([
+    hlMetaAndAssetCtxs(opts),
+    hlAllMids(opts).catch(() => ({})),
+  ]);
+
+  // metaAndAssetCtxs returns [ { universe: [...] }, [ ctx, ... ] ]
+  const universe = meta?.[0]?.universe ?? meta?.universe ?? [];
+  const ctxs = Array.isArray(meta?.[1]) ? meta[1] : [];
+
+  const rows = universe.map((asset, i) => {
+    const ctx = ctxs[i] || {};
+    const mark = num(ctx.markPx);
+    const prev = num(ctx.prevDayPx);
+    const oiCoin = num(ctx.openInterest);
+    const funding = num(ctx.funding);
+
+    return {
+      coin: asset.name,
+      index: i,
+      markPx: mark,
+      oraclePx: num(ctx.oraclePx),
+      midPx: num(ctx.midPx) ?? num(mids?.[asset.name]),
+      prevDayPx: prev,
+      change24hPct: pct(mark, prev),
+      dayNtlVolumeUsd: num(ctx.dayNtlVlm),
+      premium: num(ctx.premium),
+      // funding is the per-8h rate as a decimal; both forms are useful and
+      // people get the conversion wrong constantly.
+      fundingRate: funding,
+      fundingRateAprPct: funding == null ? null : funding * (HOURS_PER_YEAR / FUNDING_INTERVAL_HOURS) * 100,
+      openInterestCoin: oiCoin,
+      openInterestUsd: oiCoin == null || mark == null ? null : oiCoin * mark,
+      maxLeverage: asset.maxLeverage ?? null,
+      szDecimals: asset.szDecimals ?? null,
+      isDelisted: Boolean(asset.isDelisted),
+    };
+  });
+
+  const live = rows.filter((r) => !r.isDelisted);
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "market-datapoints",
+    asOfMs: Date.now(),
+    count: live.length,
+    markets: live,
+    totals: {
+      openInterestUsd: live.reduce((a, r) => a + (r.openInterestUsd || 0), 0),
+      dayNtlVolumeUsd: live.reduce((a, r) => a + (r.dayNtlVolumeUsd || 0), 0),
+    },
+  };
+}
+
+/** Top movers / volume / OI / funding leaders — the standard board cuts. */
+export async function hlLeaderboards(args = {}, opts = {}) {
+  const limit = Math.max(1, Math.min(Number(args.limit) || 10, 50));
+  const { markets, asOfMs, totals } = await hlMarketDatapoints(args, opts);
+
+  const by = (key, dir = -1) =>
+    markets
+      .filter((m) => m[key] != null)
+      .sort((a, b) => (a[key] - b[key]) * dir)
+      .slice(0, limit);
+
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "leaderboards",
+    asOfMs,
+    totals,
+    gainers: by("change24hPct"),
+    losers: by("change24hPct", 1),
+    byVolume: by("dayNtlVolumeUsd"),
+    byOpenInterest: by("openInterestUsd"),
+    fundingHighest: by("fundingRateAprPct"),
+    fundingLowest: by("fundingRateAprPct", 1),
+  };
+}
+
+/**
+ * One coin, everything a segment or card needs: current state, the recent
+ * candle series, and top-of-book depth.
+ */
+export async function hlCoinDatapoints(args = {}, opts = {}) {
+  const coin = String(args.coin || args.symbol || "").trim().toUpperCase();
+  if (!coin) throw new Error("hl-markets: coin required");
+  const interval = String(args.interval || "1h");
+  const lookbackMs = Number(args.lookbackMs) || 24 * 60 * 60 * 1000;
+  const endTime = Date.now();
+  const startTime = endTime - lookbackMs;
+
+  const [board, candles, book] = await Promise.all([
+    hlMarketDatapoints({}, opts),
+    hlCandleSnapshot({ coin, interval, startTime, endTime }, opts).catch(() => []),
+    // hlL2Book takes a bare coin string, not an args object.
+    hlL2Book(coin, opts).catch(() => null),
+  ]);
+
+  const market = board.markets.find((m) => m.coin === coin) || null;
+  if (!market) throw new Error(`hl-markets: ${coin} is not a listed perp`);
+
+  const series = (Array.isArray(candles) ? candles : []).map((c) => ({
+    t: Number(c.t),
+    open: num(c.o),
+    high: num(c.h),
+    low: num(c.l),
+    close: num(c.c),
+    volume: num(c.v),
+  }));
+
+  const levels = book?.levels ?? [];
+  const bestBid = num(levels?.[0]?.[0]?.px);
+  const bestAsk = num(levels?.[1]?.[0]?.px);
+
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "coin-datapoints",
+    asOfMs: Date.now(),
+    coin,
+    market,
+    book: {
+      bestBid,
+      bestAsk,
+      spread: bestBid == null || bestAsk == null ? null : bestAsk - bestBid,
+      spreadBps: bestBid == null || bestAsk == null || bestAsk === 0 ? null : ((bestAsk - bestBid) / bestAsk) * 10_000,
+    },
+    candles: { interval, count: series.length, series },
+  };
+}
+
+/** Spot pairs, joined the same way. */
+export async function hlSpotDatapoints(args = {}, opts = {}) {
+  const spot = await hlSpotMeta(opts);
+  const tokens = spot?.tokens ?? [];
+  const pairs = spot?.universe ?? [];
+  return {
+    provider: "hl-info",
+    venue: "hyperliquid",
+    kind: "spot-datapoints",
+    asOfMs: Date.now(),
+    tokenCount: tokens.length,
+    pairCount: pairs.length,
+    tokens: tokens.map((t) => ({
+      name: t.name,
+      index: t.index,
+      szDecimals: t.szDecimals ?? null,
+      weiDecimals: t.weiDecimals ?? null,
+      tokenId: t.tokenId ?? null,
+      isCanonical: Boolean(t.isCanonical),
+    })),
+    pairs: pairs.map((p) => ({
+      name: p.name,
+      index: p.index,
+      tokens: p.tokens,
+      isCanonical: Boolean(p.isCanonical),
+    })),
+  };
+}

package/src/data/providers/hl-perps.mjs

@@ -0,0 +1,382 @@
+// Hyperliquid perpetuals: orders, leverage, and position management.
+//
+// PREPARE-ONLY. Every function here returns EIP-712 typed data plus the exact
+// action payload the user's wallet will sign. Nothing in this file signs,
+// submits, or broadcasts — there is deliberately no submit function, and a
+// test asserts that no write-shaped export ever appears.
+//
+// Why the arithmetic is fussy: Hyperliquid rejects orders whose price or size
+// carry more precision than the asset allows, and a rejected order at the wrong
+// moment is indistinguishable from a missed fill. Prices allow at most 5
+// significant figures and (6 - szDecimals) decimal places for perps; sizes are
+// rounded to szDecimals. Integers are always allowed regardless of sig figs.
+// We do that rounding here, once, in decimal — never through a float.
+
+import { hlMetaAndAssetCtxs } from "./hl-info.mjs";
+import { toScaledInteger } from "../../exact-integer.mjs";
+
+export const HL_PERP_MAX_SIG_FIGS = 5;
+export const HL_PERP_PRICE_DECIMALS = 6; // 6 - szDecimals for perps
+export const HL_SIGNATURE_CHAIN_ID = "0x66eee";
+
+export const ORDER_TYPES = Object.freeze({
+  LIMIT: "limit",
+  MARKET: "market",
+  STOP_MARKET: "stopMarket",
+  STOP_LIMIT: "stopLimit",
+  TAKE_PROFIT_MARKET: "takeProfitMarket",
+  TAKE_PROFIT_LIMIT: "takeProfitLimit",
+});
+
+export const TIF = Object.freeze({
+  GTC: "Gtc", // rest on the book
+  IOC: "Ioc", // fill what you can, cancel the rest
+  ALO: "Alo", // add liquidity only; rejected if it would cross
+});
+
+export const MARGIN_MODE = Object.freeze({
+  CROSS: "cross",
+  ISOLATED: "isolated",
+});
+
+/** Exact decimal rounding — no floats, so 0.1+0.2 problems cannot appear. */
+function roundDecimal(value, maxDecimals, { roundDown = null } = {}) {
+  // `value` may arrive as a JS number from price math; normalise without
+  // exponent notation, which BigInt cannot parse.
+  const text = typeof value === "number" ? value.toFixed(Math.min(20, maxDecimals + 8)) : String(value).trim();
+  if (!/^-?\d+(\.\d+)?$/.test(text)) throw new Error(`hl-perps: "${value}" is not a decimal number`);
+  const neg = text.startsWith("-");
+  const [intPart, fracPart = ""] = text.replace(/^-/, "").split(".");
+  if (fracPart.length <= maxDecimals) {
+    const trimmed = fracPart.replace(/0+$/, "");
+    return (neg ? "-" : "") + (trimmed ? `${intPart}.${trimmed}` : intPart);
+  }
+  // Round on the exact decimal string. `roundDown` forces truncation (toward
+  // zero) or ceiling, which callers use to guarantee a bound is never crossed
+  // by the rounding itself; otherwise round half-up.
+  const keep = fracPart.slice(0, maxDecimals);
+  const nextDigit = Number(fracPart[maxDecimals]);
+  let scaled = BigInt(intPart + keep);
+  const remainder = fracPart.slice(maxDecimals).replace(/0+$/, "") !== "";
+  if (roundDown === true) {
+    // truncate: scaled already floors the magnitude
+  } else if (roundDown === false) {
+    if (remainder) scaled += 1n;
+  } else if (nextDigit >= 5) {
+    scaled += 1n;
+  }
+  const s = scaled.toString().padStart(maxDecimals + 1, "0");
+  const cut = maxDecimals === 0 ? s : `${s.slice(0, -maxDecimals)}.${s.slice(-maxDecimals)}`;
+  const cleaned = cut.replace(/(\.\d*?)0+$/, "$1").replace(/\.$/, "");
+  return (neg ? "-" : "") + cleaned;
+}
+
+/** Significant-figure clamp. Integers are exempt, per Hyperliquid's rule. */
+function clampSigFigs(value, sigFigs, opts = {}) {
+  const text = String(value);
+  if (!text.includes(".")) return text; // integer prices are always allowed
+  const n = Number(text);
+  if (!Number.isFinite(n) || n === 0) return text;
+  const magnitude = Math.floor(Math.log10(Math.abs(n)));
+  const decimals = Math.max(0, sigFigs - 1 - magnitude);
+  return roundDecimal(text, decimals, opts);
+}
+
+/**
+ * Format a price for a given asset. Applies BOTH constraints: at most 5
+ * significant figures AND at most (6 - szDecimals) decimal places.
+ */
+export function formatPerpPrice(price, szDecimals, opts = {}) {
+  const maxDecimals = HL_PERP_PRICE_DECIMALS - Number(szDecimals ?? 0);
+  if (maxDecimals < 0) throw new Error("hl-perps: szDecimals out of range");
+  return roundDecimal(clampSigFigs(price, HL_PERP_MAX_SIG_FIGS, opts), maxDecimals, opts);
+}
+
+/** Format an order size to the asset's size precision. */
+export function formatPerpSize(size, szDecimals) {
+  const out = roundDecimal(size, Number(szDecimals ?? 0));
+  if (BigInt(out.split(".")[0]) < 0n) throw new Error("hl-perps: size must be positive");
+  if (Number(out) <= 0) throw new Error("hl-perps: size rounds to zero at this asset's precision");
+  return out;
+}
+
+/** Resolve a coin to its asset index and precision. Required before ordering. */
+export async function hlPerpAssetInfo(args = {}, opts = {}) {
+  const coin = String(args.coin || args.symbol || "").trim().toUpperCase();
+  if (!coin) throw new Error("hl-perps: coin required");
+  const meta = await hlMetaAndAssetCtxs(opts);
+  const universe = meta?.[0]?.universe ?? meta?.universe ?? [];
+  const ctxs = Array.isArray(meta?.[1]) ? meta[1] : [];
+  const index = universe.findIndex((a) => a.name === coin);
+  if (index < 0) throw new Error(`hl-perps: ${coin} is not a listed perp`);
+  const asset = universe[index];
+  if (asset.isDelisted) throw new Error(`hl-perps: ${coin} is delisted`);
+  const ctx = ctxs[index] || {};
+  return {
+    coin,
+    assetId: index,
+    szDecimals: asset.szDecimals ?? 0,
+    maxLeverage: asset.maxLeverage ?? null,
+    markPx: ctx.markPx ?? null,
+    oraclePx: ctx.oraclePx ?? null,
+  };
+}
+
+function orderTypeWire(kind, { tif = TIF.GTC, triggerPx, isMarket, szDecimals } = {}) {
+  switch (kind) {
+    case ORDER_TYPES.LIMIT:
+      return { limit: { tif } };
+    case ORDER_TYPES.MARKET:
+      // A "market" order on Hyperliquid is an IOC limit at an aggressive price.
+      return { limit: { tif: TIF.IOC } };
+    case ORDER_TYPES.STOP_MARKET:
+    case ORDER_TYPES.TAKE_PROFIT_MARKET:
+      return {
+        trigger: {
+          isMarket: true,
+          triggerPx: formatPerpPrice(triggerPx, szDecimals),
+          tpsl: kind === ORDER_TYPES.STOP_MARKET ? "sl" : "tp",
+        },
+      };
+    case ORDER_TYPES.STOP_LIMIT:
+    case ORDER_TYPES.TAKE_PROFIT_LIMIT:
+      return {
+        trigger: {
+          isMarket: false,
+          triggerPx: formatPerpPrice(triggerPx, szDecimals),
+          tpsl: kind === ORDER_TYPES.STOP_LIMIT ? "sl" : "tp",
+        },
+      };
+    default:
+      throw new Error(`hl-perps: unknown order type ${kind}`);
+  }
+}
+
+function envelope(action, nonce) {
+  return {
+    action,
+    nonce,
+    signatureChainId: HL_SIGNATURE_CHAIN_ID,
+    // The wallet signs this; Oracle never does.
+    requiresUserSignature: true,
+    signingReady: false,
+    broadcastReady: false,
+    executionReady: false,
+    submitTo: "https://api.hyperliquid.xyz/exchange",
+    note: "Sign this action with the user's wallet and POST it. Oracle does not submit.",
+  };
+}
+
+/**
+ * Prepare a perp order.
+ *
+ * Guardrails, all enforced BEFORE anything is built:
+ *  - size and price rounded to the asset's exact precision
+ *  - a limit order must state a price; a market order must state a slippage cap
+ *  - `maxSlippageBps` is capped at 100 bps, matching every other Oracle venue
+ *  - reduce-only is explicit, never inferred
+ */
+export async function hlPreparePerpOrder(args = {}, opts = {}) {
+  const info = await hlPerpAssetInfo(args, opts);
+  const kind = String(args.type || ORDER_TYPES.LIMIT);
+  const isBuy = args.side ? String(args.side).toLowerCase() === "buy" : Boolean(args.isBuy);
+  const reduceOnly = Boolean(args.reduceOnly);
+  const size = formatPerpSize(args.size ?? args.sz, info.szDecimals);
+
+  let price;
+  if (kind === ORDER_TYPES.MARKET) {
+    const mark = Number(info.markPx);
+    if (!Number.isFinite(mark)) throw new Error("hl-perps: no mark price available for a market order");
+    const bps = Number(args.maxSlippageBps ?? 50);
+    if (!Number.isInteger(bps) || bps < 0) throw new Error("hl-perps: maxSlippageBps must be a non-negative integer");
+    if (bps > 100) throw new Error(`hl-perps: maxSlippageBps ${bps} exceeds the hard 100 bps cap`);
+    // Aggressive IOC price: cross the book by at most the allowed slippage.
+    // Rounding to the venue's tick can push the limit BACK past the cap
+    // (0.0012345 * 1.01 rounds to 0.001247 = 101.26 bps), so round toward the
+    // mark — down for a buy, up for a sell — and verify the realised bps.
+    const rawLimit = isBuy ? mark * (1 + bps / 10_000) : mark * (1 - bps / 10_000);
+    price = formatPerpPrice(rawLimit, info.szDecimals, { roundDown: isBuy });
+    const realisedBps = Math.abs(Number(price) / mark - 1) * 10_000;
+    if (realisedBps > bps + 1e-9) {
+      throw new Error(
+        `hl-perps: tick rounding makes the limit ${realisedBps.toFixed(2)} bps from mark, above the ${bps} bps cap`
+      );
+    }
+  } else {
+    if (args.price == null && args.limitPx == null) {
+      throw new Error("hl-perps: a limit order requires an explicit price");
+    }
+    price = formatPerpPrice(args.price ?? args.limitPx, info.szDecimals);
+  }
+
+  const orderType = orderTypeWire(kind, {
+    tif: args.tif ?? (kind === ORDER_TYPES.MARKET ? TIF.IOC : TIF.GTC),
+    triggerPx: args.triggerPx,
+    szDecimals: info.szDecimals,
+  });
+
+  const order = {
+    a: info.assetId,
+    b: isBuy,
+    p: price,
+    s: size,
+    r: reduceOnly,
+    t: orderType,
+  };
+  if (args.clientOrderId) order.c = String(args.clientOrderId);
+
+  const action = {
+    type: "order",
+    orders: [order],
+    grouping: args.grouping || "na",
+  };
+
+  const nonce = Number(args.nonce ?? Date.now());
+  const notional = Number(price) * Number(size);
+
+  return {
+    provider: "hl-perps",
+    venue: "hyperliquid",
+    kind: "perp-order",
+    coin: info.coin,
+    assetId: info.assetId,
+    side: isBuy ? "buy" : "sell",
+    orderType: kind,
+    price,
+    size,
+    reduceOnly,
+    notionalUsd: Number.isFinite(notional) ? notional : null,
+    maxLeverage: info.maxLeverage,
+    markPx: info.markPx,
+    ...envelope(action, nonce),
+  };
+}
+
+/** Prepare a cancel by order id. */
+export async function hlPrepareCancelOrder(args = {}, opts = {}) {
+  const info = await hlPerpAssetInfo(args, opts);
+  const oid = args.orderId ?? args.oid;
+  if (oid == null) throw new Error("hl-perps: orderId required");
+  const action = { type: "cancel", cancels: [{ a: info.assetId, o: Number(oid) }] };
+  return {
+    provider: "hl-perps",
+    venue: "hyperliquid",
+    kind: "perp-cancel",
+    coin: info.coin,
+    orderId: Number(oid),
+    ...envelope(action, Number(args.nonce ?? Date.now())),
+  };
+}
+
+/**
+ * Prepare a leverage change.
+ * Cross vs isolated is an explicit choice: isolated caps loss to the margin
+ * posted on that position, cross shares the whole account balance.
+ */
+export async function hlPrepareUpdateLeverage(args = {}, opts = {}) {
+  const info = await hlPerpAssetInfo(args, opts);
+  const leverage = Number(args.leverage);
+  if (!Number.isInteger(leverage) || leverage < 1) {
+    throw new Error("hl-perps: leverage must be a positive integer");
+  }
+  if (info.maxLeverage != null && leverage > info.maxLeverage) {
+    throw new Error(`hl-perps: ${info.coin} allows at most ${info.maxLeverage}x, requested ${leverage}x`);
+  }
+  const mode = String(args.marginMode || MARGIN_MODE.CROSS).toLowerCase();
+  if (mode !== MARGIN_MODE.CROSS && mode !== MARGIN_MODE.ISOLATED) {
+    throw new Error(`hl-perps: marginMode must be "cross" or "isolated"`);
+  }
+  const action = {
+    type: "updateLeverage",
+    asset: info.assetId,
+    isCross: mode === MARGIN_MODE.CROSS,
+    leverage,
+  };
+  return {
+    provider: "hl-perps",
+    venue: "hyperliquid",
+    kind: "perp-leverage",
+    coin: info.coin,
+    leverage,
+    marginMode: mode,
+    maxLeverage: info.maxLeverage,
+    liquidationWarning:
+      leverage >= 20
+        ? `${leverage}x liquidates on roughly a ${(100 / leverage).toFixed(2)}% adverse move before fees`
+        : null,
+    ...envelope(action, Number(args.nonce ?? Date.now())),
+  };
+}
+
+/** Prepare an isolated-margin adjustment for an existing position. */
+export async function hlPrepareUpdateIsolatedMargin(args = {}, opts = {}) {
+  const info = await hlPerpAssetInfo(args, opts);
+  const usd = args.usd ?? args.amountUsd;
+  if (usd == null) throw new Error("hl-perps: usd amount required");
+  const text = String(usd).trim();
+  if (!/^-?\d+(\.\d+)?$/.test(text)) throw new Error("hl-perps: usd must be a decimal number");
+  // Hyperliquid takes this in micro-USD as an integer. The old padEnd() sized
+  // the result from the NUMERIC magnitude, so "01.5" scaled 10x too small and
+  // silently under-posted margin. Scale by exact string arithmetic instead.
+  const micro = toScaledInteger(text, 6, "hl-perps: usd");
+  const action = {
+    type: "updateIsolatedMargin",
+    asset: info.assetId,
+    isBuy: true,
+    ntli: micro <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(micro) : micro.toString(),
+  };
+  return {
+    provider: "hl-perps",
+    venue: "hyperliquid",
+    kind: "perp-isolated-margin",
+    coin: info.coin,
+    usd: text,
+    ...envelope(action, Number(args.nonce ?? Date.now())),
+  };
+}
+
+/**
+ * Prepare a bracket: entry plus take-profit and/or stop-loss as reduce-only
+ * triggers. Grouped so the venue treats them as one position's protection.
+ */
+export async function hlPrepareBracketOrder(args = {}, opts = {}) {
+  const entry = await hlPreparePerpOrder(args, opts);
+  const info = await hlPerpAssetInfo(args, opts);
+  const isBuy = entry.side === "buy";
+  const orders = [entry.action.orders[0]];
+
+  if (args.takeProfitPx != null) {
+    orders.push({
+      a: info.assetId,
+      b: !isBuy,
+      p: formatPerpPrice(args.takeProfitPx, info.szDecimals),
+      s: entry.size,
+      r: true,
+      t: orderTypeWire(ORDER_TYPES.TAKE_PROFIT_MARKET, { triggerPx: args.takeProfitPx, szDecimals: info.szDecimals }),
+    });
+  }
+  if (args.stopLossPx != null) {
+    orders.push({
+      a: info.assetId,
+      b: !isBuy,
+      p: formatPerpPrice(args.stopLossPx, info.szDecimals),
+      s: entry.size,
+      r: true,
+      t: orderTypeWire(ORDER_TYPES.STOP_MARKET, { triggerPx: args.stopLossPx, szDecimals: info.szDecimals }),
+    });
+  }
+  if (orders.length === 1) throw new Error("hl-perps: a bracket needs takeProfitPx and/or stopLossPx");
+
+  const action = { type: "order", orders, grouping: "normalTpsl" };
+  return {
+    provider: "hl-perps",
+    venue: "hyperliquid",
+    kind: "perp-bracket",
+    coin: info.coin,
+    legs: orders.length,
+    entry: { side: entry.side, price: entry.price, size: entry.size },
+    takeProfitPx: args.takeProfitPx == null ? null : formatPerpPrice(args.takeProfitPx, info.szDecimals),
+    stopLossPx: args.stopLossPx == null ? null : formatPerpPrice(args.stopLossPx, info.szDecimals),
+    ...envelope(action, Number(args.nonce ?? Date.now())),
+  };
+}