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

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

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"