Quick Start Guide

curl -X POST https://api.hyperlightapi.xyz/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "your-secure-password",
    "tos_accepted": true
  }'

curl https://api.hyperlightapi.xyz/api/v1/orderbook/0 \
  -H "X-Api-Key: hlt_your_key_here"

# With API key
curl https://api.hyperlightapi.xyz/api/v1/orderbook/0 \
  -H "Authorization: Bearer hlt_your_key_here"

# With JWT (from login/register)
curl https://api.hyperlightapi.xyz/api/v1/keys \
  -H "Authorization: Bearer eyJhbG..."

curl "https://api.hyperlightapi.xyz/api/v1/orderbook/0?api_key=hlt_your_key_here"

// Client sends:
{"type": "auth", "api_key": "hlt_your_key_here"}

// Server responds:
{"type": "authenticated", "tier": "free", "max_subscriptions": 5}

curl https://api.hyperlightapi.xyz/health

curl https://api.hyperlightapi.xyz/api/v1/orderbook/0 \
  -H "X-Api-Key: hlt_your_key_here"

curl -X POST https://api.hyperlightapi.xyz/api/v1/accounts/batch \
  -H "X-Api-Key: hlt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"accounts": [0, 1, 2, 3, 4], "by": "index"}'

{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": 1706745600000,
    "total": 100,
    "limit": 50,
    "offset": 0
  }
}

# Install: npm install -g wscat
wscat -c wss://api.hyperlightapi.xyz/ws

# Once connected, send:
{"type": "auth", "api_key": "hlt_your_key_here"}

// Subscribe
{"type": "subscribe", "channel": "trade/0"}
// → {"type": "subscribed", "channel": "trade/0"}

// Unsubscribe
{"type": "unsubscribe", "channel": "trade/0"}
// → {"type": "unsubscribed", "channel": "trade/0"}

{
  "type": "trade_update",
  "channel": "trade/0",
  "trade": {
    "trade_id": 12345,
    "price": "3200.50",
    "size": "2.5",
    "is_maker_ask": true,
    "ask_account_id": 42,
    "bid_account_id": 99,
    "market_id": 0,
    "timestamp": 1706700000123
  }
}

import asyncio, websockets, json

async def replay():
    async with websockets.connect("wss://api.hyperlightapi.xyz/ws/replay") as ws:
        # Authenticate
        await ws.send(json.dumps({
            "type": "auth",
            "api_key": "hlt_your_key_here"
        }))
        print(json.loads(await ws.recv()))  # authenticated

        # Start replay: ETH-PERP, 1 hour, 10x speed
        await ws.send(json.dumps({
            "type": "replay",
            "market_id": 0,
            "start": "2026-01-01T00:00:00Z",
            "end": "2026-01-01T01:00:00Z",
            "speed": 10.0
        }))

        async for msg in ws:
            event = json.loads(msg)
            if event["type"] == "replay_event":
                print(f"[{event['event_type']}] {event['data']}")
            elif event["type"] == "replay_complete":
                print(f"Done! {event['events_sent']} events")
                break

asyncio.run(replay())

{"type": "pause"}    // → {"type": "replay_paused"}
{"type": "resume"}   // → {"type": "replay_resumed"}
{"type": "stop"}     // → {"type": "replay_stopped"}

{
  "type": "replay_event",
  "event_type": "trade",
  "data": {
    "market_id": 0,
    "trade_id": 12345,
    "price": "3200.50",
    "size": "2.5",
    "side": "buy"
  },
  "ts": 1717200330000,
  "replay_ts": 1706700050000
}

curl -X POST https://api.hyperlightapi.xyz/api/v1/signals \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ETH price alert",
    "market_id": 0,
    "rule_definition": {
      "conditions": [
        {"field": "trade_price", "op": "gt", "value": 4000}
      ],
      "logic": "AND"
    },
    "delivery_channels": [
      {
        "type": "webhook",
        "url": "https://your-app.com/webhook",
        "secret": "your-hmac-secret-min-16-chars"
      }
    ],
    "cooldown_secs": 300
  }'

{
  "conditions": [
    {"field": "trade_price", "op": "gt", "value": 4000},
    {"field": "trade_size", "op": "gt", "value": 50}
  ],
  "logic": "AND"
}

curl "https://api.hyperlightapi.xyz/api/v1/signals/{signal_id}/backtest?start=1767225600000&end=1767312000000" \
  -H "Authorization: Bearer <your_jwt_token>"

import time, requests

def api_call(url, headers):
    resp = requests.get(url, headers=headers)
    if resp.status_code == 429:
        wait = int(resp.headers.get("Retry-After", 60))
        print(f"Rate limited. Waiting {wait}s...")
        time.sleep(wait)
        return api_call(url, headers)  # retry
    return resp.json()

# 1. Health check (no auth)
curl -s https://api.hyperlightapi.xyz/health | jq .status
# Expected: "ok"

# 2. Orderbook (auth required)
curl -s https://api.hyperlightapi.xyz/api/v1/orderbook/0 \
  -H "X-Api-Key: hlt_your_key_here" | jq .success
# Expected: true

# 3. Trades in time range
curl -s "https://api.hyperlightapi.xyz/api/v1/trades/by-time?market_id=0&start=2026-01-01T00:00:00Z&end=2026-01-02T00:00:00Z&limit=5" \
  -H "X-Api-Key: hlt_your_key_here" | jq '.data.trades | length'
# Expected: > 0

# 4. Batch query 5 accounts
curl -s -X POST https://api.hyperlightapi.xyz/api/v1/accounts/batch \
  -H "X-Api-Key: hlt_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"accounts": [0,1,2,3,4], "by": "index"}' | jq '.data.accounts | length'
# Expected: up to 5

# 5. Current funding rates
curl -s https://api.hyperlightapi.xyz/api/v1/funding-rates \
  -H "X-Api-Key: hlt_your_key_here" | jq '.data.rates | length'
# Expected: > 0

# 6. Exchange stats
curl -s https://api.hyperlightapi.xyz/api/v1/exchange/stats \
  -H "X-Api-Key: hlt_your_key_here" | jq .success
# Expected: true

# 7. Check rate limit headers
curl -sI https://api.hyperlightapi.xyz/api/v1/orderbook/0 \
  -H "X-Api-Key: hlt_your_key_here" | grep -i x-ratelimit
# Expected: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

# 8. WebSocket (requires wscat: npm i -g wscat)
# wscat -c wss://api.hyperlightapi.xyz/ws
# > {"type":"auth","api_key":"hlt_your_key_here"}
# < {"type":"authenticated",...}
# > {"type":"subscribe","channel":"order_book/0"}
# < {"type":"subscribed","channel":"order_book/0"}

{
  "success": false,
  "data": {
    "code": "rate_limit_exceeded",
    "message": "rate limit exceeded"
  },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": 1706745600000
  }
}