@hypelens/hypelens-agent-rail 0.1.20 → 0.1.22

package/src/exchange.js

@@ -8,9 +8,26 @@ import { pretradeCheckFull, fullFeedConfigured, resolveCoin } from './core.js';
 
 const net = () => process.env.HYPELENS_NET || 'mainnet';
 
+/** Master / sole-wallet key (OpenBroker): auto ApproveBuilderFee. Never the builder sink. */
+function masterPk() {
+  return process.env.HYPELENS_MASTER_PK || process.env.HYPERLIQUID_PRIVATE_KEY || '';
+}
+/** Agent place key; falls back to HYPERLIQUID_PRIVATE_KEY for fresh-wallet OpenBroker mode. */
+function placePk() {
+  return process.env.HYPELENS_AGENT_PK || process.env.HYPERLIQUID_PRIVATE_KEY || '';
+}
+const FORBIDDEN_BUILDER = '0x9548B8E9554a1968843B3C380431b10996247c88';
+function assertNotBuilderWallet(addr, label) {
+  if (addr && addr.toLowerCase() === FORBIDDEN_BUILDER.toLowerCase()) {
+    throw new Error('Refusing to trade/farm ' + label + ' ' + FORBIDDEN_BUILDER + ' — builder fee sink only, never a trading wallet');
+  }
+}
+
 export function status() {
   const { actions, signer } = loadShipped();
   const st = signer.selfTest();
+  const hasPlace = Boolean(placePk());
+  const hasMaster = Boolean(masterPk());
   return {
     net: net(),
     mainnetPlacementEnabled: actions.MAINNET_PLACEMENT_ENABLED,
@@ -18,54 +35,185 @@ export function status() {
     feeModel: '1bp on fills only — no subscription',
     signerReady: st.ok, signerError: st.ok ? null : st.error,
     hasAgentKey: Boolean(process.env.HYPELENS_AGENT_PK),
+    hasMasterKey: hasMaster,
+    hasPlaceKey: hasPlace,
     fullFeedConfigured: fullFeedConfigured(),
     first_success: 'mainnet place',
-    nextTool: Boolean(process.env.HYPELENS_AGENT_PK) ? 'hl_approve_payloads' : 'hl_new_agent_wallet',
-    next: Boolean(process.env.HYPELENS_AGENT_PK)
-      ? 'hl_approve_payloads(agentAddress) then hl_balances — do not stop'
+    nextTool: hasPlace ? 'hl_approve_payloads' : 'hl_new_agent_wallet',
+    next: hasPlace
+      ? (hasMaster
+        ? 'hl_approve_payloads(agentAddress) — master key present: auto ApproveBuilderFee then hl_balances'
+        : 'hl_approve_payloads(agentAddress) then hl_balances — do not skip ApproveBuilderFee')
       : 'hl_new_agent_wallet',
-    note: 'Call exactly ONE nextTool. Heat blocked until after first place.'
+    note: 'Call exactly ONE nextTool. Heat blocked until after first place. Place only on explicit trade intent.'
   };
 }
 
-const MISSING_PK = 'approve missing — hl_new_agent_wallet → export HYPELENS_AGENT_PK → hl_approve_payloads → hl_balances → hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) (mainnet)';
+const MISSING_PK = 'approve missing — hl_new_agent_wallet → export HYPELENS_AGENT_PK (or HYPERLIQUID_PRIVATE_KEY) → hl_approve_payloads → hl_balances → hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2}) (mainnet)';
 
 function assertPlacementAllowed(actions) {
   if (net() === 'mainnet' && !actions.MAINNET_PLACEMENT_ENABLED) {
     throw new Error('wrong net — MAINNET_PLACEMENT_ENABLED false; set HYPELENS_NET=mainnet with placement enabled, or HYPELENS_NET=testnet to practice');
   }
-  if (!process.env.HYPELENS_AGENT_PK) throw new Error(MISSING_PK);
+  if (!placePk()) throw new Error(MISSING_PK);
 }
 
 function agentAddress() {
   const { signer } = loadShipped();
-  if (!process.env.HYPELENS_AGENT_PK) throw new Error(MISSING_PK);
-  return signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK);
+  if (!placePk()) throw new Error(MISSING_PK);
+  const addr = signer.addressFromPrivateKey(placePk());
+  assertNotBuilderWallet(addr, 'agent');
+  return addr;
 }
 
-export function approvePayloads(agentAddressArg) {
+/** Account that must have ApproveBuilderFee (master when set, else place wallet). */
+function feeAccountAddress() {
+  const { signer } = loadShipped();
+  const explicit = process.env.HYPERLIQUID_ACCOUNT_ADDRESS || process.env.HYPELENS_MASTER_ADDRESS || '';
+  if (explicit && /^0x[0-9a-fA-F]{40}$/.test(explicit)) {
+    assertNotBuilderWallet(explicit, 'account');
+    return explicit;
+  }
+  if (masterPk()) {
+    const a = signer.addressFromPrivateKey(masterPk());
+    assertNotBuilderWallet(a, 'master');
+    return a;
+  }
+  return agentAddress();
+}
+
+/** HL info maxBuilderFee — tenths of a bp. Need >= BUILDER_F (10) for 1bp attach. */
+export async function checkMaxBuilderFee({ user } = {}) {
   const { actions } = loadShipped();
+  const u = user || feeAccountAddress();
+  const r = await fetch(actions.NET[net()].info, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'maxBuilderFee', user: u, builder: actions.BUILDER })
+  });
+  if (!r.ok) throw new Error('maxBuilderFee HTTP ' + r.status);
+  const raw = await r.json();
+  const maxTenthsBp = Number(raw);
+  const required = actions.BUILDER_F;
+  const approved = Number.isFinite(maxTenthsBp) && maxTenthsBp >= required;
+  return {
+    user: u,
+    builder: actions.BUILDER,
+    maxBuilderFeeTenthsBp: maxTenthsBp,
+    requiredTenthsBp: required,
+    maxFeeRate: actions.MAX_BUILDER_FEE_RATE,
+    approved,
+    net: net()
+  };
+}
+
+async function postUserSigned(built, privateKey) {
+  const { actions, signer } = loadShipped();
+  assertNotBuilderWallet(signer.addressFromPrivateKey(privateKey), 'signer');
+  const signed = await signer.signUserSigned(privateKey, built.action);
+  const res = await fetch(actions.NET[net()].exchange, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: signed.action, signature: signed.signature, nonce: signed.nonce })
+  });
+  const body = await res.json().catch(() => ({}));
+  const ok = res.ok && body && body.status === 'ok';
+  return { ok, net: net(), response: body, error: ok ? null : (typeof body.response === 'string' ? body.response : JSON.stringify(body)) };
+}
+
+/**
+ * OpenBroker pattern: if master/sole key present, sign+POST ApproveBuilderFee (and approveAgent when agent differs).
+ * If only agent key: return clear unsigned payloads + maxBuilderFee status — never silent $0.
+ */
+export async function approvePayloads(agentAddressArg) {
+  const { actions, signer } = loadShipped();
+  if (!actions.isAddr(agentAddressArg)) throw new Error('bad agentAddress');
+  assertNotBuilderWallet(agentAddressArg, 'agent');
   const exchange = actions.NET[net()].exchange;
   const nextPlace = { coin: 'BTC', isBuy: true, sizeUsd: 12, leverage: 2 };
+  const approveAgent = actions.buildApproveAgent(net(), agentAddressArg);
+  const approveBuilderFee = actions.buildApproveBuilderFee(net());
+  const mk = masterPk();
+  let auto = null;
+  let maxCheck = null;
+  try {
+    maxCheck = await checkMaxBuilderFee({ user: feeAccountAddress() });
+  } catch (e) {
+    maxCheck = { error: String(e && e.message ? e.message : e), approved: false };
+  }
+
+  if (mk) {
+    const masterAddr = signer.addressFromPrivateKey(mk);
+    assertNotBuilderWallet(masterAddr, 'master');
+    const results = { master: masterAddr, approveBuilderFee: null, approveAgent: null };
+    // Always (re)approve builder fee once when master key available
+    results.approveBuilderFee = await postUserSigned(approveBuilderFee, mk);
+    // approveAgent only when agent is a distinct API wallet
+    if (masterAddr.toLowerCase() !== agentAddressArg.toLowerCase()) {
+      results.approveAgent = await postUserSigned(approveAgent, mk);
+    } else {
+      results.approveAgent = { ok: true, skipped: true, reason: 'agent_is_master_fresh_wallet' };
+    }
+    auto = results;
+    try { maxCheck = await checkMaxBuilderFee({ user: masterAddr }); } catch (_) { /* keep prior */ }
+    const autoOk = Boolean(results.approveBuilderFee && results.approveBuilderFee.ok);
+    return {
+      net: net(),
+      mode: 'auto_master',
+      autoApproved: autoOk,
+      auto,
+      maxBuilderFee: maxCheck,
+      approveAgent,
+      approveBuilderFee,
+      builder: actions.BUILDER,
+      maxFeeRate: actions.MAX_BUILDER_FEE_RATE,
+      fee: '1bp on fills (no sub)',
+      blocker: autoOk ? null : 'auto_approve_failed',
+      mustApproveBuilderFee: true,
+      funnel_step: autoOk ? 3 : 2,
+      steps: autoOk
+        ? ['MASTER auto ApproveBuilderFee POSTed', 'Call ONLY hl_balances', 'If equity=0: deposit USDC', 'When equity>0 + user trade intent: hl_place_order sizeUsd:12']
+        : ['Auto ApproveBuilderFee failed — inspect auto.approveBuilderFee.error', 'Retry hl_approve_payloads or MASTER-sign payloads below', 'Then hl_balances → place on intent'],
+      nextTool: 'hl_balances',
+      next: autoOk
+        ? 'ApproveBuilderFee auto-POSTed → hl_balances. If equity=0 show fundHow; when funded + user trade intent → hl_place_order.'
+        : 'Auto approve failed — fix master key / net, retry hl_approve_payloads. Skipping ApproveBuilderFee = $0 fees.',
+      nextCalls: ['hl_balances'],
+      nextPlace,
+      fundAfterApprove: {
+        depositAddress: agentAddressArg,
+        asset: 'USDC',
+        app: net() === 'testnet' ? 'https://app.hyperliquid-testnet.xyz' : 'https://app.hyperliquid.xyz',
+        minUsdSuggest: 15
+      },
+      note: 'OpenBroker: master key auto ApproveBuilderFee. Agent key places. Never trade ' + FORBIDDEN_BUILDER
+    };
+  }
+
+  // Agent-only: refuse silent $0 — clear payload + maxBuilderFee gate
   return {
     net: net(),
-    approveAgent: actions.buildApproveAgent(net(), agentAddressArg),
-    approveBuilderFee: actions.buildApproveBuilderFee(net()),
+    mode: 'agent_only_manual_master',
+    autoApproved: false,
+    maxBuilderFee: maxCheck,
+    approveAgent,
+    approveBuilderFee,
     builder: actions.BUILDER,
     maxFeeRate: actions.MAX_BUILDER_FEE_RATE,
     fee: '1bp on fills (no sub)',
-    blocker: 'master_must_sign_and_post_both',
+    blocker: (maxCheck && maxCheck.approved) ? null : 'master_must_sign_and_post_ApproveBuilderFee',
     mustApproveBuilderFee: true,
-    funnel_step: 3,
+    refusePlaceUntilApproved: !(maxCheck && maxCheck.approved),
+    funnel_step: 2,
     steps: [
-      'MASTER signs approveAgent + ApproveBuilderFee (EIP-712) — not agent pk',
+      'MASTER signs approveAgent + ApproveBuilderFee (EIP-712) — not agent pk (set HYPERLIQUID_PRIVATE_KEY / HYPELENS_MASTER_PK to auto)',
       'POST both to ' + exchange,
+      'Verify maxBuilderFee >= 10 tenths-bp for builder ' + actions.BUILDER,
       'Then call ONLY hl_balances',
-      'If equity=0: ask user to deposit USDC to agentAddress on Hyperliquid (app.hyperliquid.xyz), then hl_balances again',
       'When equity>0 and user asked to trade: hl_place_order sizeUsd:12'
     ],
-    nextTool: 'hl_balances',
-    next: 'After MASTER POST both → hl_balances. If equity=0 show depositAddress and ask user to fund USDC, then hl_balances again.',
+    nextTool: (maxCheck && maxCheck.approved) ? 'hl_balances' : 'hl_approve_payloads',
+    next: (maxCheck && maxCheck.approved)
+      ? 'Builder fee already approved on-chain → hl_balances → place on user trading intent'
+      : 'MASTER must POST ApproveBuilderFee (or export HYPERLIQUID_PRIVATE_KEY and re-call). Place with builder is REFUSED until maxBuilderFee>=10 — no silent $0.',
     nextCalls: ['hl_balances'],
     nextPlace,
     fundAfterApprove: {
@@ -74,20 +222,22 @@ export function approvePayloads(agentAddressArg) {
       app: net() === 'testnet' ? 'https://app.hyperliquid-testnet.xyz' : 'https://app.hyperliquid.xyz',
       minUsdSuggest: 15
     },
-    note: 'Skipping ApproveBuilderFee = $0 fees. After POST: hl_balances → fund if equity=0 → place on ' + net() + ' only with user trading intent.'
+    note: 'Skipping ApproveBuilderFee = $0 fees. Agent-only mode cannot auto-approve. After POST: hl_balances → fund if equity=0 → place on ' + net() + ' only with user trading intent.'
   };
 }
 
 export function newAgentWallet() {
   const { signer, sdk } = loadShipped();
   const pk = sdk.randomPrivateKey();
+  const address = signer.addressFromPrivateKey(pk);
+  assertNotBuilderWallet(address, 'agent');
   return {
     privateKey: pk,
-    address: signer.addressFromPrivateKey(pk),
+    address,
     funnel_step: 2,
     nextTool: 'hl_approve_payloads',
-    next: 'export HYPELENS_AGENT_PK=<privateKey>; call hl_approve_payloads(address) ONLY — do not stop',
-    note: 'Do not call heat tools. Next ONE tool = hl_approve_payloads.'
+    next: 'export HYPELENS_AGENT_PK=<privateKey>; optional export HYPERLIQUID_PRIVATE_KEY=<master> for auto ApproveBuilderFee; call hl_approve_payloads(address) — when user wants to trade',
+    note: 'Do not call heat tools. Next ONE tool = hl_approve_payloads. OpenBroker: master key auto-approves builder fee.'
   };
 }
 
@@ -123,23 +273,39 @@ async function assetMetaAndMark(coin) {
 
 /**
  * Resolve coin size + entryPx. Preferred first-place path: sizeUsd only
- * (fetches mark, size = sizeUsd/mark, rounds to szDecimals). Explicit size+entryPx still works.
+ * (fetches mark, size = sizeUsd/mark, rounds to szDecimals, IOC ~0.5% slip).
+ * Explicit entryPx = GTC limit intent (no slip).
+ * @param {{coin, size, entryPx, sizeUsd, isBuy}} opts
  */
-async function resolveSizeAndPx({ coin, size, entryPx, sizeUsd }) {
+async function resolveSizeAndPx({ coin, size, entryPx, sizeUsd, isBuy = true }) {
   const { actions } = loadShipped();
-  const needMark = entryPx == null || (size == null && sizeUsd != null);
+  const limitIntent = entryPx != null;
+  const needMark = !limitIntent || (size == null && sizeUsd != null);
   const meta = needMark ? await assetMetaAndMark(coin) : await assetMeta(coin);
-  let px = entryPx != null ? Number(entryPx) : meta.markPx;
+  let markPx = meta.markPx ?? null;
+  let px;
+  let tif;
+  if (limitIntent) {
+    px = Number(entryPx);
+    tif = 'Gtc';
+  } else {
+    // Market/IOC path: same 0.5% slip through mark as closePosition
+    if (!(markPx > 0)) throw new Error('entryPx required (or omit and pass sizeUsd for auto mark)');
+    px = isBuy ? markPx * 1.005 : markPx * 0.995;
+    tif = 'Ioc';
+  }
   if (!(px > 0)) throw new Error('entryPx required (or omit and pass sizeUsd for auto mark)');
   let sz = size != null ? Number(size) : null;
   let usedSizeUsd = sizeUsd != null ? Number(sizeUsd) : null;
+  // Size from notional uses mark (true market size), not slipped px
+  const sizePx = (!limitIntent && markPx > 0) ? markPx : px;
   if (sz == null) {
     if (!(usedSizeUsd > 0)) {
-      throw new Error('size or sizeUsd required — first place: {coin:"BTC", isBuy:true, sizeUsd:12, leverage:2} (auto mark + szDecimals round; entryPx optional)');
+      throw new Error('size or sizeUsd required — first place: {coin:"BTC", isBuy:true, sizeUsd:12, leverage:2} (IOC @ mark+0.5% slip; pass entryPx for GTC limit)');
     }
-    sz = usedSizeUsd / px;
+    sz = usedSizeUsd / sizePx;
   } else if (usedSizeUsd == null) {
-    usedSizeUsd = sz * px;
+    usedSizeUsd = sz * sizePx;
   }
   sz = actions.roundToDecimals(sz, meta.szDecimals);
   // Validate wire size will not collapse to 0
@@ -154,8 +320,10 @@ async function resolveSizeAndPx({ coin, size, entryPx, sizeUsd }) {
     size: sz,
     entryPx: px,
     sizeUsd: usedSizeUsd,
-    markPx: meta.markPx ?? null,
-    autoRounded: size == null || entryPx == null
+    markPx,
+    tif,
+    limitIntent,
+    autoRounded: size == null || !limitIntent
   };
 }
 
@@ -202,7 +370,7 @@ async function postL1(action) {
   const { actions, signer } = loadShipped();
   assertPlacementAllowed(actions);
   const nonce = actions.nonce();
-  const signed = await signer.signL1(process.env.HYPELENS_AGENT_PK, action, nonce, net() === 'testnet', null);
+  const signed = await signer.signL1(placePk(), action, nonce, net() === 'testnet', null);
   const res = await fetch(actions.NET[net()].exchange, {
     method: 'POST', headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ action: signed.action, signature: signed.signature, nonce: signed.nonce })
@@ -300,14 +468,54 @@ export async function getPositions({ user, coin } = {}) {
     next: positions.length
       ? 'optional hl_close_position / hl_cancel_order — or another ' + placeCall
       : 'no positions yet — call hl_balances then ' + placeCall + ' (do not open heat tools)',
-    note: 'Paying path = mainnet place. Do not stop.'
+    note: 'Paying path = mainnet place on explicit user trading intent.'
   };
 }
 
-export async function placeOrder({ coin, isBuy, size = null, entryPx = null, sizeUsd = null, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false }) {
+export async function placeOrder({ coin, isBuy, size = null, entryPx = null, sizeUsd = null, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false, confirmTrade = false, intent = null, skipBuilderFeeCheck = false }) {
   const { actions } = loadShipped();
   assertPlacementAllowed(actions);
-  const resolved = await resolveSizeAndPx({ coin, size, entryPx, sizeUsd });
+  // Consent: place only on explicit trade intent (skill + confirmTrade/intent)
+  const intentOk = confirmTrade === true || ['trade', 'place', 'execute', 'buy', 'sell'].includes(String(intent || '').toLowerCase());
+  if (!intentOk) {
+    return {
+      placed: false,
+      refused: 'consent_required',
+      error: 'Place requires explicit trade intent — pass confirmTrade:true or intent:"trade"|"place"|"execute" (ClawScan-safe). Do not place unsolicited.',
+      builderFeeAttached: false,
+      next: 'hl_place_order({..., confirmTrade:true}) only after user asked to trade/place/execute'
+    };
+  }
+  // Hard fee gate: refuse place-with-builder until maxBuilderFee approved (no silent $0)
+  let feeGate = { approved: true, skipped: true };
+  if (!skipBuilderFeeCheck && process.env.HYPELENS_TEST_SKIP_FEE_GATE !== '1') {
+    try {
+      feeGate = await checkMaxBuilderFee();
+    } catch (e) {
+      return {
+        placed: false,
+        refused: 'maxBuilderFee_check_failed',
+        error: String(e && e.message ? e.message : e),
+        builderFeeAttached: false,
+        next: 'hl_approve_payloads → MASTER ApproveBuilderFee (or set HYPERLIQUID_PRIVATE_KEY for auto) → retry place'
+      };
+    }
+    if (!feeGate.approved) {
+      const payloads = await approvePayloads(agentAddress());
+      return {
+        placed: false,
+        refused: 'builder_fee_not_approved',
+        error: 'maxBuilderFee=' + feeGate.maxBuilderFeeTenthsBp + ' < required ' + feeGate.requiredTenthsBp + ' — refusing place-with-builder (would be $0 fees). MASTER must ApproveBuilderFee 0.01% for ' + actions.BUILDER,
+        maxBuilderFee: feeGate,
+        approvePayloads: payloads,
+        builderFeeAttached: false,
+        next: masterPk()
+          ? 'hl_approve_payloads(agentAddress) — master key will auto-POST ApproveBuilderFee, then retry place'
+          : 'Export HYPERLIQUID_PRIVATE_KEY / HYPELENS_MASTER_PK and call hl_approve_payloads, OR MASTER-sign approvePayloads.approveBuilderFee and POST — then retry. No silent $0.'
+      };
+    }
+  }
+  const resolved = await resolveSizeAndPx({ coin, size, entryPx, sizeUsd, isBuy });
   let risk = null;
   const lev = leverage != null ? Number(leverage) : null;
   if (!skipRiskCheck && lev) {
@@ -346,7 +554,8 @@ export async function placeOrder({ coin, isBuy, size = null, entryPx = null, siz
     entryPx: resolved.entryPx,
     size: resolved.size,
     slPx,
-    tpPx
+    tpPx,
+    tif: resolved.tif
   });
   const posted = await postL1(action);
   const out = {
@@ -354,11 +563,16 @@ export async function placeOrder({ coin, isBuy, size = null, entryPx = null, siz
     net: posted.net,
     response: posted.response,
     risk,
-    builderFeeAttached: posted.ok,
+    builder: { b: actions.BUILDER.toLowerCase(), f: actions.BUILDER_F },
+    builderFeeAttached: posted.ok && Boolean(action.builder && action.builder.f === actions.BUILDER_F),
+    maxBuilderFee: feeGate,
     coin: resolved.name,
     size: resolved.size,
     entryPx: resolved.entryPx,
     sizeUsd: resolved.sizeUsd,
+    markPx: resolved.markPx,
+    tif: resolved.tif,
+    limitIntent: resolved.limitIntent,
     autoRounded: resolved.autoRounded,
     sizingWarn,
     feeModel: '1bp on fills only — no subscription'
@@ -389,9 +603,19 @@ export async function cancelOrder({ coin, oid = null, cloid = null }) {
 }
 
 /** IOC reduce-only close for a coin (uses position size if size omitted). */
-export async function closePosition({ coin, size = null, px = null, user } = {}) {
+export async function closePosition({ coin, size = null, px = null, user, confirmTrade = false, intent = null, skipBuilderFeeCheck = false } = {}) {
   const { actions } = loadShipped();
   assertPlacementAllowed(actions);
+  const intentOk = confirmTrade === true || ['trade', 'place', 'execute', 'close', 'cancel'].includes(String(intent || '').toLowerCase());
+  if (!intentOk) {
+    return { closed: false, refused: 'consent_required', error: 'Close requires explicit intent — pass confirmTrade:true', builderFeeAttached: false };
+  }
+  if (!skipBuilderFeeCheck && process.env.HYPELENS_TEST_SKIP_FEE_GATE !== '1') {
+    const feeGate = await checkMaxBuilderFee();
+    if (!feeGate.approved) {
+      return { closed: false, refused: 'builder_fee_not_approved', maxBuilderFee: feeGate, builderFeeAttached: false, error: 'ApproveBuilderFee required before close-with-builder' };
+    }
+  }
   const name = resolveCoin(coin).toUpperCase();
   const { positions } = await getPositions({ user, coin: name });
   const pos = positions[0];

package/src/exchange.js.bak-clearerr

@@ -0,0 +1,211 @@
+// HypeLens Agent Rail — EXECUTION (builder-code monetized).
+// Reuses Module 3: hl-actions.js builds actions (builder fee pinned on place/close),
+// hl-signer.js signs through the vendored SDK. Default HYPELENS_NET=testnet.
+// Fee model: 1bp (0.01%) on fills only — no subscription. BUILDER_F=10.
+// Risk/heat advisory when feed missing; danger-wall refuses unless override.
+import { loadShipped } from './load.js';
+import { pretradeCheckFull, fullFeedConfigured, resolveCoin } from './core.js';
+
+const net = () => process.env.HYPELENS_NET || 'testnet';
+
+export function status() {
+  const { actions, signer } = loadShipped();
+  const st = signer.selfTest();
+  return {
+    net: net(),
+    mainnetPlacementEnabled: actions.MAINNET_PLACEMENT_ENABLED,
+    builder: actions.BUILDER, builderFeeTenthsBp: actions.BUILDER_F, maxFeeRate: actions.MAX_BUILDER_FEE_RATE,
+    feeModel: '1bp on fills only — no subscription',
+    signerReady: st.ok, signerError: st.ok ? null : st.error,
+    hasAgentKey: Boolean(process.env.HYPELENS_AGENT_PK),
+    fullFeedConfigured: fullFeedConfigured()
+  };
+}
+
+function assertPlacementAllowed(actions) {
+  if (net() === 'mainnet' && !actions.MAINNET_PLACEMENT_ENABLED) {
+    throw new Error('MAINNET PLACEMENT DISABLED — Set HYPELENS_NET=testnet.');
+  }
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set — run the approve flow first (see approvePayloads)');
+}
+
+function agentAddress() {
+  const { signer } = loadShipped();
+  if (!process.env.HYPELENS_AGENT_PK) throw new Error('HYPELENS_AGENT_PK not set');
+  return signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK);
+}
+
+export function approvePayloads(agentAddressArg) {
+  const { actions } = loadShipped();
+  return {
+    approveAgent: actions.buildApproveAgent(net(), agentAddressArg),
+    approveBuilderFee: actions.buildApproveBuilderFee(net()),
+    note: 'Sign both with the MASTER wallet (EIP-712), POST each as {action, signature, nonce} to ' + actions.NET[net()].exchange
+  };
+}
+
+export function newAgentWallet() {
+  const { signer, sdk } = loadShipped();
+  const pk = sdk.randomPrivateKey();
+  return { privateKey: pk, address: signer.addressFromPrivateKey(pk), note: 'store as HYPELENS_AGENT_PK; approve via approvePayloads(address)' };
+}
+
+async function assetMeta(coin) {
+  const { actions } = loadShipped();
+  const r = await fetch(actions.NET[net()].info, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'meta' })
+  });
+  const meta = await r.json();
+  const name = resolveCoin(coin).toUpperCase();
+  const i = meta.universe.findIndex((u) => u.name === name);
+  if (i < 0) throw new Error('coin not on ' + net() + ': ' + coin);
+  return { assetIndex: i, szDecimals: meta.universe[i].szDecimals, name };
+}
+
+async function postL1(action) {
+  const { actions, signer } = loadShipped();
+  assertPlacementAllowed(actions);
+  const nonce = actions.nonce();
+  const signed = await signer.signL1(process.env.HYPELENS_AGENT_PK, action, nonce, net() === 'testnet', null);
+  const res = await fetch(actions.NET[net()].exchange, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ action: signed.action, signature: signed.signature, nonce: signed.nonce })
+  });
+  const body = await res.json().catch(() => ({}));
+  return { ok: res.ok && body.status === 'ok', net: net(), response: body };
+}
+
+async function clearinghouse(user) {
+  const { actions } = loadShipped();
+  const r = await fetch(actions.NET[net()].info, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ type: 'clearinghouseState', user })
+  });
+  if (!r.ok) throw new Error('clearinghouseState HTTP ' + r.status);
+  return r.json();
+}
+
+/** Balances / margin summary for the agent (or explicit user). */
+export async function getBalances({ user } = {}) {
+  const u = user || agentAddress();
+  const state = await clearinghouse(u);
+  const ms = state.marginSummary || {};
+  const equity = Number(ms.accountValue || 0);
+  return {
+    net: net(),
+    user: u,
+    marginSummary: ms,
+    withdrawable: state.withdrawable ?? null,
+    equity,
+    sizingWarnThresholdUsd: equity * 0.2,
+    sizing_rule: 'Warn if sizeUsd > 20% of account equity; size from balance; confirm mark before place.',
+    feeModel: '1bp on fills only — no subscription'
+  };
+}
+
+/** Open perp positions (assetPositions). */
+export async function getPositions({ user, coin } = {}) {
+  const u = user || agentAddress();
+  const state = await clearinghouse(u);
+  let positions = (state.assetPositions || []).map((ap) => {
+    const p = ap.position || ap;
+    return {
+      coin: p.coin,
+      szi: Number(p.szi || 0),
+      entryPx: p.entryPx != null ? Number(p.entryPx) : null,
+      positionValue: p.positionValue != null ? Number(p.positionValue) : null,
+      unrealizedPnl: p.unrealizedPnl != null ? Number(p.unrealizedPnl) : null,
+      leverage: p.leverage || null,
+      liquidationPx: p.liquidationPx != null ? Number(p.liquidationPx) : null,
+      marginUsed: p.marginUsed != null ? Number(p.marginUsed) : null
+    };
+  }).filter((p) => p.szi !== 0);
+  if (coin) {
+    const c = resolveCoin(coin).toUpperCase();
+    positions = positions.filter((p) => (p.coin || '').toUpperCase() === c);
+  }
+  return { net: net(), user: u, positions };
+}
+
+export async function placeOrder({ coin, isBuy, size, entryPx, slPx = null, tpPx = null, leverage = null, override = false, skipRiskCheck = false }) {
+  const { actions } = loadShipped();
+  assertPlacementAllowed(actions);
+  let risk = null;
+  if (!skipRiskCheck && leverage) {
+    risk = await pretradeCheckFull({ coin, dir: isBuy ? 'long' : 'short', leverage, entryPx });
+    if (risk.refuseReason === 'full_feed_unconfigured') {
+      risk = { ...risk, advisory: true, feedAdvisory: true, note: (risk.note || '') + ' Place allowed without full feed; heat is advisory.' };
+    }
+    if (risk.verdict === 'danger' && risk.refuseReason !== 'full_feed_unconfigured' && !override) {
+      const wallSz = risk.wall && risk.wall.sizeUsd != null
+        ? Math.round(risk.wall.sizeUsd / 1e6)
+        : (risk.wall && risk.wall.sizeUsdCoarse != null ? Math.round(risk.wall.sizeUsdCoarse / 1e6) : '?');
+      return {
+        placed: false,
+        refused: 'liq price ' + risk.liqPx + ' lands inside a $' + wallSz + 'M wall — pass override:true to force',
+        risk,
+        builderFeeAttached: false
+      };
+    }
+  }
+  const { assetIndex, szDecimals } = await assetMeta(coin);
+  const action = actions.buildOrderAction({ assetIndex, szDecimals, isBuy, entryPx, size, slPx, tpPx });
+  const posted = await postL1(action);
+  return { placed: posted.ok, net: posted.net, response: posted.response, risk, builderFeeAttached: posted.ok };
+}
+
+/** Cancel by oid and/or cloid. */
+export async function cancelOrder({ coin, oid = null, cloid = null }) {
+  const { actions } = loadShipped();
+  assertPlacementAllowed(actions);
+  const { assetIndex } = await assetMeta(coin);
+  let action;
+  if (cloid) action = actions.buildCancelByCloidAction([{ assetIndex, cloid }]);
+  else if (oid != null) action = actions.buildCancelAction([{ assetIndex, oid: Number(oid) }]);
+  else throw new Error('oid or cloid required');
+  const posted = await postL1(action);
+  return { cancelled: posted.ok, net: posted.net, response: posted.response, coin: resolveCoin(coin).toUpperCase(), oid, cloid };
+}
+
+/** IOC reduce-only close for a coin (uses position size if size omitted). */
+export async function closePosition({ coin, size = null, px = null, user } = {}) {
+  const { actions } = loadShipped();
+  assertPlacementAllowed(actions);
+  const name = resolveCoin(coin).toUpperCase();
+  const { positions } = await getPositions({ user, coin: name });
+  const pos = positions[0];
+  if (!pos || !pos.szi) throw new Error('no open position for ' + name);
+  const absSz = Math.abs(pos.szi);
+  const closeSz = size != null ? Number(size) : absSz;
+  if (!(closeSz > 0) || closeSz > absSz + 1e-12) throw new Error('bad close size');
+  const isBuy = pos.szi < 0; // short -> buy to close
+  let entryPx = px;
+  if (entryPx == null) {
+    const { actions: a2 } = loadShipped();
+    const r = await fetch(a2.NET[net()].info, {
+      method: 'POST', headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ type: 'metaAndAssetCtxs' })
+    });
+    const [meta, ctxs] = await r.json();
+    const i = meta.universe.findIndex((u) => u.name === name);
+    if (i < 0) throw new Error('coin not in meta: ' + name);
+    entryPx = Number(ctxs[i].markPx);
+    // slip 0.5% through for IOC fill
+    entryPx = isBuy ? entryPx * 1.005 : entryPx * 0.995;
+  }
+  const { assetIndex, szDecimals } = await assetMeta(name);
+  const action = actions.buildCloseAction({ assetIndex, szDecimals, isBuy, entryPx, size: closeSz });
+  const posted = await postL1(action);
+  return {
+    closed: posted.ok,
+    net: posted.net,
+    response: posted.response,
+    coin: name,
+    size: closeSz,
+    isBuy,
+    entryPx,
+    builderFeeAttached: posted.ok,
+    feeModel: '1bp on fills only — no subscription'
+  };
+}

package/src/index.js

@@ -1,2 +1,2 @@
 export { walls, cascade, pretradeCheck, whaleBook, getFeed, getMeta, binWalls, resolveCoin, quickstart } from './core.js';
-export { status as exchangeStatus, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition } from './exchange.js';
+export { status as exchangeStatus, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition, checkMaxBuilderFee } from './exchange.js';