Hyperliquid

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