# Hyperlight API — Complete Documentation

> Enhanced trading API infrastructure for the Lighter perpetual DEX. Batch queries across 1,000+ accounts, enriched WebSocket streams, historical data lake, and backtesting replay.

Last updated: 2026-03-14

---

## What is Hyperlight?

Hyperlight is the enhanced API layer for the Lighter perpetual DEX (a ZK-proof L2 on Ethereum). Lighter's native API provides ~50 REST endpoints and WebSocket streams. Hyperlight adds batch operations, enriched data streams, historical exports, and production infrastructure on top — without breaking any existing integrations.

**Base URL:** https://api.hyperlightapi.xyz
**Website:** https://hyperlightapi.xyz
**OpenAPI Spec:** https://hyperlightapi.xyz/openapi.yaml

## Key Statistics

- **1000+** Accounts per query
- **43** REST endpoints
- **1s** Orderbook snapshots
- **24/7** Real-time streaming

## Core Features

### Batch Account Queries

Query positions, fills, and liquidations across 1,000+ accounts in a single call.

Instead of looping through accounts one by one, send a single POST with up to 1,000 account indices. The response includes positions, open orders, and recent fills for every account — perfect for portfolio dashboards and risk monitoring.

```
POST /api/v1/accounts/batch
{ "accounts": [0, 1, 2, …, 999], "by": "index" }

→ 1000 accounts in a single request
```

### Enriched WebSocket Streams

See who is placing orders, not just what orders exist. Every stream message includes account attribution and whale flags.

Standard Lighter streams show anonymous orders. Hyperlight enriches every message with the submitting account index, flags large orders above configurable thresholds, and offers depth-aggregated views at custom tick sizes.

```
wss://api.hyperlightapi.xyz/stream
subscribe: { "channel": "order_book/0" }

→ { "account": 42, "side": "bid", "whale": true }
```

### Backtesting Replay

Replay historical market data via WebSocket at 0.1x–100x speed with pause and scrub.

Point your bot at a replay WebSocket endpoint. Specify a time range and playback speed. Messages arrive in the exact sequence they originally occurred — so your strategy code runs identically to how it would have in production.

```
wss://api.hyperlightapi.xyz/ws/replay
→ { "type": "replay", "market_id": 0,
    "start": "2025-01-01", "speed": 10 }

→ streams historical data at 10x speed
```

## Additional Features

### Historical Data Lake

Parquet exports of trades, orderbook snapshots, candles, and funding rates for backtesting.

Every second, Hyperlight snapshots the full orderbook across all markets. Combined with tick-level trade data, this creates a high-fidelity historical dataset exported as Parquet files.

### Time-Range Queries

Fetch trades, funding rates, and candles for arbitrary time ranges with flexible pagination.

Lighter’s native API only supports cursor-based pagination from the latest data backward. Hyperlight adds start/end timestamp parameters, forward pagination, and configurable page sizes.

### Production Infra

Tiered rate limiting, SHA-256 key storage, Prometheus metrics, and low-latency Rust performance.

Built entirely in Rust with Axum and Tokio. API keys are SHA-256 hashed before storage. Rate limits are enforced per-key with Redis sliding windows.

## Architecture

Hyperlight sits between your application and the Lighter DEX as a transparent proxy and enhancement layer. Swap your base URL and everything keeps working — enhanced endpoints are additive.

### Your Application

- Connect via REST or WebSocket — use the same endpoints you already know from Lighter.
- Existing Lighter API calls work unchanged. Just swap the base URL.
- Add batch queries, enriched streams, and historical exports on top of what you already have.

### The Hyperlight Layer

- Built in Rust with Axum and Tokio for low-latency, high-throughput performance.
- PostgreSQL for time-partitioned historical data, Redis for caching and real-time pubsub.
- Enriches every orderbook and trade message with account attribution and whale flags.
- Manages API keys, tiered rate limits, and Prometheus metrics out of the box.

### Lighter DEX

- A ZK-proof perpetual DEX running as an Ethereum L2 with ~50 native API endpoints.
- Hyperlight proxies and caches native calls — you get faster responses with no extra load on the chain.
- Native endpoints remain available as a fallback; Hyperlight adds capabilities, never removes them.

## Use Cases

### Quantitative Traders

Backtest strategies with historical orderbook snapshots, trade data, and funding rate history at variable replay speeds.

**Example:** Download Parquet exports of 1-second orderbook snapshots for backtesting spread strategies.

### Trading Ops & Surveillance

Monitor fills, exposure, and counterparty activity across hundreds of accounts with batch queries and enriched orderbook streams.

**Example:** Batch-query 500 account positions to track desk exposure and flag concentration risk across all markets.

### DeFi Protocol Teams

Integrate Lighter market data into your frontend, risk engine, or oracle with time-range queries and flexible pagination.

**Example:** Fetch hourly funding rate history to display in a protocol dashboard or use as an oracle input.

### Trading Infra Developers

Build internal tools and monitoring systems on a production API with tiered rate limits, key management, and Prometheus metrics.

**Example:** Set up real-time large order alerts via WebSocket to trigger notifications in your ops dashboard.

### Data Aggregators & Resellers

Integrate Lighter market data into multi-venue analytics packages. Batch queries and Parquet exports feed directly into existing data pipelines.

**Example:** Ingest full-depth orderbook snapshots via Parquet exports for redistribution as part of a multi-venue DEX data product.

## Getting Started

01. **Sign Up** — Create a free account in seconds. Your API key (prefixed hlt_) is generated instantly with 75K credits/month included.
02. **Swap Your Base URL** — Replace your Lighter API base URL with api.hyperlightapi.xyz. Existing queries still work — no code rewrite needed.
03. **Use Enhanced Endpoints** — Access batch queries, enriched streams, historical exports, and backtesting replay — capabilities beyond Lighter’s native API.
04. **Scale as You Grow** — Upgrade your plan for higher rate limits, larger batch sizes, more WebSocket connections, and Parquet data lake access.

## Technical Specifications

- **Built in Rust:** Axum + Tokio async runtime for low-latency, high-throughput performance.
- **PostgreSQL + Redis:** Time-partitioned tables for history, Redis for caching and pubsub.
- **Parquet Exports:** Columnar format for Python, DuckDB, Spark, and modern analytics tools.
- **1s Snapshots:** Orderbook snapshots every second for high-resolution backtesting.
- **SHA-256 Keys:** Keys hashed before storage. Plaintext shown once, never retained.
- **Production Monitoring:** Prometheus metrics, health monitoring, and automated alerting.

## Pricing

1 credit = 1 standard REST request. Batch endpoints cost 25 credits. Heavy batch operations cost 50 credits. WebSocket streaming is free (not metered).

### Free — Free/mo

  - 75K credits/month
  - 30 requests/min
  - 5 accounts per batch
  - Anonymous orderbook data
  - Hard cap (no overage)
  - 1 WebSocket connection

  Credits: 75K/month | Batch size: 5 accounts

### Starter — $199/mo

  - 750K credits/month included
  - 300 requests/min
  - 200 accounts per batch
  - $29 per 100K overage
  - 50 WebSocket connections

  Credits: 750K/month | Batch size: 200 accounts

### Growth — $849/mo

  - 5M credits/month included
  - 3,000 requests/min
  - 1,000 accounts per batch
  - $9 per 100K overage
  - 500 WebSocket connections

  Credits: 5M/month | Batch size: 1,000 accounts

### Scale — $1,799/mo

  - 25M credits/month included
  - 30,000 requests/min
  - 2,500 accounts per batch
  - $4 per 100K overage
  - 1,000 WebSocket connections

  Credits: 25M/month | Batch size: 2,500 accounts

### Enterprise — Custom/mo

  - Unlimited credits
  - Unlimited requests/min
  - 5,000 accounts per batch
  - Unlimited WebSocket connections
  - Dedicated support

  Credits: Unlimited/month | Batch size: 5,000 accounts

All paid plans include metered overage billing. Cancel or downgrade anytime via the Stripe Customer Portal.

## API Authentication

- **API Key Header:** `X-Api-Key: hlt_...` (preferred)
- **Bearer Token:** `Authorization: Bearer hlt_...`
- **Query Parameter:** `?api_key=hlt_...`
- **JWT Bearer:** `Authorization: Bearer <jwt>` (for user/dashboard endpoints)
- **WebSocket:** Send `{"type": "auth", "api_key": "hlt_..."}` as the first message

API keys are prefixed with `hlt_` and SHA-256 hashed before storage. Plaintext is shown exactly once at creation.

## API Response Format

**Success:**
```json
{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": 1706745600000
  }
}
```

**Error:**
```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "details": { "retry_after": 30 }
  }
}
```

## FAQ

**Q: What is Hyperlight?**
A: Hyperlight is an enhanced API layer for the Lighter perpetual DEX. It adds batch queries across 1,000+ accounts, enriched WebSocket streams with account attribution, a historical data lake with Parquet exports, and backtesting replay on top of Lighter's native API.

**Q: How do I get started?**
A: Sign up for a free account at hyperlightapi.xyz to get an API key (prefixed hlt_) with 75K credits/month. Replace your Lighter API base URL with api.hyperlightapi.xyz. Existing queries keep working.

**Q: What is the pricing?**
A: Free ($0/mo, 75K credits), Starter ($199/mo, 750K credits), Growth ($849/mo, 5M credits), Scale ($1,799/mo, 25M credits), Enterprise (custom). 1 credit = 1 REST request.

**Q: Is it compatible with existing Lighter API code?**
A: Yes. Swap your base URL and existing queries continue working. Enhanced endpoints are additive.

**Q: What data formats are supported?**
A: JSON via REST and WebSocket. Historical data also available as Parquet exports for Python, DuckDB, Spark, etc.

## Contact

- Website: https://hyperlightapi.xyz
- Email: hello@hyperlightapi.xyz