Hyperliquid Market Data Guide

This skill provides guidance for fetching market data from Hyperliquid, including prices, order books, candles, and real-time WebSocket subscriptions.

REST Endpoints

All Mid Prices

Get current mid prices for all assets:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "allMids"}' | jq

Response:

{
  "BTC": "105234.5",
  "ETH": "3456.78",
  "SOL": "181.25",
  "@107": "28.45"
}

Note: Spot markets use @{index} format (e.g., @107 for HYPE/USDC).

---

Order Book (L2)

Get order book depth for a specific asset:

# BTC order book
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "l2Book", "coin": "BTC"}' | jq

Response:

{
  "coin": "BTC",
  "levels": [
    [
      {"px": "105230.0", "sz": "1.5", "n": 3},
      {"px": "105225.0", "sz": "2.1", "n": 5}
    ],
    [
      {"px": "105235.0", "sz": "0.8", "n": 2},
      {"px": "105240.0", "sz": "1.2", "n": 4}
    ]
  ],
  "time": 1704067200000
}

• levels[0] = bids (buy orders)
• levels[1] = asks (sell orders)
• n = number of orders at that price

---

Recent Trades

Get recent trades for an asset:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "recentTrades", "coin": "BTC"}' | jq

Response:

[
  {
    "coin": "BTC",
    "side": "B",
    "px": "105234.5",
    "sz": "0.1",
    "time": 1704067200000,
    "hash": "0x..."
  }
]

---

Candle Data (OHLCV)

Get historical candlestick data:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "candleSnapshot", "req": {"coin": "BTC", "interval": "1h", "startTime": 1704067200000, "endTime": 1704153600000}}' | jq

Response:

[
  {
    "t": 1704067200000,
    "T": 1704070800000,
    "s": "BTC",
    "i": "1h",
    "o": "105000.0",
    "c": "105234.5",
    "h": "105500.0",
    "l": "104800.0",
    "v": "1234.5",
    "n": 5678
  }
]

Candle Intervals

| Interval | Description | |----------|-------------| | 1m | 1 minute | | 5m | 5 minutes | | 15m | 15 minutes | | 1h | 1 hour | | 4h | 4 hours | | 1d | 1 day |

Candle Fields

| Field | Description | |-------|-------------| | t | Open timestamp (ms) | | T | Close timestamp (ms) | | o | Open price | | h | High price | | l | Low price | | c | Close price | | v | Volume | | n | Number of trades |

---

Meta and Asset Contexts

Get comprehensive market metadata with 24h stats:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "metaAndAssetCtxs"}' | jq

Response:

[
  {
    "universe": [
      {"name": "BTC", "szDecimals": 5, "maxLeverage": 50}
    ]
  },
  [
    {
      "funding": "0.0001",
      "openInterest": "12345.67",
      "prevDayPx": "104000.0",
      "dayNtlVlm": "1234567890.0",
      "premium": "0.0002",
      "oraclePx": "105230.0",
      "markPx": "105234.5",
      "midPx": "105234.5",
      "impactPxs": ["105230.0", "105240.0"]
    }
  ]
]

Asset Context Fields

| Field | Description | |-------|-------------| | funding | Current funding rate | | openInterest | Total open interest | | prevDayPx | Previous day close price (for 24h change) | | dayNtlVlm | 24h notional volume | | oraclePx | Oracle price | | markPx | Mark price | | midPx | Mid price | | impactPxs | Impact prices [bid, ask] |

---

Historical Funding Rates

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "fundingHistory", "coin": "BTC", "startTime": 1704067200000}' | jq

---

WebSocket Subscriptions

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

All Mids (Real-time Prices)

{
  "method": "subscribe",
  "subscription": {
    "type": "allMids"
  }
}

Order Book Updates

{
  "method": "subscribe",
  "subscription": {
    "type": "l2Book",
    "coin": "BTC"
  }
}

Trade Stream

{
  "method": "subscribe",
  "subscription": {
    "type": "trades",
    "coin": "BTC"
  }
}

Candle Updates

{
  "method": "subscribe",
  "subscription": {
    "type": "candle",
    "coin": "BTC",
    "interval": "1h"
  }
}

Key format: coin|interval (e.g., BTC|1h, xyz:NVDA|15m)

---

HIP-3 Markets

For HIP-3 builder-deployed markets, add the dex parameter:

REST Requests

# HIP-3 market metadata
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "meta", "dex": "xyz"}' | jq

# HIP-3 asset contexts
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "metaAndAssetCtxs", "dex": "xyz"}' | jq

WebSocket Subscriptions

{
  "method": "subscribe",
  "subscription": {
    "type": "allMids",
    "dex": "xyz"
  }
}

Candles for HIP-3

Use the full dex:ticker format:

curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "candleSnapshot", "req": {"coin": "xyz:NVDA", "interval": "1h", "startTime": 1704067200000}}' | jq

WebSocket key format: xyz:NVDA|1h

---

Spot Markets

Spot markets use different identifiers:

| Identifier | Example | Use For | |------------|---------|---------| | Market name | HYPE/USDC | Store keys, display | | API format | @107 | API calls, WebSocket | | Base token index | 73 | Balance matching |

Spot Candles

Use @{index} format (NOT the market name):

# HYPE/USDC candles (market index 107)
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "candleSnapshot", "req": {"coin": "@107", "interval": "1h", "startTime": 1704067200000}}' | jq

PURR Special Case

PURR (index 0) is the only spot market that uses a human-readable name in the API:

# PURR candles - use "PURR/USDC" not "@0"
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "candleSnapshot", "req": {"coin": "PURR/USDC", "interval": "1h", "startTime": 1704067200000}}' | jq

Wrapped Tokens

Some spot tokens are wrapped versions displayed differently:

| API Token | Display | |-----------|---------| | UBTC | BTC | | USOL | SOL | | UETH | ETH |

---

Rate Limits

• Aggregate limit: 1200 weight per minute per IP
• Weight 20: Most market data requests
• Variable weight: Historical data (+1 weight per 20 items)

Polling Recommendations

| Data Type | Frequency | |-----------|-----------| | Prices (allMids) | WebSocket preferred | | Order book | WebSocket preferred | | Candles | WebSocket for updates, REST for history | | Asset contexts | REST every 5-30 seconds |

---

Quick Reference

Get All Market Data

# Current prices
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "allMids"}' | jq

# Market metadata + 24h stats
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "metaAndAssetCtxs"}' | jq

# Order book
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "l2Book", "coin": "BTC"}' | jq

# Recent trades
curl -X POST https://api.hyperliquid.xyz/info \
  -H "Content-Type: application/json" \
  -d '{"type": "recentTrades", "coin": "BTC"}' | jq

Timestamp Helpers

# Current timestamp in milliseconds
date +%s000

# 24 hours ago
echo $(($(date +%s) - 86400))000

# 7 days ago
echo $(($(date +%s) - 604800))000

Common Calculations

24h Price Change: (currentPrice - prevDayPx) / prevDayPx * 100

Spread: askPrice - bidPrice

Spread %: (askPrice - bidPrice) / midPrice * 100