hyperliquid-api - SKILL.md Agent Skill

name: hyperliquid-api description: Reference for Hyperliquid exchange API integration. Use when implementing order placement, balance queries, funding rate fetching, or WebSocket subscriptions on Hyperliquid. Contains SDK patterns, authentication setup, and common pitfalls.

Hyperliquid API Skill

SDK Setup

import eth_account
from hyperliquid.exchange import Exchange
from hyperliquid.info import Info
from hyperliquid.utils import constants

# Authentication via wallet
wallet = eth_account.Account.from_key(private_key)
exchange = Exchange(wallet, constants.MAINNET_API_URL)
info = Info(constants.MAINNET_API_URL, skip_ws=True)

Common Operations

Place Limit Order (GTC)

result = exchange.order("ETH", is_buy=True, sz=0.5, limit_px=3000.0, order_type={"limit": {"tif": "Gtc"}})

Place Post-Only Order (ALO)

result = exchange.order("ETH", is_buy=True, sz=0.5, limit_px=3000.0, order_type={"limit": {"tif": "Alo"}})

Place Stop-Loss Trigger

result = exchange.order("ETH", is_buy=True, sz=0.5, limit_px=2850.0,
    order_type={"trigger": {"triggerPx": "2900", "isMarket": True, "tpsl": "sl"}},
    reduce_only=True)

Place Take-Profit Trigger

result = exchange.order("ETH", is_buy=True, sz=0.5, limit_px=3200.0,
    order_type={"trigger": {"triggerPx": "3150", "isMarket": True, "tpsl": "tp"}},
    reduce_only=True)

Bulk Orders (atomic)

order_requests = [
    {"coin": "ETH", "is_buy": True, "sz": 0.1, "limit_px": 3000.0, "order_type": {"limit": {"tif": "Gtc"}}},
    {"coin": "ETH", "is_buy": True, "sz": 0.1, "limit_px": 2990.0, "order_type": {"limit": {"tif": "Gtc"}}},
]
result = exchange.bulk_orders(order_requests)

Get Balance and Positions

user_state = info.user_state(address)
# user_state["marginSummary"]["accountValue"]  — total account value
# user_state["marginSummary"]["totalMarginUsed"]  — margin in use
# user_state["assetPositions"]  — list of positions

Get Funding Rate

# Current funding rates (from meta)
meta = info.meta()
# Historical funding
history = info.funding_history("ETH", start_time=1681923833000)

Set Leverage

exchange.update_leverage(3, "ETH", is_cross=True)

Pitfalls

Asset index must be fetched from info.meta() — don't hardcode
Prices must respect tick size (check meta for szDecimals)
ALO orders are cancelled (not filled) if they would immediately match
Trigger orders need reduce_only=True for SL/TP
Funding settles every HOUR — different from most CEXes
Rate limit: 10,000 request buffer, then 1 per USDC traded
SDK requires Python 3.10 (some dependency issues on 3.11+)