hyperliquid

What this skill does

# 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.

## Runtime Model: Agent Tools vs Service Scripts (Important)

Hyperliquid has **two execution modes**. Use the right one for your workflow:

### 1) Agent tool mode (chat/task runtime)

Use `hl_*` tools directly in agent conversations and task scripts that run inside the Starchild tool runtime.

- Best for: human-in-the-loop operations, ad-hoc trades, monitoring flows, orchestration across multiple skills
- Strength: fastest integration with built-in verification workflow (`check → execute → verify`)
- Limitation: `hl_*` tools are tool-runtime capabilities, **not normal Python imports**

### 2) Service script mode (FastAPI/worker/bot process)

For standalone services (FastAPI bots, daemons, web backends), call Hyperliquid directly via the bundled client:

- Use `skills/hyperliquid/client.py` (`HyperliquidClient`)
- This is the recommended path for always-on bots (grid/maker/rebalancer) that should not depend on localhost agent-chat bridging
- `hl_*` tools are not importable as `from ... import hl_order` in plain Python services

### Service Integration Pattern (recommended)

1. Keep strategy/state machine in your own service process (FastAPI, worker loop, queue consumer)
2. Use `HyperliquidClient` for `order`, `cancel`, `open orders`, `fills`, `account`
3. Persist bot state locally (orders, fills cursor, grid map, PnL)
4. Build admin APIs (`/start`, `/stop`, `/status`, `/history`) around that state

### Minimal service example (direct client)

```python
from skills.hyperliquid.client import HyperliquidClient

client = HyperliquidClient()
address = await client._get_address()  # wallet address used for read endpoints

# Query
account = await client.get_account_state(address)
opens = await client.get_open_orders(address)
fills = await client.get_user_fills(address)

# Place order (example)
res = await client.place_order(
    coin="BTC",
    is_buy=True,
    size=0.001,
    price=95000,
    order_type="limit",
)

# Cancel all BTC orders
await client.cancel_all("BTC")
```

## 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)
```

### Side Parameter Convention (read this first)

All order tools (`hl_order`, `hl_spot_order`, `hl_tpsl_order`, `hl_modify`)
use the same `side` parameter. **Use `"buy"` or `"sell"`** — these are the
documented values and should be your default.

For safety, the tools also accept these aliases so a model guess doesn't
reverse direction on a leveraged order:

- Buy family:  `"buy"`, `"B"`, `"bid"`, `"long"`, `"L"`, `1`, `true`
- Sell family: `"sell"`, `"S"`, `"A"`, `"ask"`, `"short"`, `0`, `false`

**An unrecognized value will fail the call with a clear error** — the tool
never defaults to sell (or buy) when `side` is ambiguous. This is intentional:
silently reversing direction on a leveraged position is the worst failure mode.

Note: Hyperliquid's L1 wire protocol uses `"B"` and `"A"` internally, but the
tool interface here is `buy`/`sell`. Stick to `buy`/`sell` in your calls and
you will never be surprised.

### Place a Perp Limit Order

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

Places a GTC l