@hypelens/hypelens-agent-rail

@hypelens/hypelens-agent-rail

Outside-agent Hyperliquid place rail. Builder fees → 0x9548B8E9554a1968843B3C380431b10996247c88 at 1bp (f=10) on fills. Never trade/farm that wallet.

Fee capture (OpenBroker pattern)

• Every hl_place_order / close always attaches builder: { b: 0x9548…, f: 10 }.
• 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).
• Consent: hl_place_order requires confirmTrade: true or intent: "trade"|"place"|"execute".

Post-install (REQUIRED — downloads ≠ fees)

cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
# or: npx -y @hypelens/hypelens-agent-rail@0.1.28 hypelens-setup

setup.mjs / hypelens-setup:

• Registers MCP in OpenClaw/Claude/Cursor config when possible
• Auto ApproveBuilderFee when HYPERLIQUID_PRIVATE_KEY / HYPELENS_MASTER_PK present
• Prints maxBuilderFee — place stays refused until approved (no silent $0)
• Next: fund agent if equity=0 → place on explicit trade intent

Quick path (setup BEFORE start — start-mcp REFUSED without setup)

# npx setup then MCP:
npx -y @hypelens/hypelens-agent-rail@0.1.28 hypelens-setup
npx -y @hypelens/hypelens-agent-rail@0.1.28
# sticky ClawHub (REQUIRED order — skip setup = $0 / start refused):
clawhub install hyperliquid-place
cd skills/hyperliquid-place/scripts && npm install && node setup.mjs
# then restart MCP host / node start-mcp.mjs (writes .setup-ok)

Paying path: setup → maxBuilderFee>=10 → equity>0 → hl_place_order(..., confirmTrade:true) → fillStatus=FILLED (RESTING≠paid; rail auto-cancels RESTING sizeUsd→IOC once).

Env:

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

Funnel

• hl_quickstart / hl_new_agent_wallet
• hl_approve_payloads(agentAddress) — auto if master key; else MASTER signs ApproveBuilderFee 0.01%
• hl_balances (+ fundHow if equity=0)
• On explicit trade intent: hl_place_order({coin:"BTC", isBuy:true, sizeUsd:12, leverage:2, confirmTrade:true})
• Poll until fillStatus=FILLED — RESTING≠paid (rail auto-cancel RESTING→IOC same turn once)

Skipping ApproveBuilderFee / setup / fund / FILLED = $0 fees. Place is hard-refused until on-chain maxBuilderFee covers 1bp. start-mcp REFUSED until setup.mjs wrote .setup-ok.