Hyperliquid Wiki Protocol & Ecosystem Knowledge Base
🔍

Developer APIs, SDKs & WebSockets

A comprehensive developer reference covering the REST Info and Exchange APIs, WebSocket real-time event feeds, Python and TypeScript client libraries, and Agent Wallet delegation.

💻 Developer Docs 🐍 Python / TS SDKs 📡 WebSocket L2 Feeds

1. API Endpoint Overview

Hyperliquid exposes three distinct interface layers for algorithmic traders and frontend integrations:

Interface Layer Protocol Endpoint Authentication / Purpose
Info API (REST) POST https://api.hyperliquid.xyz/info Public, read-only queries (market metadata, open interest, L2 books, user positions).
Exchange API (REST) POST https://api.hyperliquid.xyz/exchange Authenticated write actions (order placement, cancels, transfers, leverage modifications).
WebSocket API wss://api.hyperliquid.xyz/ws Sub-millisecond streaming telemetry (L2 order book deltas, trades, user fills).

2. Python SDK Quickstart

The official open-source Python SDK provides typed bindings and automatic EIP-712 cryptographic signature generation:

# Install official SDK via pip
pip install hyperliquid-python-sdk eth-account

Example: Placing an On-Chain Limit Order in Python

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

# 1. Initialize Info client (read-only)
info = Info(constants.MAINNET_API_URL, skip_ws=True)
user_state = info.user_state("0xYourAddress...")
print("Account Equity:", user_state["marginSummary"]["accountValue"])

# 2. Initialize Exchange client with private key / agent wallet
account = Account.from_key("0xYourPrivateKey...")
exchange = Exchange(account, constants.MAINNET_API_URL)

# 3. Place limit buy order on ETH perpetual (Coin, is_buy, sz, limit_px, order_type)
order_result = exchange.order(
    name="ETH",
    is_buy=True,
    sz=0.5,
    limit_px=2500.0,
    order_type={"limit": {"tif": "Gtc"}}
)
print("Order Response:", order_result)

3. TypeScript SDK Quickstart

npm install @hyperliquid/sdk ethers

Example: Fetching L2 Order Book Depth in Node.js / Browser

import { Hyperliquid } from '@hyperliquid/sdk';

async function fetchOrderBook() {
  const sdk = new Hyperliquid();
  const l2Book = await sdk.info.getL2Book('HYPE');
  
  console.log('Best Bid:', l2Book.levels[0][0]);
  console.log('Best Ask:', l2Book.levels[1][0]);
}

fetchOrderBook();

4. Real-Time WebSocket Streaming Subscriptions

Connect to wss://api.hyperliquid.xyz/ws and send JSON subscription messages to receive real-time updates without polling overhead:

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}
📡 l2Book Stream
Streams real-time top-of-book bid and ask price ladders and aggregate size updates upon every state transition.
⚡ trades Stream
Emits immediate notification of every executed trade matching on the L1 engine with timestamp, size, and side.
👤 userEvents Stream
Authenticated stream pushing private order fills, margin ratio alerts, and liquidation warnings directly to connected clients.
📊 candle Stream
Provides continuous OHLCV candlestick interval updates for charting libraries and technical analysis backends.

5. Agent Wallets & Security Delegation

🔐
Agent Wallet Architecture: Instead of deploying production trading bots with your master wallet's private key (which holds your funds), Hyperliquid allows you to authorize an Agent Wallet (API Key) on-chain. The agent wallet has permission to place and cancel trades on your behalf, but has zero authority to withdraw or transfer your collateral.
← Previous Chapter Bridge Security & Multi-Sig Next Chapter → FAQ, Glossary & Legal Notices

🔗 Official External References & Primary Sources

To verify the facts, technical formulas, and architectural parameters presented in this article, consult the following primary sources and official documentation: