@candledottv/agent-sdk 0.6.1 → 0.6.3

package/dist/index.js

@@ -445,7 +445,8 @@ var HYPERLIQUID_ALLOWED_ACTION_TYPES = [
   "cancel",
   "modify",
   "updateLeverage",
-  "updateIsolatedMargin"
+  "updateIsolatedMargin",
+  "scheduleCancel"
 ];
 var HYPERLIQUID_EXCHANGE_URLS = {
   mainnet: "https://api.hyperliquid.xyz/exchange",
@@ -455,7 +456,13 @@ var HYPERLIQUID_INFO_URLS = {
   mainnet: "https://api.hyperliquid.xyz/info",
   testnet: "https://api.hyperliquid-testnet.xyz/info"
 };
-var CANDLE_HYPERLIQUID_BUILDER_ADDRESS = null;
+var CANDLE_HYPERLIQUID_BUILDER_ADDRESS = "0xc43ff1f6ad9f93fc94558e07c2071b8458e7470b";
+function resolveHyperliquidBuilder(override, releasePin = CANDLE_HYPERLIQUID_BUILDER_ADDRESS) {
+  const builder = override === undefined ? releasePin : override;
+  if (typeof builder !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(builder) || /^0x0{40}$/.test(builder))
+    throw new Error("PERPS_BUILD_REFUSED: no valid nonzero Hyperliquid builder address in the explicit override or release pin.");
+  return builder.toLowerCase();
+}
 var HYPERLIQUID_MAX_BUILDER_FEE_TENTHS_BPS = 100;
 var HYPERLIQUID_MAX_BUILDER_FEE_RATE = "0.1%";
 var HYPERLIQUID_SIGNATURE_CHAIN_ID = "0xa4b1";
@@ -624,6 +631,43 @@ function sameValue(a, b) {
   return canonical(a) === canonical(b);
 }
 var EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+var HYPERLIQUID_CLOID_RE = /^0x[0-9a-f]{32}$/;
+var HYPERLIQUID_STANDARD_ACCOUNT_MODES = ["default", "disabled"];
+async function hyperliquidAccountMode(fetcher, network, address) {
+  const res = await fetcher(HYPERLIQUID_INFO_URLS[network], {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ type: "userAbstraction", user: address.toLowerCase() })
+  });
+  if (!res.ok)
+    throw new Error("Cannot read the account mode from Hyperliquid");
+  let mode;
+  try {
+    mode = JSON.parse(await res.text());
+  } catch {
+    throw new Error("Hyperliquid returned an unreadable account mode");
+  }
+  if (typeof mode !== "string" || mode.length === 0 || mode.length > 64)
+    throw new Error("Hyperliquid returned an unreadable account mode");
+  return mode;
+}
+function perpsSetupStatusProblem(status, expect) {
+  if (!HYPERLIQUID_STANDARD_ACCOUNT_MODES.includes(expect.mode))
+    return `the account is in ${expect.mode} mode on Hyperliquid; Candle trades only a standard account`;
+  if (status.network !== expect.network)
+    return `the setup answer is for ${String(status.network)}`;
+  if (typeof status.address !== "string" || status.address.toLowerCase() !== expect.address.toLowerCase())
+    return "the setup answer is for a different wallet";
+  if (status.mode !== expect.mode)
+    return "the setup answer reports a mode Hyperliquid does not";
+  if (status.standardMode !== true)
+    return "the setup answer does not report standard mode";
+  if (typeof status.builder !== "string" || status.builder.toLowerCase() !== expect.builder.toLowerCase())
+    return "the setup answer names a builder that is not Candle's";
+  if (status.ready === true && (typeof status.approvedFeeTenthsBps !== "number" || status.approvedFeeTenthsBps < HYPERLIQUID_MAX_BUILDER_FEE_TENTHS_BPS))
+    return "the setup answer reports ready without Candle's builder approval";
+  return null;
+}
 function checkBuilderField(action, builder) {
   if (!("builder" in action) || action.builder === undefined)
     return null;
@@ -646,7 +690,67 @@ function decimal(value) {
   const n = BigInt(whole) * 10n ** 18n + BigInt(frac.padEnd(18, "0"));
   return negative ? -n : n;
 }
-function checkActionIntent(action, intent) {
+var ACTION_KEYS = {
+  order: { required: ["type", "orders", "grouping"], optional: ["builder"] },
+  cancel: { required: ["type", "cancels"], optional: [] },
+  modify: { required: ["type", "oid", "order"], optional: [] },
+  updateLeverage: { required: ["type", "asset", "isCross", "leverage"], optional: [] },
+  updateIsolatedMargin: { required: ["type", "asset", "isBuy", "ntli"], optional: [] },
+  scheduleCancel: { required: ["type"], optional: ["time"] }
+};
+function exactKeys(value, required, optional = []) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const keys = Object.keys(value);
+  return required.every((k) => keys.includes(k)) && keys.every((k) => required.includes(k) || optional.includes(k));
+}
+function actionShapeProblem(action) {
+  const shape = ACTION_KEYS[String(action.type)];
+  if (!shape)
+    return null;
+  if (!exactKeys(action, shape.required, shape.optional))
+    return `the ${String(action.type)} action carries unexpected or missing fields`;
+  if (action.type === "order") {
+    if (!["na", "normalTpsl", "positionTpsl"].includes(action.grouping))
+      return "unexpected order grouping";
+    if (action.builder !== undefined && !exactKeys(action.builder, ["b", "f"]))
+      return "builder field is not an object";
+  }
+  const orders = action.type === "order" ? action.orders : action.type === "modify" ? [action.order] : [];
+  if (!Array.isArray(orders))
+    return "invalid orders";
+  for (const raw of orders) {
+    if (!exactKeys(raw, ["a", "b", "p", "s", "r", "t"], ["c"]))
+      return "an order carries unexpected or missing fields";
+    const o = raw;
+    const t = o.t;
+    const limit = exactKeys(t, ["limit"]) && exactKeys(t.limit, ["tif"]);
+    const trigger = exactKeys(t, ["trigger"]) && exactKeys(t.trigger, ["isMarket", "triggerPx", "tpsl"]);
+    if (!limit && !trigger)
+      return "an order type carries unexpected or missing fields";
+    if (o.c !== undefined && (typeof o.c !== "string" || !HYPERLIQUID_CLOID_RE.test(o.c)))
+      return "an order carries a malformed client order id";
+  }
+  if (action.type === "cancel") {
+    const cancels = action.cancels;
+    if (!Array.isArray(cancels) || cancels.some((c) => !exactKeys(c, ["a", "o"]) || !Number.isSafeInteger(c.o) || c.o < 0))
+      return "a cancel carries unexpected or missing fields";
+  }
+  if (action.type === "modify") {
+    const oid = action.oid;
+    if (!(Number.isSafeInteger(oid) && oid >= 0) && !(typeof oid === "string" && HYPERLIQUID_CLOID_RE.test(oid)))
+      return "the modify names no order";
+  }
+  if (action.type === "scheduleCancel" && "time" in action && (!Number.isSafeInteger(action.time) || action.time <= 0))
+    return "the scheduled cancel carries an invalid time";
+  return null;
+}
+function withinBps(px, reference, isBuy, bps) {
+  const bound = BigInt(bps);
+  return isBuy ? px * 10000n <= reference * (10000n + bound) : px * 10000n >= reference * (10000n - bound);
+}
+function checkActionIntent(action, opts) {
+  const intent = opts.intent;
   const mainAsset = (a) => typeof a === "number" && Number.isInteger(a) && a >= 0 && a < 1e4;
   const orderList = action.type === "order" ? action.orders : action.type === "modify" ? [action.order] : [];
   if (!Array.isArray(orderList))
@@ -659,6 +763,8 @@ function checkActionIntent(action, intent) {
       return "order asset is outside the main perp universe";
     if (typeof o.b !== "boolean" || typeof o.r !== "boolean" || (decimal(o.s) ?? 0n) <= 0n || (decimal(o.p) ?? 0n) <= 0n)
       return "invalid order side, size, price or reduce-only flag";
+    if (opts.keyReduceOnly === true && o.r !== true)
+      return "this key is reduce-only and the build is not reducing";
   }
   if (action.type === "cancel") {
     if (!Array.isArray(action.cancels) || action.cancels.length !== 1 || !mainAsset(action.cancels[0]?.a))
@@ -676,24 +782,101 @@ function checkActionIntent(action, intent) {
     cancel: "cancel",
     modify: "modify",
     leverage: "updateLeverage",
-    margin: "updateIsolatedMargin"
+    margin: "updateIsolatedMargin",
+    tpsl: "order",
+    scheduleCancel: "scheduleCancel"
   };
   if (action.type !== types[method])
     return "action type does not match the requested method";
+  if (opts.keyReduceOnly === true && method === "open")
+    return "this key is reduce-only and an open is not reducing";
+  if (method === "cancel" && opts.cancelTarget) {
+    const target = action.cancels[0];
+    if (target?.a !== opts.cancelTarget.asset || target?.o !== opts.cancelTarget.oid)
+      return "the cancel does not name the order Hyperliquid shows for this request";
+  }
   if (method === "leverage") {
-    if (action.leverage !== p.leverage || action.isCross !== (p.mode !== "isolated"))
+    const wanted = p.leverage ?? opts.leverageTarget?.leverage;
+    const deferred = wanted === undefined && opts.awaitingVenue === true && Number.isSafeInteger(action.leverage);
+    if (!deferred && (typeof wanted !== "number" || action.leverage !== wanted) || action.isCross !== (p.mode !== "isolated"))
       return "leverage or mode does not match the request";
+    const target = opts.leverageTarget;
+    if (target) {
+      if (action.asset !== target.asset)
+        return "leverage asset is not the requested coin's on Hyperliquid";
+      const mode = action.isCross ? "cross" : "isolated";
+      if (mode !== target.mode && !target.flat)
+        return "a margin-mode change needs no position and no resting order in the coin; close and cancel first";
+      if (opts.keyReduceOnly === true && (mode !== target.mode || action.leverage > target.leverage))
+        return "this key is reduce-only: no leverage increase or margin-mode change";
+    }
   }
   if (method === "margin") {
     const amount = decimal(p.amount);
     if (amount === null || amount % 10n ** 12n !== 0n || !Number.isSafeInteger(action.ntli) || BigInt(action.ntli) !== amount / 10n ** 12n || action.isBuy !== true)
       return "isolated margin amount does not match the request";
+    if (opts.marginTarget && action.asset !== opts.marginTarget.asset)
+      return "margin asset is not the requested coin's on Hyperliquid";
+    if (opts.keyReduceOnly === true && action.ntli <= 0)
+      return "this key is reduce-only: margin may only be added";
+  }
+  if (method === "scheduleCancel") {
+    if (p.clear === true) {
+      if ("time" in action)
+        return "a clear must omit the time";
+    } else {
+      const seconds = p.seconds;
+      const time = action.time;
+      if (!Number.isSafeInteger(seconds) || seconds < 5)
+        return "a scheduled cancel needs at least 5 seconds";
+      if (!Number.isSafeInteger(time))
+        return "a scheduled cancel without a time";
+      if (opts.clock) {
+        const lead = time - opts.clock.now;
+        if (lead < HYPERLIQUID_SCHEDULE_CANCEL_MIN_LEAD_MS)
+          return "the scheduled time is less than 5 seconds ahead; build it again";
+        if (Math.abs(time - (opts.clock.now + seconds * 1000)) > HYPERLIQUID_SCHEDULE_CANCEL_DRIFT_MS)
+          return "the scheduled time is not the requested delay from now";
+      }
+    }
+  }
+  if (method === "tpsl") {
+    const list = orderList;
+    const leg = list[0];
+    if (list.length !== 1 || !leg || action.grouping !== "positionTpsl")
+      return "a take-profit / stop-loss attach is one positionTpsl order";
+    const trigger = leg.t?.trigger;
+    if (!trigger || leg.r !== true || trigger.isMarket !== true || trigger.tpsl !== p.leg || decimal(trigger.triggerPx) !== decimal(p.triggerPx))
+      return "trigger leg, reduce-only flag or price does not match the request";
+    if (typeof leg.c !== "string" || !HYPERLIQUID_CLOID_RE.test(leg.c))
+      return "the trigger leg carries no client order id";
+    const triggerPx = decimal(trigger.triggerPx) ?? 0n;
+    if (triggerPx <= 0n || !withinBps(decimal(leg.p) ?? 0n, triggerPx, leg.b === true, HYPERLIQUID_TPSL_SLIPPAGE_BPS + HYPERLIQUID_MID_DRIFT_BPS))
+      return "trigger order price is outside its slippage of the trigger price";
+    const target = opts.tpslTarget;
+    if (target) {
+      if (leg.a !== target.asset || leg.b !== target.isBuy || decimal(leg.s) !== decimal(target.size))
+        return "trigger side, asset or size does not match the position Hyperliquid shows";
+      const mark = decimal(target.markPx) ?? 0n;
+      const above = triggerPx > mark;
+      const ok = p.leg === "tp" === !target.isBuy ? above : triggerPx < mark;
+      if (mark <= 0n || !ok)
+        return "the trigger is already crossed or on the wrong side of the mark";
+    }
   }
   if (method === "open" || method === "close" || method === "modify") {
     const list = orderList;
     const first = list[0];
     if (!first)
       return "missing requested order";
+    if ((method === "open" || method === "close") && p.clientId != null) {
+      const clientId = typeof p.clientId === "string" ? p.clientId.toLowerCase() : null;
+      if (clientId === null || !HYPERLIQUID_CLOID_RE.test(clientId) || first.c !== clientId)
+        return "the order does not carry the requested client order id";
+      const ids = list.map((o) => o.c);
+      if (ids.some((c) => typeof c !== "string" || !HYPERLIQUID_CLOID_RE.test(c)) || new Set(ids).size !== ids.length)
+        return "the order legs do not carry distinct client order ids";
+    }
     const typ = first.t;
     if (!typ?.limit)
       return "requested order is not a limit/IOC order";
@@ -718,11 +901,17 @@ function checkActionIntent(action, intent) {
         const trigger = leg.t?.trigger;
         if (leg.a !== first.a || leg.b !== !buy || leg.r !== true || decimal(leg.s) !== decimal(p.size) || trigger?.tpsl !== kind || trigger.isMarket !== true || decimal(trigger.triggerPx) !== decimal(p[field]))
           return "trigger side, size, reduce-only flag or price does not match the request";
+        const px = decimal(leg.p) ?? 0n;
+        const triggerPx = decimal(trigger.triggerPx) ?? 0n;
+        if (triggerPx <= 0n || !withinBps(px, triggerPx, leg.b === true, HYPERLIQUID_TPSL_SLIPPAGE_BPS + HYPERLIQUID_MID_DRIFT_BPS))
+          return "trigger order price is outside its slippage of the trigger price";
       }
     } else {
       if (list.length !== 1)
         return "unexpected extra orders";
-      if (method === "close" && (first.r !== true || typ.limit.tif !== "Ioc" || p.size != null && (decimal(first.s) ?? 0n) > (decimal(p.size) ?? 0n)))
+      if (method === "close" && p.pct != null && p.size != null)
+        return "a close takes a size or a percentage, not both";
+      if (method === "close" && (first.r !== true || typ.limit.tif !== "Ioc" || action.grouping !== "na" || p.size != null && (decimal(first.s) ?? 0n) > (decimal(p.size) ?? 0n)))
         return "close size or reduce-only flag does not match the request";
       if (method === "modify" && p.size != null && decimal(first.s) !== decimal(p.size))
         return "replacement size does not match the request";
@@ -732,9 +921,38 @@ function checkActionIntent(action, intent) {
   }
   return null;
 }
+function hyperliquidClosePct(value) {
+  if (typeof value !== "string" || !/^(0|[1-9][0-9]{0,2})(\.[0-9]{1,4})?$/.test(value))
+    return null;
+  const [whole = "0", frac = ""] = value.split(".");
+  const millionths = BigInt(whole) * 10000n + BigInt(frac.padEnd(4, "0"));
+  return millionths > 0n && millionths <= 1000000n ? millionths : null;
+}
+function hyperliquidPctSize(held, pct, szDecimals) {
+  const scaled = decimal(held);
+  if (scaled === null || scaled < 0n)
+    throw new Error("Invalid held size");
+  if (pct === 1000000n)
+    return held;
+  return hyperliquidFloorSize(formatScaled(scaled * pct / 1000000n), szDecimals);
+}
+function hyperliquidFloorSize(value, szDecimals) {
+  const scaled = decimal(value);
+  if (scaled === null || scaled < 0n)
+    throw new Error("Invalid size");
+  const unit = 10n ** BigInt(18 - Math.max(0, Math.min(18, szDecimals)));
+  return formatScaled(scaled / unit * unit);
+}
+function formatScaled(value) {
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const whole = abs / 10n ** 18n;
+  const frac = (abs % 10n ** 18n).toString().padStart(18, "0").replace(/0+$/, "");
+  return `${negative ? "-" : ""}${whole}${frac ? `.${frac}` : ""}`;
+}
 async function hyperliquidCloseOrder(fetcher, network, address, params) {
   const read = async (body) => {
-    const res = await fetcher(HYPERLIQUID_EXCHANGE_URLS[network].replace("/exchange", "/info"), {
+    const res = await fetcher(HYPERLIQUID_INFO_URLS[network], {
       method: "POST",
       headers: { "content-type": "application/json" },
       body: JSON.stringify(body)
@@ -745,20 +963,37 @@ async function hyperliquidCloseOrder(fetcher, network, address, params) {
   };
   const [meta, state] = await Promise.all([read({ type: "meta" }), read({ type: "clearinghouseState", user: address })]);
   const coin = String(params.coin).toUpperCase();
-  const asset = meta.universe.findIndex((m) => m.name.toUpperCase() === coin);
+  const universe = meta.universe;
+  const asset = universe.findIndex((m) => m.name.toUpperCase() === coin);
   const szi = state.assetPositions.find((p) => p.position.coin.toUpperCase() === coin)?.position.szi;
   const signed = decimal(szi);
   if (asset < 0 || asset >= 1e4 || signed === null || signed === 0n)
     throw new Error("No main-universe position to close");
   const held = signed < 0n ? -signed : signed;
+  const heldSz = String(szi).replace(/^-/, "");
+  if (params.pct != null) {
+    if (params.size != null)
+      throw new Error("A close takes a size or a percentage, not both");
+    const pct = hyperliquidClosePct(params.pct);
+    const szDecimals = universe[asset]?.szDecimals;
+    if (pct === null)
+      throw new Error("pct must be above 0 and at most 100, with at most 4 decimals");
+    if (!Number.isInteger(szDecimals))
+      throw new Error("Hyperliquid did not report this market's size precision");
+    const size2 = hyperliquidPctSize(heldSz, pct, szDecimals);
+    if ((decimal(size2) ?? 0n) <= 0n)
+      throw new Error("This percentage of the position rounds to zero at the market's size step");
+    return { asset, isBuy: signed < 0n, size: size2 };
+  }
   const asked = params.size == null ? held : decimal(params.size);
   if (asked === null || asked <= 0n)
     throw new Error("Invalid close size");
-  const size = asked < held ? String(params.size) : String(szi).replace(/^-/, "");
+  const size = asked < held ? String(params.size) : heldSz;
   return { asset, isBuy: signed < 0n, size };
 }
 var HYPERLIQUID_DEFAULT_SLIPPAGE_BPS = 100;
 var HYPERLIQUID_MID_DRIFT_BPS = 100;
+var HYPERLIQUID_TPSL_SLIPPAGE_BPS = 500;
 async function hyperliquidOrderMarket(fetcher, network, address, method, params) {
   const read = async (body) => {
     const res = await fetcher(HYPERLIQUID_INFO_URLS[network], {
@@ -777,8 +1012,18 @@ async function hyperliquidOrderMarket(fetcher, network, address, method, params)
     const resting = status?.order?.order ?? null;
     if (!resting || typeof resting.coin !== "string" || decimal(resting.limitPx) === null)
       throw new Error("No resting order with this cloid on Hyperliquid");
+    if (resting.isTrigger === true)
+      throw new Error("A take-profit or stop-loss leg cannot be modified; cancel it instead");
     coin = resting.coin.toUpperCase();
-    order = { isBuy: resting.side === "B", limitPx: String(resting.limitPx) };
+    const tif = typeof resting.tif === "string" && ["Gtc", "Alo", "Ioc"].includes(resting.tif) ? resting.tif : "Gtc";
+    order = {
+      isBuy: resting.side === "B",
+      limitPx: String(resting.limitPx),
+      ...decimal(resting.sz) !== null ? { size: String(resting.sz) } : {},
+      reduceOnly: resting.reduceOnly === true,
+      tif,
+      ...Number.isSafeInteger(resting.oid) ? { oid: resting.oid } : {}
+    };
   }
   const [meta, contexts] = await read({ type: "metaAndAssetCtxs" });
   const asset = meta.universe.findIndex((m) => m.name.toUpperCase() === coin);
@@ -815,13 +1060,24 @@ function checkOrderMarket(action, intent, market) {
       return "modify changes the resting order's side";
     if (p.price == null && decimal(first.p) !== decimal(market.order.limitPx))
       return "modify changes the resting order's price";
+    const requested = typeof p.cloid === "string" ? p.cloid.toLowerCase() : null;
+    const byOid = market.order.oid !== undefined && action.oid === market.order.oid;
+    const byCloid = requested !== null && typeof action.oid === "string" && action.oid.toLowerCase() === requested;
+    if (!byOid && !byCloid)
+      return "modify does not name the resting order Hyperliquid shows for this cloid";
+    if (first.r !== market.order.reduceOnly)
+      return "modify changes the resting order's reduce-only flag";
+    if (first.t?.limit?.tif !== market.order.tif)
+      return "modify changes the resting order's time in force";
+    if (p.size == null && (market.order.size === undefined || decimal(first.s) !== decimal(market.order.size)))
+      return "modify changes the resting order's size";
   }
   return null;
 }
 function verifyPerpsBuild(build, opts) {
   try {
     const network = opts.network ?? "mainnet";
-    if (!EVM_ADDRESS_RE.test(opts.builder))
+    if (!EVM_ADDRESS_RE.test(opts.builder) || opts.builder.toLowerCase() === ZERO_ADDRESS)
       return { ok: false, reason: "no valid Candle builder address to check against" };
     if (build.network !== undefined && build.network !== network) {
       return { ok: false, reason: `the build is for ${build.network}, this client trades ${network}` };
@@ -837,7 +1093,7 @@ function verifyPerpsBuild(build, opts) {
     const action = build.action;
     if (!action || typeof action !== "object")
       return { ok: false, reason: "no action" };
-    const intentRefusal = checkActionIntent(action, opts.intent);
+    const intentRefusal = checkActionIntent(action, opts);
     if (intentRefusal)
       return { ok: false, reason: intentRefusal };
     if (opts.closeOrder) {
@@ -857,6 +1113,9 @@ function verifyPerpsBuild(build, opts) {
       if (typeof type !== "string" || !HYPERLIQUID_ALLOWED_ACTION_TYPES.includes(type)) {
         return { ok: false, reason: `action type ${String(type)} is not one Candle builds` };
       }
+      const shapeRefusal = actionShapeProblem(action);
+      if (shapeRefusal)
+        return { ok: false, reason: shapeRefusal };
       if (type === "order") {
         const refusal = checkBuilderField(action, opts.builder);
         if (refusal)
@@ -877,37 +1136,2119 @@ function verifyPerpsBuild(build, opts) {
       if (!sameValue(typed, expected)) {
         return { ok: false, reason: "the builder approval is not Candle's builder at 0.1% on Mainnet" };
       }
-      const expectedAction = {
-        type: "approveBuilderFee",
-        hyperliquidChain: "Mainnet",
-        signatureChainId: HYPERLIQUID_SIGNATURE_CHAIN_ID,
-        maxFeeRate: HYPERLIQUID_MAX_BUILDER_FEE_RATE,
-        builder: opts.builder.toLowerCase(),
-        nonce: build.nonce
-      };
-      if (!sameValue(action, expectedAction)) {
-        return { ok: false, reason: "the approval action does not match its typed data" };
+      const expectedAction = {
+        type: "approveBuilderFee",
+        hyperliquidChain: "Mainnet",
+        signatureChainId: HYPERLIQUID_SIGNATURE_CHAIN_ID,
+        maxFeeRate: HYPERLIQUID_MAX_BUILDER_FEE_RATE,
+        builder: opts.builder.toLowerCase(),
+        nonce: build.nonce
+      };
+      if (!sameValue(action, expectedAction)) {
+        return { ok: false, reason: "the approval action does not match its typed data" };
+      }
+      return { ok: true, kind: "approveBuilderFee" };
+    }
+    return { ok: false, reason: `primary type ${String(typed.primary_type)} is not one the relay signs` };
+  } catch (err) {
+    return { ok: false, reason: err instanceof Error ? err.message : "unreadable build" };
+  }
+}
+var HYPERLIQUID_SCHEDULE_CANCEL_MIN_LEAD_MS = 5000;
+var HYPERLIQUID_SCHEDULE_CANCEL_DRIFT_MS = 60000;
+async function infoRead(fetcher, network, body) {
+  const res = await fetcher(HYPERLIQUID_INFO_URLS[network], {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  if (!res.ok)
+    throw new Error(`Hyperliquid ${String(body.type)} answered ${res.status ?? "an error"}`);
+  try {
+    return JSON.parse(await res.text());
+  } catch {
+    throw new Error(`Hyperliquid returned an unreadable ${String(body.type)}`);
+  }
+}
+async function hyperliquidWalletSnapshot(fetcher, network, address, now = Date.now) {
+  const user = address.toLowerCase();
+  const [metaAndCtxs, state, open] = await Promise.all([
+    infoRead(fetcher, network, { type: "metaAndAssetCtxs" }),
+    infoRead(fetcher, network, { type: "clearinghouseState", user }),
+    infoRead(fetcher, network, { type: "frontendOpenOrders", user })
+  ]);
+  const readAt = now();
+  if (!Array.isArray(metaAndCtxs) || metaAndCtxs.length < 2 || !Array.isArray(metaAndCtxs[1]))
+    throw new Error("Hyperliquid returned an unreadable market list");
+  const rawUniverse = metaAndCtxs[0]?.universe;
+  if (!Array.isArray(rawUniverse))
+    throw new Error("Hyperliquid returned an unreadable market list");
+  const universe = rawUniverse.map((m) => {
+    const row = m;
+    if (typeof row.name !== "string" || !Number.isInteger(row.szDecimals) || !Number.isInteger(row.maxLeverage))
+      throw new Error("Hyperliquid returned an unreadable market");
+    return {
+      name: row.name,
+      szDecimals: row.szDecimals,
+      maxLeverage: row.maxLeverage,
+      onlyIsolated: row.onlyIsolated === true
+    };
+  });
+  const ctxs = metaAndCtxs[1];
+  const marks = universe.map((_, i) => {
+    const mark = ctxs[i]?.markPx;
+    return typeof mark === "string" && (decimal(mark) ?? 0n) > 0n ? mark : null;
+  });
+  const assetOf = (coin) => universe.findIndex((m) => m.name === coin);
+  const unsupported = [];
+  const positionsRaw = state?.assetPositions;
+  if (!Array.isArray(positionsRaw))
+    throw new Error("Hyperliquid returned an unreadable account state");
+  const positions = [];
+  for (const entry of positionsRaw) {
+    const p = entry?.position;
+    const coin = p?.coin;
+    const lev = p?.leverage;
+    const szi = p?.szi;
+    if (typeof coin !== "string" || typeof szi !== "string" || decimal(szi) === null) {
+      unsupported.push(`an unreadable position (${JSON.stringify(coin ?? null)})`);
+      continue;
+    }
+    const asset = assetOf(coin);
+    if (asset < 0 || asset >= 1e4 || lev?.type !== "cross" && lev?.type !== "isolated" || !Number.isInteger(lev.value)) {
+      unsupported.push(`position ${coin}`);
+      continue;
+    }
+    if (decimal(szi) === 0n)
+      continue;
+    positions.push({ coin, asset, szi, leverage: { type: lev.type, value: lev.value } });
+  }
+  if (!Array.isArray(open))
+    throw new Error("Hyperliquid returned an unreadable order list");
+  const orders = [];
+  for (const raw of open) {
+    const o = raw;
+    const coin = o?.coin;
+    if (typeof coin !== "string") {
+      unsupported.push("an unreadable order");
+      continue;
+    }
+    const asset = assetOf(coin);
+    const oid = o.oid;
+    if (asset < 0 || asset >= 1e4 || !Number.isSafeInteger(oid) || o.side !== "A" && o.side !== "B" || decimal(o.sz) === null || decimal(o.limitPx) === null) {
+      unsupported.push(`order ${coin}${Number.isSafeInteger(oid) ? ` ${oid}` : ""}`);
+      continue;
+    }
+    const orderType = typeof o.orderType === "string" ? o.orderType : "";
+    const isTrigger = o.isTrigger === true;
+    const tpsl = isTrigger ? orderType.startsWith("Take Profit") ? "tp" : orderType.startsWith("Stop") ? "sl" : null : null;
+    if (isTrigger && tpsl === null) {
+      unsupported.push(`order ${coin} ${oid} (${orderType || "unknown trigger"})`);
+      continue;
+    }
+    orders.push({
+      coin,
+      asset,
+      oid,
+      cloid: typeof o.cloid === "string" ? o.cloid.toLowerCase() : null,
+      isBuy: o.side === "B",
+      sz: o.sz,
+      limitPx: o.limitPx,
+      reduceOnly: o.reduceOnly === true,
+      isTrigger,
+      triggerPx: typeof o.triggerPx === "string" ? o.triggerPx : null,
+      tpsl
+    });
+  }
+  orders.sort((a, b) => a.asset - b.asset || a.oid - b.oid);
+  positions.sort((a, b) => a.asset - b.asset);
+  return { readAt, universe, marks, positions, orders, unsupported };
+}
+function snapshotPosition(snapshot, coin) {
+  const upper = coin.toUpperCase();
+  return snapshot.positions.find((p) => p.coin.toUpperCase() === upper) ?? null;
+}
+function hyperliquidTpslTarget(snapshot, coin) {
+  const position = snapshotPosition(snapshot, coin);
+  if (!position)
+    throw new Error(`No ${coin} position on Hyperliquid to protect`);
+  const mark = snapshot.marks[position.asset];
+  const szDecimals = snapshot.universe[position.asset]?.szDecimals;
+  if (!mark || szDecimals === undefined)
+    throw new Error(`No Hyperliquid mark for ${position.coin}`);
+  const held = position.szi.replace(/^-/, "");
+  const size = hyperliquidFloorSize(held, szDecimals);
+  return { asset: position.asset, isBuy: position.szi.startsWith("-"), size, markPx: mark };
+}
+async function venueEvidence(fetcher, network, address, intent, now) {
+  const p = intent.params;
+  switch (intent.method) {
+    case "open":
+    case "modify":
+      return { market: await hyperliquidOrderMarket(fetcher, network, address, intent.method, p) };
+    case "close":
+      return { closeOrder: await hyperliquidCloseOrder(fetcher, network, address, p) };
+    case "cancel": {
+      if (p.oid !== undefined) {
+        const snapshot = await hyperliquidWalletSnapshot(fetcher, network, address, now);
+        const order = snapshot.orders.find((o) => o.oid === p.oid && (p.coin === undefined || o.coin.toUpperCase() === String(p.coin).toUpperCase()));
+        if (!order)
+          throw new Error("Hyperliquid shows no such open order on this wallet");
+        return { cancelTarget: { asset: order.asset, oid: order.oid } };
+      }
+      const status = await infoRead(fetcher, network, {
+        type: "orderStatus",
+        user: address.toLowerCase(),
+        oid: p.cloid
+      });
+      const resting = status?.order?.order;
+      if (!resting || typeof resting.coin !== "string" || !Number.isSafeInteger(resting.oid))
+        throw new Error("Hyperliquid shows no order with this cloid on this wallet");
+      const meta = await infoRead(fetcher, network, { type: "meta" });
+      const asset = (meta.universe ?? []).findIndex((m) => m.name === resting.coin);
+      if (asset < 0 || asset >= 1e4)
+        throw new Error("The order is not on Hyperliquid's main perp exchange");
+      return { cancelTarget: { asset, oid: resting.oid } };
+    }
+    case "leverage": {
+      const snapshot = await hyperliquidWalletSnapshot(fetcher, network, address, now);
+      const coin = String(p.coin ?? "").toUpperCase();
+      const asset = snapshot.universe.findIndex((m) => m.name.toUpperCase() === coin);
+      if (asset < 0)
+        throw new Error("No main-universe market for this coin on Hyperliquid");
+      const name = snapshot.universe[asset]?.name;
+      const data = await infoRead(fetcher, network, {
+        type: "activeAssetData",
+        user: address.toLowerCase(),
+        coin: name
+      });
+      const lev = data?.leverage;
+      if (lev?.type !== "cross" && lev?.type !== "isolated" || !Number.isInteger(lev.value))
+        throw new Error("Hyperliquid did not report this market's leverage");
+      const flat = !snapshot.positions.some((x) => x.asset === asset) && !snapshot.orders.some((o) => o.asset === asset);
+      return { leverageTarget: { asset, leverage: lev.value, mode: lev.type, flat } };
+    }
+    case "margin": {
+      const snapshot = await hyperliquidWalletSnapshot(fetcher, network, address, now);
+      const position = snapshotPosition(snapshot, String(p.coin ?? ""));
+      if (!position || position.leverage.type !== "isolated")
+        throw new Error("Hyperliquid shows no isolated position in this coin");
+      return { marginTarget: { asset: position.asset } };
+    }
+    case "tpsl": {
+      const snapshot = await hyperliquidWalletSnapshot(fetcher, network, address, now);
+      return { tpslTarget: hyperliquidTpslTarget(snapshot, String(p.coin ?? "")) };
+    }
+    case "scheduleCancel":
+      return { clock: { now: now() } };
+    default:
+      return {};
+  }
+}
+async function verifyPerpsBuildAgainstVenue(build, opts) {
+  const { fetcher, now = Date.now, ...verify } = opts;
+  const first = verifyPerpsBuild(build, { ...verify, awaitingVenue: true });
+  if (!first.ok)
+    return first;
+  let evidence;
+  try {
+    evidence = await venueEvidence(fetcher, verify.network ?? "mainnet", opts.address, opts.intent, now);
+  } catch (err) {
+    return {
+      ok: false,
+      reason: `could not check it against Hyperliquid: ${err instanceof Error ? err.message : "read failed"}`
+    };
+  }
+  return verifyPerpsBuild(build, { ...verify, ...evidence });
+}
+function hyperliquidExchangeOutcome(exchange) {
+  if (!exchange || typeof exchange !== "object")
+    return { status: "unknown", error: "Hyperliquid returned no answer" };
+  const answer = exchange;
+  if (answer.status === "err")
+    return {
+      status: "rejected",
+      error: typeof answer.response === "string" ? answer.response : JSON.stringify(answer.response ?? null),
+      legs: []
+    };
+  if (answer.status !== "ok")
+    return { status: "unknown", error: "Hyperliquid's answer has no status" };
+  const response = answer.response;
+  const statuses = response?.data?.statuses;
+  if (statuses === undefined) {
+    return response?.type === "default" || response?.type === "scheduleCancel" || response?.type === "cancel" ? { status: "confirmed", legs: [] } : { status: "unknown", error: "Hyperliquid's answer is not one this client knows" };
+  }
+  if (!Array.isArray(statuses))
+    return { status: "unknown", error: "Hyperliquid's answer has unreadable statuses" };
+  const errors = statuses.filter((s) => s && typeof s === "object" && ("error" in s)).map((s) => String(s.error));
+  if (errors.length > 0)
+    return { status: "rejected", error: errors.join("; "), legs: statuses };
+  return { status: "confirmed", legs: statuses };
+}
+function hyperliquidSplitSignature(signature) {
+  if (!/^0x[0-9a-fA-F]{130}$/.test(signature))
+    throw new Error("Not a 65-byte signature");
+  let v = Number.parseInt(signature.slice(130, 132), 16);
+  if (v < 27)
+    v += 27;
+  return { r: `0x${signature.slice(2, 66)}`, s: `0x${signature.slice(66, 130)}`, v };
+}
+function hyperliquidExchangeBody(action, nonce, signature) {
+  return { action, nonce, signature: hyperliquidSplitSignature(signature), vaultAddress: null, expiresAfter: null };
+}
+function hyperliquidRelayBody(typedData) {
+  return { method: "eth_signTypedData_v4", params: { typed_data: typedData } };
+}
+
+// src/hyperliquid-manage.ts
+var PERPS_FLATTEN_MAX_STEPS = 100;
+
+class PerpsWorkflowError extends Error {
+  code;
+  details;
+  constructor(code, message, details = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+function errorCode(err) {
+  const code = err?.code;
+  return typeof code === "string" ? code : "REQUEST_FAILED";
+}
+function errorText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function runStep(io, step, path, body, intent) {
+  let build;
+  try {
+    build = await io.build(path, { walletId: io.walletId, ...body });
+  } catch (err) {
+    step.status = "rejected";
+    step.detail = `${errorCode(err)}: ${errorText(err)}`;
+    return false;
+  }
+  if (build.replayed === true) {
+    step.status = "skipped";
+    step.detail = "This client id already names an operation; nothing was signed";
+    return false;
+  }
+  step.perpOrderId = typeof build.perpOrderId === "string" ? build.perpOrderId : null;
+  step.nonce = typeof build.nonce === "number" ? build.nonce : null;
+  if (typeof build.cloid === "string")
+    step.cloid = build.cloid;
+  const check = await verifyPerpsBuildAgainstVenue(build, {
+    builder: io.builder,
+    network: io.network,
+    address: io.address,
+    intent,
+    fetcher: io.fetcher,
+    now: io.now,
+    keyReduceOnly: io.keyReduceOnly
+  });
+  if (!check.ok) {
+    step.status = "rejected";
+    step.detail = `Refused to sign this build: ${check.reason}. Nothing was signed.`;
+    return false;
+  }
+  step.status = "built";
+  if (io.mode === "no-submit")
+    return false;
+  let signature;
+  try {
+    signature = await io.sign(build.typedData);
+  } catch (err) {
+    step.status = "rejected";
+    step.detail = `The relay did not sign (${errorCode(err)}: ${errorText(err)}). Nothing was submitted.`;
+    return false;
+  }
+  step.signature = signature;
+  const exchangeBody = hyperliquidExchangeBody(build.action, build.nonce, signature);
+  if (io.mode === "sign-only") {
+    step.exchangeBody = exchangeBody;
+    return false;
+  }
+  let exchange;
+  try {
+    const res = await io.fetcher(HYPERLIQUID_EXCHANGE_URLS[io.network], {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(exchangeBody)
+    });
+    const text = await res.text();
+    if (!res.ok)
+      throw new Error(`HTTP ${res.status ?? "error"}${res.status === 429 ? " (rate limited)" : ""}`);
+    exchange = JSON.parse(text);
+  } catch (err) {
+    step.status = "unknown";
+    step.detail = `Signed, but the submit to Hyperliquid did not answer (${errorText(err)}). Reconcile before acting again.`;
+    step.exchangeBody = exchangeBody;
+    return false;
+  }
+  step.exchange = exchange;
+  const outcome = hyperliquidExchangeOutcome(exchange);
+  if (outcome.status === "confirmed") {
+    step.status = "confirmed";
+    return true;
+  }
+  step.status = outcome.status;
+  step.detail = outcome.error;
+  if (outcome.status === "unknown")
+    step.exchangeBody = exchangeBody;
+  return false;
+}
+function blankStep(n, kind, coin, extra = {}) {
+  return {
+    step: n,
+    kind,
+    coin,
+    target: null,
+    perpOrderId: null,
+    nonce: null,
+    cloid: null,
+    status: "planned",
+    ...extra
+  };
+}
+var DECIMAL_RE = /^(0|[1-9][0-9]*)(\.[0-9]+)?$/;
+var CLOID_RE = /^0x[0-9a-f]{32}$/;
+function perpsTpslParamsProblem(p) {
+  if (typeof p.coin !== "string" || !/^[A-Za-z0-9]{1,20}$/.test(p.coin))
+    return "coin must be a market name";
+  for (const [field, value] of [
+    ["takeProfit", p.takeProfit],
+    ["stopLoss", p.stopLoss]
+  ])
+    if (value !== undefined && (typeof value !== "string" || !DECIMAL_RE.test(value) || /^0+(\.0+)?$/.test(value)))
+      return `${field} must be a positive decimal`;
+  if (p.takeProfit !== undefined && p.removeTp)
+    return "cannot set and remove the take-profit together";
+  if (p.stopLoss !== undefined && p.removeSl)
+    return "cannot set and remove the stop-loss together";
+  if (p.takeProfit === undefined && p.stopLoss === undefined && !p.removeTp && !p.removeSl)
+    return "name at least one change: a take-profit, a stop-loss, or a removal";
+  for (const [field, value] of [
+    ["targetTp", p.targetTp],
+    ["targetSl", p.targetSl]
+  ])
+    if (value !== undefined && (typeof value !== "string" || !CLOID_RE.test(value.toLowerCase())))
+      return `${field} must be 0x followed by 32 hex digits`;
+  if (p.targetTp !== undefined && p.takeProfit === undefined && !p.removeTp)
+    return "targetTp needs a take-profit change";
+  if (p.targetSl !== undefined && p.stopLoss === undefined && !p.removeSl)
+    return "targetSl needs a stop-loss change";
+  return null;
+}
+function sameDecimal(a, b) {
+  if (typeof a !== "string" || typeof b !== "string")
+    return false;
+  const norm = (v) => (v.includes(".") ? v.replace(/0+$/, "").replace(/\.$/, "") : v).replace(/^0+(?=\d)/, "");
+  return norm(a) === norm(b);
+}
+async function runPerpsTpsl(io, params) {
+  const problem = perpsTpslParamsProblem(params);
+  if (problem)
+    throw new PerpsWorkflowError("VALIDATION_FAILED", problem);
+  const coinQuery = encodeURIComponent(params.coin);
+  const server = await io.read(`/api/v1/agent/perps/tpsl?walletId=${encodeURIComponent(io.walletId)}&coin=${coinQuery}`);
+  let snapshot;
+  try {
+    snapshot = await hyperliquidWalletSnapshot(io.fetcher, io.network, io.address, io.now);
+  } catch (err) {
+    throw new PerpsWorkflowError("PERPS_UNAVAILABLE", `Cannot read the account from Hyperliquid: ${errorText(err)}`);
+  }
+  const coin = typeof server.coin === "string" ? server.coin : params.coin.toUpperCase();
+  const venueLegs = snapshot.orders.filter((o) => o.coin === coin && o.tpsl !== null);
+  const tracked = [];
+  for (const raw of Array.isArray(server.tracked) ? server.tracked : []) {
+    const seen = venueLegs.find((o) => o.oid === raw.oid && o.tpsl === raw.leg && (o.cloid ?? null) === (raw.cloid ?? null));
+    if (seen)
+      tracked.push({ leg: raw.leg, oid: seen.oid, cloid: seen.cloid, triggerPx: seen.triggerPx });
+  }
+  const trackedOids = new Set(tracked.map((l) => l.oid));
+  const unowned = venueLegs.filter((o) => !trackedOids.has(o.oid)).map((o) => ({ leg: o.tpsl, oid: o.oid, cloid: o.cloid, triggerPx: o.triggerPx }));
+  const position = snapshotPosition(snapshot, coin);
+  const warnings = [];
+  if (unowned.length > 0)
+    warnings.push(`${unowned.length} take-profit / stop-loss leg(s) on ${coin} were not built by Candle; they are left untouched.`);
+  const steps = [];
+  const plans = [];
+  for (const leg of ["tp", "sl"]) {
+    const set = leg === "tp" ? params.takeProfit : params.stopLoss;
+    const remove = leg === "tp" ? params.removeTp === true : params.removeSl === true;
+    if (set === undefined && !remove)
+      continue;
+    const target = (leg === "tp" ? params.targetTp : params.targetSl)?.toLowerCase();
+    let legs = tracked.filter((l) => l.leg === leg);
+    if (target !== undefined) {
+      legs = legs.filter((l) => l.cloid === target);
+      if (legs.length === 0)
+        throw new PerpsWorkflowError("PERPS_ORDER_NOT_FOUND", `No open ${coin} ${leg} leg Candle built carries ${target}`);
+    }
+    if (legs.length > 1)
+      throw new PerpsWorkflowError("PERPS_TPSL_CONFLICT", `${legs.length} ${coin} ${leg === "tp" ? "take-profit" : "stop-loss"} legs match; name one with --target-${leg} <cloid>`, { candidates: legs });
+    const existing = legs[0] ?? null;
+    if (set !== undefined && existing && sameDecimal(existing.triggerPx, set)) {
+      steps.push(blankStep(steps.length, "attach", coin, {
+        leg,
+        target: { oid: existing.oid, cloid: existing.cloid },
+        status: "skipped",
+        detail: "Already in place at this trigger"
+      }));
+      continue;
+    }
+    if (set !== undefined && !position)
+      throw new PerpsWorkflowError("PERPS_NO_POSITION", `No ${coin} position on Hyperliquid to protect`);
+    if (remove && !existing) {
+      steps.push(blankStep(steps.length, "cancel", coin, { leg, status: "skipped", detail: "No tracked leg to remove" }));
+      continue;
+    }
+    const cancel = existing ? blankStep(steps.length, "cancel", coin, { leg, target: { oid: existing.oid, cloid: existing.cloid } }) : null;
+    if (cancel)
+      steps.push(cancel);
+    const attach = set !== undefined ? blankStep(steps.length, "attach", coin, { leg }) : null;
+    if (attach)
+      steps.push(attach);
+    if (cancel && attach)
+      warnings.push(`Changing the ${leg === "tp" ? "take-profit" : "stop-loss"} cancels the current leg first: ${coin} is unprotected on that side until the new one is placed.`);
+    if (cancel && !attach)
+      warnings.push(`Removing the ${leg === "tp" ? "take-profit" : "stop-loss"} leaves ${coin} without it.`);
+    plans.push({ leg, cancel, attach, ...set !== undefined ? { triggerPx: set } : {} });
+  }
+  if (plans.some((p) => p.attach))
+    warnings.push("New legs are sized to the position now and do not grow with later additions; triggering does not guarantee a fill.");
+  const result = {
+    operation: "tpsl",
+    walletId: io.walletId,
+    address: io.address,
+    network: io.network,
+    readAt: snapshot.readAt,
+    complete: false,
+    steps,
+    remaining: [],
+    warnings,
+    unowned
+  };
+  const active = steps.filter((s) => s.status === "planned");
+  if (active.length === 0) {
+    result.complete = true;
+    return result;
+  }
+  if (io.mode !== "no-submit" && io.confirm && !await io.confirm({ steps, warnings }))
+    throw new PerpsWorkflowError("CANCELLED", "Nothing was signed.");
+  const workflowId = `tpsl-${io.cloid().slice(2, 18)}`;
+  let stopped = false;
+  for (const plan of plans) {
+    if (stopped)
+      break;
+    if (plan.cancel) {
+      const step = plan.cancel;
+      const ok = await runStep(io, step, "/api/v1/agent/perps/tpsl", {
+        coin,
+        operation: "cancel",
+        leg: plan.leg,
+        ...step.target?.cloid ? { targetCloid: step.target.cloid } : {},
+        workflowId,
+        workflowStep: step.step
+      }, { method: "cancel", params: { coin, oid: step.target?.oid } });
+      if (!ok) {
+        stopped = true;
+        break;
+      }
+      try {
+        const after = await hyperliquidWalletSnapshot(io.fetcher, io.network, io.address, io.now);
+        result.readAt = after.readAt;
+        if (after.orders.some((o) => o.oid === step.target?.oid)) {
+          step.status = "unknown";
+          step.detail = "Hyperliquid accepted the cancel but still shows the leg open; no replacement was placed";
+          stopped = true;
+          break;
+        }
+        if (plan.attach && !snapshotPosition(after, coin)) {
+          plan.attach.status = "skipped";
+          plan.attach.detail = "The position closed meanwhile; no replacement was placed";
+          continue;
+        }
+      } catch (err) {
+        step.detail = `Canceled, but the follow-up read failed (${errorText(err)}); no replacement was placed`;
+        stopped = true;
+        break;
+      }
+    }
+    if (plan.attach) {
+      const ok = await runStep(io, plan.attach, "/api/v1/agent/perps/tpsl", {
+        coin,
+        operation: "attach",
+        leg: plan.leg,
+        triggerPx: plan.triggerPx,
+        workflowId,
+        workflowStep: plan.attach.step
+      }, { method: "tpsl", params: { coin, leg: plan.leg, triggerPx: plan.triggerPx } });
+      if (!ok)
+        stopped = true;
+    }
+  }
+  for (const s of steps) {
+    if (s.status === "planned")
+      result.remaining.push({ step: s.step, kind: s.kind, leg: s.leg, coin });
+    if (s.kind === "cancel" && s.status === "confirmed" && plans.find((p) => p.cancel === s)?.attach?.status !== "confirmed")
+      result.remaining.push({ leg: s.leg, coin, state: "old leg canceled, no new leg in place" });
+  }
+  result.complete = steps.every((s) => s.status === "confirmed" || s.status === "skipped") && !stopped;
+  return result;
+}
+function orderTarget(o) {
+  return { oid: o.oid, cloid: o.cloid };
+}
+function snapshotOrError(io) {
+  return hyperliquidWalletSnapshot(io.fetcher, io.network, io.address, io.now);
+}
+async function runPerpsFlatten(io) {
+  let snapshot;
+  try {
+    snapshot = await snapshotOrError(io);
+  } catch (err) {
+    throw new PerpsWorkflowError("PERPS_UNAVAILABLE", `Cannot read the account from Hyperliquid: ${errorText(err)}`);
+  }
+  if (snapshot.unsupported.length > 0)
+    throw new PerpsWorkflowError("PERPS_MARKET_REFUSED", `Flatten reaches Hyperliquid's main perp exchange only, and this wallet holds rows it cannot classify there: ${snapshot.unsupported.slice(0, 5).join(", ")}. Nothing was built.`, { unsupported: snapshot.unsupported });
+  const warnings = [
+    "Scope: Hyperliquid's main perp exchange only. Spot, HIP-3 and vault exposure is not read or closed.",
+    "Every open order is canceled first, take-profit and stop-loss protection included.",
+    "The final state is an observed snapshot; another client can open exposure afterwards."
+  ];
+  const steps = [];
+  for (const o of snapshot.orders)
+    steps.push(blankStep(steps.length, "cancel", o.coin, { target: orderTarget(o) }));
+  const closeIds = new Map;
+  for (const p of snapshot.positions) {
+    const id = io.cloid();
+    closeIds.set(p.coin, id);
+    steps.push(blankStep(steps.length, "close", p.coin, { cloid: id }));
+  }
+  const result = {
+    operation: "flatten",
+    walletId: io.walletId,
+    address: io.address,
+    network: io.network,
+    readAt: snapshot.readAt,
+    complete: false,
+    steps,
+    remaining: [],
+    warnings,
+    scope: "main-perps"
+  };
+  if (steps.length === 0) {
+    result.complete = true;
+    return result;
+  }
+  if (steps.length > PERPS_FLATTEN_MAX_STEPS)
+    warnings.push(`${steps.length} steps planned; this run signs at most ${PERPS_FLATTEN_MAX_STEPS} and reports the rest as remaining. Run flatten again.`);
+  if (io.mode !== "no-submit" && io.confirm && !await io.confirm({ steps, warnings }))
+    throw new PerpsWorkflowError("CANCELLED", "Nothing was signed.");
+  const workflowId = `flat-${io.cloid().slice(2, 18)}`;
+  const cancelStep = (step) => runStep(io, step, "/api/v1/agent/perps/flatten/cancel", { coin: step.coin, oid: step.target?.oid, workflowId, workflowStep: step.step }, { method: "cancel", params: { coin: step.coin, oid: step.target?.oid } });
+  const closeStep = (step) => {
+    const clientId = closeIds.get(step.coin);
+    return runStep(io, step, "/api/v1/agent/perps/close", { coin: step.coin, clientId, workflowId, workflowStep: step.step }, { method: "close", params: { coin: step.coin, clientId } });
+  };
+  if (io.mode !== "submit") {
+    const first = steps[0];
+    await (first.kind === "cancel" ? cancelStep(first) : closeStep(first));
+    for (const s of steps)
+      if (s.status === "planned")
+        result.remaining.push({ step: s.step, kind: s.kind, coin: s.coin, target: s.target });
+    return result;
+  }
+  let signed = 0;
+  let stopped = false;
+  const budgetLeft = () => signed < PERPS_FLATTEN_MAX_STEPS;
+  for (const step of steps.filter((s) => s.kind === "cancel")) {
+    if (stopped || !budgetLeft())
+      break;
+    signed++;
+    if (await cancelStep(step))
+      continue;
+    if (step.status === "rejected" && step.detail?.startsWith("PERPS_ORDER_NOT_OPEN")) {
+      step.status = "skipped";
+      continue;
+    }
+    stopped = true;
+  }
+  if (!stopped && budgetLeft()) {
+    let after = null;
+    try {
+      after = await snapshotOrError(io);
+      result.readAt = after.readAt;
+    } catch (err) {
+      warnings.push(`The read after the cancels failed (${errorText(err)}); no position was closed.`);
+      stopped = true;
+    }
+    if (after) {
+      const fresh = after.orders.filter((o) => !steps.some((s) => s.kind === "cancel" && s.target?.oid === o.oid));
+      if (fresh.length > 0)
+        warnings.push(`${fresh.length} order(s) appeared during the cancels and were not part of this run's plan.`);
+      for (const p of after.positions)
+        if (!closeIds.has(p.coin)) {
+          const id = io.cloid();
+          closeIds.set(p.coin, id);
+          steps.push(blankStep(steps.length, "close", p.coin, { cloid: id }));
+        }
+      for (const step of steps.filter((s) => s.kind === "close")) {
+        if (stopped || !budgetLeft())
+          break;
+        let now;
+        try {
+          now = await snapshotOrError(io);
+          result.readAt = now.readAt;
+        } catch (err) {
+          step.detail = `The read before this close failed (${errorText(err)})`;
+          stopped = true;
+          break;
+        }
+        const held = snapshotPosition(now, step.coin);
+        if (!held) {
+          step.status = "skipped";
+          step.detail = "No position left to close";
+          continue;
+        }
+        signed++;
+        if (await closeStep(step)) {
+          const leg = step.exchange?.response?.data?.statuses?.[0];
+          const filled = typeof leg?.filled?.totalSz === "string" ? leg.filled.totalSz : null;
+          const planned = held.szi.replace(/^-/, "");
+          if (filled !== null) {
+            step.filledSz = filled;
+            if (!sameDecimal(filled, planned)) {
+              step.remainingSz = `${planned} planned, ${filled} filled`;
+              step.detail = "Partly filled; the rest of the position is still open";
+            }
+          }
+          continue;
+        }
+        if (step.status !== "rejected" || /429|rate limit/i.test(step.detail ?? ""))
+          stopped = true;
+      }
+    }
+  }
+  let final = null;
+  try {
+    final = await snapshotOrError(io);
+    result.readAt = final.readAt;
+  } catch (err) {
+    warnings.push(`The final read failed (${errorText(err)}); the outcome is not known.`);
+  }
+  for (const s of steps)
+    if (s.status === "planned")
+      result.remaining.push({ step: s.step, kind: s.kind, coin: s.coin, target: s.target });
+  if (final) {
+    for (const p of final.positions)
+      result.remaining.push({ kind: "position", coin: p.coin, szi: p.szi });
+    for (const o of final.orders)
+      result.remaining.push({ kind: "order", coin: o.coin, oid: o.oid });
+  }
+  result.complete = final !== null && final.positions.length === 0 && final.orders.length === 0 && final.unsupported.length === 0 && !stopped && steps.every((s) => s.status === "confirmed" || s.status === "skipped");
+  return result;
+}
+
+// src/hyperliquid-markets.ts
+var INFO_URLS = {
+  mainnet: "https://api.hyperliquid.xyz/info",
+  testnet: "https://api.hyperliquid-testnet.xyz/info"
+};
+var ONE = 10n ** 18n;
+var DECIMAL = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?$/;
+
+class PerpsMarketError extends Error {
+  code;
+  retryable;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "PerpsMarketError";
+    this.retryable = code === "PERPS_UNAVAILABLE";
+  }
+}
+function unavailable() {
+  throw new PerpsMarketError("PERPS_UNAVAILABLE", "Hyperliquid market data is unavailable; retry shortly.");
+}
+function usage(message) {
+  throw new PerpsMarketError("PERPS_USAGE", message);
+}
+function object(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function decimal2(value) {
+  return typeof value === "string" && value.length <= 100 && DECIMAL.test(value) && (value.split(".")[1]?.length ?? 0) <= 18;
+}
+function scaled(value) {
+  const negative = value.startsWith("-");
+  const [whole = "0", fraction = ""] = (negative ? value.slice(1) : value).split(".");
+  const result = BigInt(whole) * ONE + BigInt(fraction.padEnd(18, "0"));
+  return negative ? -result : result;
+}
+function nonnegative(value) {
+  return decimal2(value) && !value.startsWith("-") ? scaled(value) : null;
+}
+function fixed(value, places) {
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const divisor = 10n ** BigInt(18 - places);
+  const rounded = (abs + divisor / 2n) / divisor;
+  const digits = rounded.toString().padStart(places + 1, "0");
+  return `${negative && rounded !== 0n ? "-" : ""}${places ? `${digits.slice(0, -places)}.${digits.slice(-places)}` : digits}`;
+}
+function at(values, index) {
+  const value = values[index];
+  if (value === undefined)
+    return unavailable();
+  return value;
+}
+function integer(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function parseMarkets(value) {
+  if (!Array.isArray(value) || value.length !== 2)
+    return unavailable();
+  const [meta, ctxs] = value;
+  if (!object(meta) || !Array.isArray(meta.universe) || !Array.isArray(ctxs) || meta.universe.length !== ctxs.length)
+    return unavailable();
+  for (const row of meta.universe) {
+    if (!object(row) || typeof row.name !== "string" || !integer(row.szDecimals) || row.szDecimals > 6 || !integer(row.maxLeverage))
+      return unavailable();
+    for (const key of ["isDelisted", "onlyIsolated"])
+      if (row[key] !== undefined && typeof row[key] !== "boolean")
+        return unavailable();
+    if (row.marginTableId !== undefined && !integer(row.marginTableId))
+      return unavailable();
+  }
+  for (const ctx of ctxs) {
+    if (!object(ctx))
+      return unavailable();
+    for (const key of ["markPx", "midPx", "oraclePx", "openInterest", "funding", "dayNtlVlm", "prevDayPx", "premium"]) {
+      if (ctx[key] !== undefined && ctx[key] !== null && !decimal2(ctx[key]))
+        return unavailable();
+    }
+    if (ctx.impactPxs != null && (!Array.isArray(ctx.impactPxs) || ctx.impactPxs.length !== 2 || !ctx.impactPxs.every(decimal2)))
+      return unavailable();
+  }
+  const marginTables = new Map;
+  if (meta.marginTables !== undefined) {
+    if (!Array.isArray(meta.marginTables))
+      return unavailable();
+    for (const entry of meta.marginTables) {
+      if (!Array.isArray(entry) || !integer(entry[0]) || !object(entry[1]) || !Array.isArray(entry[1].marginTiers))
+        return unavailable();
+      const tiers = [];
+      for (const tier of entry[1].marginTiers) {
+        if (!object(tier) || nonnegative(tier.lowerBound) === null || !integer(tier.maxLeverage))
+          return unavailable();
+        tiers.push({ lowerBoundUsd: tier.lowerBound, maxLeverage: tier.maxLeverage });
+      }
+      marginTables.set(entry[0], tiers);
+    }
+  }
+  return { universe: meta.universe, ctxs, marginTables };
+}
+async function info(fetcher, network, body) {
+  try {
+    const response = await fetcher(INFO_URLS[network], {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(5000),
+      redirect: "error"
+    });
+    if (!response.ok)
+      return unavailable();
+    return JSON.parse(await response.text());
+  } catch {
+    return unavailable();
+  }
+}
+async function readHyperliquidMarkets(fetcher, network) {
+  return parseMarkets(await info(fetcher, network, { type: "metaAndAssetCtxs" }));
+}
+function perpsMarketGate(meta, ctx, minOpenInterestUsd) {
+  if (meta.isDelisted === true)
+    return { tradeable: false, reason: "delisted" };
+  const mark = nonnegative(ctx.markPx);
+  const mid = nonnegative(typeof ctx.midPx === "string" ? ctx.midPx : ctx.markPx);
+  const oi = nonnegative(ctx.openInterest);
+  if (mark === null || mid === null || oi === null)
+    return { tradeable: false, reason: "noPrice" };
+  const divisor = 10n ** 30n;
+  const micros = (oi * mark + divisor - 1n) / divisor;
+  if (micros > BigInt(Number.MAX_SAFE_INTEGER))
+    return unavailable();
+  if (minOpenInterestUsd > 0 && micros < BigInt(minOpenInterestUsd) * 1000000n)
+    return { tradeable: false, reason: "minOpenInterest" };
+  return { tradeable: true, reason: null };
+}
+function resolve(snapshot, coin) {
+  if (/^[A-Za-z0-9]{1,20}$/.test(coin)) {
+    const exact = snapshot.universe.findIndex((row) => row.name === coin);
+    if (exact !== -1)
+      return exact;
+    const matches = snapshot.universe.map((row, i) => ({ row, i })).filter(({ row }) => row.name.toLowerCase() === coin.toLowerCase());
+    if (matches.length === 1)
+      return at(matches, 0).i;
+  }
+  throw new PerpsMarketError("PERPS_MARKET_NOT_FOUND", `${coin} is not a market on Hyperliquid's main perp exchange.`);
+}
+var PERPS_CANDLE_INTERVALS = [
+  "1m",
+  "3m",
+  "5m",
+  "15m",
+  "30m",
+  "1h",
+  "2h",
+  "4h",
+  "8h",
+  "12h",
+  "1d",
+  "3d",
+  "1w",
+  "1M"
+];
+var INTERVAL_MS = [
+  60000,
+  180000,
+  300000,
+  900000,
+  1800000,
+  3600000,
+  7200000,
+  14400000,
+  28800000,
+  43200000,
+  86400000,
+  259200000,
+  604800000,
+  2678400000
+];
+function perpsCandleWindow(opts, now) {
+  const interval = opts.interval ?? "1h";
+  const index = PERPS_CANDLE_INTERVALS.indexOf(interval);
+  if (index < 0)
+    return usage(`interval must be one of ${PERPS_CANDLE_INTERVALS.join(" ")}.`);
+  const count = bounded(opts.count, 100, 1, 5000, "count");
+  const raw = opts.end;
+  const endTime = raw === undefined ? now : typeof raw === "number" || /^\d+$/.test(raw) ? Number(raw) : /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/.test(raw) ? Date.parse(raw) : NaN;
+  const startTime = endTime - count * at(INTERVAL_MS, index);
+  if (!Number.isSafeInteger(endTime) || endTime < 0 || endTime > now || startTime < 0)
+    return usage("end must be an ISO 8601 time or epoch milliseconds, no later than now.");
+  return { interval, count, startTime, endTime };
+}
+function bounded(value, fallback, min, max, name) {
+  const n = value ?? fallback;
+  if (!Number.isInteger(n) || n < min || n > max)
+    return usage(`${name} must be an integer from ${min} to ${max}.`);
+  return n;
+}
+
+class PerpsMarketReader {
+  opts;
+  configPromise;
+  coreCache;
+  extrasCache;
+  corePending;
+  extrasPending;
+  now;
+  constructor(opts) {
+    this.opts = opts;
+    this.now = opts.now ?? Date.now;
+  }
+  key() {
+    if (!this.opts.apiKey?.trim())
+      throw new PerpsMarketError("PERPS_KEY_REQUIRED", "Configure a Candle agent key (any scope) to read perps markets.");
+  }
+  config() {
+    this.key();
+    this.configPromise ??= (async () => {
+      try {
+        const value = await this.opts.readConfig();
+        if (!object(value) || !object(value.limits) || !integer(value.limits.minOpenInterestUsd) || value.network !== "mainnet" && value.network !== "testnet")
+          throw new Error("config shape");
+        return {
+          minOpenInterestUsd: value.limits.minOpenInterestUsd,
+          source: "server",
+          network: value.network,
+          warnings: []
+        };
+      } catch {
+        return {
+          minOpenInterestUsd: 1e6,
+          source: "default",
+          warnings: ["Candle config unavailable; using the release's default OI floor."]
+        };
+      }
+    })();
+    return this.configPromise;
+  }
+  core() {
+    const ttl = this.opts.cacheMs ?? 5000;
+    if (this.coreCache && ttl > 0 && this.now() - this.coreCache.at < ttl)
+      return Promise.resolve(this.coreCache.value);
+    this.corePending ??= readHyperliquidMarkets(this.opts.fetcher, this.opts.network).then((value) => {
+      this.coreCache = { value, at: this.now() };
+      return value;
+    }).finally(() => {
+      this.corePending = undefined;
+    });
+    return this.corePending;
+  }
+  extras() {
+    const ttl = this.opts.cacheMs ?? 5000;
+    if (this.extrasCache && ttl > 0 && this.now() - this.extrasCache.at < ttl)
+      return Promise.resolve(this.extrasCache.value);
+    this.extrasPending ??= (async () => {
+      const warnings = [];
+      const [predicted, cap] = await Promise.all([
+        info(this.opts.fetcher, this.opts.network, { type: "predictedFundings" }).then((value2) => {
+          if (!Array.isArray(value2))
+            return unavailable();
+          const map = new Map;
+          for (const entry of value2) {
+            if (!Array.isArray(entry) || typeof entry[0] !== "string" || !Array.isArray(entry[1]))
+              return unavailable();
+            for (const venue of entry[1]) {
+              if (!Array.isArray(venue) || typeof venue[0] !== "string")
+                return unavailable();
+              if (venue[0] === "HlPerp" && venue[1] !== null) {
+                if (!object(venue[1]) || !decimal2(venue[1].fundingRate) || !integer(venue[1].nextFundingTime))
+                  return unavailable();
+                map.set(entry[0], { fundingRate: venue[1].fundingRate, nextFundingTime: venue[1].nextFundingTime });
+              }
+            }
+          }
+          return map;
+        }).catch(() => {
+          warnings.push("Predicted funding unavailable.");
+          return null;
+        }),
+        info(this.opts.fetcher, this.opts.network, { type: "perpsAtOpenInterestCap" }).then((value2) => {
+          if (!Array.isArray(value2) || !value2.every((v) => typeof v === "string"))
+            return unavailable();
+          return new Set(value2);
+        }).catch(() => {
+          warnings.push("Open-interest caps unavailable.");
+          return null;
+        })
+      ]);
+      const value = { predicted, cap, warnings: warnings.sort() };
+      this.extrasCache = { value, at: this.now() };
+      return value;
+    })().finally(() => {
+      this.extrasPending = undefined;
+    });
+    return this.extrasPending;
+  }
+  envelope(config, warnings = [], readAt = this.now()) {
+    const mismatch = config.network !== undefined && config.network !== this.opts.network;
+    return {
+      success: true,
+      network: this.opts.network,
+      readAt,
+      gate: { minOpenInterestUsd: config.minOpenInterestUsd, source: config.source },
+      warnings: [
+        ...config.warnings,
+        ...warnings,
+        ...mismatch ? ["Candle and client networks differ; tradeability is unknown."] : []
+      ]
+    };
+  }
+  row(core, extras, config, asset) {
+    const meta = at(core.universe, asset);
+    const ctx = at(core.ctxs, asset);
+    const mark = ctx.markPx == null ? null : scaled(ctx.markPx);
+    const oi = ctx.openInterest == null ? null : scaled(ctx.openInterest);
+    const prev = ctx.prevDayPx == null ? null : scaled(ctx.prevDayPx);
+    const predicted = extras.predicted?.get(meta.name);
+    return {
+      coin: meta.name,
+      asset,
+      markPx: ctx.markPx ?? null,
+      oraclePx: ctx.oraclePx ?? null,
+      midPx: ctx.midPx ?? null,
+      fundingRate: ctx.funding ?? null,
+      fundingAprPct: ctx.funding == null ? null : fixed(scaled(ctx.funding) * 876000n, 2),
+      predictedFundingRate: predicted?.fundingRate ?? null,
+      nextFundingTime: predicted?.nextFundingTime ?? null,
+      openInterest: ctx.openInterest ?? null,
+      openInterestUsd: oi === null || mark === null ? null : fixed(oi * mark / ONE, 2),
+      dayNotionalVolumeUsd: ctx.dayNtlVlm ?? null,
+      prevDayPx: ctx.prevDayPx ?? null,
+      change24hPct: prev === null || prev === 0n || mark === null ? null : fixed((mark - prev) * 100n * ONE / prev, 1),
+      maxLeverage: meta.maxLeverage,
+      onlyIsolated: meta.onlyIsolated === true,
+      isDelisted: meta.isDelisted === true,
+      atOpenInterestCap: extras.cap?.has(meta.name) ?? null,
+      candle: config.network !== undefined && config.network !== this.opts.network ? { tradeable: null, reason: "networkMismatch" } : perpsMarketGate(meta, ctx, config.minOpenInterestUsd)
+    };
+  }
+  async markets(opts = {}) {
+    this.key();
+    const sort = opts.sort ?? "volume";
+    if (!["volume", "oi", "funding", "change", "name"].includes(sort))
+      return usage("sort must be volume, oi, funding, change or name.");
+    const limit = opts.limit === undefined ? undefined : bounded(opts.limit, 500, 1, 500, "limit");
+    const [config, core, extras] = await Promise.all([this.config(), this.core(), this.extras()]);
+    const rows = core.universe.map((_, asset) => this.row(core, extras, config, asset)).filter((row) => opts.all || row.candle.tradeable !== false);
+    const field = {
+      volume: "dayNotionalVolumeUsd",
+      oi: "openInterestUsd",
+      funding: "fundingRate",
+      change: "change24hPct"
+    };
+    rows.sort((a, b) => {
+      if (sort !== "name") {
+        const av = a[field[sort]];
+        const bv = b[field[sort]];
+        if (av === null && bv !== null)
+          return 1;
+        if (bv === null && av !== null)
+          return -1;
+        if (av !== null && bv !== null) {
+          const diff = scaled(bv) - scaled(av);
+          if (diff !== 0n)
+            return diff > 0n ? 1 : -1;
+        }
+      }
+      return a.coin < b.coin ? -1 : a.coin > b.coin ? 1 : 0;
+    });
+    return {
+      ...this.envelope(config, extras.warnings, Math.max(this.coreCache?.at ?? 0, this.extrasCache?.at ?? 0)),
+      markets: limit === undefined ? rows : rows.slice(0, limit)
+    };
+  }
+  async market(coin) {
+    this.key();
+    const [config, core, extras] = await Promise.all([this.config(), this.core(), this.extras()]);
+    const asset = resolve(core, coin);
+    const meta = at(core.universe, asset);
+    const ctx = at(core.ctxs, asset);
+    return {
+      ...this.envelope(config, extras.warnings, Math.max(this.coreCache?.at ?? 0, this.extrasCache?.at ?? 0)),
+      market: {
+        ...this.row(core, extras, config, asset),
+        szDecimals: meta.szDecimals,
+        maxPriceDecimals: 6 - meta.szDecimals,
+        priceRule: "at most 5 significant figures",
+        minOrderUsd: 10,
+        impactBidPx: ctx.impactPxs?.[0] ?? null,
+        impactAskPx: ctx.impactPxs?.[1] ?? null,
+        premium: ctx.premium ?? null,
+        marginTiers: core.marginTables.get(meta.marginTableId ?? -1) ?? [
+          { lowerBoundUsd: "0", maxLeverage: meta.maxLeverage }
+        ]
+      }
+    };
+  }
+  async book(coin, opts = {}) {
+    this.key();
+    const depth = bounded(opts.depth, 20, 1, 20, "depth");
+    if (opts.sigFigs !== undefined)
+      bounded(opts.sigFigs, 5, 2, 5, "sigFigs");
+    const [config, core] = await Promise.all([this.config(), this.core()]);
+    const canonical2 = at(core.universe, resolve(core, coin)).name;
+    const value = await info(this.opts.fetcher, this.opts.network, {
+      type: "l2Book",
+      coin: canonical2,
+      ...opts.sigFigs === undefined ? {} : { nSigFigs: opts.sigFigs }
+    });
+    if (!object(value) || value.coin !== canonical2 || !integer(value.time) || !Array.isArray(value.levels) || value.levels.length !== 2)
+      return unavailable();
+    const sides = [];
+    for (const side of value.levels) {
+      if (!Array.isArray(side))
+        return unavailable();
+      const levels = [];
+      for (const level of side) {
+        if (!object(level) || nonnegative(level.px) === null || nonnegative(level.sz) === null || !integer(level.n))
+          return unavailable();
+        levels.push({ px: level.px, sz: level.sz, n: level.n });
+      }
+      sides.push(levels);
+    }
+    const bids = at(sides, 0).sort((a, b) => scaled(a.px) > scaled(b.px) ? -1 : scaled(a.px) < scaled(b.px) ? 1 : 0).slice(0, depth);
+    const asks = at(sides, 1).sort((a, b) => scaled(a.px) < scaled(b.px) ? -1 : scaled(a.px) > scaled(b.px) ? 1 : 0).slice(0, depth);
+    const bid = bids[0];
+    const ask = asks[0];
+    const spread = bid && ask ? scaled(ask.px) - scaled(bid.px) : null;
+    const mid = bid && ask ? (scaled(ask.px) + scaled(bid.px)) / 2n : null;
+    return {
+      ...this.envelope(config),
+      coin: canonical2,
+      time: value.time,
+      bids,
+      asks,
+      spreadPx: spread === null ? null : fixed(spread, 18).replace(/\.?0+$/, ""),
+      midPx: mid === null ? null : fixed(mid, 18).replace(/\.?0+$/, ""),
+      spreadBps: spread === null || mid === null || mid === 0n ? null : fixed(spread * 10000n * ONE / mid, 2)
+    };
+  }
+  async candles(coin, opts = {}) {
+    this.key();
+    const window = perpsCandleWindow(opts, this.now());
+    const [config, core] = await Promise.all([this.config(), this.core()]);
+    const canonical2 = at(core.universe, resolve(core, coin)).name;
+    const value = await info(this.opts.fetcher, this.opts.network, {
+      type: "candleSnapshot",
+      req: { coin: canonical2, interval: window.interval, startTime: window.startTime, endTime: window.endTime }
+    });
+    if (!Array.isArray(value))
+      return unavailable();
+    const candles = [];
+    for (const c of value) {
+      if (!object(c) || !integer(c.t) || !integer(c.T) || !integer(c.n) || ![c.o, c.h, c.l, c.c, c.v].every((v) => nonnegative(v) !== null) || c.s !== canonical2 || c.i !== window.interval)
+        return unavailable();
+      if (c.t <= window.endTime && c.T >= window.startTime)
+        candles.push({
+          t: c.t,
+          T: c.T,
+          o: c.o,
+          h: c.h,
+          l: c.l,
+          c: c.c,
+          v: c.v,
+          n: c.n
+        });
+    }
+    candles.sort((a, b) => a.t - b.t);
+    return {
+      ...this.envelope(config),
+      coin: canonical2,
+      interval: window.interval,
+      candles: candles.slice(-window.count)
+    };
+  }
+}
+
+// src/hyperliquid-risk.ts
+var HYPERLIQUID_RISK_INFO_URLS = {
+  mainnet: "https://api.hyperliquid.xyz/info",
+  testnet: "https://api.hyperliquid-testnet.xyz/info"
+};
+var PERPS_RISK_FIELDS = [
+  "warnDistanceBps",
+  "criticalDistanceBps",
+  "warnMarginRatioBps",
+  "criticalMarginRatioBps",
+  "clearBandBps"
+];
+var HYPERLIQUID_RISK_DEFAULTS = {
+  warnDistanceBps: 1500,
+  criticalDistanceBps: 700,
+  warnMarginRatioBps: 6000,
+  criticalMarginRatioBps: 8000,
+  clearBandBps: 200
+};
+function effectivePerpsRisk(stored) {
+  const out = { ...HYPERLIQUID_RISK_DEFAULTS };
+  for (const field of PERPS_RISK_FIELDS) {
+    const value = stored?.[field];
+    if (typeof value === "number")
+      out[field] = value;
+  }
+  return out;
+}
+function perpsRiskProblem(t) {
+  const ranges = {
+    warnDistanceBps: [1, 9900],
+    criticalDistanceBps: [1, 9900],
+    warnMarginRatioBps: [1, 9999],
+    criticalMarginRatioBps: [1, 9999],
+    clearBandBps: [0, 1000]
+  };
+  for (const field of PERPS_RISK_FIELDS) {
+    const value = t[field];
+    const [min, max] = ranges[field];
+    if (!Number.isInteger(value) || value < min || value > max)
+      return `${field} must be a whole number of bps from ${min} to ${max}`;
+  }
+  if (t.criticalDistanceBps >= t.warnDistanceBps)
+    return "criticalDistanceBps must be below warnDistanceBps";
+  if (t.warnMarginRatioBps >= t.criticalMarginRatioBps)
+    return "warnMarginRatioBps must be below criticalMarginRatioBps";
+  return null;
+}
+function perpsRiskFromLimits(body) {
+  const record = isRecord(body) ? body : {};
+  const reported = "perpsRisk" in record || "perpsRiskEffective" in record;
+  const stored = isRecord(record.perpsRisk) ? pickSettings(record.perpsRisk) : null;
+  if (!reported)
+    return { thresholds: { ...HYPERLIQUID_RISK_DEFAULTS, source: "defaults (server did not report)" }, stored };
+  const effective = isRecord(record.perpsRiskEffective) ? effectivePerpsRisk(pickSettings(record.perpsRiskEffective)) : effectivePerpsRisk(stored);
+  if (perpsRiskProblem(effective) !== null)
+    return { thresholds: { ...HYPERLIQUID_RISK_DEFAULTS, source: "defaults (server did not report)" }, stored };
+  const source = stored && Object.keys(stored).length > 0 ? "key" : "defaults";
+  return { thresholds: { ...effective, source }, stored };
+}
+function pickSettings(raw) {
+  const out = {};
+  for (const field of PERPS_RISK_FIELDS)
+    if (typeof raw[field] === "number")
+      out[field] = raw[field];
+  return out;
+}
+
+class HyperliquidReadError extends Error {
+  rateLimited;
+  code = "PERPS_READ_FAILED";
+  constructor(message, rateLimited = false) {
+    super(message);
+    this.rateLimited = rateLimited;
+    this.name = "HyperliquidReadError";
+  }
+}
+var INFO_TIMEOUT_MS = 5000;
+var RATE_LIMIT_RETRY_MS = 1000;
+async function hyperliquidInfo(fetcher, network, body, opts = {}) {
+  const sleep2 = opts.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  for (let attempt = 0;; attempt++) {
+    const controller = new AbortController;
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? INFO_TIMEOUT_MS);
+    let res;
+    let text;
+    try {
+      res = await fetcher(HYPERLIQUID_RISK_INFO_URLS[network], {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: controller.signal
+      });
+      text = res.ok ? await res.text() : "";
+    } catch {
+      throw new HyperliquidReadError(`Hyperliquid ${String(body.type)} read failed or timed out`);
+    } finally {
+      clearTimeout(timer);
+    }
+    if (res.status === 429) {
+      if (attempt === 0) {
+        await sleep2(RATE_LIMIT_RETRY_MS);
+        continue;
+      }
+      throw new HyperliquidReadError(`Hyperliquid rate-limited the ${String(body.type)} read (HTTP 429)`, true);
+    }
+    if (!res.ok)
+      throw new HyperliquidReadError(`Hyperliquid ${String(body.type)} answered HTTP ${res.status ?? "?"}`);
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new HyperliquidReadError(`Hyperliquid ${String(body.type)} answered with something other than JSON`);
+    }
+  }
+}
+async function readHyperliquidMarketSnapshot(fetcher, network, opts = {}) {
+  const sleep2 = opts.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  let limited = false;
+  const watched = async (url, init) => {
+    const res = await fetcher(url, init);
+    limited = res.status === 429;
+    return res;
+  };
+  try {
+    return await readHyperliquidMarkets(watched, network);
+  } catch {
+    await sleep2(RATE_LIMIT_RETRY_MS);
+  }
+  try {
+    return await readHyperliquidMarkets(watched, network);
+  } catch (error) {
+    throw new HyperliquidReadError(`Hyperliquid metaAndAssetCtxs read failed${error instanceof PerpsMarketError ? ` (${error.code})` : ""}`, limited);
+  }
+}
+function hyperliquidMark(markets, coin) {
+  const index = markets.universe.findIndex((m) => m.name === coin);
+  const mark = index < 0 ? undefined : markets.ctxs[index]?.markPx;
+  if (typeof mark !== "string")
+    return null;
+  const parsed = dec(mark);
+  return parsed !== null && parsed > 0n ? mark : null;
+}
+async function readHyperliquidClearinghouse(fetcher, network, address, opts = {}) {
+  return parseClearinghouse(await hyperliquidInfo(fetcher, network, { type: "clearinghouseState", user: address.toLowerCase() }, opts));
+}
+async function readHyperliquidAccountMode(fetcher, network, address, opts = {}) {
+  const body = await hyperliquidInfo(fetcher, network, { type: "userAbstraction", user: address.toLowerCase() }, opts);
+  if (typeof body !== "string" || body === "")
+    throw new HyperliquidReadError("Unexpected userAbstraction shape");
+  return body;
+}
+var HYPERLIQUID_STANDARD_MODES = ["default", "disabled"];
+function parseClearinghouse(body) {
+  const bad = (what) => new HyperliquidReadError(`Unexpected clearinghouseState shape (${what})`);
+  if (!isRecord(body))
+    throw bad("not an object");
+  const summary = (value, name) => {
+    if (!isRecord(value) || !isDecString(value.accountValue) || !isDecString(value.totalMarginUsed))
+      throw bad(name);
+    return { accountValue: value.accountValue, totalMarginUsed: value.totalMarginUsed };
+  };
+  const marginSummary = summary(body.marginSummary, "marginSummary");
+  const crossMarginSummary = summary(body.crossMarginSummary, "crossMarginSummary");
+  if (!isDecString(body.crossMaintenanceMarginUsed))
+    throw bad("crossMaintenanceMarginUsed");
+  if (!isDecString(body.withdrawable))
+    throw bad("withdrawable");
+  if (!Array.isArray(body.assetPositions))
+    throw bad("assetPositions");
+  const positions = body.assetPositions.map((entry) => {
+    const p = isRecord(entry) ? entry.position : undefined;
+    if (!isRecord(p) || typeof p.coin !== "string" || p.coin === "")
+      throw bad("position");
+    for (const field of ["szi", "entryPx", "positionValue", "unrealizedPnl", "returnOnEquity", "marginUsed"])
+      if (!isDecString(p[field]))
+        throw bad(`position ${field}`);
+    const leverage = p.leverage;
+    if (!isRecord(leverage) || typeof leverage.type !== "string" || typeof leverage.value !== "number")
+      throw bad("position leverage");
+    if (p.liquidationPx !== null && p.liquidationPx !== undefined && !isDecString(p.liquidationPx))
+      throw bad("position liquidationPx");
+    const funding = p.cumFunding;
+    if (!isRecord(funding) || !isDecString(funding.sinceOpen))
+      throw bad("position cumFunding");
+    return {
+      coin: p.coin,
+      szi: p.szi,
+      entryPx: p.entryPx,
+      positionValue: p.positionValue,
+      unrealizedPnl: p.unrealizedPnl,
+      returnOnEquity: p.returnOnEquity,
+      leverage: { type: leverage.type, value: leverage.value },
+      liquidationPx: p.liquidationPx ?? null,
+      marginUsed: p.marginUsed,
+      cumFunding: { sinceOpen: funding.sinceOpen }
+    };
+  });
+  return {
+    marginSummary,
+    crossMarginSummary,
+    crossMaintenanceMarginUsed: body.crossMaintenanceMarginUsed,
+    withdrawable: body.withdrawable,
+    positions
+  };
+}
+var PERPS_RISK_NOTE = "Phase 1 has no server-side monitor: nothing warns you unless you poll this or run candle perps watch.";
+var RANK = { ok: 0, warn: 1, critical: 2 };
+function worse(a, b) {
+  return RANK[a] >= RANK[b] ? a : b;
+}
+function hyperliquidRiskReport(state, market, mode, thresholds, now, identity = { walletId: "", address: "", network: "mainnet" }) {
+  const base = {
+    schema: "candle.perps.risk/1",
+    walletId: identity.walletId,
+    address: identity.address,
+    network: identity.network,
+    mode,
+    readAt: new Date(now).toISOString(),
+    thresholds,
+    note: PERPS_RISK_NOTE
+  };
+  if (!HYPERLIQUID_STANDARD_MODES.includes(mode)) {
+    return {
+      ...base,
+      level: "unknown",
+      reason: "PERPS_ACCOUNT_MODE",
+      drivers: [],
+      closest: null,
+      account: null,
+      positions: []
+    };
+  }
+  const ch = isParsedClearinghouse(state) ? state : parseClearinghouse(state);
+  if (!market || !Array.isArray(market.universe) || !Array.isArray(market.ctxs))
+    throw new HyperliquidReadError("Unexpected metaAndAssetCtxs shape");
+  const markets = market;
+  const t = thresholds;
+  const drivers = [];
+  const nearest = [];
+  let level = "ok";
+  let unrealized = 0n;
+  const positions = ch.positions.map((p) => {
+    const szi = dec(p.szi);
+    unrealized += dec(p.unrealizedPnl);
+    const markPx = hyperliquidMark(markets, p.coin);
+    const distance = markPx !== null && p.liquidationPx !== null ? distanceParts(markPx, p.liquidationPx) : null;
+    let rowLevel = "none";
+    if (distance) {
+      rowLevel = fracLess(distance.num, distance.den, t.criticalDistanceBps) ? "critical" : fracLess(distance.num, distance.den, t.warnDistanceBps) ? "warn" : "ok";
+    }
+    const liquidationDistance = distance ? ratioNumber(distance.num, distance.den) : null;
+    if (markPx === null) {
+      drivers.push({
+        kind: "position",
+        coin: p.coin,
+        level: "warn",
+        liquidationDistance: null,
+        threshold: null,
+        reason: "unmarked"
+      });
+      level = worse(level, "warn");
+    } else if (rowLevel === "warn" || rowLevel === "critical") {
+      drivers.push({
+        kind: "position",
+        coin: p.coin,
+        level: rowLevel,
+        liquidationDistance,
+        threshold: (rowLevel === "critical" ? t.criticalDistanceBps : t.warnDistanceBps) / 1e4
+      });
+      level = worse(level, rowLevel);
+    } else if (rowLevel === "ok" && liquidationDistance !== null) {
+      nearest.push({
+        driver: {
+          kind: "position",
+          coin: p.coin,
+          level: "ok",
+          liquidationDistance,
+          threshold: t.warnDistanceBps / 1e4
+        },
+        headroom: liquidationDistance / (t.warnDistanceBps / 1e4) - 1
+      });
+    }
+    return {
+      coin: p.coin,
+      side: szi < 0n ? "short" : "long",
+      size: p.szi.replace(/^-/, ""),
+      entryPx: p.entryPx,
+      markPx,
+      unrealizedPnlUsd: p.unrealizedPnl,
+      returnOnEquity: p.returnOnEquity,
+      leverage: { value: p.leverage.value, type: p.leverage.type },
+      liquidationPx: p.liquidationPx,
+      liquidationDistance,
+      fundingSinceOpenUsd: p.cumFunding.sinceOpen,
+      marginUsedUsd: p.marginUsed,
+      positionValueUsd: p.positionValue,
+      level: rowLevel
+    };
+  });
+  const maint = dec(ch.crossMaintenanceMarginUsed);
+  const crossValue = dec(ch.crossMarginSummary.accountValue);
+  let marginRatio = 0;
+  if (positions.length > 0 && maint > 0n) {
+    if (crossValue <= 0n) {
+      marginRatio = null;
+      drivers.push({
+        kind: "margin",
+        level: "critical",
+        marginRatio: null,
+        threshold: t.criticalMarginRatioBps / 1e4,
+        reason: "no equity"
+      });
+      level = "critical";
+    } else {
+      marginRatio = ratioNumber(maint, crossValue);
+      const marginLevel = fracGreater(maint, crossValue, t.criticalMarginRatioBps) ? "critical" : fracGreater(maint, crossValue, t.warnMarginRatioBps) ? "warn" : "ok";
+      if (marginLevel === "ok") {
+        nearest.push({
+          driver: { kind: "margin", level: "ok", marginRatio, threshold: t.warnMarginRatioBps / 1e4 },
+          headroom: 1 - marginRatio / (t.warnMarginRatioBps / 1e4)
+        });
+      } else {
+        drivers.push({
+          kind: "margin",
+          level: marginLevel,
+          marginRatio,
+          threshold: (marginLevel === "critical" ? t.criticalMarginRatioBps : t.warnMarginRatioBps) / 1e4
+        });
+        level = worse(level, marginLevel);
+      }
+    }
+  }
+  drivers.sort((a, b) => RANK[b.level] - RANK[a.level]);
+  nearest.sort((a, b) => a.headroom - b.headroom);
+  const accountValue = dec(ch.marginSummary.accountValue);
+  const marginUsed = dec(ch.marginSummary.totalMarginUsed);
+  const free = accountValue - marginUsed;
+  const account = {
+    accountValueUsd: ch.marginSummary.accountValue,
+    marginUsedUsd: ch.marginSummary.totalMarginUsed,
+    crossAccountValueUsd: ch.crossMarginSummary.accountValue,
+    freeMarginUsd: formatDec(free > 0n ? free : 0n),
+    withdrawableUsd: ch.withdrawable,
+    crossMaintenanceMarginUsedUsd: ch.crossMaintenanceMarginUsed,
+    marginRatio,
+    unrealizedPnlUsd: formatDec(unrealized),
+    positionCount: positions.length,
+    mode,
+    level
+  };
+  return {
+    ...base,
+    level,
+    reason: null,
+    drivers,
+    closest: level === "ok" ? nearest[0]?.driver ?? null : null,
+    account,
+    positions
+  };
+}
+function unknownRiskReport(identity, thresholds, reason, now, mode = null) {
+  return {
+    schema: "candle.perps.risk/1",
+    ...identity,
+    mode,
+    readAt: new Date(now).toISOString(),
+    level: "unknown",
+    reason,
+    drivers: [],
+    closest: null,
+    thresholds,
+    account: null,
+    positions: [],
+    note: PERPS_RISK_NOTE
+  };
+}
+var PERPS_RISK_STALE_MS = 30000;
+async function readPerpsRisk(opts) {
+  const identity = { walletId: opts.walletId, address: opts.address, network: opts.network };
+  const timed = async (read) => {
+    const value = await read;
+    return { value, at: opts.now() };
+  };
+  const [state, market, mode] = await Promise.all([
+    timed(readHyperliquidClearinghouse(opts.fetcher, opts.network, opts.address, opts)),
+    timed(readHyperliquidMarketSnapshot(opts.fetcher, opts.network, opts)),
+    opts.mode !== undefined ? Promise.resolve({ value: opts.mode, at: Number.NaN }) : timed(readHyperliquidAccountMode(opts.fetcher, opts.network, opts.address, opts))
+  ]);
+  const times = [state.at, market.at, mode.at].filter((at2) => !Number.isNaN(at2));
+  const earliest = Math.min(...times);
+  if (Math.max(...times) - earliest > PERPS_RISK_STALE_MS)
+    return unknownRiskReport(identity, opts.thresholds, "PERPS_READ_STALE", earliest, mode.value);
+  return hyperliquidRiskReport(state.value, market.value, mode.value, opts.thresholds, earliest, identity);
+}
+function perpsRiskExitCode(level) {
+  return level === "ok" ? 0 : level === "warn" ? 10 : level === "critical" ? 11 : 1;
+}
+var PERPS_FILLS_RESPONSE_CAP = 2000;
+var PERPS_FUNDING_RESPONSE_CAP = 500;
+var PERPS_RECENT_MAX_MS = 30 * 24 * 60 * 60 * 1000;
+function isMainPerpCoin(coin) {
+  return typeof coin === "string" && coin !== "" && !coin.includes(":") && !coin.includes("/") && !coin.startsWith("@");
+}
+async function readPerpsRecent(fetcher, network, address, window, opts = {}) {
+  const user = address.toLowerCase();
+  const [fills, funding] = await Promise.all([
+    hyperliquidInfo(fetcher, network, { type: "userFillsByTime", user, startTime: window.startTime, endTime: window.endTime }, opts),
+    hyperliquidInfo(fetcher, network, { type: "userFunding", user, startTime: window.startTime, endTime: window.endTime }, opts)
+  ]);
+  return summarizePerpsRecent(fills, funding, window);
+}
+function summarizePerpsRecent(fills, funding, window) {
+  if (!Array.isArray(fills))
+    throw new HyperliquidReadError("Unexpected userFillsByTime shape");
+  if (!Array.isArray(funding))
+    throw new HyperliquidReadError("Unexpected userFunding shape");
+  let realized = 0n;
+  let fees = 0n;
+  let paid = 0n;
+  let fillCount = 0;
+  let fundingCount = 0;
+  for (const row of fills) {
+    if (!isRecord(row))
+      throw new HyperliquidReadError("Unexpected fill row");
+    if (!isMainPerpCoin(row.coin))
+      continue;
+    const closed = dec(row.closedPnl);
+    const fee = dec(row.fee);
+    if (closed === null || fee === null)
+      throw new HyperliquidReadError("Unexpected fill amount");
+    realized += closed;
+    fees += fee;
+    fillCount++;
+  }
+  for (const row of funding) {
+    const delta = isRecord(row) ? row.delta : undefined;
+    if (!isRecord(delta))
+      throw new HyperliquidReadError("Unexpected funding row");
+    if (delta.type !== "funding" || !isMainPerpCoin(delta.coin))
+      continue;
+    const usdc = dec(delta.usdc);
+    if (usdc === null)
+      throw new HyperliquidReadError("Unexpected funding amount");
+    paid += usdc;
+    fundingCount++;
+  }
+  return {
+    startTime: window.startTime,
+    endTime: window.endTime,
+    realizedPnlUsd: formatDec(realized),
+    feesUsd: formatDec(fees),
+    fundingUsd: formatDec(paid),
+    fills: fillCount,
+    fundingPayments: fundingCount,
+    truncated: fills.length >= PERPS_FILLS_RESPONSE_CAP || funding.length >= PERPS_FUNDING_RESPONSE_CAP
+  };
+}
+function perpsAccountReport(report, recent) {
+  const { mode: _mode, level: _level, ...line } = report.account ?? {};
+  return {
+    schema: "candle.perps.account/1",
+    walletId: report.walletId,
+    address: report.address,
+    network: report.network,
+    mode: report.mode,
+    readAt: report.readAt,
+    ...line,
+    recent,
+    risk: { level: report.level, reason: report.reason, drivers: report.drivers }
+  };
+}
+function perpsRiskClears(report, leaving) {
+  const t = report.thresholds;
+  const account = report.account;
+  if (!account)
+    return false;
+  const distanceBps = (leaving === "warn" ? t.warnDistanceBps : t.criticalDistanceBps) + t.clearBandBps;
+  const ratioBps = (leaving === "warn" ? t.warnMarginRatioBps : t.criticalMarginRatioBps) - t.clearBandBps;
+  for (const p of report.positions) {
+    if (p.markPx === null) {
+      if (leaving === "warn")
+        return false;
+      continue;
+    }
+    if (p.liquidationPx === null)
+      continue;
+    const d = distanceParts(p.markPx, p.liquidationPx);
+    if (d && fracLess(d.num, d.den, distanceBps))
+      return false;
+  }
+  const maint = dec(account.crossMaintenanceMarginUsedUsd);
+  if (report.positions.length > 0 && maint > 0n) {
+    const crossValue = dec(account.crossAccountValueUsd);
+    if (crossValue <= 0n)
+      return false;
+    if (fracGreater(maint, crossValue, ratioBps))
+      return false;
+  }
+  return true;
+}
+function perpsRiskStep(previous, report) {
+  const rule = report.level;
+  if (rule === "unknown" || previous === "unknown")
+    return rule;
+  if (RANK[rule] >= RANK[previous])
+    return rule;
+  if (rule === "ok" && perpsRiskClears(report, "warn"))
+    return "ok";
+  if (previous === "critical" && perpsRiskClears(report, "critical"))
+    return "warn";
+  return previous;
+}
+var PERPS_WATCH_DEFAULT_INTERVAL_MS = 1e4;
+var PERPS_WATCH_MAX_INTERVAL_MS = 300000;
+var PERPS_WATCH_DEFAULT_HEARTBEAT_MS = 60000;
+var PERPS_WATCH_REFRESH_MS = 300000;
+var HYPERLIQUID_INFO_WEIGHTS = { clearinghouseState: 2, metaAndAssetCtxs: 20, userAbstraction: 20 };
+function perpsWatchWeightPerMinute(intervalMs) {
+  const polls = 60000 / intervalMs;
+  const modeReads = 60000 / PERPS_WATCH_REFRESH_MS;
+  return Math.round(polls * (HYPERLIQUID_INFO_WEIGHTS.clearinghouseState + HYPERLIQUID_INFO_WEIGHTS.metaAndAssetCtxs) + modeReads * HYPERLIQUID_INFO_WEIGHTS.userAbstraction);
+}
+async function watchPerpsRisk(opts) {
+  const baseInterval = opts.intervalMs ?? PERPS_WATCH_DEFAULT_INTERVAL_MS;
+  const heartbeatMs = opts.heartbeatMs ?? PERPS_WATCH_DEFAULT_HEARTBEAT_MS;
+  const identity = { walletId: opts.walletId, address: opts.address, network: opts.network };
+  const sleep2 = (ms) => abortableSleep(opts.sleep, ms, opts.signal);
+  const info2 = { sleep: opts.sleep };
+  let thresholds;
+  try {
+    thresholds = await opts.thresholds();
+  } catch {
+    thresholds = { ...HYPERLIQUID_RISK_DEFAULTS, source: "defaults (server did not report)" };
+  }
+  let thresholdsAt = opts.now();
+  let mode;
+  let modeAt = Number.NEGATIVE_INFINITY;
+  let level = "unknown";
+  let lastGoodAt = null;
+  let staleReported = false;
+  let interval = baseInterval;
+  let lastHeartbeat = opts.now();
+  let established = false;
+  await opts.onEvent({
+    event: "start",
+    ...identity,
+    at: new Date(opts.now()).toISOString(),
+    intervalSeconds: baseInterval / 1000,
+    heartbeatSeconds: heartbeatMs / 1000,
+    thresholds,
+    weightPerMinute: perpsWatchWeightPerMinute(baseInterval)
+  });
+  while (!opts.signal?.aborted) {
+    if (opts.now() - thresholdsAt >= PERPS_WATCH_REFRESH_MS) {
+      thresholdsAt = opts.now();
+      try {
+        thresholds = await opts.thresholds();
+      } catch {}
+    }
+    let report = null;
+    try {
+      if (mode === undefined || opts.now() - modeAt >= PERPS_WATCH_REFRESH_MS) {
+        mode = await readHyperliquidAccountMode(opts.fetcher, opts.network, opts.address, info2);
+        modeAt = opts.now();
+      }
+      report = await readPerpsRisk({ ...identity, fetcher: opts.fetcher, thresholds, now: opts.now, mode, ...info2 });
+      interval = baseInterval;
+    } catch (error) {
+      const rateLimited = error instanceof HyperliquidReadError && error.rateLimited;
+      if (rateLimited)
+        interval = Math.min(interval * 2, PERPS_WATCH_MAX_INTERVAL_MS);
+      await opts.onEvent({
+        event: "error",
+        at: new Date(opts.now()).toISOString(),
+        code: error instanceof HyperliquidReadError ? error.code : "PERPS_READ_FAILED",
+        message: error instanceof Error ? error.message : "Hyperliquid read failed",
+        nextPollSeconds: interval / 1000
+      });
+      if (level !== "unknown" && !staleReported && lastGoodAt !== null && opts.now() - lastGoodAt > PERPS_RISK_STALE_MS) {
+        const previous = level;
+        level = "unknown";
+        staleReported = true;
+        const stale = unknownRiskReport(identity, thresholds, "PERPS_READ_STALE", opts.now(), mode ?? null);
+        await opts.onEvent({ ...stale, event: "level", level, ruleLevel: "unknown", previous });
+        if (opts.onceLevelChange && established)
+          return { level };
+      }
+    }
+    if (report) {
+      const previous = level;
+      const next = perpsRiskStep(previous, report);
+      if (report.level !== "unknown") {
+        lastGoodAt = opts.now();
+        staleReported = false;
+      }
+      if (next !== previous) {
+        level = next;
+        const cleared = next === "ok" && (previous === "warn" || previous === "critical");
+        await opts.onEvent({
+          ...report,
+          event: "level",
+          level: next,
+          ruleLevel: report.level,
+          previous,
+          ...cleared ? { cleared: true } : {}
+        });
+        if (opts.onceLevelChange && established)
+          return { level };
+        if (next !== "unknown")
+          established = true;
+      } else if (next !== "unknown") {
+        established = true;
+      }
+      if (heartbeatMs > 0 && opts.now() - lastHeartbeat >= heartbeatMs) {
+        lastHeartbeat = opts.now();
+        await opts.onEvent({ ...report, event: "heartbeat", level, ruleLevel: report.level });
       }
-      return { ok: true, kind: "approveBuilderFee" };
     }
-    return { ok: false, reason: `primary type ${String(typed.primary_type)} is not one the relay signs` };
-  } catch (err) {
-    return { ok: false, reason: err instanceof Error ? err.message : "unreadable build" };
+    if (opts.signal?.aborted)
+      break;
+    await sleep2(interval);
   }
+  return { level };
 }
-function hyperliquidSplitSignature(signature) {
-  if (!/^0x[0-9a-fA-F]{130}$/.test(signature))
-    throw new Error("Not a 65-byte signature");
-  let v = Number.parseInt(signature.slice(130, 132), 16);
-  if (v < 27)
-    v += 27;
-  return { r: `0x${signature.slice(2, 66)}`, s: `0x${signature.slice(66, 130)}`, v };
+function abortableSleep(sleep2, ms, signal) {
+  if (!signal)
+    return sleep2(ms);
+  if (signal.aborted)
+    return Promise.resolve();
+  return new Promise((resolve2) => {
+    const done = () => {
+      signal.removeEventListener("abort", done);
+      resolve2();
+    };
+    signal.addEventListener("abort", done);
+    sleep2(ms).then(done, done);
+  });
 }
-function hyperliquidExchangeBody(action, nonce, signature) {
-  return { action, nonce, signature: hyperliquidSplitSignature(signature), vaultAddress: null, expiresAfter: null };
+var PERPS_PORTFOLIO_MAX_ACCOUNTS = 100;
+var PORTFOLIO_READS_IN_FLIGHT = 8;
+async function perpsPortfolioSection(fetcher, network, wallets, opts = {}) {
+  const now = opts.now ?? Date.now;
+  const considered = wallets.slice(0, PERPS_PORTFOLIO_MAX_ACCOUNTS);
+  const unread = wallets.slice(PERPS_PORTFOLIO_MAX_ACCOUNTS).map((w) => ({ ...w, reason: `past the ${PERPS_PORTFOLIO_MAX_ACCOUNTS}-address cap` }));
+  let markets = { universe: [], ctxs: [], marginTables: new Map };
+  if (considered.length > 0) {
+    try {
+      markets = await readHyperliquidMarketSnapshot(fetcher, network, opts);
+    } catch (error) {
+      return { read: false, reason: error instanceof Error ? error.message : "Hyperliquid market read failed" };
+    }
+  }
+  const thresholds = { ...HYPERLIQUID_RISK_DEFAULTS, source: "defaults" };
+  const results = new Array(considered.length).fill(null);
+  const failures = new Array(considered.length).fill(null);
+  let next = 0;
+  const worker = async () => {
+    while (next < considered.length) {
+      const at2 = next++;
+      const wallet = considered[at2];
+      try {
+        const state = await readHyperliquidClearinghouse(fetcher, network, wallet.address, opts);
+        const report = hyperliquidRiskReport(state, markets, "default", thresholds, now());
+        results[at2] = {
+          address: wallet.address,
+          ...wallet.label !== undefined ? { label: wallet.label } : {},
+          ...wallet.walletId !== undefined ? { walletId: wallet.walletId } : {},
+          accountValueUsd: report.account?.accountValueUsd ?? "0",
+          unrealizedPnlUsd: report.account?.unrealizedPnlUsd ?? "0",
+          positionCount: report.positions.length,
+          level: report.level
+        };
+      } catch (error) {
+        failures[at2] = error instanceof Error ? error.message : "read failed";
+      }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(PORTFOLIO_READS_IN_FLIGHT, considered.length) }, worker));
+  const accounts = [];
+  let empty = 0;
+  let value = 0n;
+  let pnl = 0n;
+  considered.forEach((wallet, at2) => {
+    const result = results[at2];
+    if (!result) {
+      unread.push({ ...wallet, reason: failures[at2] ?? "read failed" });
+      return;
+    }
+    if (result.positionCount === 0 && dec(result.accountValueUsd) === 0n) {
+      empty++;
+      return;
+    }
+    accounts.push(result);
+    value += dec(result.accountValueUsd);
+    pnl += dec(result.unrealizedPnlUsd);
+  });
+  return {
+    read: true,
+    network,
+    accounts,
+    subtotal: { accountValueUsd: formatDec(value), unrealizedPnlUsd: formatDec(pnl) },
+    empty,
+    unread,
+    thresholds: "defaults"
+  };
 }
-function hyperliquidRelayBody(typedData) {
-  return { method: "eth_signTypedData_v4", params: { typed_data: typedData } };
+var SCALE = 18;
+var ONE2 = 10n ** BigInt(SCALE);
+var DEC_RE = /^-?(0|[1-9][0-9]*)(\.[0-9]{1,18})?$/;
+var LOOSE_DEC_RE = /^-?[0-9]+(\.[0-9]{1,18})?$/;
+function isDecString(value) {
+  return typeof value === "string" && (DEC_RE.test(value) || LOOSE_DEC_RE.test(value));
+}
+function dec(value) {
+  if (!isDecString(value))
+    return null;
+  const negative = value.startsWith("-");
+  const [whole = "0", fraction = ""] = value.replace(/^-/, "").split(".");
+  const scaled2 = BigInt(whole) * ONE2 + BigInt(fraction.padEnd(SCALE, "0"));
+  return negative ? -scaled2 : scaled2;
+}
+function formatDec(value) {
+  const negative = value < 0n;
+  const abs = negative ? -value : value;
+  const whole = abs / ONE2;
+  const fraction = (abs % ONE2).toString().padStart(SCALE, "0").replace(/0+$/, "");
+  const text = fraction ? `${whole}.${fraction}` : `${whole}`;
+  return negative && text !== "0" ? `-${text}` : text;
+}
+function distanceParts(markPx, liquidationPx) {
+  const mark = dec(markPx);
+  const liq = dec(liquidationPx);
+  if (mark === null || liq === null || mark <= 0n)
+    return null;
+  const diff = mark - liq;
+  return { num: diff < 0n ? -diff : diff, den: mark };
+}
+function fracLess(num, den, bps) {
+  return num * 10000n < BigInt(bps) * den;
+}
+function fracGreater(num, den, bps) {
+  return num * 10000n > BigInt(bps) * den;
+}
+function ratioNumber(num, den) {
+  const micro = num * 1000000000000n / den;
+  return Number(micro) / 1000000000000;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isParsedClearinghouse(value) {
+  return isRecord(value) && Array.isArray(value.positions) && !("assetPositions" in value);
+}
+
+// src/hyperliquid-withdraw.ts
+var CANDLE_PERPS_WITHDRAW_PINS = {
+  token: "USDC:0x6d1e7cde53ba9467b783cb7c530ce054",
+  destinationDex: "",
+  depositories: ["0x66cf0aace1b4e562593bec10ec7868fba9932224"],
+  amountForm: "fixed6"
+};
+var RELAY_API_URL = "https://api.relay.link";
+var ZERO = "0x0000000000000000000000000000000000000000";
+var EVM_ADDRESS_RE2 = /^0x[0-9a-fA-F]{40}$/;
+var BYTES32_RE = /^0x[0-9a-fA-F]{64}$/;
+var RELAY_NONCE_MAPPING_TYPES = {
+  NonceMapping: [
+    { name: "chainId", type: "string" },
+    { name: "wallet", type: "address" },
+    { name: "depositor", type: "address" },
+    { name: "id", type: "bytes32" },
+    { name: "nonce", type: "uint256" }
+  ]
+};
+var HYPERLIQUID_SEND_ASSET_TYPES = {
+  "HyperliquidTransaction:SendAsset": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "destination", type: "string" },
+    { name: "sourceDex", type: "string" },
+    { name: "destinationDex", type: "string" },
+    { name: "token", type: "string" },
+    { name: "amount", type: "string" },
+    { name: "fromSubAccount", type: "string" },
+    { name: "nonce", type: "uint64" }
+  ]
+};
+var SEND_ASSET_KEYS = HYPERLIQUID_SEND_ASSET_TYPES["HyperliquidTransaction:SendAsset"].map((field) => field.name);
+var REQUEST_AMOUNT_RE = /^(0|[1-9][0-9]{0,11})(\.[0-9]{1,6})?$/;
+var CANONICAL_RE = /^(0|[1-9][0-9]*)(\.[0-9]{0,5}[1-9])?$/;
+var FIXED6_RE = /^(0|[1-9][0-9]*)\.[0-9]{6}$/;
+function parseWithdrawAmount(value) {
+  if (!REQUEST_AMOUNT_RE.test(value))
+    return null;
+  const [whole = "0", frac = ""] = value.split(".");
+  const micros = BigInt(whole) * 1000000n + BigInt(frac.padEnd(6, "0"));
+  return micros > 0n ? micros : null;
+}
+function parseSendAssetAmount(value, form) {
+  if (typeof value !== "string" || !(form === "canonical" ? CANONICAL_RE : FIXED6_RE).test(value))
+    return null;
+  const [whole = "0", frac = ""] = value.split(".");
+  if (frac.length > 6)
+    return null;
+  return BigInt(whole) * 1000000n + BigInt(frac.padEnd(6, "0"));
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function exactKeys2(value, keys) {
+  const own = Object.keys(value);
+  return own.length === keys.length && keys.every((key) => Object.hasOwn(value, key));
+}
+function sameEvm(a, b) {
+  return typeof a === "string" && EVM_ADDRESS_RE2.test(a) && a.toLowerCase() === b.toLowerCase();
+}
+function typesMatch(types, expected) {
+  if (!isObject(types) || !exactKeys2(types, Object.keys(expected)))
+    return false;
+  return Object.entries(expected).every(([key, want]) => {
+    const fields = types[key];
+    return Array.isArray(fields) && fields.length === want.length && fields.every((field, i) => isObject(field) && exactKeys2(field, ["name", "type"]) && field.name === want[i]?.name && field.type === want[i]?.type);
+  });
+}
+function domainMatches(domain, expected) {
+  return isObject(domain) && exactKeys2(domain, ["name", "version", "chainId", "verifyingContract"]) && domain.name === expected.name && domain.version === expected.version && domain.chainId === expected.chainId && typeof domain.verifyingContract === "string" && domain.verifyingContract.toLowerCase() === ZERO;
+}
+function verifyWithdrawMapping(build, expect) {
+  const refuse = (reason) => ({ ok: false, reason });
+  if (expect.pins === null)
+    return refuse("no withdrawal pins are set");
+  if (build.id !== expect.id)
+    return refuse("the build names another withdrawal id");
+  if (!sameEvm(build.from?.address, expect.account))
+    return refuse("the build withdraws from another account");
+  if (build.to?.chain !== expect.to)
+    return refuse(`the build lands on ${String(build.to?.chain)}, not ${expect.to}`);
+  const destination = build.to.address;
+  const own = expect.ownDestinations.some((address) => address.startsWith("0x") ? sameEvm(destination, address) : destination === address);
+  if (!own)
+    return refuse("the build lands on a wallet that is not this key's own");
+  if (parseWithdrawAmount(build.amountUsdc) !== expect.amountMicros)
+    return refuse("the build is for another amount");
+  const typed = build.typedData;
+  if (!isObject(typed) || typed.primary_type !== "NonceMapping")
+    return refuse("the typed data is not a NonceMapping");
+  if (!domainMatches(typed.domain, { name: "RelayNonceMapping", version: "2", chainId: 1 }))
+    return refuse("the NonceMapping domain is not Relay's");
+  if (!typesMatch(typed.types, RELAY_NONCE_MAPPING_TYPES))
+    return refuse("the NonceMapping type list differs");
+  const message = typed.message;
+  if (!isObject(message) || !exactKeys2(message, ["chainId", "wallet", "depositor", "id", "nonce"]))
+    return refuse("the NonceMapping message has other fields");
+  if (message.chainId !== "hyperliquid")
+    return refuse("the NonceMapping names another chain");
+  if (!sameEvm(message.wallet, expect.account))
+    return refuse("the NonceMapping wallet is not this key's account");
+  if (!sameEvm(message.depositor, expect.account))
+    return refuse("the NonceMapping depositor is not this key's account");
+  if (typeof message.id !== "string" || !BYTES32_RE.test(message.id) || message.id !== build.relayRequestId)
+    return refuse("the NonceMapping names another Relay request");
+  if (message.nonce !== build.nonce || !Number.isSafeInteger(build.nonce) || build.nonce <= 0)
+    return refuse("the NonceMapping nonce is not the build's");
+  return { ok: true };
+}
+function verifyWithdrawSendAsset(authorization, expect) {
+  const refuse = (reason) => ({ ok: false, reason });
+  const pins = expect.pins;
+  if (pins === null)
+    return refuse("no withdrawal pins are set");
+  const typed = authorization.typedData;
+  if (!isObject(typed) || typed.primary_type !== "HyperliquidTransaction:SendAsset")
+    return refuse("the typed data is not a SendAsset");
+  if (!domainMatches(typed.domain, { name: "HyperliquidSignTransaction", version: "1", chainId: 42161 }))
+    return refuse("the SendAsset domain is not Hyperliquid's user-signed domain");
+  if (!typesMatch(typed.types, HYPERLIQUID_SEND_ASSET_TYPES))
+    return refuse("the SendAsset type list differs");
+  const m = typed.message;
+  if (!isObject(m) || !exactKeys2(m, SEND_ASSET_KEYS))
+    return refuse("the SendAsset message has other fields");
+  if (m.hyperliquidChain !== "Mainnet")
+    return refuse("the SendAsset is not on Mainnet");
+  if (m.nonce !== expect.mappingNonce || authorization.nonce !== expect.mappingNonce)
+    return refuse("the SendAsset nonce is not the NonceMapping's");
+  if (parseSendAssetAmount(m.amount, pins.amountForm) !== expect.amountMicros)
+    return refuse("the SendAsset amount is not the amount asked for");
+  if (m.fromSubAccount !== "")
+    return refuse("the SendAsset moves from a sub-account");
+  if (m.sourceDex !== "")
+    return refuse("the SendAsset moves from another dex");
+  if (m.token !== pins.token)
+    return refuse("the SendAsset moves another token");
+  if (m.destinationDex !== pins.destinationDex)
+    return refuse("the SendAsset names another destination dex");
+  if (typeof m.destination !== "string" || !pins.depositories.includes(m.destination.toLowerCase()))
+    return refuse("the SendAsset destination is not a Relay depository on the allow-list");
+  const action = authorization.action;
+  if (!isObject(action) || !exactKeys2(action, ["type", "signatureChainId", ...SEND_ASSET_KEYS]))
+    return refuse("the action has other fields");
+  if (action.type !== "sendAsset" || action.signatureChainId !== "0xa4b1")
+    return refuse("the action is not a sendAsset");
+  for (const key of SEND_ASSET_KEYS) {
+    if (action[key] !== m[key])
+      return refuse(`the action's ${key} differs from what is signed`);
+  }
+  return { ok: true };
+}
+async function relayRecipientProblem(fetchImpl, requestId, recipient, relayUrl = RELAY_API_URL) {
+  let body;
+  try {
+    const res = await fetchImpl(`${relayUrl}/requests/v3?id=${encodeURIComponent(requestId)}`, { method: "GET" });
+    if (!res.ok)
+      return `Relay's record of the request could not be read (HTTP ${res.status})`;
+    body = await res.json();
+  } catch (error) {
+    return `Relay's record of the request could not be read (${error instanceof Error ? error.message : "unknown"})`;
+  }
+  const requests = isObject(body) && Array.isArray(body.requests) ? body.requests : [];
+  const match = requests.find((r) => isObject(r) && r.id === requestId);
+  if (!isObject(match))
+    return "Relay does not list this request";
+  const named = match.recipient;
+  const same = recipient.startsWith("0x") ? sameEvm(named, recipient) : named === recipient;
+  return same ? null : `Relay's request pays ${String(named)}, not this key's wallet ${recipient}`;
 }
 
 // src/internal/rpc-endpoint.ts
@@ -919,6 +3260,288 @@ function describeRpcEndpoint(url) {
   }
 }
 
+// src/perps-history.ts
+var PERPS_HISTORY_INFO_URLS = {
+  mainnet: "https://api.hyperliquid.xyz/info",
+  testnet: "https://api.hyperliquid-testnet.xyz/info"
+};
+var PERPS_HISTORY_DEFAULT_LIMIT = 100;
+var PERPS_HISTORY_MAX_LIMIT = { fills: 2000, funding: 500 };
+var PERPS_HISTORY_DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+var PERPS_HISTORY_REQUEST_BUDGET = 10;
+var PERPS_HISTORY_FILL_RETENTION = 1e4;
+var PERPS_HISTORY_MAX_CURSOR_LENGTH = 200000;
+var PERPS_HISTORY_TIMEOUT_MS = 15000;
+
+class PerpsHistoryError extends Error {
+  code;
+  extra;
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.code = code;
+    this.extra = extra;
+    this.name = "PerpsHistoryError";
+  }
+}
+var RETENTION_TEXT = "Hyperliquid serves only the 10,000 most recent fills for an account; older fills cannot be read here, and this history is not an all-time total.";
+var EVM_ADDRESS_RE3 = /^0x[0-9a-f]{40}$/;
+function isTime(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+function invalid(field, message) {
+  return new PerpsHistoryError("VALIDATION_FAILED", message, { field });
+}
+function unavailable2(message, retryAfterMs) {
+  return new PerpsHistoryError("PERPS_UNAVAILABLE", message, {
+    retryable: true,
+    ...retryAfterMs !== undefined ? { retryAfterMs } : {}
+  });
+}
+function base64UrlEncode(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = "";
+  for (const b of bytes)
+    binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function base64UrlDecode(text) {
+  if (!/^[A-Za-z0-9_-]*$/.test(text))
+    throw new Error("not base64url");
+  const padded = text.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - text.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0;i < binary.length; i++)
+    bytes[i] = binary.charCodeAt(i);
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+function encodeCursor(state) {
+  return `ph1.${base64UrlEncode(JSON.stringify(state))}`;
+}
+function decodeCursor(cursor) {
+  if (cursor.length > PERPS_HISTORY_MAX_CURSOR_LENGTH || !cursor.startsWith("ph1."))
+    throw invalid("cursor", "cursor is not one this client issued");
+  let state;
+  try {
+    state = JSON.parse(base64UrlDecode(cursor.slice(4)));
+  } catch {
+    throw invalid("cursor", "cursor is not one this client issued");
+  }
+  const ok = state !== null && typeof state === "object" && state.v === 1 && (state.k === "fills" || state.k === "funding") && (state.n === "mainnet" || state.n === "testnet") && typeof state.w === "string" && EVM_ADDRESS_RE3.test(state.w) && isTime(state.s) && isTime(state.e) && state.s <= state.e && Number.isSafeInteger(state.l) && state.l >= 1 && state.l <= PERPS_HISTORY_MAX_LIMIT[state.k] && isTime(state.t) && state.t >= state.s && state.t <= state.e && Array.isArray(state.b) && state.b.every((id) => typeof id === "string" && id.length <= 512) && Number.isSafeInteger(state.c) && state.c >= 0;
+  if (!ok)
+    throw invalid("cursor", "cursor is not one this client issued");
+  return state;
+}
+function canonical2(value) {
+  if (value === null || typeof value !== "object")
+    return JSON.stringify(value);
+  if (Array.isArray(value))
+    return `[${value.map(canonical2).join(",")}]`;
+  const record = value;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonical2(record[key])}`).join(",")}}`;
+}
+function isDecimalString(value) {
+  return typeof value === "string" && /^-?[0-9]+(\.[0-9]+)?$/.test(value);
+}
+function asFill(raw) {
+  const row = raw;
+  if (!row || typeof row !== "object" || typeof row.coin !== "string" || !isTime(row.time) || !Number.isSafeInteger(row.tid) || !Number.isSafeInteger(row.oid) || !isDecimalString(row.px) || !isDecimalString(row.sz) || typeof row.side !== "string" || !isDecimalString(row.closedPnl) || !isDecimalString(row.fee) || row.builderFee !== undefined && !isDecimalString(row.builderFee))
+    throw unavailable2("Hyperliquid returned a fill this client cannot read");
+  return row;
+}
+function asFunding(raw) {
+  const row = raw;
+  const delta = row?.delta;
+  if (!row || typeof row !== "object" || !isTime(row.time) || typeof row.hash !== "string" || !delta || typeof delta !== "object" || typeof delta.coin !== "string" || !isDecimalString(delta.usdc) || !isDecimalString(delta.fundingRate) || !isDecimalString(delta.szi))
+    throw unavailable2("Hyperliquid returned a funding payment this client cannot read");
+  return row;
+}
+function identity(kind, row) {
+  if (kind === "fills") {
+    const fill = row;
+    return `${fill.coin}|${fill.tid}|${fill.oid}`;
+  }
+  const funding = row;
+  return `${funding.hash}|${funding.time}|${funding.delta.coin}|${canonical2(funding.delta)}`;
+}
+function rowCoin(kind, row) {
+  return kind === "fills" ? row.coin : row.delta.coin;
+}
+async function postInfo(req, body, what) {
+  const controller = typeof AbortController === "function" ? new AbortController : null;
+  const timer = controller ? setTimeout(() => controller.abort(), PERPS_HISTORY_TIMEOUT_MS) : null;
+  let res;
+  try {
+    res = await req.fetch(PERPS_HISTORY_INFO_URLS[req.network], {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      ...controller ? { signal: controller.signal } : {}
+    });
+  } catch (err) {
+    const aborted = err instanceof Error && err.name === "AbortError";
+    throw unavailable2(aborted ? `Hyperliquid did not answer the ${what} read in time; retry shortly` : `Hyperliquid could not be reached for the ${what} read; retry shortly`);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+  }
+  if (!res.ok) {
+    if (res.status === 429) {
+      const header = res.headers?.get("retry-after") ?? null;
+      const seconds = header !== null && /^[0-9]{1,6}$/.test(header.trim()) ? Number(header.trim()) : undefined;
+      throw unavailable2(`Hyperliquid rate-limited the ${what} read${seconds !== undefined ? `; retry after ${seconds}s` : "; retry shortly"}`, seconds !== undefined ? seconds * 1000 : undefined);
+    }
+    throw unavailable2(`Hyperliquid answered the ${what} read with HTTP ${res.status}; retry shortly`);
+  }
+  try {
+    return JSON.parse(await res.text());
+  } catch {
+    throw unavailable2(`Hyperliquid returned an unreadable ${what} response`);
+  }
+}
+async function mainPerpCoins(req) {
+  let universe;
+  try {
+    universe = (await readHyperliquidMarkets(req.fetch, req.network)).universe;
+  } catch {
+    throw unavailable2("Hyperliquid's market list could not be read; history is not reported without it");
+  }
+  if (universe.length === 0)
+    throw unavailable2("Hyperliquid's market list could not be read; history is not reported without it");
+  return new Set(universe.map((market) => market.name));
+}
+function resolveWindow(req) {
+  const options = req.options ?? {};
+  const kind = req.kind;
+  const address = req.address.toLowerCase();
+  if (!EVM_ADDRESS_RE3.test(address))
+    throw invalid("wallet", "The wallet's Hyperliquid account is not an EVM address");
+  for (const field of ["startTime", "endTime"]) {
+    const value = options[field];
+    if (value !== undefined && !isTime(value))
+      throw invalid(field, `${field} must be a whole, non-negative number of epoch milliseconds`);
+  }
+  const max = PERPS_HISTORY_MAX_LIMIT[kind];
+  if (options.limit !== undefined && (!Number.isSafeInteger(options.limit) || options.limit < 1 || options.limit > max))
+    throw invalid("limit", `limit must be a whole number from 1 to ${max} for ${kind}`);
+  if (options.cursor !== undefined) {
+    if (typeof options.cursor !== "string" || options.cursor.length === 0)
+      throw invalid("cursor", "cursor is not one this client issued");
+    const state = decodeCursor(options.cursor);
+    if (state.k !== kind)
+      throw invalid("cursor", `This cursor pages ${state.k}, not ${kind}`);
+    if (state.n !== req.network)
+      throw invalid("cursor", `This cursor pages ${state.n}, not ${req.network}`);
+    if (state.w !== address)
+      throw invalid("cursor", "This cursor pages another wallet");
+    if (options.startTime !== undefined && options.startTime !== state.s || options.endTime !== undefined && options.endTime !== state.e || options.limit !== undefined && options.limit !== state.l)
+      throw invalid("cursor", "The window or page size changed; start again without a cursor");
+    return { state };
+  }
+  const endTime = options.endTime ?? req.now();
+  const startTime = options.startTime ?? Math.max(0, endTime - PERPS_HISTORY_DEFAULT_WINDOW_MS);
+  if (!isTime(endTime))
+    throw invalid("endTime", "endTime must be epoch milliseconds");
+  if (startTime > endTime)
+    throw invalid("startTime", "startTime must not be after endTime");
+  return {
+    state: {
+      v: 1,
+      k: kind,
+      n: req.network,
+      w: address,
+      s: startTime,
+      e: endTime,
+      l: options.limit ?? PERPS_HISTORY_DEFAULT_LIMIT,
+      t: startTime,
+      b: [],
+      c: 0
+    }
+  };
+}
+async function readPerpsHistoryPage(req) {
+  const { state } = resolveWindow(req);
+  const kind = req.kind;
+  const max = PERPS_HISTORY_MAX_LIMIT[kind];
+  const readAt = req.now();
+  const coins = await mainPerpCoins(req);
+  const page = [];
+  const warnings = [];
+  let t = state.t;
+  let boundary = new Set(state.b);
+  let consumed = state.c;
+  let done = false;
+  let truncated = false;
+  let requests = 0;
+  const stop = (code, message, ends) => {
+    warnings.push({ code, message });
+    if (ends) {
+      done = true;
+      truncated = true;
+    }
+  };
+  walk:
+    while (page.length < state.l && !done) {
+      if (requests >= PERPS_HISTORY_REQUEST_BUDGET) {
+        stop("PERPS_HISTORY_PAGE_BUDGET", `Stopped after ${PERPS_HISTORY_REQUEST_BUDGET} Hyperliquid reads; pass nextCursor to continue`, false);
+        break;
+      }
+      const body = kind === "fills" ? { type: "userFillsByTime", user: state.w, startTime: t, endTime: state.e, aggregateByTime: false } : { type: "userFunding", user: state.w, startTime: t, endTime: state.e };
+      const raw = await postInfo(req, body, kind === "fills" ? "fills" : "funding");
+      requests++;
+      if (!Array.isArray(raw))
+        throw unavailable2(`Hyperliquid returned an unreadable ${kind} response`);
+      const rows = raw.map((r) => kind === "fills" ? asFill(r) : asFunding(r));
+      const keyed = rows.map((row) => ({ row, id: identity(kind, row) })).sort((a, b) => a.row.time - b.row.time || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+      const full = rows.length >= max;
+      const startedAt = t;
+      let previousId = null;
+      for (const { row, id } of keyed) {
+        if (id === previousId)
+          continue;
+        previousId = id;
+        if (row.time < t || row.time > state.e || row.time === t && boundary.has(id))
+          continue;
+        if (page.length >= state.l)
+          break walk;
+        if (row.time > t) {
+          t = row.time;
+          boundary = new Set;
+        }
+        boundary.add(id);
+        consumed++;
+        if (coins.has(rowCoin(kind, row)))
+          page.push(row);
+        if (kind === "fills" && consumed >= PERPS_HISTORY_FILL_RETENTION) {
+          stop("PERPS_HISTORY_RETENTION_LIMIT", "Reached Hyperliquid's 10,000-fill retention across this cursor chain; older fills are not available", true);
+          break walk;
+        }
+      }
+      if (!full) {
+        done = true;
+      } else if (t === startedAt) {
+        stop("PERPS_HISTORY_BOUNDARY_LIMIT", `More than ${max} ${kind === "fills" ? "fills" : "funding rows"} share one millisecond (${t}); coverage stops there`, true);
+      }
+    }
+  if (kind === "fills" && !warnings.some((w) => w.code === "PERPS_HISTORY_RETENTION_LIMIT"))
+    warnings.unshift({ code: "PERPS_HISTORY_RETENTION_LIMIT", message: RETENTION_TEXT });
+  const nextCursor = done ? null : encodeCursor({ ...state, t, b: [...boundary], c: consumed });
+  const envelope = {
+    success: true,
+    walletId: req.walletId,
+    address: state.w,
+    network: state.n,
+    source: "hyperliquid",
+    readAt,
+    startTime: state.s,
+    endTime: state.e,
+    nextCursor,
+    hasMore: nextCursor !== null,
+    truncated,
+    warnings
+  };
+  return kind === "fills" ? { ...envelope, fills: page } : { ...envelope, funding: page };
+}
+
 // src/wallet-import.ts
 import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
 import { CipherSuite, DhkemP256HkdfSha256, HkdfSha256 } from "@hpke/core";
@@ -1005,6 +3628,32 @@ function historyTime(value) {
 }
 var HYPERLIQUID_RELAY_CHAIN_ID = 1337;
 var HYPERLIQUID_RELAY_USDC = "0x00000000000000000000000000000000";
+function perpsClientId(clientId) {
+  if (clientId === undefined)
+    return;
+  const lower = typeof clientId === "string" ? clientId.toLowerCase() : "";
+  if (!HYPERLIQUID_CLOID_RE.test(lower))
+    throw new Error("perps: clientId must be 0x followed by 32 hex digits");
+  return lower;
+}
+function perpsReplayOf(build, walletId, clientId) {
+  const answer = build;
+  if (answer.replayed === true) {
+    if (clientId === undefined || answer.clientId !== clientId || answer.walletId !== walletId)
+      throw new Error("perps: refused a replay that does not name this request's client id and wallet");
+    return {
+      replayed: true,
+      replay: build,
+      build: null,
+      signature: null,
+      submitted: false,
+      exchange: null
+    };
+  }
+  if (clientId !== undefined && (answer.clientId !== clientId || answer.cloid !== clientId))
+    throw new Error("perps: PERPS_CLIENT_ID_UNSUPPORTED: this Candle API did not echo the client order id, so its order could not be deduplicated. Nothing was signed.");
+  return null;
+}
 function perpsDepositProblem(build, params) {
   const same = (a, b) => typeof a === "string" && a.toLowerCase() === b.toLowerCase();
   if (build.walletId !== params.walletId)
@@ -1046,7 +3695,7 @@ function isRetryableLaunchFailure(error) {
   return error.status >= 500 || error.status === 409;
 }
 function sleep2(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 var MAX_BLOCKHASH_REBUILDS = 2;
 function isBlockhashExpiry(error) {
@@ -1196,7 +3845,29 @@ class CandleClient {
   solanaRpcUrl;
   evmRpcUrl;
   hyperliquidNetwork;
+  perpsMarketReader;
   hyperliquidBuilder;
+  perpsWithdrawPins;
+  perps = {
+    withdraw: {
+      build: async (request) => {
+        this.requireKey("perps.withdraw.build()");
+        return this.requestJson("POST", "/api/v1/agent/perps/withdraw", request);
+      },
+      authorize: async (request) => {
+        this.requireKey("perps.withdraw.authorize()");
+        return this.requestJson("POST", "/api/v1/agent/perps/withdraw/authorize", request);
+      },
+      reportSubmitted: async (request) => {
+        this.requireKey("perps.withdraw.reportSubmitted()");
+        return this.requestJson("POST", "/api/v1/agent/perps/withdraw/submitted", request);
+      },
+      get: async (clientWithdrawalId) => {
+        this.requireKey("perps.withdraw.get()");
+        return this.requestJson("GET", `/api/v1/agent/perps/withdraw/${encodeURIComponent(clientWithdrawalId)}`);
+      }
+    }
+  };
   wallets = {
     swapReceipt: async (hash) => {
       this.requireKey("wallets.swapReceipt()");
@@ -1270,9 +3941,9 @@ class CandleClient {
     if (opts.evmRpcUrl !== undefined)
       this.evmRpcUrl = opts.evmRpcUrl;
     this.hyperliquidNetwork = opts.hyperliquidNetwork ?? "mainnet";
-    const builder = opts.hyperliquidBuilder ?? CANDLE_HYPERLIQUID_BUILDER_ADDRESS;
-    if (builder)
-      this.hyperliquidBuilder = builder.toLowerCase();
+    this.perpsWithdrawPins = opts.perpsWithdrawPins ?? CANDLE_PERPS_WITHDRAW_PINS;
+    if (opts.hyperliquidBuilder !== undefined)
+      this.hyperliquidBuilder = opts.hyperliquidBuilder;
   }
   async getQuotePairs(chain) {
     const query = chain ? `?chain=${chain}` : "";
@@ -1987,13 +4658,47 @@ class CandleClient {
     }
     return txHash;
   }
+  marketReader() {
+    this.perpsMarketReader ??= new PerpsMarketReader({
+      apiKey: this.apiKey,
+      network: this.hyperliquidNetwork,
+      fetcher: this.fetchImpl,
+      readConfig: () => this.perpsConfig()
+    });
+    return this.perpsMarketReader;
+  }
+  async perpsMarkets(opts = {}) {
+    return this.marketReader().markets(opts);
+  }
+  async perpsMarket(coin) {
+    return this.marketReader().market(coin);
+  }
+  async perpsBook(coin, opts = {}) {
+    return this.marketReader().book(coin, opts);
+  }
+  async perpsCandles(coin, opts = {}) {
+    return this.marketReader().candles(coin, opts);
+  }
   async perpsConfig() {
     this.requireKey("perpsConfig()");
     return this.requestJson("GET", "/api/v1/agent/perps/config");
   }
   async perpsSetup(params) {
     this.requireKey("perpsSetup()");
+    const builder = this.perpsBuilder();
+    const address = await this.perpsWalletAddress(params.walletId);
+    const mode = await hyperliquidAccountMode(this.fetchImpl, this.hyperliquidNetwork, address);
+    if (!HYPERLIQUID_STANDARD_ACCOUNT_MODES.includes(mode))
+      throw new Error(`perps: PERPS_ACCOUNT_MODE: the account is in ${mode} mode on Hyperliquid; Candle trades only a standard account. Nothing was requested or signed.`);
     const res = await this.requestJson("POST", "/api/v1/agent/perps/setup", { walletId: params.walletId });
+    const problem = perpsSetupStatusProblem(res, {
+      network: this.hyperliquidNetwork,
+      address,
+      builder,
+      mode
+    });
+    if (problem)
+      throw new Error(`perps: refused this setup answer: ${problem}. Nothing was signed.`);
     const status = {
       walletId: res.walletId,
       address: res.address,
@@ -2004,7 +4709,8 @@ class CandleClient {
       withdrawable: res.withdrawable,
       builder: res.builder,
       approvedFeeTenthsBps: res.approvedFeeTenthsBps,
-      ready: res.ready
+      ready: res.ready,
+      preview: { builderTrust: this.perpsBuilderTrust() }
     };
     if (res.ready)
       return status;
@@ -2012,18 +4718,39 @@ class CandleClient {
   }
   async perpsOpen(params) {
     this.requireKey("perpsOpen()");
+    this.perpsBuilder();
     const { walletId, privyWalletId: _p, submit: _s, ...order } = params;
-    const build = await this.requestJson("POST", "/api/v1/agent/perps/open", { walletId, ...order });
-    return this.perpsComplete(build, params, "open");
+    const clientId = perpsClientId(params.clientId);
+    const build = await this.requestJson("POST", "/api/v1/agent/perps/open", {
+      walletId,
+      ...order,
+      ...clientId !== undefined ? { clientId } : {}
+    });
+    const replay = perpsReplayOf(build, walletId, clientId);
+    if (replay)
+      return replay;
+    return this.perpsComplete(build, { ...params, ...clientId ? { clientId } : {} }, "open");
   }
   async perpsClose(params) {
     this.requireKey("perpsClose()");
+    if (params.pct !== undefined && params.size !== undefined)
+      throw new Error("perpsClose(): give a size or a pct, not both");
+    this.perpsBuilder();
     const { walletId, privyWalletId: _p, submit: _s, ...close } = params;
-    const build = await this.requestJson("POST", "/api/v1/agent/perps/close", { walletId, ...close });
-    return this.perpsComplete(build, params, "close");
+    const clientId = perpsClientId(params.clientId);
+    const build = await this.requestJson("POST", "/api/v1/agent/perps/close", {
+      walletId,
+      ...close,
+      ...clientId !== undefined ? { clientId } : {}
+    });
+    const replay = perpsReplayOf(build, walletId, clientId);
+    if (replay)
+      return replay;
+    return this.perpsComplete(build, { ...params, ...clientId ? { clientId } : {} }, "close");
   }
   async perpsCancel(params) {
     this.requireKey("perpsCancel()");
+    this.perpsBuilder();
     const build = await this.requestJson("POST", "/api/v1/agent/perps/cancel", {
       walletId: params.walletId,
       cloid: params.cloid
@@ -2032,18 +4759,42 @@ class CandleClient {
   }
   async perpsModify(params) {
     this.requireKey("perpsModify()");
+    this.perpsBuilder();
     const { walletId, privyWalletId: _p, submit: _s, ...modify } = params;
     const build = await this.requestJson("POST", "/api/v1/agent/perps/modify", { walletId, ...modify });
     return this.perpsComplete(build, params, "modify");
   }
   async perpsLeverage(params) {
     this.requireKey("perpsLeverage()");
+    if (params.leverage === undefined && params.mode === undefined)
+      throw new Error("perpsLeverage(): leverage is required unless mode names the margin mode");
+    this.perpsBuilder();
     const { walletId, privyWalletId: _p, submit: _s, ...leverage } = params;
     const build = await this.requestJson("POST", "/api/v1/agent/perps/leverage", { walletId, ...leverage });
-    return this.perpsComplete(build, params, "leverage");
+    const result = await this.perpsComplete(build, params, "leverage");
+    if (params.mode === undefined || result.outcome?.status !== "confirmed")
+      return result;
+    let confirmedMode = null;
+    try {
+      const res = await this.fetchImpl(HYPERLIQUID_EXCHANGE_URLS[this.hyperliquidNetwork].replace("/exchange", "/info"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          type: "activeAssetData",
+          user: build.address,
+          coin: String(build.preview.coin ?? params.coin)
+        })
+      });
+      const type = JSON.parse(await res.text())?.leverage?.type;
+      confirmedMode = type === "cross" || type === "isolated" ? type : null;
+    } catch {
+      confirmedMode = null;
+    }
+    return { ...result, requestedMode: params.mode, confirmedMode };
   }
   async perpsMargin(params) {
     this.requireKey("perpsMargin()");
+    this.perpsBuilder();
     const build = await this.requestJson("POST", "/api/v1/agent/perps/margin", {
       walletId: params.walletId,
       coin: params.coin,
@@ -2053,7 +4804,22 @@ class CandleClient {
   }
   async perpsPositions(walletId) {
     this.requireKey("perpsPositions()");
-    return this.requestJson("GET", `/api/v1/agent/perps/positions?walletId=${encodeURIComponent(walletId)}`);
+    const server = await this.requestJson("GET", `/api/v1/agent/perps/positions?walletId=${encodeURIComponent(walletId)}`);
+    const { effective } = await this.perpsThresholdsOrDefaults();
+    const identity2 = { walletId, address: server.address, network: this.hyperliquidNetwork };
+    let report;
+    try {
+      report = await readPerpsRisk({
+        ...identity2,
+        fetcher: this.fetchImpl,
+        thresholds: effective,
+        now: Date.now
+      });
+    } catch {
+      report = unknownRiskReport(identity2, effective, "PERPS_READ_FAILED", Date.now());
+    }
+    const { positions: rows, ...risk } = report;
+    return { ...server, rows, accountLine: report.account, risk };
   }
   async perpsOrders(walletId, opts = {}) {
     this.requireKey("perpsOrders()");
@@ -2062,6 +4828,43 @@ class CandleClient {
       params.set("limit", String(opts.limit));
     return this.requestJson("GET", `/api/v1/agent/perps/orders?${params}`);
   }
+  async perpsFillsPage(walletId, options = {}) {
+    this.requireKey("perpsFillsPage()");
+    return await this.perpsHistoryPage("fills", walletId, options);
+  }
+  async perpsFundingPage(walletId, options = {}) {
+    this.requireKey("perpsFundingPage()");
+    return await this.perpsHistoryPage("funding", walletId, options);
+  }
+  async perpsHistoryPage(kind, walletId, options) {
+    const address = await this.perpsWalletAddress(walletId);
+    return readPerpsHistoryPage({
+      kind,
+      network: this.hyperliquidNetwork,
+      walletId,
+      address,
+      options,
+      fetch: this.fetchImpl,
+      now: Date.now
+    });
+  }
+  async perpsWalletAddress(walletId) {
+    let cursor = null;
+    for (let page = 0;page < 10; page++) {
+      const query = cursor ? `?cursor=${encodeURIComponent(cursor)}` : "";
+      const listed = await this.requestJson("GET", `/api/v1/agent/wallets/trading${query}`);
+      const row = (listed.page ?? []).find((r) => r.id === walletId);
+      if (row) {
+        if (row.chain !== "evm" || !/^0x[0-9a-fA-F]{40}$/.test(row.address))
+          throw new Error(`perps: wallet ${walletId} is not an EVM TEE wallet`);
+        return row.address.toLowerCase();
+      }
+      if (listed.isDone !== false || !listed.continueCursor)
+        break;
+      cursor = listed.continueCursor;
+    }
+    throw new Error(`perps: wallet ${walletId} is not an EVM TEE wallet bound to this key`);
+  }
   async perpsFills(walletId) {
     this.requireKey("perpsFills()");
     return this.requestJson("GET", `/api/v1/agent/perps/fills?walletId=${encodeURIComponent(walletId)}`);
@@ -2073,6 +4876,87 @@ class CandleClient {
       params.set("startTime", String(startTime));
     return this.requestJson("GET", `/api/v1/agent/perps/funding?${params}`);
   }
+  async getPerpsRisk() {
+    this.requireKey("getPerpsRisk()");
+    const { thresholds, stored } = perpsRiskFromLimits(await this.requestJson("GET", "/api/v1/agent/keys/self/limits"));
+    return { perpsRisk: stored, effective: thresholds };
+  }
+  async setPerpsRisk(fields) {
+    this.requireKey("setPerpsRisk()");
+    return this.requestJson("PUT", "/api/v1/agent/keys/self/perps-risk", { perpsRisk: fields });
+  }
+  async setKeyPerpsRisk(keyPrefix, fields, owner) {
+    const res = await this.fetchImpl(`${this.apiUrl}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/perps-risk`, {
+      method: "PUT",
+      headers: { "content-type": "application/json", authorization: `Bearer ${owner.bearerToken}` },
+      body: JSON.stringify({ perpsRisk: fields })
+    });
+    return this.parseResponse(res);
+  }
+  async perpsRisk(params) {
+    this.requireKey("perpsRisk()");
+    const address = params.address ?? await this.perpsWalletAddress(params.walletId);
+    const { effective } = await this.perpsThresholdsOrDefaults();
+    return readPerpsRisk({
+      fetcher: this.fetchImpl,
+      network: this.hyperliquidNetwork,
+      walletId: params.walletId,
+      address,
+      thresholds: effective,
+      now: Date.now
+    });
+  }
+  async perpsAccount(params) {
+    this.requireKey("perpsAccount()");
+    const now = Date.now();
+    const startTime = params.since ?? now - 24 * 60 * 60 * 1000;
+    if (!Number.isSafeInteger(startTime) || startTime >= now || now - startTime > PERPS_RECENT_MAX_MS)
+      throw new Error("perpsAccount(): since must be an epoch-ms time within the last 30 days");
+    const address = params.address ?? await this.perpsWalletAddress(params.walletId);
+    const { effective } = await this.perpsThresholdsOrDefaults();
+    const fetcher = this.fetchImpl;
+    const [report, recent] = await Promise.all([
+      readPerpsRisk({
+        fetcher,
+        network: this.hyperliquidNetwork,
+        walletId: params.walletId,
+        address,
+        thresholds: effective,
+        now: Date.now
+      }),
+      readPerpsRecent(fetcher, this.hyperliquidNetwork, address, { startTime, endTime: now })
+    ]);
+    return perpsAccountReport(report, recent);
+  }
+  async watchPerpsRisk(params) {
+    this.requireKey("watchPerpsRisk()");
+    const address = params.address ?? await this.perpsWalletAddress(params.walletId);
+    return watchPerpsRisk({
+      fetcher: this.fetchImpl,
+      network: this.hyperliquidNetwork,
+      walletId: params.walletId,
+      address,
+      thresholds: async () => (await this.getPerpsRisk()).effective,
+      ...params.intervalMs !== undefined ? { intervalMs: params.intervalMs } : {},
+      ...params.heartbeatMs !== undefined ? { heartbeatMs: params.heartbeatMs } : {},
+      ...params.signal ? { signal: params.signal } : {},
+      ...params.onceLevelChange ? { onceLevelChange: true } : {},
+      now: Date.now,
+      sleep: (ms) => new Promise((resolve2) => setTimeout(resolve2, ms)),
+      onEvent: params.onEvent
+    });
+  }
+  async perpsPortfolioSection(wallets) {
+    return perpsPortfolioSection(this.fetchImpl, this.hyperliquidNetwork, wallets);
+  }
+  async perpsThresholdsOrDefaults() {
+    try {
+      return await this.getPerpsRisk();
+    } catch {
+      const { thresholds, stored } = perpsRiskFromLimits(null);
+      return { perpsRisk: stored, effective: thresholds };
+    }
+  }
   async perpsDeposit(params) {
     this.requireKey("perpsDeposit()");
     const build = await this.requestJson("POST", "/api/v1/agent/perps/deposit", {
@@ -2146,45 +5030,32 @@ class CandleClient {
     this.requireKey("perpsDepositStatus()");
     return this.requestJson("GET", `/api/v1/agent/perps/deposit/${encodeURIComponent(clientDepositId)}`);
   }
-  async perpsBuilder() {
-    if (this.hyperliquidBuilder)
-      return this.hyperliquidBuilder;
-    const config = await this.perpsConfig();
-    if (!config.builder)
-      throw new Error("perps: the server reports no Hyperliquid builder address");
-    this.hyperliquidBuilder = config.builder.toLowerCase();
-    return this.hyperliquidBuilder;
+  perpsBuilder() {
+    return resolveHyperliquidBuilder(this.hyperliquidBuilder);
+  }
+  perpsBuilderTrust() {
+    return {
+      address: this.perpsBuilder(),
+      source: this.hyperliquidBuilder === undefined ? "release" : "override"
+    };
   }
   async perpsComplete(build, ref, method) {
-    const check = verifyPerpsBuild(build, {
-      builder: await this.perpsBuilder(),
+    build = { ...build, preview: { ...build.preview, builderTrust: this.perpsBuilderTrust() } };
+    const params = ref;
+    const opts = {
+      builder: this.perpsBuilder(),
       network: this.hyperliquidNetwork,
-      intent: { method, params: ref }
+      intent: { method, params },
+      keyReduceOnly: build.perpsReduceOnly === true
+    };
+    const check = method === "setup" ? verifyPerpsBuild(build, opts) : await verifyPerpsBuildAgainstVenue(build, {
+      ...opts,
+      address: build.address,
+      fetcher: this.fetchImpl,
+      now: Date.now
     });
     if (!check.ok)
       throw new Error(`perps: refused to sign this build: ${check.reason}`);
-    if (method === "close") {
-      const closeOrder = await hyperliquidCloseOrder(this.fetchImpl, this.hyperliquidNetwork, build.address, ref);
-      const closeCheck = verifyPerpsBuild(build, {
-        builder: await this.perpsBuilder(),
-        network: this.hyperliquidNetwork,
-        intent: { method, params: ref },
-        closeOrder
-      });
-      if (!closeCheck.ok)
-        throw new Error(`perps: refused to sign this build: ${closeCheck.reason}`);
-    }
-    if (method === "open" || method === "modify") {
-      const market = await hyperliquidOrderMarket(this.fetchImpl, this.hyperliquidNetwork, build.address, method, ref);
-      const marketCheck = verifyPerpsBuild(build, {
-        builder: await this.perpsBuilder(),
-        network: this.hyperliquidNetwork,
-        intent: { method, params: ref },
-        market
-      });
-      if (!marketCheck.ok)
-        throw new Error(`perps: refused to sign this build: ${marketCheck.reason}`);
-    }
     if (ref.submit === false)
       return { build, signature: null, submitted: false, exchange: null };
     const signature = await this.signLinkedTypedData({
@@ -2202,7 +5073,8 @@ class CandleClient {
       if (!res.ok) {
         return { build, signature, submitted: false, exchange: null, submitError: `HTTP ${res.status}: ${text}` };
       }
-      return { build, signature, submitted: true, exchange: JSON.parse(text) };
+      const exchange = JSON.parse(text);
+      return { build, signature, submitted: true, exchange, outcome: hyperliquidExchangeOutcome(exchange) };
     } catch (err) {
       return {
         build,
@@ -2213,6 +5085,162 @@ class CandleClient {
       };
     }
   }
+  async perpsScheduleCancel(params) {
+    this.requireKey("perpsScheduleCancel()");
+    const clear = params.clear === true;
+    if (clear === (params.seconds !== undefined))
+      throw new Error("perpsScheduleCancel(): give seconds, or clear: true");
+    const build = await this.requestJson("POST", "/api/v1/agent/perps/schedule-cancel", {
+      walletId: params.walletId,
+      ...clear ? { clear: true } : { seconds: params.seconds }
+    });
+    const result = await this.perpsComplete(build, params, "scheduleCancel");
+    if (result.outcome?.status === "rejected")
+      return { ...result, submitError: `PERPS_SCHEDULE_CANCEL_REJECTED: ${result.outcome.error}` };
+    if (result.outcome?.status !== "confirmed")
+      return result;
+    let acknowledged = false;
+    try {
+      const ack = await this.requestJson("POST", "/api/v1/agent/perps/schedule-cancel/ack", {
+        walletId: params.walletId,
+        perpOrderId: build.perpOrderId,
+        exchange: result.exchange
+      });
+      acknowledged = ack.acknowledged === true;
+    } catch {
+      acknowledged = false;
+    }
+    return { ...result, acknowledged };
+  }
+  async perpsTpsl(params) {
+    this.requireKey("perpsTpsl()");
+    const { walletId, privyWalletId: _p, submit: _s, ...tpsl } = params;
+    return runPerpsTpsl(await this.perpsWorkflowIo(params), tpsl);
+  }
+  async perpsFlatten(params) {
+    this.requireKey("perpsFlatten()");
+    return runPerpsFlatten(await this.perpsWorkflowIo(params));
+  }
+  async perpsWorkflowIo(ref) {
+    const address = await this.perpsWalletAddress(ref.walletId);
+    const builder = this.perpsBuilder();
+    const reduceOnly = await this.getPerpsReduceOnly().catch(() => null);
+    return {
+      network: this.hyperliquidNetwork,
+      walletId: ref.walletId,
+      address,
+      builder,
+      keyReduceOnly: reduceOnly === null ? true : reduceOnly.perpsReduceOnly,
+      fetcher: this.fetchImpl,
+      now: Date.now,
+      build: (path, body) => this.requestJson("POST", path, body),
+      read: (path) => this.requestJson("GET", path),
+      sign: (typedData) => this.signLinkedTypedData({ linkedWalletId: ref.walletId, privyWalletId: ref.privyWalletId, typedData }),
+      mode: ref.submit === false ? "no-submit" : "submit",
+      cloid: () => {
+        const bytes = new Uint8Array(16);
+        globalThis.crypto.getRandomValues(bytes);
+        return `0x${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+      }
+    };
+  }
+  async getPerpsReduceOnly() {
+    this.requireKey("getPerpsReduceOnly()");
+    return this.requestJson("GET", "/api/v1/agent/keys/self/perps-reduce-only");
+  }
+  async setPerpsReduceOnly(perpsReduceOnly) {
+    this.requireKey("setPerpsReduceOnly()");
+    return this.requestJson("PUT", "/api/v1/agent/keys/self/perps-reduce-only", {
+      perpsReduceOnly
+    });
+  }
+  async setKeyPerpsReduceOnly(keyPrefix, perpsReduceOnly, owner) {
+    const res = await this.fetchImpl(`${this.apiUrl}/api/v1/agent/keys/${encodeURIComponent(keyPrefix)}/perps-reduce-only`, {
+      method: "PUT",
+      headers: { "content-type": "application/json", authorization: `Bearer ${owner.bearerToken}` },
+      body: JSON.stringify({ perpsReduceOnly })
+    });
+    return this.parseResponse(res);
+  }
+  async perpsWithdraw(params) {
+    this.requireKey("perpsWithdraw()");
+    if (this.hyperliquidNetwork !== "mainnet")
+      throw new Error("perpsWithdraw: withdrawals are mainnet only");
+    if (this.perpsWithdrawPins === null) {
+      throw new Error("perpsWithdraw: no withdrawal pins are set; nothing was built");
+    }
+    const amountMicros = parseWithdrawAmount(params.amountUsdc);
+    if (amountMicros === null)
+      throw new Error("perpsWithdraw: amountUsdc must be a positive decimal, at most 6 dp");
+    const id = params.clientWithdrawalId ?? `withdraw-${crypto.randomUUID()}`;
+    const build = await this.perps.withdraw.build({
+      clientWithdrawalId: id,
+      amountUsdc: params.amountUsdc,
+      to: params.to,
+      wallet: params.walletId
+    });
+    if (build.status !== "quoted") {
+      throw new Error(`perpsWithdraw: withdrawal ${id} is already ${build.status}; read it with perps.withdraw.get()`);
+    }
+    const mapping = verifyWithdrawMapping(build, {
+      id,
+      account: params.account,
+      to: params.to,
+      amountMicros,
+      ownDestinations: params.ownDestinations,
+      pins: this.perpsWithdrawPins
+    });
+    if (!mapping.ok)
+      throw new Error(`perpsWithdraw: refused to sign this withdrawal: ${mapping.reason}`);
+    const recipient = await relayRecipientProblem(this.fetchImpl, build.relayRequestId, build.to.address);
+    if (recipient)
+      throw new Error(`perpsWithdraw: refused to sign this withdrawal: ${recipient}`);
+    const mappingSignature = await this.signLinkedTypedData({
+      linkedWalletId: params.walletId,
+      privyWalletId: params.privyWalletId,
+      typedData: build.typedData
+    });
+    const authorization = await this.perps.withdraw.authorize({ clientWithdrawalId: id, signature: mappingSignature });
+    const send = verifyWithdrawSendAsset(authorization, {
+      mappingNonce: build.nonce,
+      amountMicros,
+      pins: this.perpsWithdrawPins
+    });
+    if (!send.ok)
+      throw new Error(`perpsWithdraw: refused to sign the transfer: ${send.reason}`);
+    const signature = await this.signLinkedTypedData({
+      linkedWalletId: params.walletId,
+      privyWalletId: params.privyWalletId,
+      typedData: authorization.typedData
+    });
+    let exchange = null;
+    let submitError;
+    try {
+      const res = await this.fetchImpl(HYPERLIQUID_EXCHANGE_URLS.mainnet, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(hyperliquidExchangeBody(authorization.action, authorization.nonce, signature))
+      });
+      const text = await res.text();
+      if (res.ok)
+        exchange = JSON.parse(text);
+      else
+        submitError = `HTTP ${res.status}: ${text}`;
+    } catch (err) {
+      submitError = err instanceof Error ? err.message : String(err);
+    }
+    if (exchange !== null) {
+      await this.perps.withdraw.reportSubmitted({ clientWithdrawalId: id, exchangeResponse: exchange }).catch(() => {});
+    }
+    return {
+      build,
+      authorization,
+      signature,
+      submitted: exchange !== null,
+      exchange,
+      ...submitError !== undefined ? { submitError } : {}
+    };
+  }
   async signLinkedTypedData(params) {
     if (!this.privyAppId) {
       throw new Error("perps signing requires privyAppId in CandleClientOptions (the relay's Privy app id)");
@@ -2424,7 +5452,7 @@ function generateClientLaunchId() {
 function generateClientTradeId() {
   return generateSdkId();
 }
-var SDK_VERSION = "0.6.1";
+var SDK_VERSION = "0.6.3";
 var sdkUpdateWarned = false;
 function noteLatestSdkVersion(value) {
   if (sdkUpdateWarned || !value || !/^\d+\.\d+\.\d+$/.test(value))
@@ -2645,7 +5673,7 @@ async function withFileLock(target, fn) {
       if (Date.now() > deadline) {
         throw new Error(`Timed out waiting for ${lockPath}. Another candle process is writing; if none is running, delete that file.`);
       }
-      await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+      await new Promise((resolve2) => setTimeout(resolve2, RETRY_MS));
     }
   }
   try {
@@ -2781,29 +5809,61 @@ function verifyWebhookSignature(secret, header, body, nowSec, toleranceSec = 300
   return timingSafeEqual(provided, expected);
 }
 export {
+  watchPerpsRisk,
+  verifyWithdrawSendAsset,
+  verifyWithdrawMapping,
   verifyWebhookSignature,
+  verifyPerpsBuildAgainstVenue,
   verifyPerpsBuild,
+  relayRecipientProblem,
+  readPerpsRisk,
+  readPerpsHistoryPage,
+  readHyperliquidMarkets,
   planTableRows,
   planTableMarkdown,
   planPromotionLine,
   planLabel,
+  perpsSetupStatusProblem,
+  perpsRiskStep,
+  perpsRiskExitCode,
+  perpsPortfolioSection,
+  perpsMarketGate,
   perpsDepositProblem,
+  perpsCandleWindow,
+  parseWithdrawAmount,
+  parseSendAssetAmount,
   operationIds,
   isSolanaRpcErrorData,
+  hyperliquidWalletSnapshot,
+  hyperliquidRiskReport,
   hyperliquidOrderMarket,
+  hyperliquidExchangeOutcome,
   hyperliquidActionHash,
+  hyperliquidAccountMode,
   generateSignerKeypair,
   formatPlanBps,
   encryptWalletKeyForImport,
+  effectivePerpsRisk,
   TradeLegOutcomeError,
   TradeLandedUnconfirmedError,
   TradeLandedFeeLegError,
   SelfLaunchOutcomeError,
+  PerpsWorkflowError,
+  PerpsMarketReader,
+  PerpsMarketError,
+  PerpsHistoryError,
   PLAN_CAPABILITY_NOTE,
   PLAN_CAPABILITY_LABELS,
+  PERPS_HISTORY_MAX_LIMIT,
+  PERPS_HISTORY_DEFAULT_LIMIT,
+  PERPS_FLATTEN_MAX_STEPS,
+  PERPS_CANDLE_INTERVALS,
   KeychainSecretStore,
   JsonRpcError,
   InMemorySecretStore,
+  HyperliquidReadError,
+  HYPERLIQUID_STANDARD_ACCOUNT_MODES,
+  HYPERLIQUID_RISK_DEFAULTS,
   HYPERLIQUID_EXCHANGE_URLS,
   HYPERLIQUID_ALLOWED_ACTION_TYPES,
   EncryptedFileSecretStore,
@@ -2811,6 +5871,7 @@ export {
   CandleOperationError,
   CandleClient,
   CandleApiError,
+  CANDLE_PERPS_WITHDRAW_PINS,
   CANDLE_HYPERLIQUID_BUILDER_ADDRESS,
   BRIDGE_ERROR_CODES
 };