hyperliquid

name	hyperliquid
description	Trade perpetual futures & spot on Hyperliquid DEX — market data, orders, positions, and vaults.
metadata	{"cryptoclaw":{"emoji":"💎","always":true}}

Hyperliquid DEX

Trade perpetual futures and spot tokens on Hyperliquid — a high-performance DEX built on its own L1 chain. USDC is the primary collateral for perpetuals; the native token is HYPE.

Base URLs

Mainnet:

POST https://api.hyperliquid.xyz/info      # read-only queries
POST https://api.hyperliquid.xyz/exchange   # signed trading actions
WSS  wss://api.hyperliquid.xyz/ws           # real-time subscriptions

Testnet:

POST https://api.hyperliquid-testnet.xyz/info
POST https://api.hyperliquid-testnet.xyz/exchange
WSS  wss://api.hyperliquid-testnet.xyz/ws

All requests use POST with JSON body Content-Type: application/json.

Info Endpoints (POST /info)

Perpetual Metadata

{ "type": "meta" }

Returns universe array (coin name, szDecimals, maxLeverage) and margin tables.

Metadata + Market Context

{ "type": "metaAndAssetCtxs" }

Returns metadata plus per-asset context: mark price, funding rate, open interest, 24h volume.

All Mid Prices

{ "type": "allMids" }

Returns { "BTC": "62345.5", "ETH": "3012.1", ... } — mid prices for every listed asset.

Order Book (L2)

{ "type": "l2Book", "coin": "BTC", "nSigFigs": 5 }

• nSigFigs: 2–5, controls price level grouping
• Returns levels: [[{px, sz, n}]] for bids and asks (up to 20 levels per side)

Candles (OHLCV)

{
  "type": "candleSnapshot",
  "req": { "coin": "ETH", "interval": "1h", "startTime": 1700000000000, "endTime": 1700100000000 }
}

Intervals: 1m, 3m, 5m, 15m, 30m, 1h, 2h, 4h, 8h, 12h, 1d, 1M

Returns: [{ t, T, s, i, o, c, h, l, v, n }] (open/close/high/low/volume).

Funding History

{ "type": "fundingHistory", "coin": "BTC", "startTime": 1700000000000 }

Returns array of { coin, fundingRate, premium, time }. Max 500 per query; paginate with last time.

User Account State (Perpetuals)

{ "type": "clearinghouseState", "user": "0x..." }

Returns: marginSummary (accountValue, totalMarginUsed, withdrawable), assetPositions array (coin, size, entryPx, unrealizedPnl, leverage, liquidationPx).

User Open Orders

{ "type": "openOrders", "user": "0x..." }

Returns array of { coin, side, limitPx, sz, oid, timestamp }.

User Fills

{ "type": "userFills", "user": "0x..." }

Returns array of { coin, px, sz, side, time, fee, oid, crossed }.

Order Status

{ "type": "orderStatus", "user": "0x...", "oid": 12345 }

Returns order details and current status (open, filled, cancelled).

Spot Metadata

{ "type": "spotMeta" }

Returns tokens array and universe (trading pairs with index, name, tokens).

Spot Metadata + Market Context

{ "type": "spotMetaAndAssetCtxs" }

Returns spot metadata plus per-pair context: mark price, mid price, 24h volume.

Spot Balances

{ "type": "spotClearinghouseState", "user": "0x..." }

Returns user's spot token balances.

Vault Details

{ "type": "vaultDetails", "vaultAddress": "0x..." }

Returns vault info: leader, followers, portfolio, APR, PnL history.

Exchange Endpoints (POST /exchange)

All exchange requests require EIP-712 signatures (see Authentication below).

Place Order

{
  "action": {
    "type": "order",
    "orders": [{
      "a": 0,
      "b": true,
      "p": "62000",
      "s": "0.01",
      "r": false,
      "t": { "limit": { "tif": "Gtc" } }
    }],
    "grouping": "na"
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

Fields:

• a: asset index (from meta universe)
• b: true = buy/long, false = sell/short
• p: price (string)
• s: size in base asset (string)
• r: reduce-only
• t: order type — { "limit": { "tif": "Gtc" } }, { "limit": { "tif": "Ioc" } }, or { "limit": { "tif": "Alo" } }

Time-in-force: Gtc (Good-til-Cancel), Ioc (Immediate-or-Cancel), Alo (Add-Liquidity-Only / post-only).

Cancel Order

{
  "action": {
    "type": "cancel",
    "cancels": [{ "a": 0, "o": 12345 }]
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

• a: asset index, o: order ID

Modify Order

{
  "action": {
    "type": "batchModify",
    "modifies": [{
      "oid": 12345,
      "order": { "a": 0, "b": true, "p": "63000", "s": "0.01", "r": false, "t": { "limit": { "tif": "Gtc" } } }
    }]
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

TWAP Order

{
  "action": {
    "type": "twapOrder",
    "twap": { "a": 0, "b": true, "s": "1.0", "r": false, "m": 10, "t": true }
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

• m: duration in minutes, t: randomize

Update Leverage

{
  "action": {
    "type": "updateLeverage",
    "asset": 0,
    "isCross": true,
    "leverage": 10
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

Update Isolated Margin

{
  "action": {
    "type": "updateIsolatedMargin",
    "asset": 0,
    "isBuy": true,
    "ntli": 100
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

• ntli: signed integer, positive to add margin, negative to remove

Transfer (Spot <-> Perp)

{
  "action": {
    "type": "usdClassTransfer",
    "amount": "100",
    "toPerp": true
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

Vault Deposit/Withdraw

{
  "action": {
    "type": "vaultTransfer",
    "vaultAddress": "0x...",
    "isDeposit": true,
    "usd": 1000000
  },
  "nonce": 1700000000000,
  "signature": { ... }
}

• usd: amount in raw units (6 decimals, e.g. 1000000 = 1 USDC)

WebSocket Subscriptions

Connect to wss://api.hyperliquid.xyz/ws and send:

{ "method": "subscribe", "subscription": { "type": "<channel>", ... } }

Channels

Channel	Params	Description
allMids	—	All mid prices (streaming)
trades	coin	Real-time trades for a coin
l2Book	coin	Order book updates
candle	coin, interval	Live candle updates
userEvents	user	Fills, order updates, margin changes for a user
liquidation	—	Real-time liquidation feed

Limits per connection: max 1000 subscriptions, max 2000 messages/min sent.

Authentication

Exchange endpoints require EIP-712 typed data signatures.

• Sign with the wallet private key (or an approved API wallet)
• nonce: current timestamp in milliseconds — must be unique and increasing
• signatureChainId: "0x66eee" for mainnet (chain ID 421614 hex), varies per environment
• Two signing schemes: sign_l1_action (for trading) and sign_user_signed_action (for agent setup)

Strongly recommended: Use the official Python SDK (hyperliquid-python-sdk) or a community TypeScript SDK for signing. Manual EIP-712 construction is error-prone.

Rate Limits

• Aggregate weight: 1200 per minute per IP
• Exchange actions: weight = 1 + floor(batch_size / 40)
• Info requests: weight 2–60 depending on endpoint
• When rate limited: 1 request per 10 seconds until window resets
• Open order limit: 1000 base + 1 per 5M USDC cumulative volume (max 5000)

Asset Reference (Perpetuals)

Common tickers (asset index from meta universe):

Ticker	Description
BTC	Bitcoin perpetual
ETH	Ethereum perpetual
SOL	Solana perpetual
BNB	BNB perpetual
ARB	Arbitrum perpetual
DOGE	Dogecoin perpetual
AVAX	Avalanche perpetual
MATIC	Polygon perpetual
OP	Optimism perpetual
APT	Aptos perpetual
SUI	Sui perpetual
HYPE	Hyperliquid native token perpetual

For the full list and exact asset indices, query { "type": "meta" }.

Spot assets use index 10000 + spotIndex (from spotMeta universe).

Security Rules

• ALWAYS show order details (side, size, price, leverage, estimated margin) before placing
• ALWAYS confirm with the user before submitting any order or modifying leverage
• NEVER place orders without explicit user approval
• Warn if leverage exceeds 10x or position notional exceeds $10,000
• Warn if the order book is thin (low liquidity at target price)
• For large positions, suggest using TWAP orders to reduce market impact
• Check clearinghouseState before orders to verify sufficient margin
• Default to Gtc limit orders — avoid Ioc market orders unless user explicitly requests
• Always display liquidation price after a position is opened

Example Interactions

User: "What's the current BTC price on Hyperliquid?" -> POST /info with { "type": "allMids" }, return BTC mid price

User: "Show me ETH order book" -> POST /info with { "type": "l2Book", "coin": "ETH", "nSigFigs": 5 } -> Display top 5 bid/ask levels with size

User: "Show my open positions" -> POST /info with { "type": "clearinghouseState", "user": "<active_wallet>" } -> Display positions table: coin, side, size, entry, unrealizedPnl, leverage, liqPx

User: "Long 0.1 BTC at $62,000 with 5x leverage" -> First set leverage: updateLeverage asset=BTC, leverage=5, isCross=true -> Then place order: buy 0.1 BTC @ $62,000 GTC -> Show order summary, ask for confirmation, then execute

User: "Cancel all my open orders" -> Query openOrders for user -> batch cancel all returned oids

User: "What's the funding rate for ETH?" -> POST /info with { "type": "metaAndAssetCtxs" }, extract ETH funding from asset context

User: "Show me the 4h ETH chart" -> POST /info with { "type": "candleSnapshot", "req": { "coin": "ETH", "interval": "4h", ... } } -> Summarize recent candles: open, close, high, low, volume trend

User: "Transfer 500 USDC from spot to perp wallet" -> POST /exchange with usdClassTransfer, amount="500", toPerp=true

Usage Notes

• All prices and sizes are strings in API requests/responses
• Pagination: max 500 results per query; use last time as startTime for next page
• Spot asset index = 10000 + index from spotMeta universe
• Testnet is recommended for development and testing
• Report data source: "Hyperliquid API, fetched just now"