1---
2name: hyperliquid
3version: 1.4.0
4description: Trade perpetual futures and spot on Hyperliquid DEX
5delivery: script
6tools:
7  - hl_account
8  - hl_balances
9  - hl_open_orders
10  - hl_market
11  - hl_orderbook
12  - hl_fills
13  - hl_candles
14  - hl_funding
15  - hl_order
16  - hl_spot_order
17  - hl_tpsl_order
18  - hl_cancel
19  - hl_cancel_all
20  - hl_modify
21  - hl_leverage
22  - hl_transfer_usd
23  - hl_withdraw
24  - hl_deposit
25metadata:
26  starchild:
27    emoji: "📈"
28    skillKey: hyperliquid
29    requires:
30      env: [WALLET_SERVICE_URL]
31user-invocable: true
32disable-model-invocation: false
33---
34 
35# Hyperliquid Trading
36 
37Trade 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.
38 
39## Prerequisites
40 
41Before 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.
42 
43## Runtime Model: Agent Tools vs Service Scripts (Important)
44 
45Hyperliquid has **two execution modes**. Use the right one for your workflow:
46 
47### 1) Agent tool mode (chat/task runtime)
48 
49Use `hl_*` tools directly in agent conversations and task scripts that run inside the Starchild tool runtime.
50 
51- Best for: human-in-the-loop operations, ad-hoc trades, monitoring flows, orchestration across multiple skills
52- Strength: fastest integration with built-in verification workflow (`check → execute → verify`)
53- Limitation: `hl_*` tools are tool-runtime capabilities, **not normal Python imports**
54 
55### 2) Service script mode (FastAPI/worker/bot process)
56 
57For standalone services (FastAPI bots, daemons, web backends), call Hyperliquid directly via the bundled client:
58 
59- Use `skills/hyperliquid/client.py` (`HyperliquidClient`)
60- This is the recommended path for always-on bots (grid/maker/rebalancer) that should not depend on localhost agent-chat bridging
61- `hl_*` tools are not importable as `from ... import hl_order` in plain Python services
62 
63### Service Integration Pattern (recommended)
64 
651. Keep strategy/state machine in your own service process (FastAPI, worker loop, queue consumer)
662. Use `HyperliquidClient` for `order`, `cancel`, `open orders`, `fills`, `account`
673. Persist bot state locally (orders, fills cursor, grid map, PnL)
684. Build admin APIs (`/start`, `/stop`, `/status`, `/history`) around that state
69 
70### Minimal service example (direct client)
71 
72```python
73from skills.hyperliquid.client import HyperliquidClient
74 
75client = HyperliquidClient()
76address = await client._get_address()  # wallet address used for read endpoints
77 
78# Query
79account = await client.get_account_state(address)
80opens = await client.get_open_orders(address)
81fills = await client.get_user_fills(address)
82 
83# Place order (example)
84res = await client.place_order(
85    coin="BTC",
86    is_buy=True,
87    size=0.001,
88    price=95000,
89    order_type="limit",
90)
91 
92# Cancel all BTC orders
93await client.cancel_all("BTC")
94```
95 
96## Available Tools
97 
98### Account & Market Info
99 
100| Tool | What it does |
101|------|--------------|
102| `hl_total_balance` | Check how much you can trade with (use this for balance checks!) |
103| `hl_account` | See your open positions and PnL |
104| `hl_balances` | See your token holdings (USDC, HYPE, etc.) |
105| `hl_market` | Get current prices for crypto or stocks |
106| `hl_orderbook` | Check order book depth and liquidity |
107| `hl_fills` | See recent trade fills and execution prices |
108| `hl_candles` | Get price charts (1m, 5m, 1h, 4h, 1d) |
109| `hl_funding` | Check funding rates for perps |
110| `hl_open_orders` | See pending orders |
111 
112### Trading
113 
114| Tool | What it does |
115|------|--------------|
116| `hl_order` | Buy or sell perps (crypto/stocks) |
117| `hl_spot_order` | Buy or sell spot tokens |
118| `hl_tpsl_order` | Place stop loss or take profit orders |
119| `hl_leverage` | Set leverage (1x to asset max) |
120| `hl_cancel` | Cancel a specific order |
121| `hl_cancel_all` | Cancel all open orders |
122| `hl_modify` | Change order price or size |
123 
124### Funds
125 
126| Tool | What it does |
127|------|--------------|
128| `hl_deposit` | Add USDC from Arbitrum (min $5) |
129| `hl_withdraw` | Send USDC to Arbitrum (1 USDC fee, ~5 min) |
130| `hl_transfer_usd` | Move USDC between spot/perp (rarely needed) |
131 
132---
133 
134## Quick Start
135 
136Just tell the agent what you want to trade - it handles everything automatically.
137 
138**Examples:**
139 
140```
141User: "Buy $20 of Bitcoin with 5x leverage"
142Agent: [checks balance → sets leverage → places order → reports fill]
143Result: "✓ Bought 0.0002 BTC at $95,432 with 5x leverage. Position opened."
144 
145User: "Long NVIDIA with $50, 10x"
146Agent: [auto-detects NVIDIA = xyz:NVDA → executes → verifies]
147Result: "✓ Bought 0.25 NVDA at $198.50 with 10x leverage. Filled at $198.62."
148 
149User: "Sell my ETH position"
150Agent: [checks position size → closes → reports PnL]
151Result: "✓ Sold 0.5 ETH at $3,421. Realized PnL: +$12.50"
152```
153 
154**You don't need to:**
155- Understand account modes or fund transfers
156- Check balances manually (agent does it)
157- Calculate position sizes (agent does it)
158- Verify fills (agent does it)
159 
160**Just say what you want, the agent handles the rest.**
161 
162---
163 
164## Agent Behavior Guidelines
165 
166**🤖 As the agent, you should ALWAYS do these automatically (never ask the user):**
167 
1681. **Check available funds** - Use `hl_total_balance` before EVERY trade to see total available margin
1692. **Detect asset type** - Recognize if user wants crypto (BTC, ETH, SOL) or stocks/RWA (NVIDIA→xyz:NVDA, TESLA→xyz:TSLA)
1703. **Set leverage** - Always call `hl_leverage` before placing orders (unless user specifies not to)
1714. **Verify fills** - After placing ANY order, immediately call `hl_fills` to check if it filled
1725. **Report results** - Tell user the outcome: filled price, size, and any PnL
1736. **Suggest risk management** - For leveraged positions, remind users about stop losses or offer to set them
174 
175**🎯 User just says:** "buy X" or "sell Y" or "long Z with $N"
176 
177**🔧 You figure out:**
178- Current balance (hl_total_balance)
179- Asset resolution (crypto vs RWA)
180- Leverage settings (hl_leverage)
181- Order sizing (calculate from user's $ amount or size)
182- Execution (hl_order)
183- Verification (hl_fills)
184- Final report to user
185 
186**📊 Balance checking hierarchy:**
187- ✅ Use `hl_total_balance` - shows ACTUAL available margin regardless of account mode
188- ❌ Don't use `hl_account` for balance - may show $0 even if funds available
189- ❌ Don't use `hl_balances` for margin - only shows spot tokens
190 
191**🚀 Be proactive, not reactive:**
192- Don't wait for user to ask "did it fill?" - check automatically
193- Don't ask "should I check your balance?" - just do it
194- Don't explain account modes - user doesn't care, just execute
195 
196---
197 
198## Tool Usage Examples
199 
200### Check Account State
201 
202```
203hl_account()              # Default crypto perps account
204hl_account(dex="xyz")     # Builder dex (RWA/stock perps) account
205```
206 
207Returns `marginSummary` (accountValue, totalMarginUsed, withdrawable) and `assetPositions` array with each position's coin, szi (signed size), entryPx, unrealizedPnl, leverage.
208 
209**Important:** Builder perps (xyz:NVDA, xyz:TSLA, etc.) have separate clearinghouses. Always check the correct dex when trading RWA/stock perps.
210 
211### Check Spot Balances
212 
213```
214hl_balances()
215```
216 
217Returns balances array with coin, hold, total for USDC and all spot tokens.
218 
219### Check Market Prices
220 
221```
222hl_market()                  # All mid prices
223hl_market(coin="BTC")        # BTC price + metadata (maxLeverage, szDecimals)
224```
225 
226### Side Parameter Convention (read this first)
227 
228All order tools (`hl_order`, `hl_spot_order`, `hl_tpsl_order`, `hl_modify`)
229use the same `side` parameter. **Use `"buy"` or `"sell"`** — these are the
230documented values and should be your default.
231 
232For safety, the tools also accept these aliases so a model guess doesn't
233reverse direction on a leveraged order:
234 
235- Buy family:  `"buy"`, `"B"`, `"bid"`, `"long"`, `"L"`, `1`, `true`
236- Sell family: `"sell"`, `"S"`, `"A"`, `"ask"`, `"short"`, `0`, `false`
237 
238**An unrecognized value will fail the call with a clear error** — the tool
239never defaults to sell (or buy) when `side` is ambiguous. This is intentional:
240silently reversing direction on a leveraged position is the worst failure mode.
241 
242Note: Hyperliquid's L1 wire protocol uses `"B"` and `"A"` internally, but the
243tool interface here is `buy`/`sell`. Stick to `buy`/`sell` in your calls and
244you will never be surprised.
245 
246### Place a Perp Limit Order
247 
248```
249hl_order(coin="BTC", side="buy", size=0.01, price=95000)
250```
251 
252Places a GTC limit buy for 0.01 BTC at $95,000.
253 
254### Place a Perp Market Order
255 
256```
257hl_order(coin="ETH", side="sell", size=0.1)
258```
259 
260Omitting `price` submits an IoC order at mid price +/- 3% slippage.
261 
262**Parameter format behavior:**
263- Preferred: pass correct JSON types (`size` as number, `reduce_only` as boolean)
264- Hyperliquid tools now include tolerant coercion for common LLM formatting mistakes:
265  - numeric strings like `"0.01"` → `0.01`
266  - boolean strings like `"true"/"false"` → `true/false`
267  - integer strings like `"5"`/`"5.0"` → `5`
268- Invalid/empty/non-finite values still fail with explicit validation errors
269 
270### Place a Post-Only Order
271 
272```
273hl_order(coin="BTC", side="buy", size=0.01, price=94000, order_type="alo")
274```
275 
276ALO (Add Liquidity Only) = post-only. Rejected if it would immediately fill.
277 
278**Practical guardrail for bots:** If your ALO price is too close to mid (often within ~0.1% on liquid pairs), Hyperliquid may reject it. For market-making/grid bots, compute current mid first and skip or shift levels that sit inside your no-cross buffer zone.
279 
280### Place a Stop Loss Order
281 
282```
283hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl")
284```
285 
286Automatically sells 0.01 BTC if the price drops to $90,000. Executes as market order when triggered.
287 
288For a limit order when triggered (instead of market):
289 
290```
291hl_tpsl_order(coin="BTC", side="sell", size=0.01, trigger_px=90000, tpsl="sl", is_market=false, limit_px=89900)
292```
293 
294### Place a Take Profit Order
295 
296```
297hl_tpsl_order(coin="ETH", side="sell", size=0.5, trigger_px=3500, tpsl="tp")
298```
299 
300Automatically sells 0.5 ETH if the price rises to $3,500. Executes as market order when triggered.
301 
302### Close a Perp Position
303 
304```
305hl_order(coin="BTC", side="sell", size=0.01, reduce_only=true)
306```
307 
308Use `reduce_only=true` to ensure it only closes, never opens a new position.
309 
310### Place a Spot Order
311 
312```
313hl_spot_order(coin="HYPE", side="buy", size=10, price=25.0)
314```
315 
316Spot orders use the same interface — just specify the token name.
317 
318### Cancel an Order
319 
320```
321hl_cancel(coin="BTC", order_id=12345678)
322```
323 
324Get `order_id` from `hl_open_orders`.
325 
326### Cancel All Orders
327 
328```
329hl_cancel_all()              # Cancel everything
330hl_cancel_all(coin="BTC")    # Cancel only BTC orders
331```
332 
333### Modify an Order
334 
335```
336hl_modify(order_id=12345678, coin="BTC", side="buy", size=0.02, price=94500)
337```
338 
339### Set Leverage
340 
341```
342hl_leverage(coin="BTC", leverage=10)               # 10x cross margin
343hl_leverage(coin="ETH", leverage=5, cross=false)    # 5x isolated margin
344```
345 
346### Transfer USDC (rarely needed)
347 
348```
349hl_transfer_usd(amount=1000, to_perp=true)     # Spot → Perp
350hl_transfer_usd(amount=500, to_perp=false)      # Perp → Spot
351```
352 
353Note: Usually not needed - funds are automatically shared. Only use if you get an error saying you need to transfer.
354 
355### Withdraw USDC to Arbitrum
356 
357```
358hl_withdraw(amount=100)                              # Withdraw to own wallet
359hl_withdraw(amount=50, destination="0xABC...")        # Withdraw to specific address
360```
361 
362Fee: 1 USDC deducted by Hyperliquid. Processing takes ~5 minutes.
363 
364### Deposit USDC from Arbitrum
365 
366```
367hl_deposit(amount=500)
368```
369 
370Sends USDC from the agent's Arbitrum wallet to the Hyperliquid bridge contract. Minimum deposit: 5 USDC. Requires USDC balance on Arbitrum.
371 
372### Get Candles
373 
374```
375hl_candles(coin="BTC", interval="1h", lookback=48)
376```
377 
378Intervals: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`. Lookback in hours.
379 
380### Check Funding Rates
381 
382```
383hl_funding()                 # All predicted fundings
384hl_funding(coin="BTC")       # BTC predicted + 24h history
385```
386 
387### Get Recent Fills
388 
389```
390hl_fills(limit=10)
391```
392 
393---
394 
395## Coin vs RWA Resolution
396 
397When 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).
398 
399### Decision Workflow
400 
4011. **Known crypto** → use plain name: `"BTC"`, `"ETH"`, `"SOL"`, `"DOGE"`, `"HYPE"`, etc.
4022. **Known stock/commodity/forex** → use `xyz:` prefix: `"xyz:NVDA"`, `"xyz:TSLA"`, `"xyz:GOLD"`, etc.
4033. **Unsure** → resolve with tool calls:
404   - First try `hl_market(coin="X")` — if it returns a price, it's a crypto perp
405   - If not found, try `hl_market(dex="xyz")` to list all RWA markets and search the results
406   - Use whichever returns a match
407 
408### Common RWA Categories (all use `xyz:` prefix)
409 
410| Category | Examples |
411|----------|----------|
412| **US Stocks** | `xyz:NVDA`, `xyz:TSLA`, `xyz:AAPL`, `xyz:MSFT`, `xyz:AMZN`, `xyz:GOOG`, `xyz:META`, `xyz:TSM` |
413| **Commodities — Metals** | `xyz:GOLD`, `xyz:SILVER`, `xyz:COPPER`, `xyz:PLATINUM`, `xyz:PALLADIUM`, `xyz:ALUMINIUM` |
414| **Commodities — Energy** | `xyz:CL` (WTI), `xyz:BRENTOIL`, `xyz:NATGAS`, `xyz:TTF` (EU Gas) |
415| **Commodities — Agriculture** | `xyz:CORN`, `xyz:WHEAT` |
416| **Commodities — Other** | `xyz:URANIUM` |
417| **Indices** | `xyz:SPY` |
418| **Forex** | `xyz:EUR`, `xyz:GBP`, `xyz:JPY` |
419 
420> If a user says "buy NVDA" or "trade GOLD", use `xyz:NVDA` / `xyz:GOLD`. These are real-world assets, not crypto.
421 
422### ⚠️ HIP-3 Commodity Price Lookup
423 
424**All 13 commodity markets are HIP-3 builder-deployed perps.** Their symbols use the `xyz:` prefix (e.g. `xyz:GOLD`, `xyz:CL`), NOT standard formats like XAU, XAG, or WTI.
425 
426**Full commodity list:** GOLD, SILVER, COPPER, PLATINUM, PALLADIUM, ALUMINIUM, CL (WTI crude), BRENTOIL, NATGAS, TTF (EU gas), CORN, WHEAT, URANIUM.
427 
428**Key gotcha:** HIP-3 assets are **NOT included in `allMids`** (the standard price feed). This means:
429- `hl_market(coin="xyz:GOLD")` may return **no price** or fail to find the asset
430- `hl_market(dex="xyz")` lists all builder markets but may not include mid prices
431 
432**The reliable way to get commodity prices is `hl_candles`:**
433 
434```
435# Get latest gold price (use 1h candles, lookback=24 for 24h data)
436hl_candles(coin="xyz:GOLD", interval="1h", lookback=24)
437 
438# Get latest copper price
439hl_candles(coin="xyz:COPPER", interval="1h", lookback=24)
440 
441# Get latest silver price
442hl_candles(coin="xyz:SILVER", interval="1h", lookback=24)
443```
444 
445The `close` field of the most recent candle = current price. The oldest candle's `open` vs latest `close` gives 24h change.
446 
447### Prefixed Name — Same Tools
448 
449All existing tools work with `xyz:TICKER` — just pass the prefixed coin name:
450 
451```
452hl_market(coin="xyz:NVDA")                                    # Check NVIDIA stock perp price
453hl_market(dex="xyz")                                           # List ALL available RWA/stock perps
454hl_orderbook(coin="xyz:NVDA")                                 # Check liquidity
455hl_leverage(coin="xyz:NVDA", leverage=3)                      # Set leverage (auto-isolated)
456hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188)    # Limit buy 0.5 NVDA
457hl_order(coin="xyz:TSM", side="buy", size=1)                  # Market buy 1 TSM
458hl_cancel(coin="xyz:NVDA", order_id=12345678)                 # Cancel order
459```
460 
461### Example: User Says "Buy NVIDIA"
462 
4631. Recognize NVIDIA = stock → use `xyz:NVDA`
4642. `hl_market(coin="xyz:NVDA")` — Check current price, leverage limits
4653. `hl_leverage(coin="xyz:NVDA", leverage=3)` — Set leverage (builder perps use isolated margin)
4664. `hl_order(coin="xyz:NVDA", side="buy", size=0.5, price=188)` — Place limit buy
4675. `hl_fills()` — Check if filled
468 
469### Notes
470 
471- Builder perps (HIP-3) use isolated margin only — `hl_leverage` handles this automatically
472- The `dex` prefix (e.g. `xyz`) identifies which builder deployed the perp
473- All tools (candles, orderbook, funding, etc.) work the same way with prefixed names
474 
475---
476 
477## Common Workflows
478 
479### Query Commodity Prices
480 
481User: "What's the gold price?" or "Show me commodity prices" or "Oil price?"
482 
483**Name → Symbol mapping:**
484- Metals: GOLD→`xyz:GOLD`, SILVER→`xyz:SILVER`, COPPER→`xyz:COPPER`, PLATINUM→`xyz:PLATINUM`, PALLADIUM→`xyz:PALLADIUM`, ALUMINIUM→`xyz:ALUMINIUM`
485- Energy: WTI/Crude Oil→`xyz:CL`, Brent→`xyz:BRENTOIL`, Natural Gas→`xyz:NATGAS`, EU Gas→`xyz:TTF`
486- Agriculture: Corn→`xyz:CORN`, Wheat→`xyz:WHEAT`
487- Other: Uranium→`xyz:URANIUM`
488 
489**Steps:**
4901. Map commodity name → HIP-3 symbol using the table above
4912. `hl_candles(coin="xyz:GOLD", interval="1h", lookback=24)` — Get 24h of hourly candles
4923. Current price = last candle's `close`
4934. 24h change = `(last_close - first_open) / first_open * 100`
4945. Repeat for each commodity as needed
495 
496**Do NOT use `hl_market()` for commodities** — HIP-3 assets are not in `allMids`. Always use `hl_candles`.
497 
498**Liquidity note:** CL (WTI) and BRENTOIL have the highest volume. ALUMINIUM, URANIUM, CORN, WHEAT, TTF may have zero or very low liquidity — warn the user before trading these.
499 
500### Trade Crypto Perps (BTC, ETH, SOL, etc.)
501 
502User: "Buy BTC" or "Long ETH with 5x"
503 
504Agent workflow:
5051. `hl_total_balance()` → Check available funds
5062. `hl_leverage(coin="BTC", leverage=5)` → Set leverage
5073. `hl_order(...)` → Place order
5084. `hl_fills()` → Verify fill and report result
509 
510### Trade Stocks/RWA (NVIDIA, TESLA, GOLD, etc.)
511 
512User: "Buy NVIDIA" or "Short TESLA"
513 
514Agent workflow:
5151. Detect asset type → Convert "NVIDIA" to "xyz:NVDA"
5162. `hl_total_balance()` → Check available funds
5173. `hl_leverage(coin="xyz:NVDA", leverage=10)` → Set leverage
5184. `hl_order(coin="xyz:NVDA", ...)` → Place order
5195. `hl_fills()` → Verify fill and report result
520 
521### Close Positions
522 
523User: "Close my BTC position"
524 
525Agent workflow:
5261. `hl_account()` → Get current position size
5272. `hl_order(coin="BTC", side="sell", size=X, reduce_only=true)` → Close position
5283. `hl_fills()` → Report PnL
529 
530### Grid / Market-Making Bot Loop (service mode)
531 
532For always-on bots running inside FastAPI/worker services:
533 
5341. Read open orders via `get_open_orders(address)`
5352. Read fills via `get_user_fills(address)`
5363. Use **fills as source of truth** for "order executed" events
5374. On fill:
538   - buy fill → place paired sell at next grid level
539   - sell fill → place paired buy at previous grid level
5405. Keep periodic reconciliation: local state vs exchange open orders
541 
542**Important:** Do not treat "order disappeared from open orders" as guaranteed fill. It can also mean cancel/reject/expired. Always confirm with `get_user_fills` (or `get_order_status` when needed).
543 
544### Spot Trading
545 
546User: "Buy 100 HYPE tokens"
547 
548Agent workflow:
5491. `hl_total_balance()` → Check available USDC
5502. `hl_spot_order(coin="HYPE", side="buy", size=100)` → Buy tokens
5513. `hl_balances()` → Verify purchase
552 
553### Deposit/Withdraw Funds
554 
555**Deposit:**
556User: "Deposit $500 USDC to Hyperliquid"
557Agent: `hl_deposit(amount=500)` → Done
558 
559**Withdraw:**
560User: "Withdraw $100 to my Arbitrum wallet"
561Agent: `hl_withdraw(amount=100)` → Done (5 min, 1 USDC fee)
562 
563---
564 
565## Order Types
566 
567| Type | Parameter | Behavior |
568|------|-----------|----------|
569| **Limit (GTC)** | `order_type="limit"` | Rests on book until filled or cancelled |
570| **Market (IoC)** | omit `price` | Immediate-or-Cancel at mid +/- 3% slippage |
571| **Post-Only (ALO)** | `order_type="alo"` | Rejected if it would cross the spread |
572| **Fill-or-Kill** | `order_type="ioc"` + explicit price | Fill immediately at price or cancel |
573| **Stop Loss** | `hl_tpsl_order` with `tpsl="sl"` | Triggers when price drops to limit losses |
574| **Take Profit** | `hl_tpsl_order` with `tpsl="tp"` | Triggers when price rises to lock gains |
575 
576---
577 
578## Stop Loss & Take Profit Orders
579 
580Stop 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.
581 
582### How They Work
583 
5841. **Order Placement**: Place a dormant trigger order with a trigger price
5852. **Monitoring**: Order sits inactive, watching the market price
5863. **Trigger**: When market price reaches `trigger_px`, order activates
5874. **Execution**: Order executes immediately (as market or limit order)
588 
589### Stop Loss (SL)
590 
591**Use case**: Limit losses on a position by automatically exiting if price moves against you.
592 
593**Example**: You're long BTC at $95,000 and want to exit if it drops below $90,000.
594 
595```
596hl_tpsl_order(coin="BTC", side="sell", size=0.1, trigger_px=90000, tpsl="sl")
597```
598 
599- **trigger_px=90000**: Activates when BTC drops to $90k
600- **side="sell"**: Closes your long position
601- **tpsl="sl"**: Marks this as a stop loss order
602- **Default**: Executes as market order when triggered (instant exit)
603 
604### Take Profit (TP)
605 
606**Use case**: Lock in gains by automatically exiting when price reaches your profit target.
607 
608**Example**: You're long ETH at $3,000 and want to take profit at $3,500.
609 
610```
611hl_tpsl_order(coin="ETH", side="sell", size=1.0, trigger_px=3500, tpsl="tp")
612```
613 
614- **trigger_px=3500**: Activates when ETH rises to $3,500
615- **side="sell"**: Closes your long position
616- **tpsl="tp"**: Marks this as a take profit order
617- **Default**: Executes as market order when triggered (instant exit)
618 
619### Market vs Limit Execution
620 
621By default, TP/SL orders execute as **market orders** when triggered (instant fill, possible slippage).
622 
623For more control, use a **limit order** when triggered:
624 
625```
626hl_tpsl_order(
627    coin="BTC",
628    side="sell",
629    size=0.1,
630    trigger_px=90000,
631    tpsl="sl",
632    is_market=false,
633    limit_px=89900
634)
635```
636 
637- **trigger_px=90000**: Activates at $90k
638- **is_market=false**: Use limit order (not market)
639- **limit_px=89900**: Limit price when triggered ($89,900)
640 
641**Trade-off**: Limit orders avoid slippage but may not fill in fast-moving markets.
642 
643### Short Positions
644 
645For short positions, reverse the `side` parameter:
646 
647**Stop loss on short** (exit if price rises):
648```
649hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=98000, tpsl="sl")
650```
651 
652**Take profit on short** (exit if price drops):
653```
654hl_tpsl_order(coin="BTC", side="buy", size=0.1, trigger_px=92000, tpsl="tp")
655```
656 
657### Best Practices
658 
6591. **Always use `reduce_only=true`** (default) - ensures TP/SL only closes positions, never opens new ones
6602. **Match size to position** - TP/SL size should equal or be less than your position size
6613. **Set both TP and SL** - protect both upside (take profit) and downside (stop loss)
6624. **Account for volatility** - don't set stops too tight or they'll trigger on normal price swings
6635. **Check open orders** - use `hl_open_orders` to verify TP/SL orders are active
664 
665### Common Mistakes
666 
667| Mistake | Problem | Solution |
668|---------|---------|----------|
669| Wrong side | SL buys instead of sells | Long position → `side="sell"` for SL/TP |
670| Size too large | TP/SL opens new position | Set `size` ≤ position size, use `reduce_only=true` |
671| Trigger = limit | Confusion about prices | `trigger_px` = when to activate, `limit_px` = execution price |
672| No SL on leverage | Liquidation risk | Always set stop loss on leveraged positions |
673 
674---
675 
676## Perps vs Spot
677 
678| Aspect | Perps | Spot |
679|--------|-------|------|
680| Tool | `hl_order` | `hl_spot_order` |
681| Leverage | Yes (up to asset max) | No |
682| Funding | Paid/received every hour | None |
683| Short selling | Yes (native) | Must own tokens to sell |
684| Check positions | `hl_account` | `hl_balances` |
685 
686---
687 
688## Risk Management
689 
690- **Always check account state before trading** — know your margin usage and existing positions
691- **Set leverage explicitly** before opening new positions (default may vary)
692- **Use reduce_only** when closing to avoid accidentally opening the opposite direction
693- **Monitor funding rates** — high positive funding means longs are expensive to hold
694- **Start with small sizes** — Hyperliquid has minimum order sizes per asset (check szDecimals)
695- **Post-only (ALO) orders** save on fees (maker vs taker rates)
696- **Check fills after market orders** — IoC orders may partially fill or not fill at all
697 
698---
699 
700## Common Errors
701 
702| Error | Fix |
703|-------|-----|
704| "Unknown perp asset" | Check coin name. Crypto: "BTC", "ETH". Stocks: "xyz:NVDA", "xyz:TSLA" |
705| "Insufficient margin" | Use `hl_total_balance` to check funds. Reduce size or add more USDC |
706| "Order must have minimum value of $10" | Increase size. Formula: `size × price ≥ $10` |
707| "Size too small" | BTC min is typically 0.001. Check asset's szDecimals |
708| "Order would cross" | ALO order rejected. Use regular limit order instead |
709| "User or wallet does not exist" | Deposit USDC first with `hl_deposit(amount=500)` |
710| "Minimum deposit is 5 USDC" | Hyperliquid requires at least $5 per deposit |
711| "Policy violation" | Load wallet-policy skill and propose wildcard policy |
712| "Action disabled when unified account is active" | Transfers blocked in unified mode (default). Just place orders directly |
713| "'side' must be one of: buy/sell ..." | You passed an unrecognized direction. Use `"buy"` or `"sell"`. See **Side Parameter Convention** above |
714