@hypelens/hypelens-agent-rail 0.1.21 → 0.1.23

package/README.md

@@ -1,37 +1,51 @@
 # @hypelens/hypelens-agent-rail
-**Place, cancel, close Hyperliquid perps.** Agent wallet once · auto-round · **1bp on fills — no sub.**
-## Install → approve → place
-```bash
-# MCP stdio (Claude / Cursor / any MCP host)
-npx @hypelens/hypelens-agent-rail@0.1.21
 
-# Claude Code one-liner
-claude mcp add hypelens -- npx @hypelens/hypelens-agent-rail@0.1.21
+Outside-agent Hyperliquid **place** rail. Builder fees → `0x9548B8E9554a1968843B3C380431b10996247c88` at **1bp** (`f=10`) on fills. **Never** trade/farm that wallet.
 
-# OpenClaw / ClawHub skill (skill slug, not npm alone)
-clawhub install hypelens-agent-rail
-# skills.sh (needs public GH; polyparlay anon currently 404)
-npx skills add polyparlay/hypelens -s hypelens-agent-rail -y
-```
-1. `hl_quickstart` (optional) → `hl_new_agent_wallet` → `HYPELENS_AGENT_PK`
-2. `hl_approve_payloads(agentAddress)` — **MASTER** signs approveAgent + ApproveBuilderFee **0.01%** once, then POST both
-3. `hl_balances` — if `equity=0`, ask user to deposit **USDC** to `fundHow.depositAddress` on [app.hyperliquid.xyz](https://app.hyperliquid.xyz) (~$15+), then recheck
-4. `hl_place_order` / `hl_cancel_order` / `hl_close_position` / `hl_positions` — place only when the user asks to trade
+## Fee capture (OpenBroker pattern)
+
+1. Every `hl_place_order` / close **always** attaches `builder: { b: 0x9548…, f: 10 }`.
+2. **Setup / `hl_approve_payloads`:**
+   - If `HYPERLIQUID_PRIVATE_KEY` or `HYPELENS_MASTER_PK` is set → **auto sign+POST** `ApproveBuilderFee` (and `approveAgent` when agent ≠ master).
+   - If only agent key (`HYPELENS_AGENT_PK`) → return clear unsigned approve payloads + `maxBuilderFee` status; **refuse place-with-builder** until `maxBuilderFee >= 10` (no silent $0).
+3. **Consent:** `hl_place_order` requires `confirmTrade: true` or `intent: "trade"|"place"|"execute"`.
+
+## Post-install (REQUIRED — downloads ≠ fees)
 
-**First place (mainnet default):** after approve, `hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2})` — **sizeUsd alone** = **IOC / market** at mark ± ~0.5% slip (same pattern as close) so fills land and builder fees accrue. Pass explicit `entryPx` only for a **GTC limit**. No feed required. On reject after sizeUsd, response includes `error` + `next` (margin / approve / min notional).
+```bash
+cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
+# or: npx -y @hypelens/hypelens-agent-rail@0.1.23 hypelens-setup
+```
 
-Default **mainnet**. Practice: `HYPELENS_NET=testnet`. Fee: **1bp on fills** — no sub. Missing `HYPELENS_AGENT_PK` errors point at the same path.
+`setup.mjs` / `hypelens-setup`:
+1. Registers MCP in OpenClaw/Claude/Cursor config when possible
+2. Auto `ApproveBuilderFee` when `HYPERLIQUID_PRIVATE_KEY` / `HYPELENS_MASTER_PK` present
+3. Prints `maxBuilderFee` — place stays refused until approved (no silent $0)
+4. Next: fund agent if equity=0 → place on explicit trade intent
 
-## Optional after install: sizing edge
+## Quick path
 
-`hl_walls` / `hl_whale_book` / `hl_cascade` / `hl_pretrade_check` — live liq heat to improve size/entry. Missing feed is **advisory** (does not block place).
+```bash
+npx -y @hypelens/hypelens-agent-rail@0.1.23
+# or sticky ClawHub:
+clawhub install hyperliquid-place
+cd skills/hyperliquid-place/scripts && npm install && node start-mcp.mjs
+```
 
-**Sizing rule:** warn if `sizeUsd` > 20% of account equity; size from balance; confirm mark before place.
+Env:
 
-## Tools
+| Var | Role |
+| --- | --- |
+| `HYPELENS_AGENT_PK` | Agent key for places |
+| `HYPERLIQUID_PRIVATE_KEY` / `HYPELENS_MASTER_PK` | Master — auto ApproveBuilderFee |
+| `HYPERLIQUID_ACCOUNT_ADDRESS` | Master address when using API wallet |
+| `HYPELENS_NET` | `mainnet` (default) or `testnet` |
 
-Place path: `hl_quickstart`, `hl_exchange_status`, `hl_new_agent_wallet`, `hl_approve_payloads`, `hl_place_order`, `hl_cancel_order`, `hl_close_position`, `hl_balances`, `hl_positions`.
+## Funnel
 
-Optional edge: `hl_walls`, `hl_cascade`, `hl_pretrade_check`, `hl_whale_book`.
+1. `hl_quickstart` / `hl_new_agent_wallet`
+2. `hl_approve_payloads(agentAddress)` — auto if master key; else MASTER signs ApproveBuilderFee **0.01%**
+3. `hl_balances` (+ fundHow if equity=0)
+4. On explicit trade intent: `hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2, confirmTrade:true})`
 
-MIT. [HypeLens](https://github.com/polyparlay/hypelens).
+Skipping ApproveBuilderFee = **$0 fees**. Place is hard-refused until on-chain `maxBuilderFee` covers 1bp.

package/bin/hypelens-setup.js

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * OpenBroker-style post-install one-shot:
+ * 1) Wire MCP into host config (OpenClaw / Claude / Cursor) when possible
+ * 2) Ensure agent key (generate if missing)
+ * 3) Auto ApproveBuilderFee when HYPERLIQUID_PRIVATE_KEY / HYPELENS_MASTER_PK present
+ * 4) Print maxBuilderFee + fund + place next (never silent $0)
+ * NEVER trades/farms 0x9548…
+ */
+import { writeFileSync, readFileSync, existsSync, mkdirSync, chmodSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const FORBIDDEN = '0x9548B8E9554a1968843B3C380431b10996247c88';
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+function loadRail() {
+  process.env.HYPELENS_QUIET = '1';
+  return import(pathToFileURL(join(ROOT, 'src', 'index.js')).href);
+}
+
+function expand(p) {
+  return p.replace(/^~(?=\/|$)/, homedir());
+}
+
+/** Candidate MCP host config files (best-effort; never overwrite unrelated keys). */
+function hostConfigPaths() {
+  const h = homedir();
+  return [
+    { kind: 'openclaw', path: join(h, '.openclaw', 'openclaw.json') },
+    { kind: 'openclaw', path: join(h, '.openclaw', 'config.json') },
+    { kind: 'openclaw', path: join(h, '.openclaw', 'mcp.json') },
+    { kind: 'claude', path: join(h, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json') },
+    { kind: 'claude', path: join(h, '.config', 'Claude', 'claude_desktop_config.json') },
+    { kind: 'cursor', path: join(h, '.cursor', 'mcp.json') },
+  ];
+}
+
+function mcpServerEntry(scriptsDir) {
+  const start = scriptsDir ? join(scriptsDir, 'start-mcp.mjs') : null;
+  if (start && existsSync(start)) {
+    return {
+      command: 'node',
+      args: [start],
+      env: {
+        HYPELENS_NET: process.env.HYPELENS_NET || 'mainnet',
+        ...(process.env.HYPELENS_AGENT_PK ? { HYPELENS_AGENT_PK: process.env.HYPELENS_AGENT_PK } : {}),
+        ...(process.env.HYPERLIQUID_PRIVATE_KEY ? { HYPERLIQUID_PRIVATE_KEY: process.env.HYPERLIQUID_PRIVATE_KEY } : {}),
+        ...(process.env.HYPELENS_MASTER_PK ? { HYPELENS_MASTER_PK: process.env.HYPELENS_MASTER_PK } : {}),
+        ...(process.env.HYPERLIQUID_ACCOUNT_ADDRESS ? { HYPERLIQUID_ACCOUNT_ADDRESS: process.env.HYPERLIQUID_ACCOUNT_ADDRESS } : {}),
+      },
+    };
+  }
+  return {
+    command: 'npx',
+    args: ['-y', '@hypelens/hypelens-agent-rail@0.1.23'],
+    env: {
+      HYPELENS_NET: process.env.HYPELENS_NET || 'mainnet',
+      ...(process.env.HYPELENS_AGENT_PK ? { HYPELENS_AGENT_PK: process.env.HYPELENS_AGENT_PK } : {}),
+      ...(process.env.HYPERLIQUID_PRIVATE_KEY ? { HYPERLIQUID_PRIVATE_KEY: process.env.HYPERLIQUID_PRIVATE_KEY } : {}),
+      ...(process.env.HYPELENS_MASTER_PK ? { HYPELENS_MASTER_PK: process.env.HYPELENS_MASTER_PK } : {}),
+    },
+  };
+}
+
+function wireMcp({ scriptsDir, name = 'hyperliquid-place' } = {}) {
+  const entry = mcpServerEntry(scriptsDir);
+  const wired = [];
+  const suggested = { mcpServers: { [name]: entry } };
+  for (const host of hostConfigPaths()) {
+    try {
+      const dir = dirname(host.path);
+      if (!existsSync(dir) && host.kind === 'openclaw') {
+        mkdirSync(dir, { recursive: true });
+      }
+      if (!existsSync(dirname(host.path))) continue;
+      let cfg = {};
+      if (existsSync(host.path)) {
+        cfg = JSON.parse(readFileSync(host.path, 'utf8'));
+      } else if (host.kind !== 'openclaw') {
+        // only auto-create openclaw configs; for others print snippet
+        continue;
+      }
+      if (!cfg.mcpServers || typeof cfg.mcpServers !== 'object') cfg.mcpServers = {};
+      cfg.mcpServers[name] = entry;
+      writeFileSync(host.path, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+      try { chmodSync(host.path, 0o600); } catch (_) {}
+      wired.push({ kind: host.kind, path: host.path });
+    } catch (e) {
+      wired.push({ kind: host.kind, path: host.path, error: String(e && e.message ? e.message : e) });
+    }
+  }
+  return { wired, suggested, entry };
+}
+
+async function runApprove() {
+  const rail = await loadRail();
+  const { newAgentWallet, approvePayloads, checkMaxBuilderFee, exchangeStatus } = rail;
+  const status = exchangeStatus();
+  let agentPk = process.env.HYPELENS_AGENT_PK || '';
+  let agentAddress = null;
+  let generated = null;
+  if (!agentPk && process.env.HYPERLIQUID_PRIVATE_KEY) {
+    // Fresh-wallet OpenBroker: sole key places + can auto-approve
+    agentPk = process.env.HYPERLIQUID_PRIVATE_KEY;
+    process.env.HYPELENS_AGENT_PK = agentPk;
+  }
+  if (!agentPk) {
+    generated = newAgentWallet();
+    agentPk = generated.privateKey;
+    agentAddress = generated.address;
+    process.env.HYPELENS_AGENT_PK = agentPk;
+  } else {
+    const { loadShipped } = await import(pathToFileURL(join(ROOT, 'src', 'load.js')).href);
+    const { signer } = loadShipped();
+    agentAddress = signer.addressFromPrivateKey(agentPk);
+  }
+  if (agentAddress && agentAddress.toLowerCase() === FORBIDDEN.toLowerCase()) {
+    throw new Error('Refusing setup for builder sink wallet ' + FORBIDDEN);
+  }
+  const approve = await approvePayloads(agentAddress);
+  let fee = null;
+  try { fee = await checkMaxBuilderFee({ user: agentAddress }); } catch (e) {
+    fee = { error: String(e && e.message ? e.message : e), approved: false };
+  }
+  return { status, generated, agentAddress, approve, maxBuilderFee: fee };
+}
+
+function parseArgs(argv) {
+  const out = { scriptsDir: null, writeEnv: null, json: false };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--json') out.json = true;
+    else if (a === '--scripts-dir' && argv[i + 1]) out.scriptsDir = expand(argv[++i]);
+    else if (a === '--write-env' && argv[i + 1]) out.writeEnv = expand(argv[++i]);
+  }
+  // default scripts dir = cwd if start-mcp.mjs present
+  if (!out.scriptsDir && existsSync(join(process.cwd(), 'start-mcp.mjs'))) out.scriptsDir = process.cwd();
+  return out;
+}
+
+async function main() {
+  const args = parseArgs(process.argv);
+  const mcp = wireMcp({ scriptsDir: args.scriptsDir });
+  const feePath = await runApprove();
+  if (args.writeEnv && feePath.generated) {
+    const lines = [
+      `# hypelens setup ${new Date().toISOString()}`,
+      `HYPELENS_NET=${process.env.HYPELENS_NET || 'mainnet'}`,
+      `HYPELENS_AGENT_PK=${feePath.generated.privateKey}`,
+      process.env.HYPERLIQUID_PRIVATE_KEY ? `HYPERLIQUID_PRIVATE_KEY=${process.env.HYPERLIQUID_PRIVATE_KEY}` : '# export HYPERLIQUID_PRIVATE_KEY=<master> for auto ApproveBuilderFee',
+      '',
+    ];
+    writeFileSync(args.writeEnv, lines.join('\n'), { mode: 0o600 });
+    try { chmodSync(args.writeEnv, 0o600); } catch (_) {}
+  }
+  const approved = Boolean(feePath.maxBuilderFee && feePath.maxBuilderFee.approved) || Boolean(feePath.approve && feePath.approve.autoApproved);
+  const report = {
+    ok: true,
+    package: '@hypelens/hypelens-agent-rail',
+    builder: FORBIDDEN,
+    builderFee: '1bp (f=10) — never trade builder wallet',
+    mcpWired: mcp.wired.filter((w) => !w.error),
+    mcpWireErrors: mcp.wired.filter((w) => w.error),
+    mcpSuggested: mcp.suggested,
+    agentAddress: feePath.agentAddress,
+    generatedAgent: Boolean(feePath.generated),
+    generatedPrivateKey: feePath.generated ? feePath.generated.privateKey : undefined,
+    approveMode: feePath.approve && feePath.approve.mode,
+    autoApproved: Boolean(feePath.approve && feePath.approve.autoApproved),
+    maxBuilderFee: feePath.maxBuilderFee,
+    placeAllowed: approved,
+    next: !approved
+      ? 'Export HYPERLIQUID_PRIVATE_KEY=<master> and re-run setup (auto ApproveBuilderFee), OR MASTER-sign approve payloads. Place is REFUSED until maxBuilderFee>=10 — no silent $0.'
+      : 'Restart MCP host. hl_balances — if equity=0 deposit USDC to agentAddress. On explicit trade intent: hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2, confirmTrade:true})',
+    funnel: ['mcp_wired', 'approve_builder_fee', 'fund_if_needed', 'place_on_intent'],
+  };
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log('HypeLens setup (OpenBroker)');
+    console.log('- MCP wired:', report.mcpWired.length ? report.mcpWired.map((w) => w.path).join(', ') : '(none — paste mcpSuggested into host config)');
+    if (report.mcpWireErrors.length) console.log('- MCP wire errors:', report.mcpWireErrors);
+    console.log('- Agent:', report.agentAddress);
+    if (report.generatedAgent) {
+      console.log('- Generated HYPELENS_AGENT_PK (store securely):', report.generatedPrivateKey);
+    }
+    console.log('- Approve mode:', report.approveMode, '| autoApproved:', report.autoApproved);
+    console.log('- maxBuilderFee:', JSON.stringify(report.maxBuilderFee));
+    console.log('- placeAllowed:', report.placeAllowed);
+    console.log('- NEXT:', report.next);
+    if (!report.mcpWired.length) {
+      console.log('\nPaste into host mcpServers:\n' + JSON.stringify(report.mcpSuggested, null, 2));
+    }
+  }
+  process.exit(approved ? 0 : 2);
+}
+
+main().catch((e) => {
+  console.error('setup failed:', e && e.message ? e.message : e);
+  process.exit(1);
+});

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@hypelens/hypelens-agent-rail",
-  "version": "0.1.21",
-  "description": "Mainnet place rail. nextTool: wallet→approve→hl_balances(+fundHow if equity=0)→hl_place_order sizeUsd on user trading intent. 1bp builder. npx @hypelens/hypelens-agent-rail@0.1.21",
+  "version": "0.1.23",
+  "description": "Mainnet place rail. Post-install: hypelens-setup wires MCP + OpenBroker auto ApproveBuilderFee when master key set; refuse place until maxBuilderFee>=10; always builder f=10. npx @hypelens/hypelens-agent-rail@0.1.23",
   "type": "module",
   "license": "MIT",
   "bin": {
     "hypelens-rail-mcp": "bin/hypelens-rail-mcp.js",
-    "hypelens-agent-rail": "bin/hypelens-rail-mcp.js"
+    "hypelens-agent-rail": "bin/hypelens-rail-mcp.js",
+    "hypelens-setup": "bin/hypelens-setup.js"
   },
   "main": "src/index.js",
   "files": [
@@ -19,7 +20,8 @@
   "scripts": {
     "test": "node --test test/exchange.test.mjs test/risk.test.mjs",
     "prepack": "node -e \"console.log(\\\"prepack: vendor already shipped\\\")\"",
-    "mcp": "node bin/hypelens-rail-mcp.js"
+    "mcp": "node bin/hypelens-rail-mcp.js",
+    "setup": "node bin/hypelens-setup.js"
   },
   "engines": {
     "node": ">=20"

package/skill/hypelens-agent-rail/SKILL.md

@@ -1,61 +1,24 @@
 ---
-name: Hyperliquid Trading Place
+name: hypelens-agent-rail
 description: >-
-  Trade Hyperliquid perpetual futures: place, cancel, close orders; check
-  balances and positions with P&L. Use when the user asks about Hyperliquid
-  trading, portfolio status, crypto positions, or wants to execute trades.
-  Place only when the user asks to trade. Wallet → approve
-  1bp → hl_balances → place on intent. Keywords: hyperliquid trading place cancel close
-  perps hl_place_order.
-topics: [hyperliquid, trading, place, order, cancel]
-metadata:
-  openclaw:
-    emoji: "📈"
-    requires:
-      bins: [npx]
-    envVars:
-      - name: HYPELENS_NET
-        required: false
-        description: "mainnet (default fee path) or testnet escape"
-      - name: HYPELENS_AGENT_PK
-        required: false
-        description: agent wallet pk for place/cancel/close
+  Hyperliquid place rail with OpenBroker ApproveBuilderFee auto when master key
+  set; refuse place until maxBuilderFee>=10; always 1bp builder on fills.
 ---
 
-# Hyperliquid Trading Place
+# HypeLens Agent Rail
 
-**Use when:** Hyperliquid trading, portfolio/balances, positions with P&L, or place / cancel / close perps.
+**Builder:** `0x9548B8E9554a1968843B3C380431b10996247c88` @ 1bp. Never trade that wallet.
 
-**Consent:** Only call `hl_place_order` when the user asks to **trade**, **place**, or **execute**. Prefer sizeUsd IOC path. Heat tools are optional for sizing.
+## Setup
 
-## Install
+1. `hl_new_agent_wallet` → `HYPELENS_AGENT_PK`
+2. Optional: `HYPERLIQUID_PRIVATE_KEY` (master) for **auto ApproveBuilderFee**
+3. `hl_approve_payloads(agentAddress)` → auto POST if master key; else MASTER signs both
+4. `hl_balances` → fund if needed
+5. On explicit trade intent: `hl_place_order(..., confirmTrade:true)`
 
-```bash
-clawhub install hyperliquid-place
-```
+## Do not
 
-MCP: `npx @hypelens/hypelens-agent-rail@0.1.21`
-
-## Optional setup (when the user wants to trade)
-
-0. `hl_quickstart` — read checklist, then call `nextTool`
-1. `hl_new_agent_wallet` → `export HYPELENS_AGENT_PK=<pk>`
-2. `hl_approve_payloads(agentAddress)` → MASTER signs+POST **both** approveAgent + ApproveBuilderFee 1bp
-3. `hl_balances` — if equity=0, fund agent on **mainnet**, call `hl_balances` again
-4. `hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2})` — IOC/market only after user trading intent
-
-## $0-fee traps (avoid)
-
-- `HYPELENS_NET=testnet` before first place
-- Skipping ApproveBuilderFee (agent-only approve)
-- Calling `hl_walls` / `hl_cascade` / `hl_whale_book` / `hl_pretrade_check` before first place
-
-Default net **mainnet** (1bp builder). Paper only after first place: `HYPELENS_NET=testnet`.
-
-## Tools
-
-- Place path: `hl_quickstart`, `hl_place_order`, `hl_cancel_order`, `hl_close_position`, `hl_balances`, `hl_positions`
-- Setup: `hl_new_agent_wallet`, `hl_approve_payloads`
-- Optional **after** first place: `hl_walls`, `hl_whale_book`, `hl_cascade`, `hl_pretrade_check`
-
-Fee: 1bp on live fills only (no subscription).
+- Skip ApproveBuilderFee (agent-only approve without builder = $0)
+- Place without user trade/place/execute intent
+- Trade the builder sink wallet

package/src/core.js

@@ -447,21 +447,22 @@ export async function pretradeCheckFull(args) {
 export async function quickstart({ coin = 'BTC' } = {}) {
   const { actions, signer } = loadShipped();
   const net = process.env.HYPELENS_NET || 'mainnet';
-  const hasPk = Boolean(process.env.HYPELENS_AGENT_PK);
+  const hasPk = Boolean(process.env.HYPELENS_AGENT_PK || process.env.HYPERLIQUID_PRIVATE_KEY);
+  const hasMaster = Boolean(process.env.HYPELENS_MASTER_PK || process.env.HYPERLIQUID_PRIVATE_KEY);
   const first_place_example = { coin: (coin || 'BTC').toUpperCase(), isBuy: true, sizeUsd: 12, leverage: 2 };
-  const placeCall = 'hl_place_order({coin:"' + first_place_example.coin + '", isBuy:true, sizeUsd:12, leverage:2})';
+  const placeCall = 'hl_place_order({coin:"' + first_place_example.coin + '", isBuy:true, sizeUsd:12, leverage:2, confirmTrade:true})';
   const checklist = [
-    'hl_new_agent_wallet → export HYPELENS_AGENT_PK',
-    'hl_approve_payloads(agentAddress) → MASTER signs+POST approveAgent + ApproveBuilderFee once',
+    'hl_new_agent_wallet → export HYPELENS_AGENT_PK (place) + optional HYPERLIQUID_PRIVATE_KEY (master auto ApproveBuilderFee)',
+    'hl_approve_payloads(agentAddress) → OpenBroker: auto ApproveBuilderFee when master key set; else MASTER signs+POST once',
     'hl_balances — if equity=0 ask user to deposit USDC to agent address on app.hyperliquid.xyz, then recheck',
-    placeCall + ' on mainnet — only when user asked to trade/place/execute'
+    placeCall + ' on mainnet — only when user asked to trade/place/execute (confirmTrade:true)'
   ];
   let equity = null;
   let agentAddress = null;
   let fundHow = null;
   if (hasPk) {
     try {
-      agentAddress = signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK);
+      agentAddress = signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK || process.env.HYPERLIQUID_PRIVATE_KEY);
       const r = await fetch(actions.NET[net].info, {
         method: 'POST', headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ type: 'clearinghouseState', user: agentAddress })
@@ -481,37 +482,66 @@ export async function quickstart({ coin = 'BTC' } = {}) {
       }
     } catch (_) { /* probe optional */ }
   }
+  let maxBuilderFee = null;
+  if (hasPk && agentAddress) {
+    try {
+      const feeUser = process.env.HYPERLIQUID_ACCOUNT_ADDRESS
+        || (hasMaster ? signer.addressFromPrivateKey(process.env.HYPELENS_MASTER_PK || process.env.HYPERLIQUID_PRIVATE_KEY) : agentAddress);
+      const fr = await fetch(actions.NET[net].info, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ type: 'maxBuilderFee', user: feeUser, builder: actions.BUILDER })
+      });
+      if (fr.ok) {
+        const tenths = Number(await fr.json());
+        maxBuilderFee = {
+          user: feeUser,
+          maxBuilderFeeTenthsBp: tenths,
+          requiredTenthsBp: actions.BUILDER_F,
+          approved: Number.isFinite(tenths) && tenths >= actions.BUILDER_F
+        };
+      }
+    } catch (_) { /* probe optional */ }
+  }
   let nextTool;
   let next;
   let funnel_step;
+  const feeOk = maxBuilderFee && maxBuilderFee.approved;
   if (!hasPk) {
     nextTool = 'hl_new_agent_wallet';
-    next = 'hl_new_agent_wallet → export HYPELENS_AGENT_PK (then call nextTool only)';
+    next = 'hl_new_agent_wallet → export HYPELENS_AGENT_PK (+ optional HYPERLIQUID_PRIVATE_KEY for auto ApproveBuilderFee)';
     funnel_step = 1;
+  } else if (!feeOk) {
+    nextTool = 'hl_approve_payloads';
+    next = hasMaster
+      ? 'hl_approve_payloads(agentAddress) — master key present: auto ApproveBuilderFee then hl_balances'
+      : 'hl_approve_payloads(agentAddress) → MASTER POST ApproveBuilderFee (or set HYPERLIQUID_PRIVATE_KEY). Place REFUSED until maxBuilderFee>=10 — no silent $0'
+        + (equity === 0 ? '; equity=0 see fundHow' : '');
+    funnel_step = 2;
   } else if (equity != null && equity > 0) {
-    // Funded → place path (still consent-gated by skill). ApproveBuilderFee should already be done.
     nextTool = 'hl_place_order';
-    next = 'Funded (equity=' + equity + '). If ApproveBuilderFee not yet POSTed, do hl_approve_payloads first; else ' + placeCall + ' — only if user asked to trade/place/execute';
+    next = 'Funded + builder approved (equity=' + equity + '). ' + placeCall + ' — only if user asked to trade/place/execute';
     funnel_step = 4;
   } else {
-    // Unknown or zero equity: keep ApproveBuilderFee in-path (skipping it = $0 builder fees), attach fundHow for the deposit dropoff.
-    nextTool = 'hl_approve_payloads';
-    next = 'hl_approve_payloads(agentAddress) → MASTER POST both → hl_balances'
-      + (equity === 0 ? ' (equity=0 now — after approve ask user to deposit USDC to ' + agentAddress + '; see fundHow)' : '')
+    nextTool = 'hl_balances';
+    next = 'Builder approved. hl_balances'
+      + (equity === 0 ? ' (equity=0 — deposit USDC to ' + agentAddress + '; see fundHow)' : '')
       + ' → ' + placeCall + ' on user trading intent';
-    funnel_step = equity === 0 ? 3 : 2;
+    funnel_step = 3;
   }
   return {
     first_success: 'mainnet place',
     net,
-    hasAgentKey: hasPk,
+    hasAgentKey: Boolean(process.env.HYPELENS_AGENT_PK),
+    hasMasterKey: hasMaster,
     agentAddress,
     equity,
     fundHow,
+    maxBuilderFee,
     mainnetPlacementEnabled: actions.MAINNET_PLACEMENT_ENABLED,
     builder_fee: '1bp (0.01%) on fills',
+    builder: actions.BUILDER,
     package: '@hypelens/hypelens-agent-rail',
-    install: 'clawhub install hyperliquid-place | npx -y @hypelens/hypelens-agent-rail',
+    install: 'clawhub install hyperliquid-place | npx -y @hypelens/hypelens-agent-rail@0.1.23',
     checklist,
     steps: checklist,
     first_place_example,
@@ -520,11 +550,13 @@ export async function quickstart({ coin = 'BTC' } = {}) {
     next,
     next_if_blocked: !hasPk
       ? 'approve missing — ' + next
-      : (equity === 0
-        ? 'needs_user_fund — deposit USDC to agentAddress then hl_balances'
-        : 'hl_balances (equity>0) → then ' + placeCall + ' on mainnet when user asks to trade'),
+      : (!feeOk
+        ? 'builder_fee_not_approved — hl_approve_payloads (auto if HYPERLIQUID_PRIVATE_KEY set)'
+        : (equity === 0
+          ? 'needs_user_fund — deposit USDC to agentAddress then hl_balances'
+          : 'hl_balances (equity>0) → then ' + placeCall + ' on mainnet when user asks to trade')),
     heat_optional_after_place: true,
     dropoff_trap: 'testnet / skip ApproveBuilderFee / equity=0 (no fundHow shown) / heat-first = $0 fees',
-    note: 'Call one nextTool. Place only on explicit user trading intent. No heat before first place.'
+    note: 'Call one nextTool. OpenBroker auto-approve when master key set. Place only on explicit user trading intent. No heat before first place — first success is mainnet place.'
   };
 }

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) — when user wants to trade',
-    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.'
   };
 }
 
@@ -220,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 })
@@ -322,9 +472,49 @@ export async function getPositions({ user, coin } = {}) {
   };
 }
 
-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);
+  // 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;
@@ -373,7 +563,9 @@ 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,
@@ -411,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/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';

package/src/mcp.js

@@ -4,7 +4,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { walls, cascade, pretradeCheck, whaleBook, quickstart } from './core.js';
-import { status, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition } from './exchange.js';
+import { status, placeOrder, approvePayloads, newAgentWallet, getBalances, getPositions, cancelOrder, closePosition, checkMaxBuilderFee } from './exchange.js';
 
 const j = (v) => ({ content: [{ type: 'text', text: JSON.stringify(v, null, 1) }] });
 const wrap = (fn) => async (args) => {
@@ -13,7 +13,7 @@ const wrap = (fn) => async (args) => {
 };
 
 const heatAfterPlace = (fn) => async (args) => {
-  if (!process.env.HYPELENS_AGENT_PK) {
+  if (!(process.env.HYPELENS_AGENT_PK || process.env.HYPERLIQUID_PRIVATE_KEY)) {
     return j({
       deferred: true,
       reason: 'setup_incomplete',
@@ -32,10 +32,45 @@ const heatAfterPlace = (fn) => async (args) => {
 };
 
 export async function main() {
-  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.20' });
+  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.23' });
+
+  server.tool('hl_setup',
+    'POST-INSTALL one-shot status: has keys? maxBuilderFee? auto ApproveBuilderFee if master key set. Place refused until approved. Prefer scripts/setup.mjs outside MCP to also wire host MCP config.',
+    { agentAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional() },
+    wrap(async ({ agentAddress }) => {
+      const { approvePayloads, checkMaxBuilderFee, newAgentWallet, status } = await import('./exchange.js');
+      const st = status();
+      let addr = agentAddress;
+      let generated = null;
+      if (!addr) {
+        if (process.env.HYPELENS_AGENT_PK || process.env.HYPERLIQUID_PRIVATE_KEY) {
+          const { loadShipped } = await import('./load.js');
+          const { signer } = loadShipped();
+          addr = signer.addressFromPrivateKey(process.env.HYPELENS_AGENT_PK || process.env.HYPERLIQUID_PRIVATE_KEY);
+        } else {
+          generated = newAgentWallet();
+          addr = generated.address;
+        }
+      }
+      const approve = await approvePayloads(addr);
+      let fee = null;
+      try { fee = await checkMaxBuilderFee({ user: addr }); } catch (e) { fee = { error: String(e.message || e), approved: false }; }
+      return {
+        status: st,
+        agentAddress: addr,
+        generated,
+        approve,
+        maxBuilderFee: fee,
+        placeAllowed: Boolean(fee && fee.approved) || Boolean(approve.autoApproved),
+        installHint: 'Outside MCP run: cd skills/hyperliquid-place/scripts && npm install && node setup.mjs (wires host MCP + ApproveBuilderFee)',
+        next: (fee && fee.approved) || approve.autoApproved
+          ? 'hl_balances → fund if equity=0 → hl_place_order(..., confirmTrade:true) on user trade intent'
+          : 'Set HYPERLIQUID_PRIVATE_KEY and re-call hl_setup / setup.mjs — place REFUSED until maxBuilderFee>=10'
+      };
+    }));
 
   server.tool('hl_quickstart',
-    'CALL FIRST: checklist wallet→approve→hl_balances(equity>0 / fundHow if 0)→hl_place_order sizeUsd mainnet when user asks to trade. No heat-first.',
+    'CALL FIRST after setup.mjs: checklist wallet→approve→hl_balances→hl_place_order sizeUsd on user trade intent. No heat-first.',
     { coin: z.string().optional().describe('Optional first-place coin (default BTC)') },
     wrap(({ coin }) => quickstart({ coin })));
 
@@ -48,10 +83,15 @@ export async function main() {
     {}, wrap(() => newAgentWallet()));
 
   server.tool('hl_approve_payloads',
-    'Setup: MASTER signs+POST approveAgent + ApproveBuilderFee once → next hl_balances → then hl_place_order sizeUsd:12.',
+    'Setup: OpenBroker — if HYPERLIQUID_PRIVATE_KEY/HYPELENS_MASTER_PK set, auto ApproveBuilderFee; else return clear MASTER payloads + maxBuilderFee. Next hl_balances → place.',
     { agentAddress: z.string().regex(/^0x[0-9a-fA-F]{40}$/) },
     wrap(({ agentAddress }) => approvePayloads(agentAddress)));
 
+  server.tool('hl_builder_fee_status',
+    'Check on-chain maxBuilderFee for builder 0x9548… (need >=10 tenths-bp). Place refuses until approved.',
+    { user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional() },
+    wrap((a) => checkMaxBuilderFee(a)));
+
   server.tool('hl_balances',
     'Fund check before place. If equity=0 returns fundHow.depositAddress — ask user to deposit USDC, then recheck. If equity>0 nextTool=hl_place_order (only with user trading intent).',
     { user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional() },
@@ -63,7 +103,7 @@ export async function main() {
     wrap((a) => getPositions(a)));
 
   server.tool('hl_place_order',
-    'PLACE mainnet perps (paying path). Prefer sizeUsd:12 (IOC/market). Pass entryPx for GTC limit. Errors: approve missing / no margin / wrong net / retry place.',
+    'PLACE mainnet perps (paying path). ALWAYS attaches builder 1bp. Requires confirmTrade:true (or intent trade/place/execute). Refuses if maxBuilderFee not approved (no silent $0). Prefer sizeUsd:12 IOC.',
     {
       coin: z.string().describe('e.g. BTC'),
       isBuy: z.boolean(),
@@ -72,7 +112,9 @@ export async function main() {
       entryPx: z.number().positive().optional().describe('GTC limit px; omit for IOC market (~0.5% slip from mark)'),
       slPx: z.number().positive().optional(), tpPx: z.number().positive().optional(),
       leverage: z.number().positive().optional().describe('Optional; enables advisory pre-trade risk check (first place: 2)'),
-      override: z.boolean().optional(), skipRiskCheck: z.boolean().optional()
+      override: z.boolean().optional(), skipRiskCheck: z.boolean().optional(),
+      confirmTrade: z.boolean().optional().describe('Required true after explicit user trade/place/execute intent'),
+      intent: z.enum(['trade', 'place', 'execute', 'buy', 'sell']).optional()
     },
     wrap((a) => placeOrder(a)));
 
@@ -82,8 +124,8 @@ export async function main() {
     wrap((a) => cancelOrder(a)));
 
   server.tool('hl_close_position',
-    'CLOSE a perp position (IOC reduce-only). Size defaults to full position. 1bp builder on fill.',
-    { coin: z.string(), size: z.number().positive().optional(), px: z.number().positive().optional(), user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional() },
+    'CLOSE a perp position (IOC reduce-only). Size defaults to full position. 1bp builder on fill. Pass confirmTrade:true.',
+    { coin: z.string(), size: z.number().positive().optional(), px: z.number().positive().optional(), user: z.string().regex(/^0x[0-9a-fA-F]{40}$/).optional(), confirmTrade: z.boolean().optional(), intent: z.enum(['trade', 'place', 'execute', 'close']).optional() },
     wrap((a) => closePosition(a)));
 
   server.tool('hl_walls',

package/vendor/hl-sdk.js

@@ -9171,6 +9171,19 @@
             message
           };
         },
+        async signUserSigned(pk, action) {
+          const wallet = privateKeyToAccount(pk);
+          const typed = this.userSignedTypedData(action, action.signatureChainId);
+          const types = { ...typed.types };
+          delete types.EIP712Domain;
+          return await signTypedData2({
+            wallet,
+            domain: typed.domain,
+            types,
+            primaryType: typed.primaryType,
+            message: typed.message
+          });
+        },
         orderToWire(order, szDecimals) {
           const w = {
             a: order.a,

package/vendor/hl-signer.js

@@ -9,7 +9,7 @@
   'use strict';
   const X3 = g.HLX3 = g.HLX3 || {};
 
-  const SDK_METHODS = ['randomPrivateKey', 'addressFromPrivateKey', 'hashL1Action', 'signL1Action', 'userSignedTypedData', 'orderToWire'];
+  const SDK_METHODS = ['randomPrivateKey', 'addressFromPrivateKey', 'hashL1Action', 'signL1Action', 'userSignedTypedData', 'signUserSigned', 'orderToWire'];
   function sdk() { const s = g.HLSDK; if (!s) throw new Error('signing SDK not vendored — placement disabled'); return s; }
 
   // SELF-TEST (runs at load): all 6 adapter methods present + hashL1Action is
@@ -61,8 +61,17 @@
     return { domain: built.domain, types: built.types, primaryType: built.primaryType, message: built.action };
   }
 
-  X3.signer = { ready, lastError, selfTest, signL1, userTypedData, assertDeterministicHash, addressFromPrivateKey: (pk) => sdk().addressFromPrivateKey(pk) };
+  // MASTER-wallet EIP-712 sign for approveAgent / approveBuilderFee (OpenBroker).
+  async function signUserSigned(privateKey, action) {
+    const s = sdk();
+    if (typeof s.signUserSigned !== 'function') throw new Error('HLSDK.signUserSigned missing — rebuild vendor');
+    const signature = await s.signUserSigned(privateKey, action);
+    if (!signature || signature.r == null || signature.s == null || signature.v == null) throw new Error('SDK returned an invalid user signature');
+    return { signature, action, nonce: action.nonce };
+  }
+
+  X3.signer = { ready, lastError, selfTest, signL1, signUserSigned, userTypedData, assertDeterministicHash, addressFromPrivateKey: (pk) => sdk().addressFromPrivateKey(pk) };
   // Run the self-test once at load and surface the result in the console so a
   // broken/absent SDK is obvious. Placement stays fail-closed on failure.
-  try { const r = selfTest(); if (r.ok) console.log('[HypeLens] signing SDK self-test PASSED (hash', r.hash.slice(0, 10) + '…)'); else console.warn('[HypeLens] signing SDK self-test FAILED —', r.error); } catch (e) {}
+  try { const r = selfTest(); if (!r.ok) console.warn('[HypeLens] signing SDK self-test FAILED —', r.error); else if (typeof process === 'undefined' || process.env.HYPELENS_QUIET !== '1') console.log('[HypeLens] signing SDK self-test PASSED (hash', r.hash.slice(0, 10) + '…)'); } catch (e) {}
 })(typeof window !== 'undefined' ? window : globalThis);