hyperliquid

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: hyperliquid
version: 1.8.0
description: |
  Trade perp futures, spot, and RWA on Hyperliquid DEX with up to asset max leverage.

  Use when placing perp or spot orders, setting TP/SL, or moving funds on Hyperliquid (e.g. long BTC 5x, sell ETH, deposit USDC, set stop).
delivery: script
metadata:
  starchild:
    emoji: "📈"
    skillKey: hyperliquid
    requires:
      env: [WALLET_SERVICE_URL]
user-invocable: true
disable-model-invocation: false

---

# 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: How to Call Hyperliquid (Read This First)

This skill is **script-delivery**. It registers **no** `hl_*` agent tools — calling
`hl_deposit`, `hl_order`, or any other `hl_*` name as a tool will always fail with
"not found in registry". That is by design, not a bug or a missing install.

There are exactly two working lanes:

### Lane 1 — Read-only queries (`exports.py`)

```python
from core.skill_tools import hyperliquid

account = hyperliquid.hl_account()
mids    = hyperliquid.hl_market()
candles = hyperliquid.hl_candles(coin="BTC", interval="1h", hours_back=24)
```

**Any wallet, not just your own.** Every user-scoped function takes an optional
`address`. Omit it for the agent's own wallet; pass a 0x address to inspect a
third party. This is what makes "analyse this wallet's Hyperliquid PnL"
answerable — Hyperliquid is an off-chain order book, so a DeBank-style
chain scan cannot see any of it.

```python
hyperliquid.hl_portfolio(address="0x1f16...")   # PnL time series
hyperliquid.hl_account(address="0x1f16...")     # their open positions
```

32 functions, grouped:

| Group | Functions |
|-------|-----------|
| Account | `hl_account` `hl_balances` `hl_total_balance` `hl_user_role` `hl_user_fees` `hl_rate_limit` `hl_sub_accounts` `hl_referral` `hl_extra_agents` |
| PnL & history | `hl_portfolio` `hl_fills` `hl_fills_by_time` `hl_historical_orders` `hl_ledger` `hl_funding_payments` `hl_twap_fills` `hl_vault_equities` |
| Orders | `hl_open_orders` `hl_open_orders_full` `hl_order_status` |
| Market | `hl_market` `hl_orderbook` `hl_candles` `hl_funding` `hl_predicted_funding` `hl_meta` `hl_meta_ctxs` `hl_spot_meta` `hl_spot_meta_ctxs` `hl_perp_dexs` |
| Staking | `hl_staking` `hl_staking_delegations` `hl_staking_rewards` |

Read-only only — no writes on this lane.

### Answering "what is this wallet's PnL?"

`hl_portfolio` returns 8 windows — `day`, `week`, `month`, `allTime` and the
`perp*` equivalents — each with `accountValueHistory` and `pnlHistory` as
`[epoch_ms, value]` pairs. `pnlHistory` restarts at 0 at the start of each
window, so read `allTime` for lifetime PnL.

```python
pf = dict(hyperliquid.hl_portfolio(address=addr))
pnl = float(pf["allTime"]["pnlHistory"][-1][1])
```

For a cost-basis reconstruction, combine three sources: `hl_ledger` (capital
in/out — deposits, withdrawals, vault moves), `hl_fills_by_time` (realized
`closedPnl` per fill, 2000 max per call — page by passing the last fill's
`time` as the next `start`), and `hl_funding_payments` (funding paid/received).
Check `hl_user_role` first: role `"missing"` means the address never traded
here, which is not the same as "no positions".

### Lane 2 — Writes: orders, cancels, transfers, deposits (`client.py`)

Every write goes through `HyperliquidClient`, which owns the EIP-712 signing
pipeline. It is an **async** class — `await` every call.

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

client = HyperliquidClient()

# Deposit USDC to the Hyperliquid bridge (minimum 5 USDC)
res = await client