dex/docs/API.md

LX API Documentation

Table of Contents

• WebSocket API
• REST API
• gRPC API
• Authentication
• Rate Limiting
• Error Handling

WebSocket API

Connection

ws://localhost:8080/ws
wss://api.lux.network/ws (production)

Message Format

All WebSocket messages use JSON format:

{
  "type": "message_type",
  "data": {},
  "timestamp": 1234567890
}

Subscription Messages

Subscribe to Order Book

{
  "type": "subscribe",
  "channel": "orderbook",
  "symbol": "BTC-USDT",
  "depth": 20
}

Response:

{
  "type": "orderbook_snapshot",
  "symbol": "BTC-USDT",
  "bids": [[50000, 1.5], [49999, 2.0]],
  "asks": [[50001, 1.2], [50002, 0.8]],
  "timestamp": 1234567890
}

Subscribe to Trades

{
  "type": "subscribe",
  "channel": "trades",
  "symbol": "BTC-USDT"
}

Response:

{
  "type": "trade",
  "symbol": "BTC-USDT",
  "price": 50000,
  "size": 0.5,
  "side": "buy",
  "timestamp": 1234567890
}

Trading Messages

Place Order

{
  "type": "place_order",
  "symbol": "BTC-USDT",
  "side": "buy",
  "order_type": "limit",
  "price": 50000,
  "size": 0.1,
  "time_in_force": "GTC",
  "post_only": false
}

Response:

{
  "type": "order_placed",
  "order_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "open",
  "filled_size": 0,
  "remaining_size": 0.1,
  "timestamp": 1234567890
}

Cancel Order

{
  "type": "cancel_order",
  "order_id": "123e4567-e89b-12d3-a456-426614174000"
}

REST API

Base URL

http://localhost:8080/api/v1
https://api.lux.network/v1 (production)

Endpoints

GET /orderbook/{symbol}

Get order book for a symbol.

Parameters:

• symbol (path): Trading pair symbol (e.g., BTC-USDT)
• depth (query): Order book depth (default: 20, max: 100)

Response:

{
  "symbol": "BTC-USDT",
  "bids": [
    {"price": 50000, "size": 1.5},
    {"price": 49999, "size": 2.0}
  ],
  "asks": [
    {"price": 50001, "size": 1.2},
    {"price": 50002, "size": 0.8}
  ],
  "timestamp": 1234567890
}

POST /orders

Place a new order.

Request Body:

{
  "symbol": "BTC-USDT",
  "side": "buy",
  "type": "limit",
  "price": 50000,
  "size": 0.1,
  "time_in_force": "GTC"
}

Response:

{
  "order_id": "123e4567-e89b-12d3-a456-426614174000",
  "symbol": "BTC-USDT",
  "side": "buy",
  "type": "limit",
  "price": 50000,
  "size": 0.1,
  "status": "open",
  "created_at": 1234567890
}

DELETE /orders/{order_id}

Cancel an order.

Parameters:

• order_id (path): Order ID to cancel

Response:

{
  "order_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "cancelled",
  "cancelled_at": 1234567890
}

GET /trades

Get recent trades.

Parameters:

• symbol (query): Trading pair symbol
• limit (query): Number of trades (default: 100, max: 1000)

Response:

{
  "trades": [
    {
      "trade_id": "abc123",
      "symbol": "BTC-USDT",
      "price": 50000,
      "size": 0.5,
      "side": "buy",
      "timestamp": 1234567890
    }
  ]
}

gRPC API

Proto Definition

syntax = "proto3";
package lxdex;

service TradingService {
  rpc PlaceOrder(OrderRequest) returns (OrderResponse);
  rpc CancelOrder(CancelRequest) returns (CancelResponse);
  rpc GetOrderBook(OrderBookRequest) returns (OrderBookResponse);
  rpc StreamTrades(StreamRequest) returns (stream Trade);
}

message OrderRequest {
  string symbol = 1;
  string side = 2;
  string type = 3;
  double price = 4;
  double size = 5;
}

message OrderResponse {
  string order_id = 1;
  string status = 2;
  int64 timestamp = 3;
}

Connection

conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
client := pb.NewTradingServiceClient(conn)

Authentication

API Key Authentication

Include API key in headers:

X-API-Key: your_api_key_here
X-API-Secret: your_api_secret_here

JWT Authentication

After login, include JWT token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Rate Limiting

Limits

• Public endpoints: 100 requests per minute
• Private endpoints: 300 requests per minute
• WebSocket connections: 5 concurrent connections
• Order placement: 10 orders per second

Headers

Rate limit information in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1234567890

Error Handling

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Insufficient balance for order",
    "details": {
      "required": 100.5,
      "available": 50.0
    }
  }
}

Common Error Codes

Code	Description
INVALID_SYMBOL	Trading pair not supported
INVALID_ORDER_TYPE	Order type not recognized
INSUFFICIENT_BALANCE	Not enough balance
ORDER_NOT_FOUND	Order ID does not exist
RATE_LIMIT_EXCEEDED	Too many requests
UNAUTHORIZED	Authentication required
FORBIDDEN	Access denied
INTERNAL_ERROR	Server error

WebSocket Error Handling

{
  "type": "error",
  "error": {
    "code": "SUBSCRIPTION_FAILED",
    "message": "Failed to subscribe to channel",
    "channel": "orderbook",
    "symbol": "INVALID-PAIR"
  }
}

SDKs

Go SDK

import "github.com/luxfi/dex/sdk/go"

client := lxdex.NewClient("api_key", "api_secret")
order, err := client.PlaceOrder("BTC-USDT", "buy", "limit", 50000, 0.1)

Python SDK

from luxfi_dex import Client

client = Client(api_key="your_key", api_secret="your_secret")
order = client.place_order("BTC-USDT", "buy", "limit", 50000, 0.1)

TypeScript SDK

import { Client } from '@luxfi/trading';

const client = new Client({
  apiKey: 'your_key',
  apiSecret: 'your_secret'
});

const order = await client.placeOrder({
  symbol: 'BTC-USDT',
  side: 'buy',
  type: 'limit',
  price: 50000,
  size: 0.1
});