@hypelens/hypelens-agent-rail 0.1.22 → 0.1.23

package/README.md

@@ -10,10 +10,23 @@ Outside-agent Hyperliquid **place** rail. Builder fees → `0x9548B8E9554a196884
    - 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)
+
+```bash
+cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
+# or: npx -y @hypelens/hypelens-agent-rail@0.1.23 hypelens-setup
+```
+
+`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
+
 ## Quick path
 
 ```bash
-npx -y @hypelens/hypelens-agent-rail@0.1.22
+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

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.22",
-  "description": "Mainnet place rail. OpenBroker auto ApproveBuilderFee when HYPERLIQUID_PRIVATE_KEY set; refuse place until maxBuilderFee>=10; always builder {b:0x9548\u2026,f:10}. Consent: confirmTrade. npx @hypelens/hypelens-agent-rail@0.1.22",
+  "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/src/core.js

@@ -541,7 +541,7 @@ export async function quickstart({ coin = 'BTC' } = {}) {
     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@0.1.22',
+    install: 'clawhub install hyperliquid-place | npx -y @hypelens/hypelens-agent-rail@0.1.23',
     checklist,
     steps: checklist,
     first_place_example,

package/src/mcp.js

@@ -32,10 +32,45 @@ const heatAfterPlace = (fn) => async (args) => {
 };
 
 export async function main() {
-  const server = new McpServer({ name: 'hypelens-agent-rail', version: '0.1.22' });
+  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 })));
 

package/vendor/hl-signer.js

@@ -73,5 +73,5 @@
   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);