Moon Dev API

curl https://api.moondev.com/api/ai/health

curl -X POST "https://api.moondev.com/api/ai/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "moondev-ai",
    "messages": [{"role": "user", "content": "How do I build a trading bot?"}],
    "max_tokens": 500
  }'

import requests

response = requests.post(
    "https://api.moondev.com/api/ai/v1/chat/completions",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_API_KEY"
    },
    json={
        "model": "moondev-ai",
        "messages": [{"role": "user", "content": "What is the RBI system?"}],
        "max_tokens": 500
    }
)

print(response.json()["choices"][0]["message"]["content"])

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.moondev.com/api/ai/v1"
)

response = client.chat.completions.create(
    model="moondev-ai",
    messages=[{"role": "user", "content": "What is the RBI system?"}],
    max_tokens=500
)

print(response.choices[0].message.content)

{
  "id": "gen-xxx",
  "choices": [
    {
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 1289,
    "completion_tokens": 500,
    "total_tokens": 1789
  }
}

?api_key=YOUR_API_KEY

X-API-Key: YOUR_API_KEY

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

# add this line to ~/.zshrc or ~/.bashrc, then open a new terminal
export MOONDEV_API_KEY="your_key_here"

claude mcp add --transport http moondev https://api.moondev.com/mcp \
  --header "Authorization: Bearer $MOONDEV_API_KEY"

{
  "mcpServers": {
    "moondev": {
      "type": "http",
      "url": "https://api.moondev.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MOONDEV_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "moondev": {
      "url": "https://api.moondev.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_MOONDEV_API_KEY"
      }
    }
  }
}

{
  "mcpServers": {
    "moondev": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.moondev.com/mcp",
        "--header",
        "Authorization:${AUTH_HEADER}"
      ],
      "env": {
        "AUTH_HEADER": "Bearer YOUR_MOONDEV_API_KEY"
      }
    }
  }
}

{
  "symbol": "RUNE",
  "total_longs": 1,
  "total_shorts": 2,
  "closest_to_liquidation": {
    "address": "0x3596f701162a0bcbad8a5c52127ed02310a4707f",
    "side": "long",
    "size": 146740.9,
    "value": 117232.77,
    "entry_price": 0.5252,
    "current_price": 0.7985,
    "liq_price": 0.4265,
    "distance_pct": 46.58,
    "leverage": 5.0,
    "pnl": 40156.24
  }
}

curl -N https://api.moondev.com/mcp \
  -H "Authorization: Bearer $MOONDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_positions","arguments":{"symbol":"RUNE"}}}'

curl -N https://api.moondev.com/mcp \
  -H "Authorization: Bearer $MOONDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

import json
import os
import requests

URL = "https://api.moondev.com/mcp"
HEADERS = {
    "Authorization": f"Bearer {os.environ.get('MOONDEV_API_KEY')}",
    "Content-Type": "application/json",
    "Accept": "application/json, text/event-stream",
}

def call_tool(name, arguments):
    body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
            "params": {"name": name, "arguments": arguments}}
    r = requests.post(URL, headers=HEADERS, json=body, timeout=30)
    r.raise_for_status()
    line = next(l for l in r.text.splitlines() if l.startswith("data:"))
    result = json.loads(line[5:])["result"]
    if result.get("isError"):
        raise RuntimeError(result["content"][0]["text"])
    return result["structuredContent"]

data = call_tool("get_positions", {"symbol": "RUNE", "limit": 10})
for p in data["positions"]:
    print(f"{p['side']:5} {p['address']}  ${p['value']:,.0f}  " \
          f"liq {p['liq_price']}  {p['distance_pct']}% away")

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

{
  "count": 228,
  "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"
  }
}

{
  "coin": "BTC",
  "timestamp": "2026-01-29T15:37:44Z",
  "best_bid": "85324.0",
  "best_ask": "85325.0",
  "best_bid_size": "0.00036",
  "best_ask_size": "5.7609",
  "mid_price": "85324.5",
  "spread": "1.0",
  "spread_bps": 0.12
}

{
  "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"}
    ]
  ]
}

[
  {
    "t": 1792929600000,
    "T": 1792933199999,
    "s": "BTC",
    "i": "1h",
    "o": "80557.0",
    "c": "80434.0",
    "h": "80557.0",
    "l": "80295.0",
    "v": "924.58",
    "n": 5902
  }
]

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']}")

{
  "address": "0xdfc24b077bc1425ad1dea75bcb6f8158e10df303",
  "timestamp": 1781703404216,
  "marginSummary": {
    "accountValue": "241896794.51",
    "totalNtlPos": "...",
    "totalRawUsd": "...",
    "totalMarginUsed": "..."
  },
  "crossMarginSummary": {
    "accountValue": "...",
    "totalNtlPos": "...",
    "totalRawUsd": "...",
    "totalMarginUsed": "..."
  },
  "crossMaintenanceMarginUsed": "0.0",
  "withdrawable": "0.0",
  "assetPositions": [
    {
      "type": "oneWay",
      "position": {
        "coin": "BTC",
        "szi": "0.001",
        "entryPx": "93210.0",
        "positionValue": "...",
        "unrealizedPnl": "...",
        "returnOnEquity": "0.0123",
        "leverage": { "type": "isolated", "value": 10 },
        "liquidationPx": "...",
        "marginUsed": "...",
        "maxLeverage": 40,
        "cumFunding": { "allTime": "...", "sinceOpen": "...", "sinceChange": "..." }
      }
    }
  ],
  "source": "local"
}

curl -H "X-API-Key: $KEY" \
  "https://api.moondev.com/api/hl/clearinghouse/0xdfc24b077bc1425ad1dea75bcb6f8158e10df303"

import requests

r = requests.get(
    f"https://api.moondev.com/api/hl/clearinghouse/{addr}",
    headers={"X-API-Key": KEY},
    timeout=5,
)
r.raise_for_status()
state = r.json()
account_value = float(state["marginSummary"]["accountValue"])

{
  "address": "0xc71cc6f1d8b6d1b0ee55cfc70cd210b2bd1bc506",
  "timestamp": 1781704744647,
  "orders": [
    {
      "coin": "BTC",
      "oid": 123456789,
      "side": "B",
      "limitPx": "93000.0",
      "sz": "0.001",
      "origSz": "0.001",
      "timestamp": 1781700000000,
      "reduceOnly": false,
      "orderType": "Limit",
      "tif": "Gtc",
      "cloid": null
    }
  ],
  "source": "local"
}

# All open orders
curl -H "X-API-Key: $KEY" \
  "https://api.moondev.com/api/hl/open_orders/0xC71CC6f1d8B6D1b0ee55cfc70CD210b2bd1BC506"

# Only BTC
curl -H "X-API-Key: $KEY" \
  "https://api.moondev.com/api/hl/open_orders/0xC71CC6f1d8B6D1b0ee55cfc70CD210b2bd1BC506?coin=BTC"

import requests

r = requests.get(
    f"https://api.moondev.com/api/hl/open_orders/{addr}",
    headers={"X-API-Key": KEY},
    params={"coin": "BTC"},
    timeout=5,
)
r.raise_for_status()
oids = [o["oid"] for o in r.json()["orders"]]

curl -X POST https://api.moondev.com/api/hl/info \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"type":"spotClearinghouseState","user":"0xYOUR_ADDRESS"}'

{"balances":[{"coin":"USDC","token":0,"total":"99.121993","hold":"83.10294","entryNtl":"0.0"}],
 "tokenToAvailableAfterMaintenance":[[0,"98.083207"]]}

// activeAssetData
{"user":"0x1d3e...9e5d","coin":"BTC","leverage":{"type":"cross","value":1},
 "maxTradeSzs":["0.00232","0.0002"],"availableToTrade":["181.88568","15.6798"],"markPx":"78399.0"}

// perpsAtOpenInterestCap: a plain list of coin names
["CANTO","FTM","JELLY","LOOM","RLB","VINE","ZEREBRO"]

// meta
{"universe":[{"szDecimals":5,"name":"BTC","maxLeverage":40,"marginTableId":56},
             {"szDecimals":4,"name":"ETH","maxLeverage":25,"marginTableId":55}, ...],
 "marginTables":[...]}

// perpDexs: the first entry is null (the main dex)
[null,{"name":"xyz","fullName":"XYZ","deployer":"0x8880...0888", ...}, ...]

// spotMeta
{"universe":[{"tokens":[1,0],"name":"PURR/USDC","index":0,"isCanonical":true}, ...],"tokens":[...]}

curl -X POST https://api.moondev.com/api/hl/info \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"type":"portfolio","user":"0xYOUR_ADDRESS"}'

[
  ["day",     {"accountValueHistory":[[1793713260000,"100.31"], ...],
               "pnlHistory":[[1793713260000,"0.0"], ...],
               "vlm":"0.0"}],
  ["week",    {...}],
  ["month",   {...}],
  ["allTime", {...}],
  ["perpDay", {...}], ["perpWeek", {...}], ["perpMonth", {...}], ["perpAllTime", {...}]
]

curl -X POST https://api.moondev.com/api/hl/info \
  -H 'X-API-Key: YOUR_KEY' -H 'Content-Type: application/json' \
  -d '{"type":"userFillsByTime","user":"0xYOUR_ADDRESS","startTime":1793800000000}'

[{"coin":"xyz:TSLA","px":"376.84","sz":"0.71","side":"B","time":1793801160123,"startPosition":"0.0",
  "dir":"Open Long","closedPnl":"0.0","hash":"0x...","oid":594448767657,"crossed":true,
  "fee":"0.0124","tid":81234567,"feeToken":"USDC","twapId":null}, ...]

from hyperliquid.info import Info

MOONDEV_KEY = "YOUR_KEY"

class MoonDevInfo(Info):
    def post(self, url_path, payload=None):
        self.session.headers["X-API-Key"] = MOONDEV_KEY
        return super().post(url_path, payload)

info = MoonDevInfo(base_url="https://api.moondev.com/api/hl", skip_ws=True)
# include HIP-3 dexes:  MoonDevInfo(..., skip_ws=True, perp_dexs=["", "xyz"])

info.spot_user_state("0xYOUR_ADDRESS")       # spotClearinghouseState
info.portfolio("0xYOUR_ADDRESS")             # portfolio
info.user_fills_by_time("0xYOUR_ADDRESS", start_ms)   # userFillsByTime
info.meta()                                   # meta
info.meta(dex="xyz")                          # HIP-3 meta
info.spot_meta()                              # spotMeta
info.post("/info", {"type": "perpDexs"})
info.post("/info", {"type": "activeAssetData", "user": "0xYOUR_ADDRESS", "coin": "xyz:TSLA"})
info.post("/info", {"type": "perpsAtOpenInterestCap", "dex": "xyz"})

import requests
r = requests.post("https://api.moondev.com/api/hl/info",
                  headers={"X-API-Key": "YOUR_KEY"},
                  json={"type": "activeAssetData", "user": "0xYOUR_ADDRESS", "coin": "xyz:TSLA"},
                  timeout=10)
lev = r.json()["leverage"]        # {"type": "cross", "value": 20}

const r = await fetch("https://api.moondev.com/api/hl/info", {
  method: "POST",
  headers: { "X-API-Key": "YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({ type: "portfolio", user: "0xYOUR_ADDRESS" }),
});
const windows = Object.fromEntries(await r.json());   // windows.day.pnlHistory, ...

import time, requests

MOONDEV = "https://api.moondev.com/api/hl/info"
HL = "https://api.hyperliquid.xyz/info"
KEY = "YOUR_KEY"
_skip_until = 0

def hl_info(body):
    global _skip_until
    if time.time() >= _skip_until:
        try:
            r = requests.post(MOONDEV, json=body, headers={"X-API-Key": KEY}, timeout=10)
            if r.status_code == 200:
                return r.json()
            if r.status_code == 400:
                r.raise_for_status()                      # our request is wrong; don't retry elsewhere
            if r.status_code in (429, 503):
                _skip_until = time.time() + int(r.headers.get("Retry-After", 60))
            elif r.status_code >= 500:                    # 502/504 from the network in between
                _skip_until = time.time() + 60
        except requests.ConnectionError:
            _skip_until = time.time() + 60
        except requests.Timeout:
            _skip_until = time.time() + 60
    return requests.post(HL, json=body, timeout=10).json()

{
  "updated_at": "2026-10-20T16:13:41.447080+00:00",
  "total_positions": 7937,
  "total_longs": 50,
  "total_shorts": 50,
  "min_position_value": 75000,
  "price_source": "websocket",
  "longs": [
    {
      "address": "0x...",
      "coin": "BTC",
      "value": 1250000.50,
      "entry_price": 85000.0,
      "current_price": 86500.0,
      "liq_price": 82000.0,
      "distance_pct": 5.20,
      "leverage": 10.0,
      "size": 14.705882,
      "pnl": 22058.82
    }
  ],
  "shorts": [ ... ]
}

{
  "updated_at": "2026-10-20T16:13:42.901856+00:00",
  "min_position_value": 75000,
  "total_symbols": 139,
  "symbols": {
    "BTC": {
      "total_positions": 892,
      "total_longs": 510,
      "total_shorts": 382,
      "total_long_value": 450000000.00,
      "total_short_value": 280000000.00,
      "longs": [ ... ],
      "shorts": [ ... ]
    },
    "ETH": { ... }
  }
}

{
  "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"
    }
  ]
}

{
  "symbol": "BTC",
  "venue": "crypto",            // crypto or hip3
  "price": 82560.0,
  "pct_24h": 0.876,             // % change over 24h
  "pct_7d": -0.853,             // % change over 7 days
  "adx": 28.6,                  // trend strength
  "dd_24h": 2.56,               // drawdown over 24h, %
  "max_dd_7d": 5.20,            // worst drawdown over 7 days, %
  "dd_ret_ratio": 6.10,         // drawdown to return ratio
  "roc": 1.25,                  // rate of change
  "mom_atr": 1.29,              // momentum in ATR units
  "ema_align": 33.3,            // % of EMAs stacked in trend order
  "donch_breakout_up": false,
  "donch_breakout_dn": false,
  "donch_break_age": 1,         // bars since the last Donchian break
  "above_bb_upper": false,
  "below_bb_lower": false,
  "vol_ratio": 0.013,           // current 4h volume vs its average
  "quote_vol_4h": 4219236.23,
  "quote_vol_24h": 2278454777.52,
  "high_7d": 84103.0,
  "low_7d": 79732.0,
  "rng_pos_7d": 64.7,           // where price sits in the 7 day range, 0 = low, 100 = high
  "bars": 90                    // 4h bars of history used
}

import os, requests

KEY = os.environ["MOONDEV_API_KEY"]
scan = requests.get("https://api.moondev.com/api/trenders/latest.json",
                    params={"api_key": KEY}, timeout=10).json()

print(f"scored {scan['symbols_scored']} of {scan['symbols_discovered']} markets "
      f"(history complete: {scan['history_complete']})")
for r in scan["trenders_up"]:
    print(f"UP   {r['symbol']:14} {r['venue']:6} 24h {r['pct_24h']:+.1f}%  7d {r['pct_7d']:+.1f}%  adx {r['adx']:.0f}")
for r in scan["fresh_breakouts"]:
    print(f"BRK  {r['symbol']:14} broke out {r['donch_break_age']} bars ago")

# every symbol's full row
rows = requests.get("https://api.moondev.com/api/trenders/all.json",
                    params={"api_key": KEY}, timeout=10).json()["rows"]
strong = [r for r in rows if r["adx"] > 25 and r["ema_align"] == 100]
print(len(strong), "markets fully aligned with ADX over 25")

{
  "coin": "BTC",
  "market_type": "perp",
  "interval": "10s",
  "count": 2,
  "bars": [
    {
      "t": 1792800940000,    // bar open time, ms UTC
      "o": 80961.0,          // open
      "h": 80961.0,          // high
      "l": 80941.0,          // low
      "c": 80941.0,          // close
      "v": 0.31444,          // volume (coins)
      "bv": 0.02976,         // buy volume (taker buys)
      "sv": 0.28468,         // sell volume (taker sells), bv + sv = v
      "qv": 25453.31016,     // dollar volume
      "n": 23                // trade count
    },
    ...
  ],
  "prev_end": 1792800940000,   // pass as end= for the page before this one (null = no more)
  "next_start": null,          // pass as start= for the page after this one (null = no more)
  "has_more": true,
  "data_through": 1792800961458,
  "last_bar_complete": false,  // the newest bar is still filling
  "coin_first_bar": 1792540800000,
  "history_start": 1792540800000
}

import os, requests

KEY = os.environ["MOONDEV_API_KEY"]
URL = "https://api.moondev.com/api/candles/v2/BTC"

bars, end = [], None
while True:
    params = {"interval": "10s", "limit": 10000, "api_key": KEY}
    if end:
        params["end"] = end
    page = requests.get(URL, params=params, timeout=30).json()
    bars = page["bars"] + bars          # each page is older than the last
    end = page["prev_end"]
    if end is None:
        break

print(len(bars), "bars from", bars[0]["t"], "to", bars[-1]["t"])
last = bars[-1]
print(f"close {last['c']}  buy vol {last['bv']}  sell vol {last['sv']}  trades {last['n']}")

# newest 10,000 ten second BTC bars
curl "https://api.moondev.com/api/candles/v2/BTC?interval=10s&limit=10000&api_key=YOUR_KEY"

# 4h crude oil (HIP3) as CSV
curl "https://api.moondev.com/api/candles/v2/xyz:CL?interval=4h&format=csv&api_key=YOUR_KEY"

# forward from a date: keep passing next_start as start until it is null
curl "https://api.moondev.com/api/candles/v2/ETH?interval=1m&start=1792540800000&api_key=YOUR_KEY"

# Get BTC tick data (last hour)
curl "https://api.moondev.com/api/ticks/btc_1h.json?api_key=YOUR_KEY"

# Get ADA tick data (last 24 hours)
curl "https://api.moondev.com/api/ticks/ada_24h.json?api_key=YOUR_KEY"

# Get TRUMP tick data (last 7 days)
curl "https://api.moondev.com/api/ticks/trump_7d.json?api_key=YOUR_KEY"

{
  "generated_at": "2026-01-29T15:37:44Z",
  "symbols": ["0G", "2Z", "AAVE", "ACE", "ADA", "...129 total"],
  "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
    }
  }
}

{
  "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"}
  ]
}

{
  "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"
    }
  ]
}

{
  "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
    }
  ]
}

{
  "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"
    }
  ]
}

curl -H "X-API-Key: YOUR_QE_KEY" \
  "https://api.moondev.com/api/bulk/hl_liquidations?start_ms=2026-10-27&end_ms=2026-10-28&limit=10000"

{
  "endpoint": "bulk_hl_liquidations",
  "access_tier": "quant_elite",
  "start_ms": 1793059200000,
  "end_ms": 1793145600000,
  "coin": null,
  "order": "oldest_first",
  "count": 6927,
  "next_start_ms": null,
  "has_more": false,
  "gaps": [],
  "data": [
    {
      "timestamp": "2026-10-27T00:00:24.657Z",
      "time_ms": 1793059224657,
      "coin": "xyz:SKHX",
      "dex": "xyz",
      "side": "short",
      "size": 0.1,
      "price": 1019.4,
      "value_usd": 101.94,
      "address": "0x0ab6d64f501bf5cc44f968bd6b4ad482c385df11",
      "pnl": -5.599,
      "tid": 133304234435535,
      "hash": "0xe191aea36eff5e3ce30b04476fbad10207ca008909f27d0e855a59f62df33827",
      "method": "market",
      "mark_px": 1013.5,
      "counterparty": "0xf30120f0487a9093dbd47a69527ac9a9edbb7895",
      "counterparty_role": "maker",
      "source": "fills"
    }
  ]
}

import requests

API_KEY = "YOUR_QE_KEY"
URL = "https://api.moondev.com/api/bulk/hl_liquidations"

def get_liquidations(start, end, coin=None):
    rows, seen = [], set()
    params = {"start_ms": start, "end_ms": end, "limit": 10000}
    if coin:
        params["coin"] = coin
    while True:
        r = requests.get(URL, params=params, headers={"X-API-Key": API_KEY}, timeout=60)
        r.raise_for_status()
        page = r.json()
        for row in page["data"]:
            key = (row["coin"], row["tid"])
            if key not in seen:
                seen.add(key)
                rows.append(row)
        if page.get("gaps"):
            print("known gaps in this window:", page["gaps"])
        if not page["has_more"]:
            return rows
        params["start_ms"] = page["next_start_ms"]

liqs = get_liquidations("2026-10-01", "2026-10-28")
print(len(liqs), "liquidations")

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

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']}")

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

{
  "generated_at": "2026-04-26T15:39:48Z",
  "market_type": "HIP3",
  "collection_method": "WebSocket Streaming",
  "dexes": ["xyz", "flx", "vntl", "hyna", "km", "cash", "para"],
  "symbol_count": 136,
  "by_category": {
    "stocks": ..., "indices": ..., "commodities": ...,
    "fx": ..., "crypto": ..., "pre_ipo": ..., "other": ...
  }
}

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

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

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

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

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

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

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

{
  "count": 136,
  "categories": {
    "stocks": ["xyz:TSLA", "xyz:NVDA", "xyz:HIMS", ...],
    "commodities": ["xyz:GOLD", "xyz:SILVER", "xyz:CL", "flx:OIL", ...],
    "fx": ["xyz:JPY", "xyz:EUR"],
    "indices": ["xyz:XYZ100", "cash:USA500", "km:USTECH", ...],
    "crypto": ["hyna:BTC", "hyna:ETH", "hyna:HYPE", ...],
    "pre_ipo": ["vntl:OPENAI", "vntl:ANTHROPIC", "vntl:SPACEX"]
  }
}

{
  "generated_at": "2026-04-26T15:39:48Z",
  "market_type": "HIP3",
  "dexes": ["xyz", "flx", "vntl", "hyna", "km", "cash", "para"],
  "prices": {
    "xyz:HIMS":    {"dex": "xyz",  "ticker": "HIMS",    "price": 30.399, "category": "other"},
    "xyz:TSLA":    {"dex": "xyz",  "ticker": "TSLA",    "price": 431.64, "category": "stocks"},
    "cash:USA500": {"dex": "cash", "ticker": "USA500",  "price": 6780.6, "category": "indices"},
    "vntl:OPENAI": {"dex": "vntl", "ticker": "OPENAI",  "price": 412.5,  "category": "pre_ipo"}
  }
}

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

{
  "symbol": "xyz:HIMS",
  "dex": "xyz",
  "ticker": "HIMS",
  "price": 30.399,
  "category": "other",
  "market_type": "HIP3",
  "timestamp": "2026-04-26T15:39:48.793000+00:00"
}

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
  }
]

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"
    }
  ]
}

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)

# Bare ticker (resolves to correct dex automatically)
curl "https://api.moondev.com/api/hip3/ticks/CL?duration=1h&api_key=YOUR_KEY"

# Full dex:ticker format
curl "https://api.moondev.com/api/hip3/ticks/xyz:CL?duration=1h&api_key=YOUR_KEY"

# Non-xyz dex
curl "https://api.moondev.com/api/hip3/ticks/cash:USA500?duration=1h&api_key=YOUR_KEY"

curl "https://api.moondev.com/api/hip3/candles/symbols?api_key=YOUR_KEY"

{
  "count": 136,
  "dexes": ["xyz", "flx", "vntl", "hyna", "km", "cash", "para"],
  "intervals": ["1m", "5m", "15m", "1h", "4h", "1d"],
  "by_category": {
    "stocks":      ["xyz:TSLA", "xyz:NVDA", "xyz:HIMS", "..."],
    "indices":     ["xyz:XYZ100", "cash:USA500", "km:USTECH", "..."],
    "commodities": ["xyz:CL", "xyz:GOLD", "xyz:SILVER", "flx:OIL", "..."],
    "fx":          ["xyz:EUR", "xyz:JPY"],
    "crypto":      ["hyna:BTC", "hyna:ETH", "hyna:HYPE", "..."],
    "pre_ipo":     ["vntl:OPENAI", "vntl:ANTHROPIC", "vntl:SPACEX"]
  },
  "market_type": "HIP3"
}

curl "https://api.moondev.com/api/hip3/ticks/CL?duration=1h&api_key=YOUR_KEY"

{
  "symbol": "xyz:CL",
  "category": "commodities",
  "market_type": "HIP3",
  "duration": "1h",
  "tick_count": 1842,
  "start_time": 1741611600000,
  "end_time": 1741615200000,
  "latest_price": 87.89,
  "ticks": [
    {"t": 1741611600500, "p": 87.65, "dt": "2026-03-10T13:00:00+00:00"},
    {"t": 1741611601000, "p": 87.66, "dt": "2026-03-10T13:00:01+00:00"}
  ]
}

curl "https://api.moondev.com/api/hip3/candles/CL?interval=5m&api_key=YOUR_KEY"
curl "https://api.moondev.com/api/hip3/candles/cash:USA500?interval=1h&api_key=YOUR_KEY"

[
  {
    "t": 1741611600000, "T": 1741611899999,
    "s": "CL", "i": "5m",
    "o": "87.65", "h": "87.92", "l": "87.60", "c": "87.89",
    "v": "0", "n": 42
  }
]

curl "https://api.moondev.com/api/hip3/price/HIMS?api_key=YOUR_KEY"

{
  "symbol": "xyz:HIMS",
  "dex": "xyz",
  "ticker": "HIMS",
  "price": 30.399,
  "category": "other",
  "market_type": "HIP3",
  "timestamp": "2026-04-26T15:39:48.793000+00:00"
}

curl "https://api.moondev.com/api/hip3/prices?api_key=YOUR_KEY"

{
  "generated_at": "2026-04-26T15:39:48+00:00",
  "market_type": "HIP3",
  "dexes": ["xyz", "flx", "vntl", "hyna", "km", "cash", "para"],
  "prices": {
    "xyz:HIMS":     {"dex": "xyz",  "ticker": "HIMS",     "price": 30.399, "category": "other"},
    "xyz:CL":       {"dex": "xyz",  "ticker": "CL",       "price": 87.89,  "category": "commodities"},
    "cash:USA500":  {"dex": "cash", "ticker": "USA500",   "price": 6780.6, "category": "indices"},
    "vntl:OPENAI":  {"dex": "vntl", "ticker": "OPENAI",   "price": 412.5,  "category": "pre_ipo"},
    "hyna:BTC":     {"dex": "hyna", "ticker": "BTC",      "price": 96420,  "category": "crypto"}
  }
}

# Live HIMS price
curl "https://api.moondev.com/api/hip3/price/HIMS?api_key=KEY"

# Last hour of HIMS ticks
curl "https://api.moondev.com/api/hip3/ticks/HIMS?duration=1h&api_key=KEY"

# 1-minute HIMS candles for the last 7 days
NOW=$(($(date +%s)*1000)); WEEK=$((NOW - 7*86400*1000))
curl "https://api.moondev.com/api/hip3/candles/HIMS?interval=1m&startTime=$WEEK&endTime=$NOW&api_key=KEY"

# All current HIP3 prices (136 symbols across 7 dexes)
curl "https://api.moondev.com/api/hip3/prices?api_key=KEY"

# Pre-IPO exposure via Ventuals
curl "https://api.moondev.com/api/hip3/price/vntl:OPENAI?api_key=KEY"
curl "https://api.moondev.com/api/hip3/price/vntl:ANTHROPIC?api_key=KEY"

curl -H "X-API-Key: YOUR_KEY" https://api.moondev.com/api/all_liquidations/totals.json

# or with the key as a query parameter
curl "https://api.moondev.com/api/all_liquidations/totals.json?api_key=YOUR_KEY"

{
  "generated_at": "2026-07-20T19:47:02Z",
  "note": "Total liquidations (USD amount + count) across binance, bybit, okx, hyperliquid.",
  "windows": {
    "5m": {
      "total_volume_usd": 247147,
      "total_count": 112,
      "long_volume_usd": 166096,
      "long_count": 78,
      "short_volume_usd": 81051,
      "short_count": 34,
      "by_exchange": {
        "binance": {
          "volume_usd": 103379,
          "count": 56,
          "long_volume_usd": 78161,
          "long_count": 38,
          "short_volume_usd": 25217,
          "short_count": 18
        },
        "bybit":       { "...": "same shape" },
        "okx":         { "...": "same shape" },
        "hyperliquid": { "...": "same shape" }
      }
    },
    "15m": { "...": "same shape" },
    "1h":  { "...": "same shape" },
    "2h":  { "...": "same shape" },
    "3h":  { "...": "same shape" },
    "4h":  { "...": "same shape" }
  }
}

{
  "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}
  ]
}

{
  "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"
    }
  ]
}

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

{
  "dataset": "binance_futures_liquidations",
  "generated_at": "2026-07-19T15:17:00Z",
  "segments": [
    {
      "name": "historical",
      "status": "frozen",
      "note": "Complete historical archive. This segment is final and will not change.",
      "start": "2024-06-04T12:46:58Z",
      "end":   "2026-04-23T16:30:49Z",
      "records": 35624285
    },
    {
      "name": "live",
      "status": "collecting",
      "note": "Live feed, collected in real time.",
      "start": "2026-07-18T23:47:58Z",
      "end":   "2026-07-19T15:17:00Z",
      "records": 1234
    }
  ],
  "gap": {
    "from": "2026-04-23",
    "to": "2026-07-18",
    "reason": "No liquidation data was collected during this period. This gap is permanent and the data cannot be recovered."
  },
  "access": {
    "bulk_endpoint": "/api/bulk/binance_liquidations",
    "tier": "quant_elite",
    "historical_example": "/api/bulk/binance_liquidations?end=2026-04-23",
    "live_example": "/api/bulk/binance_liquidations?start=2026-07-18"
  }
}

{
  "endpoint": "bulk_binance_liquidations",
  "access_tier": "quant_elite",
  "total_records": 35624285,
  "returned": 10000,
  "limit": 10000,
  "offset": 0,
  "has_more": true,
  "next_offset": 10000,
  "data": [
    {
      "symbol": "BTCUSDT",
      "side": "SELL",
      "price": 96500.0,
      "avg_price": 96312.5,
      "qty": 0.103,
      "usd_size": 9920.19,
      "trade_time": 1771514647172
    }
  ]
}

import requests, csv, time

API_KEY = "yourkey_qe"
URL = "https://api.moondev.com/api/bulk/binance_liquidations"
limit, offset = 100000, 0

with open("binance_liqs.csv", "w", newline="") as f:
    writer = None
    while True:
        r = requests.get(URL, params={
            "api_key": API_KEY,
            "limit": limit,
            "offset": offset
        }).json()
        if not r["data"]:
            break
        if not writer:
            writer = csv.DictWriter(f, fieldnames=r["data"][0].keys())
            writer.writeheader()
        writer.writerows(r["data"])
        print(f"{offset + len(r['data']):,} / {r['total_records']:,}")
        if not r["has_more"]:
            break
        offset = r["next_offset"]
        time.sleep(0.5)

{
  "overall": {
    "total_snapshots": 39128,
    "unique_users": 2579,
    "avg_distance_pct": 6.46
  },
  "by_symbol": {
    "BTC": {
      "snapshots": 22952,
      "unique_users": 1710,
      "avg_distance_pct": 5.95,
      "longs": 17646,
      "shorts": 5306
    },
    "ETH": { "snapshots": 8500, "unique_users": 620, "avg_distance_pct": 6.8, "longs": 5200, "shorts": 3300 },
    "SOL": { "snapshots": 4200, "unique_users": 380, "avg_distance_pct": 7.2, "longs": 2800, "shorts": 1400 },
    "XRP": { "snapshots": 2100, "unique_users": 180, "avg_distance_pct": 8.1, "longs": 1400, "shorts": 700 },
    "HYPE": { "snapshots": 1376, "unique_users": 95, "avg_distance_pct": 7.5, "longs": 900, "shorts": 476 }
  },
  "top_10_closest": [
    {
      "user": "0x702f...",
      "symbol": "BTC",
      "side": "long",
      "position_value": 184600,
      "entry_price": 74913.80,
      "liquidation_price": 67164.00,
      "distance_pct": 0.00
    }
  ]
}

{
  "symbol": "BTC",
  "snapshots": [
    {
      "snapshot_time": 1738763400000,
      "user": "0xabc123...",
      "symbol": "BTC",
      "side": "long",
      "position_value": 333500,
      "entry_price": 69469.50,
      "liquidation_price": 66859.73,
      "current_price": 68500.00,
      "distance_pct": 2.43,
      "leverage": 20.0
    }
  ],
  "count": 50
}

# Get stats for last hour
curl "https://api.moondev.com/api/position_snapshots/stats?hours=1" \
  -H "X-API-Key: YOUR_API_KEY"

# Get BTC snapshots (last hour, limit 50)
curl "https://api.moondev.com/api/position_snapshots/symbol/BTC?hours=1&limit=50" \
  -H "X-API-Key: YOUR_API_KEY"

# Get ETH shorts only, within 5% of liquidation
curl "https://api.moondev.com/api/position_snapshots/symbol/ETH?hours=24&side=short&max_distance_pct=5" \
  -H "X-API-Key: YOUR_API_KEY"

import requests

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

# Get aggregate stats
stats = requests.get(
    f"{BASE_URL}/api/position_snapshots/stats",
    headers=headers,
    params={"hours": 24}
).json()

print(f"Total snapshots: {stats['overall']['total_snapshots']}")
print(f"Unique users: {stats['overall']['unique_users']}")
print(f"Top at risk: {stats['top_10_closest']}")

# Get BTC positions close to liquidation
btc = requests.get(
    f"{BASE_URL}/api/position_snapshots/symbol/BTC",
    headers=headers,
    params={"hours": 24, "limit": 100}
).json()

for snap in btc['snapshots']:
    print(f"{snap['user']}: {snap['distance_pct']}% from liq")

# Filter to very risky positions only
risky = requests.get(
    f"{BASE_URL}/api/position_snapshots/symbol/ETH",
    headers=headers,
    params={"hours": 12, "max_distance_pct": 5}
).json()

# Get all positions that were within 3% of liquidation yesterday
risky_positions = requests.get(
    f"{BASE_URL}/api/position_snapshots/symbol/BTC",
    headers=headers,
    params={"hours": 24, "max_distance_pct": 3, "limit": 5000}
).json()

# Group by snapshot_time to see how risk evolved
# Cross-reference with price data to see which got liquidated
for snap in risky_positions['snapshots']:
    print(f"{snap['snapshot_time']}: {snap['user']} - {snap['distance_pct']}% from liq")

{
  "coin": "BTC",
  "at": 1792936651022,
  "mark_price": 80339.0,
  "min_usd": 10000.0,
  "side": "both",
  "long_usd": 882499099.09,
  "long_count": 2930,
  "short_usd": 1310430967.89,
  "short_count": 1351,
  "count": 1,
  "total_matching": 4281,
  "truncated": true,
  "positions": [
    {
      "address": "0x5b5d51203a0f9079f8aeb098a6523a13f298c060",
      "side": "short",
      "size": -2640.20445,
      "notional_usd": 212111385.31,
      "last_change": 1792913160000
    }
  ],
  "data_through": 1792936651022,
  "history_start": 1792540800000
}

{
  "coin": "BTC",
  "from": 1792933133863,
  "to": 1792934933863,
  "mark_from": 80429.0,
  "mark_to": 80257.0,
  "min_usd": 10000.0,
  "wallets_changed": 201,
  "by_kind": {"open": 19, "increase": 65, "reduce": 52, "close": 24, "flip": 41},
  "net_long_usd_change": -11065828.9,
  "net_short_usd_change": -1915862.62,
  "count": 201,
  "truncated": false,
  "changes": [
    {
      "address": "0xa379bedcc2a237cab1021cc2a4744edfb6c42618",
      "kind": "close",
      "size_before": 164.92724,
      "size_after": 0.0,
      "size_change": -164.92724,
      "usd_before": 13264932.99,
      "usd_after": 0.0,
      "usd_change": -13264932.99,
      "fills": 802
    }
  ]
}

{
  "address": "0x3d7a23552dfddc40b5872cbd148f4f1b4f055c36",
  "start": 1792850311022,
  "end": 1792936711022,
  "current": [
    {"coin": "BTC", "side": "long", "size": 0.66336, "notional_usd": 53293.68}
  ],
  "count": 362,
  "truncated": false,
  "order": "newest_first",
  "changes": [
    {
      "t": 1792936620000,
      "coin": "BTC",
      "kind": "increase",
      "size_before": 0.66321,
      "size_after": 0.66336,
      "size_change": 0.00015,
      "price": 80345.0,
      "usd_after": 53297.66,
      "fills": 1
    }
  ]
}

import requests, time

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

# Who holds the biggest BTC positions right now?
book = requests.get(f"{BASE}/BTC/book?limit=10", headers=headers).json()
print(f"Longs ${book['long_usd']:,.0f} vs shorts ${book['short_usd']:,.0f}")
for p in book["positions"]:
    print(p["side"], p["address"], f"${p['notional_usd']:,.0f}")

# What changed in the last hour?
now = int(time.time() * 1000)
diff = requests.get(f"{BASE}/BTC/diff?from={now - 3600_000}", headers=headers).json()
print(diff["by_kind"], f"net long change ${diff['net_long_usd_change']:,.0f}")

# Every change in a window, page by page
start, changes = now - 6 * 3600_000, []
while True:
    page = requests.get(f"{BASE}/BTC/changes?start={start}&end={now}", headers=headers).json()
    changes += page["changes"]
    if not page["has_more"]:
        break
    start = page["next_start"]
print(len(changes), "BTC position changes in 6 hours")

{
  "coin": null,
  "start": 1793021821298,
  "end": 1793108221298,
  "method": null,
  "total": {
    "liquidations": 5482,
    "usd": 11433816.13,
    "usd_market": 11428245.21,
    "usd_backstop": 5570.92,
    "takers": 988,
    "liquidated_wallets": 1800
  },
  "count": 100,
  "takers": [
    {
      "address": "0x25773676902085225ae5751075e4161369334897",
      "usd": 619452.41,
      "share": 0.0542,
      "liquidations": 108,
      "maker_usd": 619452.41,
      "backstop_usd": 0,
      "coins": 25,
      "top_coins": [
        { "coin": "io:NBIS", "usd": 134393.49 },
        { "coin": "xyz:CRWV", "usd": 127254.53 },
        { "coin": "BTC", "usd": 80811.24 }
      ],
      "first": 1793022598701,
      "last": 1793107986924
    }
  ],
  "data_through": 1793108221297,
  "history_start": 1792540800000
}

{
  "coin": "BTC",
  "start": 1793021821298,
  "end": 1793108221298,
  "address": null,
  "role": null,
  "method": null,
  "count": 1,
  "liquidations": [
    {
      "t": 1793026697729,
      "coin": "BTC",
      "tid": 405580047710537,
      "hash": "0xc3c5f710886aea8c...",
      "method": "market",
      "liquidated": "0xd4802f72024d88fef5ee4991423073605aa084ce",
      "liquidated_side": "short",
      "size": 0.00178,
      "px": 80353.0,
      "usd": 143.03,
      "mark_px": 80344.0,
      "liquidated_size_before": -0.00178,
      "counterparty": "0x6e8bc7cd0978397b06a14af2a8c31f5daeffea79",
      "counterparty_role": "maker",
      "counterparty_size_before": -20.60243,
      "counterparty_size_after": -20.60421
    }
  ],
  "next_start": 1793026697730,
  "has_more": true,
  "data_through": 1793108221297,
  "history_start": 1792540800000
}

import requests

KEY = "YOUR_KEY"
BASE = "https://api.moondev.com/api/hl/liquidation_flow"

# Who took the BTC liquidations in the last 24 hours?
top = requests.get(f"{BASE}/takers", params={"coin": "BTC", "limit": 10, "api_key": KEY}).json()
print(f"${top['total']['usd']:,.0f} liquidated, {top['total']['takers']} wallets took the other side")
for t in top["takers"]:
    print(t["address"], f"${t['usd']:,.0f}", f"{t['share']:.1%}")

# Every liquidation one wallet has taken this week
wallet = top["takers"][0]["address"]
start, fills = None, []
while True:
    params = {"address": wallet, "role": "taker", "limit": 10000, "api_key": KEY}
    if start:
        params["start"] = start
    page = requests.get(f"{BASE}/fills", params=params).json()
    fills += page["liquidations"]
    if not page["has_more"]:
        break
    start = page["next_start"]
print(len(fills), "liquidations taken by", wallet)

{
  "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": []
  }
}

{
  "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
    }
  ]
}

{
  "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
    }
  ]
}

{
  "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
    }
  }
}

{
  "time_window": "1h",
  "overall": {
    "buy_volume_usd": 923134333.04,
    "sell_volume_usd": 1146007719.76,
    "imbalance_ratio": -0.1077,
    "dominant_side": "SELL"
  },
  "by_coin": {
    "BTC": {
      "buy_volume_usd": 616856512.28,
      "sell_volume_usd": 814592126.43,
      "net_imbalance_usd": -197735614.15,
      "imbalance_ratio": -0.1381,
      "buy_count": 15420,
      "sell_count": 18350,
      "dominant_side": "SELL"
    },
    "ETH": { "..." : "..." },
    "SOL": { "..." : "..." },
    "ADA": { "..." : "..." },
    "EIGEN": { "..." : "..." },
    "...": "130 symbols total"
  }
}

import requests

API_KEY = "your_api_key"

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

# Compare any two coins for pairs trading
ada = r["by_coin"]["ADA"]["imbalance_ratio"]
eigen = r["by_coin"]["EIGEN"]["imbalance_ratio"]
spread = ada - eigen  # Your entry signal!

print(f"ADA imbalance: {ada:.4f}")
print(f"EIGEN imbalance: {eigen:.4f}")
print(f"Spread: {spread:.4f}")

import requests, json

API_KEY = "your_api_key"

# Pull all recent trades and save locally
trades = requests.get(
    "https://api.moondev.com/api/trades.json",
    headers={"X-API-Key": API_KEY}
).json()

with open("trades_backup.json", "w") as f:
    json.dump(trades, f)

print(f"Saved {trades['trade_count']} trades")

curl "https://api.moondev.com/api/user/0xABC.../fills?minutes=10&limit=2000&api_key=YOUR_KEY"

{
  "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
}

{
  "address": "0xABC123...",
  "fills": [
    {
      "coin": "BTC",
      "side": "A",
      "px": 80278.0,
      "sz": 0.25536,
      "value_usd": 20499.79,
      "time": 1793104908590,
      "timestamp": "2026-10-27T12:41:48.590000+00:00",
      "dir": "Open Short",
      "closedPnl": 0.0,
      "fee": -0.614993,
      "feeToken": "USDC",
      "hash": "0x305bae4e...",
      "oid": 587247279724,
      "tid": 184579510914126,
      "crossed": false,
      "startPosition": "0.0",
      "liquidation": null,
      "counterparty": "0x8fc63e5b8166253346b95b747c4e0a73bc8944fb",
      "counterparty_order": {
        "oid": 587247342306,
        "crossed": true,
        "has_cloid": true,
        "twap": false,
        "tif": null,
        "orig_sz": null,
        "limit_px": null
      }
    }
  ],
  "total_count": 1543,
  "since_ms": 1765183800000,
  "order": "newest_first",
  "truncated": true,
  "newest_ms": 1786651098765,
  "oldest_ms": 1786650012345,
  "page_summary": {
    "scope": "returned_page",
    "total_pnl": 1250.40,
    "total_volume": 185000.00,
    "total_fees": 92.50
  },
  "summary": "(deprecated alias of page_summary)"
}

curl "https://api.moondev.com/api/user/0xABC.../flow?minutes=60&coin=BTC&api_key=YOUR_KEY"

{
  "address": "0x...",
  "since_ms": 1786650000000,
  "coin": "BTC",
  "bought_sz": 1.08012,
  "sold_sz": 0.77272,
  "net_sz": 0.3074,
  "bought_usd": 68540.12,
  "sold_usd": 49102.77,
  "net_usd": 19437.35,
  "count": 8,
  "first_ms": 1786650012345,
  "last_ms": 1786651098765,
  "truncated": false
}

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}")

# Poll recent fills (fast lane — ~50ms for any wallet)
recent = requests.get(
    f"https://api.moondev.com/api/user/{WALLET}/fills?minutes=10&limit=2000",
    headers={"X-API-Key": API_KEY}
)
if recent.status_code == 503:
    # fills_scanner_busy — retry shortly or use your fallback source
    print("Scanner busy, retrying shortly...")
else:
    data = recent.json()
    print(f"Fills in last 10 min: {data['total_count']} (window start: {data['since_ms']})")
    if data["truncated"]:
        # newest fills kept — page backwards from oldest_ms for the rest
        print(f"Page covers {data['oldest_ms']} → {data['newest_ms']}, older fills cut off")

# Net flow — has this wallet net-bought or net-sold in the last hour?
# Cap-proof: aggregated server-side over EVERY fill in the window
flow = requests.get(
    f"https://api.moondev.com/api/user/{WALLET}/flow?minutes=60&coin=BTC",
    headers={"X-API-Key": API_KEY}
).json()
side = "net BUYER" if flow["net_usd"] > 0 else "net SELLER"
print(f"BTC last hour: {side} of ${abs(flow['net_usd']):,.0f} ({flow['count']} fills)")

# Get ALL fills (no window — first contact with a fill-sparse
# wallet can take ~30s; prefer paging with since_ms windows)
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']}")

{
  "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}
      ]
    }
  ]
}

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

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}")

# Position snapshots over the last 24 hours
history = requests.get(
    f"{BASE_URL}/api/hlp/positions/history?hours=24",
    headers={"X-API-Key": API_KEY}
).json()

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

{
  "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"
}

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

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

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

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

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})")

curl "https://api.moondev.com/api/poly/profitable-traders?api_key=YOUR_API_KEY"

from api import MoonDevAPI

api = MoonDevAPI()  # reads MOONDEV_API_KEY from .env
data = api.get_poly_profitable_traders()

for trader in data["traders"]:
    print(f"{trader['wallet']}: ${trader['pnl_7d']:,.2f} P&L | ${trader['volume_7d']:,.2f} volume")
    print(f"  Profile: {trader['polymarket_link']}")

import requests

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

for trader in data["traders"]:
    print(f"{trader['wallet']}: ${trader['pnl_7d']:,.2f} P&L ({trader['trades_7d']} trades)")
    print(f"  Profile: {trader['polymarket_link']}")

const response = await fetch(
  "https://api.moondev.com/api/poly/profitable-traders",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);
const data = await response.json();

data.traders.forEach(t => {
  const short = `${t.wallet.slice(0,6)}...${t.wallet.slice(-4)}`;
  console.log(`${short}: $${t.pnl_7d.toFixed(2)} P&L (${t.trades_7d} trades)`);
});

{
  "total": 2894,
  "full_list": true,
  "updated_at": "2026-04-14T15:41:42.182139+00:00",
  "stats": {
    "wallets_checked": 1163,
    "queue_depth": 0,
    "uptime_minutes": 5.3
  },
  "traders": [
    {
      "wallet": "0x8c80d213c0cbad777d06ee3f58f6ca4bc03102c3",
      "polymarket_link": "https://polymarket.com/0x8c80d213c0cbad777d06ee3f58f6ca4bc03102c3",
      "pnl_7d": 1183556.88,
      "volume_7d": 1376544.64,
      "trades_7d": 470,
      "redeems_7d": 1,
      "discovered_at": "2026-04-13T22:50:05.965342+00:00",
      "source": "trending"
    }
  ]
}

python examples/34_polymarket_traders.py

curl "https://api.moondev.com/api/poly/whales?api_key=YOUR_API_KEY&min_usd=5000&days=7&side=BUY"

from api import MoonDevAPI

api = MoonDevAPI()

whales      = api.get_poly_whales(min_usd=5000, days=7, side="BUY")
top_wallets = api.get_poly_whale_top_traders(days=7)
top_markets = api.get_poly_whale_top_markets(days=7)
daily       = api.get_poly_whale_daily(days=30)
status      = api.poly_whales_health()   # no auth required

for trade in whales["trades"]:
    print(f"{trade['ts']} {trade['side']} ${trade['usd_amount']:,.0f} | {trade['market_title']}")
    print(f"  wallet: {trade['wallet']}  tx: {trade['tx_hash']}")

import requests

response = requests.get(
    "https://api.moondev.com/api/poly/whales",
    headers={"X-API-Key": "YOUR_API_KEY"},
    params={"min_usd": 5000, "days": 7, "side": "BUY"},
)
data = response.json()

for trade in data["trades"]:
    print(f"{trade['ts']} {trade['side']} ${trade['usd_amount']:,.0f} | {trade['market_title']}")

const url = new URL("https://api.moondev.com/api/poly/whales");
url.searchParams.set("min_usd", "5000");
url.searchParams.set("days", "7");
url.searchParams.set("side", "BUY");

const response = await fetch(url, { headers: { "X-API-Key": "YOUR_API_KEY" } });
const data = await response.json();

data.trades.forEach(t => {
  console.log(`${t.ts} ${t.side} $${t.usd_amount.toLocaleString()} | ${t.market_title}`);
});

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}")

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

# Overall market pressure
overall = imbalance["overall"]
print(f"Market: {overall['dominant_side']} pressure (ratio: {overall['imbalance_ratio']:.4f})")

# Top coins by sell pressure
for coin, data in sorted(imbalance["by_coin"].items(), key=lambda x: x[1]["imbalance_ratio"]):
    print(f"{coin}: {data['dominant_side']} ({data['imbalance_ratio']:.4f})")

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);
  });

# 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