+------------------------------------------------------------------+
|                    LX DATA INFRASTRUCTURE                     |
+------------------------------------------------------------------+
|                                                                    |
|  Real-Time Feeds                    Historical Data               |
|  +---------------------------+     +---------------------------+  |
|  | Order Book (L1/L2/L3)    |     | OHLCV Candles            |  |
|  | Trade Tick Stream        |     | Tick-by-Tick Archive     |  |
|  | Best Bid/Offer (BBO)     |     | Order Book Snapshots     |  |
|  | Market Status Updates    |     | Funding Rate History     |  |
|  +---------------------------+     +---------------------------+  |
|              |                              |                      |
|              v                              v                      |
|  +---------------------------+     +---------------------------+  |
|  | WebSocket Streams        |     | REST API / Bulk Download  |  |
|  | Binary Protocol (gRPC)   |     | Parquet / CSV / JSON      |  |
|  | Multicast UDP            |     | S3-Compatible Storage     |  |
|  +---------------------------+     +---------------------------+  |
|                                                                    |
+------------------------------------------------------------------+

// All timestamps are Unix nanoseconds (int64)
interface Timestamp {
  // Nanoseconds since Unix epoch (1970-01-01T00:00:00Z)
  // Example: 1702339200000000000 = 2023-12-12T00:00:00Z
  timestamp_ns: bigint

  // Human-readable ISO 8601 (optional, for display)
  timestamp_iso?: string  // "2023-12-12T00:00:00.000000000Z"
}

// Fixed-point decimal representation
interface Decimal {
  // String representation for exact precision
  value: string       // "50000.12345678"

  // Scaled integer (price * 10^decimals)
  scaled: bigint      // 5000012345678n

  // Decimal places for this market
  decimals: number    // 8
}

// All prices use quote currency precision
// All quantities use base currency precision

BASE-QUOTE[-TYPE][-EXPIRY]

Examples:
  BTC-USD          # Spot
  ETH-USDT         # Spot
  BTC-USD-PERP     # Perpetual
  BTC-USD-241227   # Future (Dec 27, 2024)
  BTC-USD-C-50000  # Call option, strike 50000

import { LxDataClient } from '@luxfi/dex-data'

const client = new LxDataClient({
  endpoint: 'wss://data.lux.network/ws',
  apiKey: process.env.LX_API_KEY
})

// Subscribe to order book
await client.subscribe({
  channel: 'orderbook',
  symbol: 'BTC-USD',
  depth: 25
})

// Handle updates
client.on('orderbook', (update) => {
  console.log(`${update.symbol} bid: ${update.bids[0].price}`)
})

// Subscribe to trades
await client.subscribe({
  channel: 'trades',
  symbol: 'BTC-USD'
})

client.on('trade', (trade) => {
  console.log(`Trade: ${trade.price} x ${trade.size}`)
})

# Get order book snapshot
curl -H "X-API-Key: $API_KEY" \
  "https://api.lux.network/v1/data/orderbook/BTC-USD?depth=100"

# Get recent trades
curl -H "X-API-Key: $API_KEY" \
  "https://api.lux.network/v1/data/trades/BTC-USD?limit=1000"

# Get OHLCV candles
curl -H "X-API-Key: $API_KEY" \
  "https://api.lux.network/v1/data/candles/BTC-USD?interval=1h&limit=500"

import (
    "github.com/luxfi/dex/pkg/data"
    pb "github.com/luxfi/dex/pkg/data/proto"
)

client, err := data.NewClient(&data.Config{
    Endpoint: "data.lux.network:9760",
    APIKey:   os.Getenv("LX_API_KEY"),
})

// Stream order book
stream, err := client.StreamOrderBook(ctx, &pb.OrderBookRequest{
    Symbol: "BTC-USD",
    Depth:  100,
})

for {
    update, err := stream.Recv()
    if err != nil {
        break
    }
    fmt.Printf("Bid: %s Ask: %s\n", update.BestBid, update.BestAsk)
}

// Client must send ping every 30 seconds
// Server responds with pong containing server timestamp

// Ping
{ "type": "ping", "timestamp": 1702339200000 }

// Pong
{ "type": "pong", "timestamp": 1702339200001, "server_time": 1702339200000 }

const reconnectConfig = {
  // Initial delay before first reconnect attempt
  initialDelay: 100,        // ms

  // Maximum delay between attempts
  maxDelay: 30000,          // ms

  // Exponential backoff multiplier
  backoffMultiplier: 2,

  // Add random jitter to prevent thundering herd
  jitterFactor: 0.1,

  // Maximum reconnection attempts
  maxAttempts: 10
}

interface DataMessage {
  // Global sequence (monotonically increasing)
  sequence: bigint

  // Channel-specific sequence
  channel_sequence: bigint

  // Timestamp of generation
  timestamp_ns: bigint
}

// Request missing messages
{
  "type": "replay",
  "channel": "trades",
  "symbol": "BTC-USD",
  "from_sequence": 12345,
  "to_sequence": 12350
}

// Response includes all messages in range
{
  "type": "replay_response",
  "messages": [...],
  "complete": true
}

// Measure end-to-end latency
client.on('message', (msg) => {
  const now = Date.now() * 1_000_000  // Convert to nanoseconds
  const latency = now - msg.timestamp_ns

  metrics.recordLatency('e2e', latency)
})

{
  "type": "metrics",
  "latency": {
    "p50_us": 12,
    "p95_us": 45,
    "p99_us": 89,
    "p999_us": 234
  },
  "throughput": {
    "messages_per_sec": 1234567,
    "bytes_per_sec": 45678901
  }
}