n8n node for trading HIP3 assets on Hyperliquid
npm install n8n-nodes-hyperliquid-hip3bash
npm install n8n-nodes-hyperliquid-hip3
`
$3
`bash
Clone the repository
git clone https://github.com/yourusername/n8n-nodes-hyperliquid-hip3.git
cd n8n-nodes-hyperliquid-hip3
Install dependencies
npm install
Build the node
npm run build
Link for local testing
npm link
In your n8n custom folder
cd ~/.n8n/custom
npm link n8n-nodes-hyperliquid-hip3
`
Prerequisites
- n8n installed (self-hosted or cloud)
- Hyperliquid wallet with private key
- Understanding of HIP3 asset format: dex_name:ASSET (e.g., xyz:XYZ100)
Credentials
This node requires Hyperliquid API credentials with the following information:
- Private Key: Your Hyperliquid wallet private key (without 0x prefix)
- Wallet Address (optional): Your wallet address (auto-derived if not provided)
- Network: Choose between Mainnet or Testnet
- Vault Address (optional): If trading on behalf of a vault or subaccount
Operations
$3
Place a new order on a HIP3 perpetual market.
Parameters:
- HIP3 Asset: Asset identifier (e.g., xyz:XYZ100)
- Side: Buy (B) or Sell (A)
- Size: Order size
- Order Type: Market or Limit
- Price: Required for limit orders
- Reduce Only: Whether order only reduces position
$3
Cancel a specific order by order ID.
Parameters:
- Order ID: The ID of the order to cancel
- Coin: HIP3 asset of the order
$3
Cancel all orders for a specific HIP3 asset.
Parameters:
- HIP3 Asset: Asset to cancel all orders for
$3
Retrieve all open orders for your account.
Returns: Array of open orders with details
$3
Get current HIP3 positions.
Returns: Current positions with entry price, size, PnL, etc.
$3
Get account balance and margin information.
Returns: Account value, margin used, withdrawable balance
$3
Fetch metadata about all HIP3 perpetual dexs.
Returns: List of HIP3 dexs with their assets and configuration
$3
Retrieve the order book for a specific HIP3 asset.
Parameters:
- HIP3 Asset: Asset to get order book for
Returns: Bids and asks with prices and sizes
$3
Get historical trade fills.
Parameters:
- User Address (optional): Address to get fills for (defaults to credential address)
Returns: Array of historical fills
Usage Example
$3
1. Get Market Info to see available HIP3 dexs and assets
2. Get Order Book to check current prices
3. Place Order to enter a position
4. Get Positions to monitor your position
5. Cancel Order or Cancel All Orders if needed
$3
`
Trigger (Schedule) → Get Order Book → If (Price Condition) → Place Order → Get Positions
`
HIP3 Important Notes
$3
HIP3 assets must use the format dex_name:ASSET:
- ✅ Correct: xyz:XYZ100
- ❌ Wrong: XYZ100
- ❌ Wrong: BTC (this is standard perp, not HIP3)
$3
1. Isolated Margin Only: HIP3 markets require isolated margin mode
2. Higher Fees: Trading fees are 2x standard perpetuals (protocol still receives same amount)
3. Custom Oracles: HIP3 deployers set their own oracle prices
4. DEX Prefix: Always include the DEX name prefix (e.g., xyz:)
5. Builder-Deployed: These are community-created markets, not validator-operated
$3
Use the Get Market Info operation to retrieve all available HIP3 dexs and their assets:
`json
{
"perpDexs": [
[null, { "name": "first dex", ... }],
["xyz", { "name": "XYZ Dex", "assets": ["XYZ100", "XYZ200"], ... }]
]
}
`
The DEX name (e.g., "xyz") is used as the prefix for all assets in that DEX.
API Endpoints
- Mainnet: https://api.hyperliquid.xyz
- Testnet: https://api.hyperliquid-testnet.xyz
Security Best Practices
⚠️ Security Warnings:
1. Never share your private key or commit it to version control
2. Use API Wallets for production environments when possible
3. Test on testnet first before using mainnet
4. Start with small amounts when testing live
5. Monitor your positions regularly
6. Understand HIP3 risks including oracle manipulation and lower liquidity
Troubleshooting
$3
Make sure you're using the HIP3 format with the DEX prefix (e.g., xyz:XYZ100), not just the asset name.
$3
The asset might not exist or might not have any orders. Check the asset name and verify it exists using Get Market Info.
$3
Your account doesn't have enough balance. Deposit funds or reduce order size.
$3
- For market orders: Check if there's sufficient liquidity
- For limit orders: Verify price is within reasonable bounds
- Ensure you're not in reduce-only mode when trying to increase position
Resources
- Hyperliquid Documentation
- HIP-3 Specification
- Hyperliquid API Reference
- n8n Community Nodes Documentation
Support
- Issues: GitHub Issues
- n8n Community: n8n Community Forum
- Hyperliquid: Hyperliquid Discord
Development
$3
`bash
npm run build
`
$3
`bash
npm run lint
npm run lint:fix
`
$3
`bash
npm run dev
`
This starts n8n with your node automatically loaded.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature`)