---
id: ssh2-hyperliquid
name: "hyperliquid"
url: https://skills.yangsir.net/skill/ssh2-hyperliquid
author: starchild-ai-agent
domain: web3
tags: ["hyperliquid", "decentralized-finance-(defi)", "perpetual-futures", "blockchain-trading"]
install_count: 6500
rating: 4.50 (20 reviews)
github: https://github.com/starchild-ai-agent/official-skills
---

# hyperliquid

> 在Hyperliquid去中心化交易所（DEX）进行永续合约和现货交易，提供Web3领域的金融操作能力。

**Stats**: 6,500 installs · 4.5/5 (20 reviews)

## Before / After 对比

### 轻松交易永续合约与现货，把握市场机遇

## Readme

# Hyperliquid Trading

Trade perpetual futures and spot tokens on Hyperliquid, a fully on-chain decentralized exchange. Orders are signed using this agent's EVM wallet and submitted directly to the Hyperliquid L1.

## Prerequisites

Before trading, the wallet policy must be active. Load the **wallet-policy** skill and propose the standard wildcard policy (deny key export + allow `*`). This covers all Hyperliquid operations — USDC deposits, EIP-712 order signing, and withdrawals.

## Available Tools

### Account & Market Info

| Tool | What it does |
|------|--------------|
| `hl_total_balance` | Check how much you can trade with (use this for balance checks!) |
| `hl_account` | See your open positions and PnL |
| `hl_balances` | See your token holdings (USDC, HYPE, etc.) |
| `hl_market` | Get current prices for crypto or stocks |
| `hl_orderbook` | Check order book depth and liquidity |
| `hl_fills` | See recent trade fills and execution prices |
| `hl_candles` | Get price charts (1m, 5m, 1h, 4h, 1d) |
| `hl_funding` | Check funding rates for perps |
| `hl_open_orders` | See pending orders |

### Trading

| Tool | What it does |
|------|--------------|
| `hl_order` | Buy or sell perps (crypto/stocks) |
| `hl_spot_order` | Buy or sell spot tokens |
| `hl_tpsl_order` | Place stop loss or take profit orders |
| `hl_leverage` | Set leverage (1x to asset max) |
| `hl_cancel` | Cancel a specific order |
| `hl_cancel_all` | Cancel all open orders |
| `hl_modify` | Change order price or size |

### Funds

| Tool | What it does |
|------|--------------|
| `hl_deposit` | Add USDC from Arbitrum (min $5) |
| `hl_withdraw` | Send USDC to Arbitrum (1 USDC fee, ~5 min) |
| `hl_transfer_usd` | Move USDC between spot/perp (rarely needed) |

---

## Quick Start

Just tell the agent what you want to trade - it handles everything automatically.

**Examples:**

```
User: "Buy $20 of Bitcoin with 5x leverage"
Agent: [checks balance → sets leverage → places order → reports fill]
Result: "✓ Bought 0.0002 BTC at $95,432 with 5x leverage. Position opened."

User: "Long NVIDIA with $50, 10x"
Agent: [auto-detects NVIDIA = xyz:NVDA → executes → verifies]
Result: "✓ Bought 0.25 NVDA at $198.50 with 10x leverage. Filled at $198.62."

User: "Sell my ETH position"
Agent: [checks position size → closes → reports PnL]
Result: "✓ Sold 0.5 ETH at $3,421. Realized PnL: +$12.50"
```

**You don't need to:**
- Understand account modes or fund transfers
- Check balances manually (agent does it)
- Calculate position sizes (agent does it)
- Verify fills (agent does it)

**Just say what you want, the agent handles the rest.**

---

## Agent Behavior Guidelines

**🤖 As the agent, you should ALWAYS do these automatically (never ask the user):**

1. **Check available funds** - Use `hl_total_balance` before EVERY trade to see total available margin
2. **Detect asset type** - Recognize if user wants crypto (BTC, ETH, SOL) or stocks/RWA (NVIDIA→xyz:NVDA, TESLA→xyz:TSLA)
3. **Set leverage** - Always call `hl_leverage` before placing orders (unless user specifies not to)
4. **Verify fills** - After placing ANY order, immediately call `hl_fills` to check if it filled
5. **Report results** - Tell user the outcome: filled price, size, and any PnL
6. **Suggest risk management** - For leveraged positions, remind users about stop losses or offer to set them

**🎯 User just says:** "buy X" or "sell Y" or "long Z with $N"

**🔧 You figure out:**
- Current balance (hl_total_balance)
- Asset resolution (crypto vs RWA)
- Leverage settings (hl_leverage)
- Order sizing (calculate from user's $ amount or size)
- Execution (hl_order)
- Verification (hl_fills)
- Final report to user

**📊 Balance checking hierarchy:**
- ✅ Use `hl_total_balance` - shows ACTUAL available margin regardless of account mode
- ❌ Don't use `hl_account` for balance - may show $0 even if funds available
- ❌ Don't use `hl_balances` for margin - only shows spot tokens

**🚀 Be proactive, not reactive:**
- Don't wait for user to ask "did it fill?" - check automatically
- Don't ask "should I check your balance?" - just do it
- Don't explain account modes - user doesn't care, just execute

---

## Tool Usage Examples

### Check Account State

```
hl_account()              # Default crypto perps account
hl_account(dex="xyz")     # Builder dex (RWA/stock perps) account
```

Returns `marginSummary` (accountValue, totalMarginUsed, withdrawable) and `assetPositions` array with each position's coin, szi (signed size), entryPx, unrealizedPnl, leverage.

**Important:** Builder perps (xyz:NVDA, xyz:TSLA, etc.) have separate clearinghouses. Always check the correct dex when trading RWA/stock perps.

### Check Spot Balances

```
hl_balances()
```

Returns balances array with coin, hold, total for USDC and all spot tokens.

### Check Market Prices

```
hl_market()                  # All mid prices
hl_market(coin="BTC")        # BTC price + metadata (maxLeverage, szDecimals)
```

### Place a Perp Limit Order

```
hl_order(coin="BTC", side="buy", size=0.01, price=95000)
```

Places a GTC limit buy for 0.01 BTC at $95,000.

### Place a Perp Market Order

```
hl_order(coin="ETH", side="sell", size=0.1)
```

Omitting `price` submits an IoC order at mid price +/- 3% slippage.

### Place a Post-Only Order

```
hl_order(coin="BTC", side="buy", size=0.01, price=94000, order_type="alo")
```

ALO (Add Liquidity Only) = post-only. Rejected if it would immediately fill.

### Place a Stop Loss Order

```
hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl")
```

Automatically sells 0.01 BTC if the price drops to $90,000. Executes as market order when triggered.

For a limit order when triggered (instead of market):

```
hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl", is_market=false, limit_px=89900)
```

### Place a Take Profit Order

```
hl_tpsl_order(coin="ETH", side="sell", size=0.5, trigger_px=3500, tpsl="tp")
```

Automatically sells 0.5 ETH if the price rises to $3,500. Executes as market order when triggered.

### Close a Perp Position

```
hl_order(coin="BTC", side="sell", size=0.01, reduce_only=true)
```

Use `reduce_only=true` to ensure it only closes, never opens a new position.

### Place a Spot Order

```
hl_spot_order(coin="HYPE", side="buy", size=10, price=25.0)
```

Spot orders use the same interface — just specify the token name.

### Cancel an Order

```
hl_cancel(coin="BTC", order_id=12345678)
```

Get `order_id` from `hl_open_orders`.

### Cancel All Orders

```
hl_cancel_all()              # Cancel everything
hl_cancel_all(coin="BTC")    # Cancel only BTC orders
```

### Modify an Order

```
hl_modify(order_id=12345678, coin="BTC", side="buy", size=0.02, price=94500)
```

### Set Leverage

```
hl_leverage(coin="BTC", leverage=10)               # 10x cross margin
hl_leverage(coin="ETH", leverage=5, cross=false)    # 5x isolated margin
```

### Transfer USDC (rarely needed)

```
hl_transfer_usd(amount=1000, to_perp=true)     # Spot → Perp
hl_transfer_usd(amount=500, to_perp=false)      # Perp → Spot
```

Note: Usually not needed - funds are automatically shared. Only use if you get an error saying you need to transfer.

### Withdraw USDC to Arbitrum

```
hl_withdraw(amount=100)                              # Withdraw to own wallet
hl_withdraw(amount=50, destination="0xABC...")        # Withdraw to specific address
```

Fee: 1 USDC deducted by Hyperliquid. Processing takes ~5 minutes.

### Deposit USDC from Arbitrum

```
hl_deposit(amount=500)
```

Sends USDC from the agent's Arbitrum wallet to the Hyperliquid bridge contract. Minimum deposit: 5 USDC. Requires USDC balance on Arbitrum.

### Get Candles

```
hl_candles(coin="BTC", interval="1h", lookback=48)
```

Intervals: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. Lookback in hours.

### Check Funding Rates

```
hl_funding()                 # All predicted fundings
hl_funding(coin="BTC")       # BTC predicted + 24h history
```

### Get Recent Fills

```
hl_fills(limit=10)
```

---

## Coin vs RWA Resolution

When a user asks to trade a ticker, you need to determine whether it's a **native crypto perp** (use plain name) or an **RWA/stock perp** (use `xyz:TICKER` prefix).

### Decision Workflow

1. **Known crypto** → use plain name: `"BTC"`, `"ETH"`, `"SOL"`, `"DOGE"`, `"HYPE"`, etc.
2. **Known stock/commodity/forex** → use `xyz:` prefix: `"xyz:NVDA"`, `"xyz:TSLA"`, `"xyz:GOLD"`, etc.
3. **Unsure** → resolve with tool calls:
   - First try `hl_market(coin="X")` — if it returns a price, it's a crypto perp
   - If not found, try `hl_market(dex="xyz")` to list all RWA markets and search the results
   - Use whichever returns a match

### Common RWA Categories (all use `xyz:` prefix)

| Category | Examples |
|----------|----------|
| **US Stocks** | `xyz:NVDA`, `xyz:TSLA`, `xyz:AAPL`, `xyz:MSFT`, `xyz:AMZN`, `xyz:GOOG`, `xyz:META`, `xyz:TSM` |
| **Commodities** | `xyz:GOLD`, `xyz:SILVER` |
| **Indices** | `xyz:SPY` |
| **Forex** | `xyz:EUR`, `xyz:GBP`, `xyz:JPY` |

> If a user says "buy NVDA" or "trade GOLD", use `xyz:NVDA` / `xyz:GOLD`. These are real-world assets, not crypto.

### Prefixed Name — Same Tools

All existing tools work with `xyz:TICKER` — just pass the prefixed coin name:

```
hl_market(coin="xyz:NVDA")                                    # Check NVIDIA stock perp price
hl_market(dex="xyz")                                           # List ALL available RWA/stock perps
hl_orderbook(coin="xyz:NVDA")                                 # Check liquidity
hl_leverage(coin="xyz:NVDA", leverage=3)                      # Set leverage (auto-isolated)
hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188)    # Limit buy 0.5 NVDA
hl_order(coin="xyz:TSM", side="buy", size=1)                  # Market buy 1 TSM
hl_cancel(coin="xyz:NVDA", order_id=12345678)                 # Cancel order
```

### Example: User Says "Buy NVIDIA"

1. Recognize NVIDIA = stock → use `xyz:NVDA`
2. `hl_market(coin="xyz:NVDA")` — Check current price, leverage limits
3. `hl_leverage(coin="xyz:NVDA", leverage=3)` — Set leverage (builder perps use isolated margin)
4. `hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188)` — Place limit buy
5. `hl_fills()` — Check if filled

### Notes

- Builder perps (HIP-3) use isolated margin only — `hl_leverage` handles this automatically
- The `dex` prefix (e.g. `xyz`) identifies which builder deployed the perp
- All tools (candles, orderbook, funding, etc.) work the same way with prefixed names

---

## Common Workflows

### Trade Crypto Perps (BTC, ETH, SOL, etc.)

User: "Buy BTC" or "Long ETH with 5x"

Agent workflow:
1. `hl_total_balance()` → Check available funds
2. `hl_leverage(coin="BTC", leverage=5)` → Set leverage
3. `hl_order(...)` → Place order
4. `hl_fills()` → Verify fill and report result

### Trade Stocks/RWA (NVIDIA, TESLA, GOLD, etc.)

User: "Buy NVIDIA" or "Short TESLA"

Agent workflow:
1. Detect asset type → Convert "NVIDIA" to "xyz:NVDA"
2. `hl_total_balance()` → Check available funds
3. `hl_leverage(coin="xyz:NVDA", leverage=10)` → Set leverage
4. `hl_order(coin="xyz:NVDA", ...)` → Place order
5. `hl_fills()` → Verify fill and report result

### Close Positions

User: "Close my BTC position"

Agent workflow:
1. `hl_account()` → Get current position size
2. `hl_order(coin="BTC", side="sell", size=X, reduce_only=true)` → Close position
3. `hl_fills()` → Report PnL

### Spot Trading

User: "Buy 100 HYPE tokens"

Agent workflow:
1. `hl_total_balance()` → Check available USDC
2. `hl_spot_order(coin="HYPE", side="buy", size=100)` → Buy tokens
3. `hl_balances()` → Verify purchase

### Deposit/Withdraw Funds

**Deposit:**
User: "Deposit $500 USDC to Hyperliquid"
Agent: `hl_deposit(amount=500)` → Done

**Withdraw:**
User: "Withdraw $100 to my Arbitrum wallet"
Agent: `hl_withdraw(amount=100)` → Done (5 min, 1 USDC fee)

---

## Order Types

| Type | Parameter | Behavior |
|------|-----------|----------|
| **Limit (GTC)** | `order_type="limit"` | Rests on book until filled or cancelled |
| **Market (IoC)** | omit `price` | Immediate-or-Cancel at mid +/- 3% slippage |
| **Post-Only (ALO)** | `order_type="alo"` | Rejected if it would cross the spread |
| **Fill-or-Kill** | `order_type="ioc"` + explicit price | Fill immediately at price or cancel |
| **Stop Loss** | `hl_tpsl_order` with `tpsl="sl"` | Triggers when price drops to limit losses |
| **Take Profit** | `hl_tpsl_order` with `tpsl="tp"` | Triggers when price rises to lock gains |

---

## Stop Loss & Take Profit Orders

Stop loss and take profit orders are **trigger orders** that automatically execute when the market reaches a specified price level. Use these to manage risk and lock in profits without monitoring positions 24/7.

### How They Work

1. **Order Placement**: Place a dormant trigger order with a trigger price
2. **Monitoring**: Order sits inactive, watching the market price
3. **Trigger**: When market price reaches `trigger_px`, order activates
4. **Execution**: Order executes immediately (as market or limit order)

### Stop Loss (SL)

**Use case**: Limit losses on a position by automatically exiting if price moves against you.

**Example**: You're long BTC at $95,000 and want to exit if it drops below $90,000.

```
hl_tpsl_order(coin="BTC", side="sell", size=0.1, trigger_px=90000, tpsl="sl")
```

- **trigger_px=90000**: Activates when BTC drops to $90k
- **side="sell"**: Closes your long position
- **tpsl="sl"**: Marks this as a stop loss order
- **Default**: Executes as market order when triggered (instant exit)

### Take Profit (TP)

**Use case**: Lock in gains by automatically exiting when price reaches your profit target.

**Example**: You're long ETH at $3,000 and want to take profit at $3,500.

```
hl_tpsl_order(coin="ETH", side="sell", size=1.0, trigger_px=3500, tpsl="tp")
```

- **trigger_px=3500**: Activates when ETH rises to $3,500
- **side="sell"**: Closes your long position
- **tpsl="tp"**: Marks this as a take profit order
- **Default**: Executes as market order when triggered (instant exit)

### Market vs Limit Execution

By default, TP/SL orders execute as **market orders** when triggered (instant fill, possible slippage).

For more control, use a **limit order** when triggered:

```
hl_tpsl_order(
    coin="BTC",
    side="sell",
    size=0.1,
    trigger_px=90000,
    tpsl="sl",
    is_market=false,
    limit_px=89900
)
```

- **trigger_px=90000**: Activates at $90k
- **is_market=false**: Use limit order (not market)
- **limit_px=89900**: Limit price when triggered ($89,900)

**Trade-off**: Limit orders avoid slippage but may not fill in fast-moving markets.

### Short Positions

For short positions, reverse the `side` parameter:

**Stop loss on short** (exit if price rises):
```
hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=98000, tpsl="sl")
```

**Take profit on short** (exit if price drops):
```
hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=92000, tpsl="tp")
```

### Best Practices

1. **Always use `reduce_only=true`** (default) - ensures TP/SL only closes positions, never opens new ones
2. **Match size to position** - TP/SL size should equal or be less than your position size
3. **Set both TP and SL** - protect both upside (take profit) and downside (stop loss)
4. **Account for volatility** - don't set stops too tight or they'll trigger on normal price swings
5. **Check open orders** - use `hl_open_orders` to verify TP/SL orders are active

### Common Mistakes

| Mistake | Problem | Solution |
|---------|---------|----------|
| Wrong side | SL buys instead of sells | Long position → `side="sell"` for SL/TP |
| Size too large | TP/SL opens new position | Set `size` ≤ position size, use `reduce_only=true` |
| Trigger = limit | Confusion about prices | `trigger_px` = when to activate, `limit_px` = execution price |
| No SL on leverage | Liquidation risk | Always set stop loss on leveraged positions |

---

## Perps vs Spot

| Aspect | Perps | Spot |
|--------|-------|------|
| Tool | `hl_order` | `hl_spot_order` |
| Leverage | Yes (up to asset max) | No |
| Funding | Paid/received every hour | None |
| Short selling | Yes (native) | Must own tokens to sell |
| Check positions | `hl_account` | `hl_balances` |

---

## Risk Management

- **Always check account state before trading** — know your margin usage and existing positions
- **Set leverage explicitly** before opening new positions (default may vary)
- **Use reduce_only** when closing to avoid accidentally opening the opposite direction
- **Monitor funding rates** — high positive funding means longs are expensive to hold
- **Start with small sizes** — Hyperliquid has minimum order sizes per asset (check szDecimals)
- **Post-only (ALO) orders** save on fees (maker vs taker rates)
- **Check fills after market orders** — IoC orders may partially fill or not fill at all

---

## Common Errors

| Error | Fix |
|-------|-----|
| "Unknown perp asset" | Check coin name. Crypto: "BTC", "ETH". Stocks: "xyz:NVDA", "xyz:TSLA" |
| "Insufficient margin" | Use `hl_total_balance` to check funds. Reduce size or add more USDC |
| "Order must have minimum value of $10" | Increase size. Formula: `size × price ≥ $10` |
| "Size too small" | BTC min is typically 0.001. Check asset's szDecimals |
| "Order would cross" | ALO order rejected. Use regular limit order instead |
| "User or wallet does not exist" | Deposit USDC first with `hl_deposit(amount=500)` |
| "Minimum deposit is 5 USDC" | Hyperliquid requires at least $5 per deposit |
| "Policy violation" | Load wallet-policy skill and propose wildcard policy |
| "Action disabled when unified account is active" | Transfers blocked in unified mode (default). Just place orders directly |


---
*Source: https://skills.yangsir.net/skill/ssh2-hyperliquid*
*Markdown mirror: https://skills.yangsir.net/api/skill/ssh2-hyperliquid/markdown*