Self-hosted Lighter API Backend

Rust services for running an enhanced API layer in front of the Lighter exchange APIs. The stack ingests market data, stores local history, serves REST endpoints, provides WebSocket fan-out and replay, exports data-lake files, and includes optional user auth, API keys, rate limits, billing hooks, metrics, and dashboards.

This repository is meant for operators who want to run their own backend on their own hardware. It does not include a frontend, hosted account system, private deployment history, or operator-specific infrastructure.

What is included

• api: Axum REST API on port 8080
• ws-proxy: WebSocket stream and replay service on port 8081
• ingestion: Lighter REST/WebSocket ingestion into Postgres and Redis
• data-lake: optional Parquet export service backed by S3-compatible storage
• storage, common, and lighter-client library crates
• PostgreSQL migrations, Docker Compose, Prometheus, Grafana, load tests, and CI

Quick start

Requirements: Docker, Docker Compose, Rust 1.91 if building locally, and jq for the smoke script.

cp .env.example .env
docker compose up -d --build
bash scripts/smoke_test.sh --no-teardown

Create an API key manually:

curl -X POST http://localhost:8080/api/v1/keys \
  -H "X-Admin-Secret: replace_with_64_hex_chars_from_openssl_rand" \
  -H "Content-Type: application/json" \
  -d '{"name":"local-dev","tier":"free"}'

Use the key:

curl http://localhost:8080/api/v1/orderbook/0 \
  -H "X-Api-Key: hlt_your_key_here"

Grafana is available at http://localhost:3000 in the default Compose stack. Prometheus is available at http://localhost:9090.

Configuration

All application settings use the HML_* environment variable prefix. The runtime interface is intentionally stable for this release:

• API keys keep the hlt_ prefix.
• REST endpoints remain under /api/v1.
• WebSocket endpoints remain /ws and /ws/replay.
• Stripe billing is optional. If Stripe settings are omitted, billing endpoints are unavailable and core API service continues to run.
• /metrics requires X-Admin-Secret when HML_API__ADMIN_SECRET is configured. Without an admin secret, metrics are disabled.

See docs/SELF_HOSTING.md and deploy/SECRETS.md before deploying publicly.

Local development

cargo fmt --all -- --check
cargo check --workspace --locked
cargo clippy --workspace --locked -- -D warnings
cargo test --workspace --locked

Load testing uses k6:

k6 run -e API_URL=http://localhost:8080 -e ADMIN_SECRET="$HML_API__ADMIN_SECRET" tests/load/api_baseline.js

Documentation

• API design
• Architecture
• Database schema
• Lighter API mapping
• Self-hosting guide
• Security notes

License

MIT