Description

⚡ n8n Community Node for Hyperliquid HIP-3 DEXes


Supercharge your n8n workflows with direct integration to Hyperliquid HIP-3 builder-deployed perpetual DEXes (e.g., xyz, flx, etc.). Seamlessly manage custom perp futures markets, check user balances, handle leverage parameters, and automate trades directly in n8n.

> 💡 Looking for standard Hyperliquid perpetuals (BTC, ETH, etc.)?
> Use the n8n-nodes-hyperliquid node instead.

—

🔍 How Scoping Works (Auto-Prefixing)

HIP-3 assets are registered on the chain in a dex:SYMBOL format. This node handles the scoping context dynamically so you do not have to double-prefix.

[Your n8n Node] ────────► Input Symbol: "XYZ100"
                                │
                       (Auto-prefixes symbol)
                                ▼
                       Node Sends: "xyz:XYZ100" ────────► [Hyperliquid API]

• Dynamic Prefixing: Simply type XYZ100. The node reads your set credentials and automatically formats it to xyz:XYZ100.
• Smart Detection: Already inputting xyz:XYZ100? The node detects the existing colon and passes it directly without re-prefixing.

—

🚀 Key Features

📈 Order Management

• Market Order: Execute market buy / sell with custom slippage protection.

Limit Order: Place orders with GTC (Good Till Cancel), IOC (Immediate or Cancel), or ALO* (Post Only) execution parameters.

• Take Profit (TP) & Stop Loss (SL): Configure conditional trigger orders (always set to reduce-only automatically).
• Cancel Orders: Terminate orders by ID, Client ID (cloid), or cancel all open orders on target DEX.
• Open & Historical Orders: Query status endpoints for open resting orders or historic reports.

💼 Position & Margin Control

• Get Positions: View active positions, entry prices, leverage status, and real-time open PnL.
• Modify Leverage: Set custom leverage parameters (includes automatic API checks for isolated-only assets).
• Update Margin: Easily inject or retrieve isolated margin from open positions.

📊 Market & Account Data

• Market Contexts: Retrieve mark price, open interest (OI), and dynamic daily funding metrics.
• Order Books: Check live L2 order book levels.
• OHLCV Candles: Fetch historic candle snapshots for customized intervals (e.g., 1m, 5m, 1h, 1d).

—

🛠️ Installation

Option A: From n8n Admin Panel (e.g. Cloud/Desktop)

1. Go to Settings → Community Nodes in your n8n interface.
2. Click Install.
3. Under NPM Package Name, enter: n8n-nodes-hyperliquid-hip3
4. Confirm installation terms.

Option B: Local/Docker command line

Navigate to your n8n installation directory and execute:

npm install n8n-nodes-hyperliquid-hip3

—

🔑 Credentials Setup

Add a new credential of type Hyperliquid HIP-3 API inside n8n:

| Field | Required | Description | Example |
| :— | :—: | :— | :— |
| DEX Name | Yes | Name of the builder-deployed perpetual DEX | xyz |
| Wallet Type | Yes | Trade using an API Agent (recommended) or the Main Wallet | API Wallet (Agent) |
| Private Key | Yes | 64-character private key with 0x prefix | 0x327a554... |
| Master Address | Yes* | Master wallet address (Only required if using Agent Wallet) | 0x10c2359... |
| Network | Yes | Connect to Hyperliquid standard L1 exchanges | Mainnet / Testnet |

—

⚡ Developer Guide

If you want to run or test modifications locally:

1. Install dependencies
npm install
2. Build files
npm run build
3. Path references configuration
export N8NCUSTOMEXTENSIONS="/path/to/n8n-nodes-hyperliquid-hip3"
n8n start

—

📝 License

Distributed under BUSL-1.1 license.