Hyperliquid Data Layer API

Real-time liquidation tracking, whale monitoring, smart money signals, and position analytics.

Base URL: https://api.moondev.com

Version: 1.0

Updated: 2026-01-14

Quick Startcopy & run

Copy-paste this to test your API key instantly:

curl "https://api.moondev.com/api/ticks/btc.json?api_key=YOUR_API_KEY"

Or in Python:

import requests

data = requests.get(
    "https://api.moondev.com/api/ticks/btc.json",
    headers={"X-API-Key": "YOUR_API_KEY"}
).json()

print(f"BTC Price: ${data['latest_price']:,.2f}")

Need an API key?

Common Errors & Fixes

Error	Cause	Fix
401 Unauthorized	Missing or invalid API key	Add ?api_key=YOUR_KEY to URL or use X-API-Key header
404 Not Found	Uppercase symbol (BTC.json)	Use lowercase: btc.json not BTC.json
404 Not Found	Missing .json extension	Add .json: /api/ticks/btc.json

Authentication

All /api/* endpoints require authentication via API key.Need an API key?

Method 1: Query Parameter

?api_key=YOUR_API_KEY

Method 2: Header (Recommended)

X-API-Key: YOUR_API_KEY

Error Response (401)

{
  "error": "Unauthorized",
  "message": "Valid API key required. Use ?api_key=YOUR_KEY or X-API-Key header"
}

Rate Limits & Caching

Setting	Value
Rate Limit	60 requests/second sustained, burst up to 200
Response Format	JSON (Content-Type: application/json)

Health & Info

Endpoint	Auth	Description
GET /health	No	Health check
GET /	No	API info and endpoint listing

{"status": "ok", "service": "hyperliquid-data-layer"}

Market Data

Drop-in replacements for Hyperliquid API calls. All requests go through Moon Dev's local node.

These endpoints replace metaAndAssetCtxs, l2Book, clearinghouseState, userFills, and candleSnapshot.

Prices (All 224 Coins)

Endpoint	Description
GET /api/prices	All prices, funding rates, and OI for 224 coins (replaces metaAndAssetCtxs)
GET /api/price/{coin}	Quick single-coin price with bid/ask/spread (e.g., /api/price/BTC)

Orderbook

Endpoint	Description
GET /api/orderbook/{coin}	L2 orderbook with ~20 levels each side (replaces l2Book)

Account & Fills

Endpoint	Description
GET /api/account/{address}	Full account state for any wallet (replaces clearinghouseState)
GET /api/fills/{address}?limit=N	Trade fills in Hyperliquid-compatible format (replaces userFills)

Candles (OHLCV)

Endpoint	Description
GET /api/candles/{coin}?interval=1h	OHLCV candles (intervals: 1m, 5m, 15m, 1h, 4h, 1d)

Available symbols: BTC, ETH, HYPE, SOL, XRP

Response Example (/api/prices)

{
  "count": 224,
  "timestamp": "2026-01-14T12:00:00Z",
  "prices": {
    "BTC": "94500.50",
    "ETH": "3250.25",
    "SOL": "185.30"
  },
  "funding_rates": {
    "BTC": "0.0001",
    "ETH": "0.00008"
  },
  "open_interest": {
    "BTC": "125000.5",
    "ETH": "850000.2"
  }
}

Response Example (/api/price/BTC)

{
  "symbol": "BTC",
  "best_bid": "94500.00",
  "best_bid_size": "2.5",
  "best_ask": "94501.00",
  "best_ask_size": "1.8",
  "mid_price": "94500.50",
  "spread": "1.00",
  "spread_bps": "0.11",
  "timestamp": "2026-01-14T12:00:00Z"
}

Response Example (/api/orderbook/BTC)

{
  "symbol": "BTC",
  "best_bid": "94500.00",
  "best_ask": "94501.00",
  "mid_price": "94500.50",
  "spread_bps": "0.11",
  "bid_depth": 20,
  "ask_depth": 20,
  "levels": [
    [
      {"px": "94500.0", "sz": "2.5"},
      {"px": "94499.0", "sz": "1.2"}
    ],
    [
      {"px": "94501.0", "sz": "1.8"},
      {"px": "94502.0", "sz": "3.1"}
    ]
  ]
}

Response Example (/api/candles/BTC?interval=1h)

[
  {
    "t": 1736856000000,
    "o": "94200.0",
    "h": "94600.0",
    "l": "94100.0",
    "c": "94500.0",
    "n": 1250
  }
]

Migration Cheatsheet

Old Hyperliquid Call	New Moon Dev API
{"type": "metaAndAssetCtxs"}	GET /api/prices
{"type": "l2Book", "coin": "BTC"}	GET /api/orderbook/BTC
{"type": "clearinghouseState", "user": "0x..."}	GET /api/account/0x...
{"type": "userFills", "user": "0x..."}	GET /api/fills/0x...
{"type": "candleSnapshot", ...}	GET /api/candles/BTC?interval=1h

Python Example

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.moondev.com"
headers = {"X-API-Key": API_KEY}

# Get all prices (replaces metaAndAssetCtxs)
prices = requests.get(f"{BASE_URL}/api/prices", headers=headers).json()
print(f"BTC: ${prices['prices']['BTC']}")
print(f"Loaded {prices['count']} coins")

# Quick price check
btc = requests.get(f"{BASE_URL}/api/price/BTC", headers=headers).json()
print(f"Mid: ${btc['mid_price']} | Spread: {btc['spread_bps']} bps")

# Get orderbook (replaces l2Book)
book = requests.get(f"{BASE_URL}/api/orderbook/BTC", headers=headers).json()
print(f"Best Bid: ${book['best_bid']} | Best Ask: ${book['best_ask']}")

# Get account state (replaces clearinghouseState)
wallet = "0x1234567890abcdef..."
account = requests.get(f"{BASE_URL}/api/account/{wallet}", headers=headers).json()
print(f"Account Value: ${account['marginSummary']['accountValue']}")

# Get candles
candles = requests.get(
    f"{BASE_URL}/api/candles/BTC?interval=1h",
    headers=headers
).json()
print(f"Latest close: ${candles[-1]['c']}")

Core Data

Endpoint	Description
GET /api/positions.json	Top 50 positions across ALL symbols (fast, 1s updates)
GET /api/positions/all.json	All 148 symbols with top 50 positions each (500KB, 60s updates)
GET /api/whales.json	Recent whale trades ($25k+, buys & sells)
GET /api/buyers.json	Recent buyers only ($5k+, HYPE/SOL/XRP/ETH)
GET /api/depositors.json	All Hyperliquid depositors - canonical address list
GET /api/whale_addresses.txt	Plain text list of whale addresses

Response Example (depositors.json)

{
  "updated_at": "2026-01-14T12:00:00Z",
  "stats": {
    "total_count": 125000,
    "total_deposited": 2500000000
  },
  "depositors": [
    {
      "address": "0x1234567890abcdef...",
      "amount": 50000,
      "timestamp": "2026-01-14T11:30:00Z"
    }
  ]
}

The depositors endpoint contains every wallet that has ever bridged USDC to Hyperliquid - the canonical address list.

Tick Data

Real-time price ticks for BTC, ETH, HYPE, SOL, XRP.

⚠️ IMPORTANT: Symbols MUST be lowercase. BTC.json returns 404. Use btc.json

Available symbols (lowercase only): btc, eth, hype, sol, xrp

Endpoint	Description
GET /api/ticks/stats.json	Collection statistics
GET /api/ticks/latest.json	Current prices for all symbols
GET /api/ticks/btc.json	Latest hour of ticks (example: btc)
GET /api/ticks/btc_10m.json	Last 10 minutes
GET /api/ticks/btc_1h.json	Last 1 hour
GET /api/ticks/btc_4h.json	Last 4 hours
GET /api/ticks/btc_24h.json	Last 24 hours
GET /api/ticks/btc_7d.json	Last 7 days

Replace btc with any symbol: eth, hype, sol, xrp

Response Example (stats.json)

{
  "generated_at": "2026-01-06T19:17:38Z",
  "symbols": ["BTC", "ETH", "HYPE", "SOL", "XRP"],
  "collector_stats": {
    "ticks_collected": 1552,
    "ticks_saved": 1552,
    "errors": 0,
    "started_at": "2026-01-06T19:03:35Z"
  },
  "db_size_mb": 0.16,
  "symbol_stats": {
    "BTC": {
      "tick_count": 251,
      "min_price": 91950.5,
      "max_price": 92296.0,
      "last_price": 92256.5
    }
  }
}

Response Example (btc_1h.json)

{
  "symbol": "BTC",
  "generated_at": "2026-01-06T19:17:38Z",
  "duration": "1h",
  "tick_count": 251,
  "latest_price": 92256.5,
  "ticks": [
    {"timestamp": 1767726130918, "price": 91950.5, "datetime": "2026-01-06T19:02:10Z"}
  ]
}

Blockchain Events

Endpoint	Description
GET /api/events.json	Real-time decoded blockchain events from Hyperliquid L1

{
  "updated_at": "2026-01-06T19:17:00Z",
  "stats": {
    "total_events": 2424,
    "events_by_type": {
      "Transfer": 1200,
      "Swap": 500,
      "Approval": 200,
      "Deposit": 150,
      "Withdrawal": 100
    }
  },
  "recent_events": [
    {
      "block_number": 23863116,
      "tx_hash": "0x...",
      "event_type": "Transfer",
      "contract": "0x5555555555555555555555555555555555555555",
      "timestamp": "2026-01-06T19:17:00Z"
    }
  ]
}

Contract Registry

Endpoint	Description
GET /api/contracts.json	Complete registry of Hyperliquid EVM smart contracts

{
  "generated_at": "2026-01-06T18:54:45Z",
  "chain": "hyperliquid_evm",
  "chain_id": 999,
  "total_contracts": 27,
  "high_value_count": 12,
  "key_contracts": {
    "system_treasury": "0x2222222222222222222222222222222222222222",
    "whype": "0x5555555555555555555555555555555555555555",
    "core_trading": "0x8549fd7ffc092f8366e416e129a622ec060104ea",
    "deposit_bridge": "0x5ed8551f90acc6395810d8274b019bf13ef1f696",
    "oracle": "0x200302c99d93ae1a024ecf9475df7d71b125efed"
  },
  "liquidation_contracts": ["0x8549...", "0x2003..."],
  "trading_alpha_contracts": ["0x8549...", "0x2180..."],
  "contracts": [
    {
      "address": "0x2222222222222222222222222222222222222222",
      "name": "Hyperliquid System Treasury",
      "type": "system",
      "description": "System treasury holding 954M+ HYPE",
      "is_high_value": true,
      "monitoring_priority": 10
    }
  ]
}

Hyperliquid Liquidations

Real-time liquidation data from Hyperliquid DEX.

Endpoint	Description
GET /api/liquidations/stats.json	Liquidation monitoring statistics
GET /api/liquidations/scan_summary.json	Recent liquidation scan results
GET /api/liquidations/10m.json	Last 10 minutes
GET /api/liquidations/1h.json	Last 1 hour
GET /api/liquidations/4h.json	Last 4 hours
GET /api/liquidations/12h.json	Last 12 hours
GET /api/liquidations/24h.json	Last 24 hours
GET /api/liquidations/2d.json	Last 2 days
GET /api/liquidations/7d.json	Last 7 days
GET /api/liquidations/14d.json	Last 14 days
GET /api/liquidations/30d.json	Last 30 days

{
  "scan_timestamp": "2026-01-06T19:00:00Z",
  "blocks_scanned": 500,
  "total_alerts": 150,
  "critical_count": 5,
  "warning_count": 25,
  "alerts": [
    {
      "timestamp": "2026-01-06T18:55:00Z",
      "block_number": 23863000,
      "tx_hash": "0x...",
      "contract_name": "Core Trading",
      "alert_type": "trade_executed",
      "level": "info"
    }
  ]
}

Alert Levels: info, warning, critical

HIP3 Liquidations (TradFi Assets)

Real-time liquidation data for traditional finance assets trading on Hyperliquid. Includes stocks, commodities, indices, and forex pairs.

Asset Categories

Category	Assets	Approx OI
Stocks	TSLA, NVDA, AAPL, META, MSFT, GOOGL, AMZN, AMD, INTC, PLTR, COIN, HOOD, MSTR, ORCL, MU, NFLX, RIVN, BABA	~$100M+
Commodities	GOLD, SILVER, COPPER, CL (Oil), NATGAS, URANIUM	~$125M
Indices	XYZ100 (Nasdaq proxy)	~$120M
FX	EUR, JPY	~$3M

Get HIP3 Liquidations

Endpoint	Description
GET /api/hip3_liquidations/10m.json	Last 10 minutes
GET /api/hip3_liquidations/1h.json	Last 1 hour
GET /api/hip3_liquidations/24h.json	Last 24 hours
GET /api/hip3_liquidations/7d.json	Last 7 days

Response Fields

Field	Type	Description
symbol	string	Asset symbol (TSLA, GOLD, etc.)
side	string	long or short
size	number	Position size
price	number	Liquidation price
value_usd	number	USD value of liquidation
category	string	stocks, commodities, indices, or fx
timestamp	number	Event timestamp (Unix ms)

Get HIP3 Liquidation Stats

Endpoint	Description
GET /api/hip3_liquidations/stats.json	Aggregated statistics for HIP3 liquidations

Stats Response Fields

Field	Type	Description
total_count	number	Total liquidation count
total_volume	number	Total USD volume liquidated
long_count	number	Number of long liquidations
short_count	number	Number of short liquidations
long_volume	number	USD volume of long liquidations
short_volume	number	USD volume of short liquidations
by_category	object	Breakdown by category (stocks, commodities, indices, fx)
by_symbol	object	Breakdown by individual symbol
top_symbols	array	Top symbols by liquidation volume

Example Request

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_liquidations/1h.json

Python SDK Usage

from api import MoonDevAPI

api = MoonDevAPI()

# Get HIP3 liquidation stats
stats = api.get_hip3_liquidation_stats()
print(f"Total liquidations: {stats['total_count']}")
print(f"Total volume: ${stats['total_volume']:,.0f}")

# Get HIP3 liquidations for different timeframes
liqs_10m = api.get_hip3_liquidations("10m")   # Last 10 minutes
liqs_1h = api.get_hip3_liquidations("1h")     # Last 1 hour
liqs_24h = api.get_hip3_liquidations("24h")   # Last 24 hours
liqs_7d = api.get_hip3_liquidations("7d")     # Last 7 days

# Process liquidation data
for liq in liqs_1h:
    print(f"{liq['symbol']} {liq['side'].upper()} ${liq['value_usd']:,.0f} @ ${liq['price']}")

Use Cases

Risk Management - Monitor liquidation activity across traditional finance assets to gauge market stress
Trading Signals - High liquidation volume in one direction may indicate squeeze potential
Market Analysis - Track which asset categories are seeing the most liquidation activity
Alert Systems - Build alerts for large liquidations on specific symbols

Rate limit: 3,600 requests per minute. Data updates in real-time. Historical data available up to 7 days.

HIP3 Market Data (Multi-Dex)

Real-time tick data for 58 traditional finance and crypto assets across 5 different dexes on Hyperliquid via WebSocket streaming.

Dex Breakdown (58 Symbols)

Dex	Count	Focus	Symbols
xyz	27	Stocks, Commodities, FX	AAPL, AMD, AMZN, BABA, CL, COIN, COPPER, CRCL, EUR, GOLD, GOOGL, HOOD, INTC, JPY, META, MSFT, MSTR, MU, NFLX, NVDA, ORCL, PLTR, RIVN, SILVER, SNDK, TSLA, XYZ100
flx	7	Stocks, XMR, Commodities	COIN, CRCL, GOLD, OIL, SILVER, TSLA, XMR
vntl	7	Pre-IPO & Indices	ANTHROPIC, INFOTECH, MAG7, OPENAI, ROBOT, SEMIS, SPACEX
hyna	12	Crypto	BNB, BTC, DOGE, ETH, FARTCOIN, HYPE, LIGHTER, PUMP, SOL, SUI, XRP, ZEC
km	5	US Indices	BABA, SMALL2000, TSLA, US500, USTECH

Category Breakdown

Category	Count
Stocks	25
Indices	8
Commodities	7
FX	2
Crypto	13
Pre-IPO	3

Symbol Format: {dex}:{ticker} (e.g., xyz:TSLA, hyna:BTC, km:US500, vntl:OPENAI)

Get All HIP3 Symbols & Prices

Endpoint	Description
GET /api/hip3/meta	Returns all 58 symbols with current prices organized by dex
GET /api/hip3/meta?include_delisted=true	Include delisted symbols

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3/meta

Get Tick Collector Stats

Endpoint	Description
GET /api/hip3_ticks/stats.json	Returns tick collector statistics including all 58 symbols

{
  "generated_at": "2026-01-19T14:02:35Z",
  "market_type": "HIP3",
  "collection_method": "WebSocket Streaming",
  "dexes": ["xyz", "flx", "vntl", "hyna", "km"],
  "dex_counts": {
    "xyz": 27, "flx": 7, "vntl": 7, "hyna": 12, "km": 5
  },
  "symbols": [
    "xyz:TSLA", "xyz:NVDA", "xyz:GOLD", "hyna:BTC", "vntl:OPENAI", ...
  ],
  "symbol_count": 58,
  "collector_stats": {
    "ticks_received": 4550,
    "ticks_saved": 2136
  },
  "by_category": {
    "stocks": 25, "indices": 8, "commodities": 7,
    "fx": 2, "crypto": 13, "pre_ipo": 3
  }
}

Get Individual Symbol Tick Data

Endpoint	Description
GET /api/hip3_ticks/{dex}_{ticker}.json	Returns tick data for a specific symbol

XYZ Dex (27) - Stocks, Commodities, FX

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/xyz_tsla.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/xyz_nvda.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/xyz_gold.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/xyz_eur.json

FLX Dex (7) - Stocks, XMR, Commodities

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/flx_xmr.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/flx_gold.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/flx_oil.json

VNTL Dex (7) - Pre-IPO & Indices

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/vntl_openai.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/vntl_anthropic.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/vntl_spacex.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/vntl_mag7.json

HYNA Dex (12) - Crypto

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/hyna_btc.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/hyna_eth.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/hyna_hype.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/hyna_sol.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/hyna_fartcoin.json

KM Dex (5) - US Indices

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/km_us500.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/km_ustech.json
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3_ticks/km_small2000.json

Python SDK Usage

from api import MoonDevAPI

api = MoonDevAPI()

# Get all HIP3 symbols with prices
meta = api.get_hip3_meta()
for sym in meta['symbols']:
    print(f"{sym['dex']}:{sym['ticker']} = ${sym['price']}")

# Get tick stats
stats = api.get_hip3_tick_stats()
print(f"Symbols: {stats['symbol_count']}")
print(f"Ticks received: {stats['collector_stats']['ticks_received']}")

# Get tick data by dex:ticker
tsla = api.get_hip3_ticks("xyz", "tsla")      # Tesla
openai = api.get_hip3_ticks("vntl", "openai") # OpenAI Pre-IPO
btc = api.get_hip3_ticks("hyna", "btc")       # Bitcoin
sp500 = api.get_hip3_ticks("km", "us500")     # S&P 500

Example Dashboard

python examples/21_hip3_market_data.py               # All 58 symbols with prices
python examples/21_hip3_market_data.py xyz tsla      # Tesla ticks
python examples/21_hip3_market_data.py vntl openai   # OpenAI Pre-IPO ticks
python examples/21_hip3_market_data.py hyna btc      # Bitcoin ticks
python examples/21_hip3_market_data.py km us500      # S&P 500 ticks

Legacy Endpoints (Still Supported)

The following endpoints from the original HIP3 Market Data are still available:

Endpoint	Description
GET /api/hip3/candles/symbols	List all symbols organized by category
GET /api/hip3/prices	All prices at once
GET /api/hip3/price/{coin}	Single symbol price
GET /api/hip3/candles/{coin}?interval=	OHLCV candles (1m, 5m, 15m, 1h, 4h, 1d)
GET /api/hip3/ticks/{coin}?duration=	Raw tick data (10m, 1h, 4h, 24h, 7d)

List All HIP3 Symbols

Endpoint	Description
GET /api/hip3/candles/symbols	Returns all 33 HIP3 symbols organized by category

{
  "count": 33,
  "categories": {
    "stocks": ["TSLA", "NVDA", "META", "AAPL", ...],
    "commodities": ["GOLD", "SILVER", "CL", "COPPER", "NATGAS", "URANIUM"],
    "fx": ["JPY", "EUR"],
    "indices": ["XYZ100"]
  },
  "symbols": ["TSLA", "NVDA", "META", ...]
}

Get All HIP3 Prices

Endpoint	Description
GET /api/hip3/prices	Returns current prices for all 33 HIP3 symbols

{
  "timestamp": "2026-01-19T13:09:00Z",
  "count": 33,
  "prices": {
    "TSLA": {"price": 431.64, "category": "stocks"},
    "GOLD": {"price": 4672.30, "category": "commodities"},
    "EUR": {"price": 1.0285, "category": "fx"},
    "XYZ100": {"price": 21450.50, "category": "indices"}
  }
}

Get Single Symbol Price

Endpoint	Description
GET /api/hip3/price/{coin}	Returns current price for a single HIP3 symbol

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/hip3/price/TSLA

{
  "symbol": "TSLA",
  "price": 431.64,
  "category": "stocks",
  "timestamp": "2026-01-19T13:09:39.215000+00:00"
}

Get OHLCV Candles

Endpoint	Description
GET /api/hip3/candles/{coin}?interval={interval}	Returns OHLCV candle data for any HIP3 symbol

Param	Default	Description
coin	required	Symbol (TSLA, GOLD, EUR, XYZ100, etc.)
interval	5m	Candle interval: 1m, 5m, 15m, 1h, 4h, 1d
startTime	auto	Start timestamp (Unix ms)
endTime	now	End timestamp (Unix ms)

curl -H "X-API-Key: YOUR_KEY" "https://api.moondev.com/api/hip3/candles/TSLA?interval=1h"

[
  {
    "t": 1737288000000,
    "T": 1737291599999,
    "s": "TSLA",
    "i": "1h",
    "o": "430.50",
    "h": "432.20",
    "l": "429.80",
    "c": "431.90",
    "v": "0",
    "n": 245
  }
]

Candle Response Fields

Field	Description
t	Open time (Unix ms)
T	Close time (Unix ms)
s	Symbol
i	Interval
o	Open price
h	High price
l	Low price
c	Close price
v	Volume
n	Number of ticks in candle

Get Raw Tick Data

Endpoint	Description
GET /api/hip3/ticks/{coin}?duration={duration}	Returns raw tick-by-tick price data for any HIP3 symbol

Param	Default	Description
coin	required	Symbol (TSLA, GOLD, EUR, XYZ100, etc.)
duration	1h	Time window: 10m, 1h, 4h, 24h, 7d
limit	10000	Max ticks to return
startTime	-	Start time (Unix ms), overrides duration
endTime	-	End time (Unix ms)

curl -H "X-API-Key: YOUR_KEY" "https://api.moondev.com/api/hip3/ticks/GOLD?duration=1h"

{
  "symbol": "GOLD",
  "duration": "1h",
  "tick_count": 112,
  "latest_price": 4672.40,
  "ticks": [
    {
      "t": 1737288000000,
      "p": 4671.50,
      "dt": "2026-01-19T13:00:00.000000+00:00"
    },
    {
      "t": 1737288003000,
      "p": 4671.80,
      "dt": "2026-01-19T13:00:03.000000+00:00"
    }
  ]
}

Python SDK Usage

from api import MoonDevAPI

api = MoonDevAPI()

# Get all HIP3 symbols by category
symbols = api.get_hip3_symbols()
print(f"{symbols['count']} symbols available")
print(f"Stocks: {symbols['categories']['stocks']}")
print(f"Commodities: {symbols['categories']['commodities']}")

# Get all HIP3 prices at once
prices = api.get_hip3_prices()
print(f"TSLA: ${prices['prices']['TSLA']['price']}")
print(f"GOLD: ${prices['prices']['GOLD']['price']}")

# Get single symbol price
tsla = api.get_hip3_price("TSLA")
print(f"TSLA: ${tsla['price']} ({tsla['category']})")

# Get OHLCV candles
candles = api.get_hip3_candles("TSLA", interval="5m")
for c in candles[-5:]:
    print(f"O:{c['o']} H:{c['h']} L:{c['l']} C:{c['c']}")

# Get 1-hour candles for GOLD
gold_candles = api.get_hip3_candles("GOLD", interval="1h")

# Get daily candles
daily = api.get_hip3_candles("NVDA", interval="1d")

# Get raw tick data
ticks = api.get_hip3_ticks("TSLA", duration="1h")
print(f"{ticks['tick_count']} ticks, latest: ${ticks['latest_price']}")

# Get 24h of tick data
ticks_24h = api.get_hip3_ticks("GOLD", duration="24h")

# Custom time range (Unix ms)
ticks = api.get_hip3_ticks("EUR", start_time=1737280000000, end_time=1737290000000)

Use Cases

Technical Analysis - Build charts and indicators using OHLCV candles
Algorithmic Trading - Use tick data for high-frequency strategies
Cross-Asset Analysis - Compare crypto with TradFi assets on same platform
Price Alerts - Monitor tick-by-tick price changes for specific assets
Backtesting - Historical candle data for strategy testing

Data Collection Details

Polling Interval: 500ms (only stores price changes)
Auto-Discovery: New symbols detected every 5 minutes
Candle Intervals: 1m, 5m, 15m, 1h, 4h, 1d
Tick Durations: 10m, 1h, 4h, 24h, 7d

Rate limit: 3,600 requests per minute. Data updates at 500ms intervals. Tick data stored only on price changes.

Multi-Exchange Liquidations

Real-time liquidation data from multiple exchanges: Binance, Bybit, and OKX. Get individual exchange data or combined aggregated stats across all exchanges.

Combined (All Exchanges)

Endpoint	Description
GET /api/all_liquidations/stats.json	Combined stats from Binance + Bybit + OKX
GET /api/all_liquidations/10m.json	Last 10 minutes (all exchanges)
GET /api/all_liquidations/1h.json	Last hour (all exchanges)
GET /api/all_liquidations/24h.json	Last 24 hours (all exchanges)
GET /api/all_liquidations/7d.json	Last 7 days (all exchanges)
GET /api/all_liquidations/30d.json	Last 30 days (all exchanges)

Binance Liquidations

Endpoint	Description
GET /api/binance_liquidations/stats.json	Binance stats (24h volume, counts, top coins)
GET /api/binance_liquidations/10m.json	Last 10 minutes
GET /api/binance_liquidations/1h.json	Last hour
GET /api/binance_liquidations/24h.json	Last 24 hours
GET /api/binance_liquidations/7d.json	Last 7 days
GET /api/binance_liquidations/30d.json	Last 30 days

Bybit Liquidations

Endpoint	Description
GET /api/bybit_liquidations/stats.json	Bybit stats (24h volume, counts, top coins)
GET /api/bybit_liquidations/10m.json	Last 10 minutes
GET /api/bybit_liquidations/1h.json	Last hour
GET /api/bybit_liquidations/24h.json	Last 24 hours
GET /api/bybit_liquidations/7d.json	Last 7 days
GET /api/bybit_liquidations/30d.json	Last 30 days

OKX Liquidations

Endpoint	Description
GET /api/okx_liquidations/stats.json	OKX stats (24h volume, counts, top coins)
GET /api/okx_liquidations/10m.json	Last 10 minutes
GET /api/okx_liquidations/1h.json	Last hour
GET /api/okx_liquidations/24h.json	Last 24 hours
GET /api/okx_liquidations/7d.json	Last 7 days
GET /api/okx_liquidations/30d.json	Last 30 days

Response Example (all_liquidations/stats.json)

{
  "updated_at": "2026-01-09T12:00:00Z",
  "exchanges": ["binance", "bybit", "okx"],
  "combined": {
    "total_liquidations": 45000,
    "total_value_usd": 380000000,
    "long_liquidations": {
      "count": 25000,
      "value_usd": 215000000
    },
    "short_liquidations": {
      "count": 20000,
      "value_usd": 165000000
    }
  },
  "by_exchange": {
    "binance": {"count": 18000, "value_usd": 165000000},
    "bybit": {"count": 15000, "value_usd": 125000000},
    "okx": {"count": 12000, "value_usd": 90000000}
  },
  "top_liquidated_coins": [
    {"symbol": "BTC", "value_usd": 125000000, "count": 9500},
    {"symbol": "ETH", "value_usd": 85000000, "count": 8200},
    {"symbol": "SOL", "value_usd": 45000000, "count": 5100}
  ]
}

Response Example (binance_liquidations/1h.json)

{
  "exchange": "binance",
  "timeframe": "1h",
  "generated_at": "2026-01-09T12:00:00Z",
  "stats": {
    "total_count": 850,
    "long_count": 480,
    "short_count": 370,
    "total_value_usd": 8500000,
    "long_value_usd": 5200000,
    "short_value_usd": 3300000
  },
  "liquidations": [
    {
      "symbol": "BTCUSDT",
      "side": "SELL",
      "quantity": 0.15,
      "price": 42500.00,
      "value_usd": 6375.00,
      "timestamp": "2026-01-09T11:55:00Z"
    }
  ]
}

Python Example - Multi-Exchange

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.moondev.com"
headers = {"X-API-Key": API_KEY}

# Get combined stats from ALL exchanges
all_stats = requests.get(
    f"{BASE_URL}/api/all_liquidations/stats.json",
    headers=headers
).json()

print("=== COMBINED LIQUIDATIONS (All Exchanges) ===")
print(f"Total Volume: ${all_stats['combined']['total_value_usd']:,.0f}")
print(f"Longs Rekt:   ${all_stats['combined']['long_liquidations']['value_usd']:,.0f}")
print(f"Shorts Rekt:  ${all_stats['combined']['short_liquidations']['value_usd']:,.0f}")

print("\n=== BY EXCHANGE ===")
for exchange, data in all_stats['by_exchange'].items():
    print(f"{exchange.upper()}: {data['count']:,} liquidations, ${data['value_usd']:,.0f}")

# Get individual exchange data
for exchange in ["binance", "bybit", "okx"]:
    hourly = requests.get(
        f"{BASE_URL}/api/{exchange}_liquidations/1h.json",
        headers=headers
    ).json()
    print(f"\n{exchange.upper()} Last Hour: {hourly['stats']['total_count']} liquidations")

Note: side: "SELL" = Long position liquidated, side: "BUY" = Short position liquidated.

Smart Money

Endpoint	Description
GET /api/smart_money/rankings.json	Top 100 smart + Bottom 100 dumb money by PnL
GET /api/smart_money/leaderboard.json	Top 50 performers with detailed metrics
GET /api/smart_money/signals_10m.json	Trading signals - last 10 minutes
GET /api/smart_money/signals_1h.json	Trading signals - last 1 hour
GET /api/smart_money/signals_24h.json	Trading signals - last 24 hours

Response Example (rankings.json)

{
  "updated_at": "2026-01-06T19:17:19Z",
  "total_tracked_addresses": 3488,
  "smart_money": {
    "description": "Top 100 most profitable addresses",
    "count": 100,
    "addresses": [
      {
        "address": "0x...",
        "total_pnl": 5000000.00,
        "win_rate": 0.72,
        "total_trades": 500
      }
    ]
  },
  "dumb_money": {
    "description": "Bottom 100 least profitable addresses",
    "count": 100,
    "addresses": []
  }
}

Response Example (signals_1h.json)

{
  "updated_at": "2026-01-06T19:17:19Z",
  "duration": "1h",
  "signals": [
    {
      "timestamp": "2026-01-06T19:15:00Z",
      "address": "0x...",
      "address_type": "smart_money",
      "action": "open_long",
      "coin": "BTC",
      "size": 2.5,
      "price": 92000.0,
      "leverage": 10
    }
  ]
}

Trades & Order Flow

Endpoint	Description
GET /api/trades.json	Recent trades (last 1000)
GET /api/large_trades.json	Large trades only (>$100k)
GET /api/orderflow.json	Current order flow metrics
GET /api/orderflow/stats.json	Order flow statistics
GET /api/imbalance/5m.json	Buy/sell imbalance - 5 minutes
GET /api/imbalance/15m.json	Buy/sell imbalance - 15 minutes
GET /api/imbalance/1h.json	Buy/sell imbalance - 1 hour
GET /api/imbalance/4h.json	Buy/sell imbalance - 4 hours
GET /api/imbalance/24h.json	Buy/sell imbalance - 24 hours

Response Example (trades.json)

{
  "updated_at": "2026-01-06T19:17:00Z",
  "trade_count": 1000,
  "trades": [
    {
      "timestamp": 1767727000000,
      "coin": "BTC",
      "side": "buy",
      "size": 0.5,
      "price": 92000.0,
      "value_usd": 46000.0,
      "is_large": false
    }
  ]
}

Response Example (orderflow.json)

{
  "updated_at": "2026-01-06T19:17:00Z",
  "window": "5m",
  "metrics": {
    "BTC": {
      "buy_volume": 5000000.0,
      "sell_volume": 4500000.0,
      "net_flow": 500000.0,
      "buy_count": 150,
      "sell_count": 140,
      "imbalance_ratio": 1.11
    }
  }
}

Response Example (imbalance/1h.json)

{
  "updated_at": "2026-01-06T19:17:00Z",
  "duration": "1h",
  "imbalance": {
    "BTC": {
      "buy_volume": 15000000.0,
      "sell_volume": 12000000.0,
      "imbalance": 3000000.0,
      "imbalance_pct": 20.0,
      "signal": "bullish"
    }
  }
}

Signals: bullish, bearish, neutral

User Data (Local Node)

Get positions and trade history for any Hyperliquid wallet. Powered by Moon Dev's local node for fast responses.

Endpoint	Description
GET /api/user/{address}/positions	Current positions for any wallet
GET /api/user/{address}/fills?limit=N	Historical fills (default: 100, max: 2000, -1 for ALL)

Response Example (positions)

{
  "address": "0xABC123...",
  "positions": [
    {
      "symbol": "BTC",
      "side": "long",
      "size": 0.5,
      "size_usd": 21250,
      "entry_price": 42500,
      "mark_price": 42800,
      "unrealized_pnl": 150,
      "leverage": 10
    }
  ],
  "total_value": 45000,
  "margin_used": 4500
}

Response Example (fills)

{
  "address": "0xABC123...",
  "fills": [
    {
      "symbol": "ETH",
      "side": "buy",
      "size": 2.5,
      "price": 2245.00,
      "fee": 1.12,
      "realized_pnl": 0,
      "timestamp": "2026-01-08T10:30:00Z",
      "order_type": "limit"
    }
  ],
  "total_count": 1543
}

Python Example

import requests

API_KEY = "your_api_key"
WALLET = "0x1234567890abcdef..."

# Get positions
positions = requests.get(
    f"https://api.moondev.com/api/user/{WALLET}/positions",
    headers={"X-API-Key": API_KEY}
).json()

print(f"Total Value: ${positions['total_value']:,.2f}")
for pos in positions["positions"]:
    print(f"  {pos['symbol']} {pos['side']}: ${pos['size_usd']:,.0f}")

# Get ALL fills
fills = requests.get(
    f"https://api.moondev.com/api/user/{WALLET}/fills?limit=-1",
    headers={"X-API-Key": API_KEY}
).json()

print(f"Total trades: {fills['total_count']}")

HLP (Hyperliquidity Provider)

Complete reverse engineering of Hyperliquid's native market-making protocol (~$210M+ AUM, 7 strategies, 5,000+ trades tracked).

Endpoint	Description
GET /api/hlp/positions	All 7 HLP strategy positions + combined net exposure
GET /api/hlp/positions?include_strategies=false	Summary only (faster response)
GET /api/hlp/trades?limit=N	Historical HLP trade fills (5,000+ collected)
GET /api/hlp/trades/stats	Trade volume and fee statistics
GET /api/hlp/positions/history?hours=N	Position snapshots over time
GET /api/hlp/liquidators	Liquidator activation events
GET /api/hlp/deltas?hours=N	Net exposure changes over time

Response Example (positions)

{
  "total_value_usd": 210000000,
  "net_exposure": {
    "BTC": {"long": 125000000, "short": 98000000, "net": 27000000},
    "ETH": {"long": 85000000, "short": 92000000, "net": -7000000}
  },
  "strategies": [
    {
      "name": "Strategy A",
      "vault_address": "0x...",
      "value_usd": 45000000,
      "positions": [
        {"symbol": "BTC", "side": "long", "size_usd": 12000000}
      ]
    }
  ]
}

Response Example (trades)

{
  "trades": [
    {
      "strategy": "Strategy A",
      "symbol": "BTC",
      "side": "buy",
      "size": 0.25,
      "price": 42500,
      "fee": 0.85,
      "timestamp": "2026-01-08T11:00:00Z"
    }
  ],
  "total_count": 5432
}

Response Example (trades/stats)

{
  "total_volume_usd": 850000000,
  "total_fees_paid": 425000,
  "volume_by_coin": {
    "BTC": 450000000,
    "ETH": 280000000,
    "SOL": 120000000
  },
  "volume_by_strategy": {
    "Strategy A": 320000000,
    "Strategy B": 280000000
  }
}

Response Example (deltas)

{
  "deltas": [
    {
      "timestamp": "2026-01-08T10:00:00Z",
      "BTC": {"delta": 500000, "direction": "more_long"},
      "ETH": {"delta": -200000, "direction": "more_short"}
    }
  ]
}

Python Example

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.moondev.com"

# Get HLP positions (full details)
hlp = requests.get(
    f"{BASE_URL}/api/hlp/positions",
    headers={"X-API-Key": API_KEY}
).json()

print(f"Total HLP Value: ${hlp['total_value_usd']:,.0f}")
print(f"Strategies: {len(hlp['strategies'])}")

# Net exposure per coin
for coin, exp in hlp["net_exposure"].items():
    direction = "LONG" if exp["net"] > 0 else "SHORT"
    print(f"  {coin}: ${abs(exp['net']):,.0f} {direction}")

# Get trade stats
stats = requests.get(
    f"{BASE_URL}/api/hlp/trades/stats",
    headers={"X-API-Key": API_KEY}
).json()

print(f"Total Volume: ${stats['total_volume_usd']:,.0f}")

HLP data collection started Nov 3, 2025. Historical analysis covers this full period.

HLP Sentiment & Analytics

Advanced analytics endpoints for HLP sentiment analysis, liquidator monitoring, market maker tracking, and timing analysis. These endpoints provide institutional-grade signals based on HLP positioning data.

Available Endpoints

Endpoint	Description
GET /api/hlp/sentiment	Net delta with z-scores and trading signals - THE sentiment indicator
GET /api/hlp/liquidators/status	Real-time liquidator status (active/idle) with PnL
GET /api/hlp/market-maker	Strategy B tracker for BTC/ETH/SOL positions
GET /api/hlp/timing	Hourly and session profitability analysis
GET /api/hlp/correlation	Delta-price correlation analysis by coin

Sentiment Analysis (The Big One)

The /api/hlp/sentiment endpoint analyzes HLP net delta positions and generates z-score based trading signals. This is the primary sentiment indicator for understanding institutional positioning.

curl "https://api.moondev.com/api/hlp/sentiment?api_key=YOUR_KEY"

Response Example

{
  "timestamp": "2025-01-12T15:30:00Z",
  "net_delta": {
    "BTC": { "value": -2450000, "z_score": 2.2, "signal": "Retail heavily SHORT - potential short squeeze" },
    "ETH": { "value": 1200000, "z_score": -0.8, "signal": "Neutral positioning" },
    "SOL": { "value": -580000, "z_score": 1.5, "signal": "Moderate retail SHORT bias" }
  },
  "overall_signal": "Market sentiment: Retail skewed SHORT on majors",
  "confidence": "high"
}

Liquidator Status

Monitor liquidator wallet activity in real-time. Track which liquidators are active/idle and their recent PnL.

curl "https://api.moondev.com/api/hlp/liquidators/status?api_key=YOUR_KEY"

Market Maker (Strategy B)

Track Strategy B market maker positions across BTC, ETH, and SOL. Useful for understanding MM inventory and potential mean reversion.

curl "https://api.moondev.com/api/hlp/market-maker?api_key=YOUR_KEY"

Timing Analysis

Analyze HLP profitability by hour of day and trading session. Identify optimal trading windows based on historical HLP performance.

curl "https://api.moondev.com/api/hlp/timing?api_key=YOUR_KEY"

Correlation Analysis

Analyze correlation between HLP delta changes and price movements by coin. Higher correlation suggests stronger predictive signal.

curl "https://api.moondev.com/api/hlp/correlation?api_key=YOUR_KEY"

Python Example

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.moondev.com"

# Get HLP sentiment signals
sentiment = requests.get(
    f"{BASE_URL}/api/hlp/sentiment",
    params={"api_key": API_KEY}
).json()

print(f"Overall: {sentiment['overall_signal']}")
print(f"Confidence: {sentiment['confidence']}")

for coin, data in sentiment["net_delta"].items():
    print(f"  {coin}: z={data['z_score']:.1f} - {data['signal']}")

# Check liquidator activity
liquidators = requests.get(
    f"{BASE_URL}/api/hlp/liquidators/status",
    params={"api_key": API_KEY}
).json()

for liq in liquidators.get("liquidators", []):
    status = "ACTIVE" if liq["active"] else "IDLE"
    print(f"  {liq['address'][:10]}...: {status} (PnL: ${liq['pnl']:,.0f})")

Code Examples

More examples on GitHub

Every new API endpoint gets a working example added to the repo. Clone it and start building!

View Repo

Replace your_api_key with your actual key.Need an API key?

Python - Get Smart Money Signals

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.moondev.com"

# Get smart money signals from last hour
signals = requests.get(
    f"{BASE_URL}/api/smart_money/signals_1h.json",
    headers={"X-API-Key": API_KEY}
).json()

for signal in signals["signals"][:10]:
    print(f"{signal['action']} {signal['coin']} @ ${signal['price']:,.0f}")

Python - Monitor Order Flow

import requests

API_KEY = "your_api_key"

imbalance = requests.get(
    "https://api.moondev.com/api/imbalance/1h.json",
    headers={"X-API-Key": API_KEY}
).json()

for coin, data in imbalance["imbalance"].items():
    print(f"{coin}: {data['signal']} ({data['imbalance_pct']:.1f}% imbalance)")

JavaScript - Real-time Ticks

const API_KEY = "your_api_key";

fetch("https://api.moondev.com/api/ticks/latest.json", {
  headers: { "X-API-Key": API_KEY }
})
  .then(res => res.json())
  .then(data => {
    console.log("Current prices:", data);
  });

cURL

# Get smart money rankings
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/smart_money/rankings.json

# Get BTC ticks for last hour
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/ticks/btc_1h.json

# Get large trades
curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/large_trades.json

Want more? Check out the full collection of examples on GitHub.

Data Freshness

Category	Update Frequency
Tick Data	500ms
Events	2 seconds
Trades/Order Flow	5 seconds
User Data	5 seconds
Binance Liquidations	Real-time (WebSocket)
Bybit Liquidations	Real-time (WebSocket)
OKX Liquidations	Real-time (WebSocket)
All Liquidations (Combined)	Real-time (WebSocket)
HIP3 Liquidations (TradFi)	Real-time
HIP3 Market Data (Candles/Ticks)	500ms
HLP Positions	30 seconds
HLP Trades	30 seconds
HLP Sentiment/Analytics	30 seconds
Hyperliquid Liquidations	30 seconds
Positions/Whales	30 seconds
Smart Money	60 seconds
Contracts	5 minutes

Error Codes

HTTP Code	Meaning
200	Success
401	Unauthorized - Invalid or missing API key
404	Endpoint not found
429	Rate limit exceeded
500	Server error

Getting 401 errors? Get your API key here.

Quick Reference - All Endpoints

# Market Data

/api/prices

/api/price/{coin}

/api/orderbook/{coin}

/api/account/{address}

/api/fills/{address}?limit=N

/api/candles/{coin}?interval={1m,5m,15m,1h,4h,1d}

# Core Data

/api/positions.json

/api/positions/all.json

/api/whales.json

/api/buyers.json

/api/depositors.json

/api/whale_addresses.txt

# Blockchain

/api/events.json

/api/contracts.json

# Tick Data

/api/ticks/{stats,latest}.json

/api/ticks/{btc,eth,hype,sol,xrp}.json

/api/ticks/{btc,eth,hype,sol,xrp}_{10m,1h,4h,24h,7d}.json

# Trades & Order Flow

/api/trades.json

/api/large_trades.json

/api/orderflow.json

/api/orderflow/stats.json

/api/imbalance/{5m,15m,1h,4h,24h}.json

# Hyperliquid Liquidations

/api/liquidations/{stats,scan_summary}.json

/api/liquidations/{10m,1h,4h,12h,24h,2d,7d,14d,30d}.json

# HIP3 Liquidations (TradFi)

/api/hip3_liquidations/stats.json

/api/hip3_liquidations/{10m,1h,24h,7d}.json

# HIP3 Market Data (TradFi OHLCV)

/api/hip3/candles/symbols

/api/hip3/prices

/api/hip3/price/{coin}

/api/hip3/candles/{coin}?interval={1m,5m,15m,1h,4h,1d}

/api/hip3/ticks/{coin}?duration={10m,1h,4h,24h,7d}

# Multi-Exchange Liquidations

/api/all_liquidations/stats.json

/api/all_liquidations/{10m,1h,24h,7d,30d}.json

/api/binance_liquidations/stats.json

/api/binance_liquidations/{10m,1h,24h,7d,30d}.json

/api/bybit_liquidations/stats.json

/api/bybit_liquidations/{10m,1h,24h,7d,30d}.json

/api/okx_liquidations/stats.json

/api/okx_liquidations/{10m,1h,24h,7d,30d}.json

# Smart Money

/api/smart_money/{rankings,leaderboard}.json

/api/smart_money/signals_{10m,1h,24h}.json

# User Data (Local Node)

/api/user/{address}/positions

/api/user/{address}/fills?limit=N

# HLP (Hyperliquidity Provider)

/api/hlp/positions

/api/hlp/positions?include_strategies=false

/api/hlp/trades?limit=N

/api/hlp/trades/stats

/api/hlp/positions/history?hours=N

/api/hlp/liquidators

/api/hlp/deltas?hours=N

# HLP Sentiment & Analytics

/api/hlp/sentiment

/api/hlp/liquidators/status

/api/hlp/market-maker

/api/hlp/timing

/api/hlp/correlation

Need an API key or integration support? Contact Moon Dev

GitHub Examples & Code