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: 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)

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.

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

32 functions, grouped:

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.

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.

from skills.hyperliquid.client import HyperliquidClient

client = HyperliquidClient()

# Deposit USDC to the Hyperliquid bridge (minimum 5 USDC)
res = await client.deposit_usdc(amount=500)

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

# Cancel / leverage / transfer / withdraw
await client.cancel_all("BTC")
await client.update_leverage(coin="BTC", leverage=5, is_cross=True)
await client.transfer_usd(amount=100, to_perp=True)
await client.withdraw_from_bridge(amount=50)

Prerequisite for Lane 2: the wallet policy must be active — load the wallet-policy skill and propose the standard wildcard policy (deny key export + allow *). That covers deposits, EIP-712 order signing, and withdrawals.

Naming note: the rest of this document refers to operations by their historical hl_* names (e.g. "hl_deposit"). Those are labels for the operation, not callable tools — always reach them via Lane 1 or Lane 2 above.

Available Tools

Account & Market Info

All of the above accept address="0x..." to inspect any wallet, not just the agent's own.

Trading

Funds

Platform

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