API Reference

Complete API documentation for LX - WebSocket, REST, and gRPC APIs

LX API Documentation

Specification: LP-9002 DEX API & RPC | Discussions

Overview

LX provides multiple API protocols for integration:

  • JSON-RPC 2.0 - Primary RPC interface (dex.* namespace)
  • gRPC - High-performance binary protocol (port 9760)
  • WebSocket - Real-time push feeds
  • REST - Standard HTTP endpoints
  • FIX - Financial Information eXchange (institutional)

Implementation Status

ComponentSourceStatus
JSON-RPC APIpkg/api/jsonrpc.goComplete
WebSocket Serverpkg/api/websocket_server.goComplete
Trader Clientpkg/client/trader_client.goComplete
gRPC Protocolpkg/grpc/pb/Complete

WebSocket API

Connection

ws://localhost:8081/ws       # Development
wss://ws.lux.exchange/v1     # Production

Endpoints

ProtocolDevelopmentProduction
WebSocketws://localhost:8081wss://ws.lux.exchange
RESThttp://localhost:8080https://api.lux.exchange
gRPClocalhost:9760grpc.lux.exchange:9760
FIX 4.4localhost:9880fix.lux.exchange:9880

Message Format

All WebSocket messages use JSON:

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

Subscriptions

Order Book

Subscribe to real-time order book updates:

{
  "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
}

Trades

Subscribe to trade stream:

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

Response:

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

Trading Operations

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      # Development
https://api.lux.network/v1        # Production

Endpoints

GET /orderbook/:symbol

Get order book snapshot.

Parameters:

  • symbol (path): Trading pair (e.g., BTC-USDT)
  • depth (query): 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:

{
  "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.

Response:

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

GET /trades

Get recent trades.

Parameters:

  • symbol (query): Trading pair
  • 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)

JSON-RPC 2.0

Endpoint

POST http://localhost:8080/rpc

Methods

MethodDescriptionParameters
lx_pingTest connectivity{}
lx_getInfoGet node information{}
lx_placeOrderPlace ordersymbol, type, side, price, size, userID
lx_cancelOrderCancel orderorderId
lx_getOrderGet order detailsorderId
lx_getOrderBookGet order bookdepth
lx_getBestBidGet best bid{}
lx_getBestAskGet best ask{}
lx_getTradesGet recent tradeslimit

Example

curl -X POST http://localhost:8080/rpc \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "lx_placeOrder",
    "params": {
      "symbol": "BTC-USD",
      "type": 0,
      "side": 0,
      "price": 50000,
      "size": 1.0,
      "userID": "trader1"
    },
    "id": 1
  }'

Authentication

API Key

Include in headers:

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

JWT

After login:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Rate Limiting

Limits

Endpoint TypeLimit
Public endpoints100 req/min
Private endpoints300 req/min
WebSocket connections5 concurrent
Order placement10 orders/sec

Headers

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

Error Handling

Error Format

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

Error Codes

CodeDescription
INVALID_SYMBOLTrading pair not supported
INVALID_ORDER_TYPEOrder type not recognized
INSUFFICIENT_BALANCENot enough balance
ORDER_NOT_FOUNDOrder ID does not exist
RATE_LIMIT_EXCEEDEDToo many requests
UNAUTHORIZEDAuthentication required
FORBIDDENAccess denied
INTERNAL_ERRORServer error

JSON-RPC Error Codes

CodeDescription
-32700Parse Error
-32600Invalid Request
-32601Method Not Found
-32602Invalid Params
-32603Internal Error

Glossary

Complete glossary of LX terminology - 100+ terms covering trading, blockchain, and system concepts

Market Data RPCs

gRPC API for order book, trades, and real-time market data streaming

On this page

LX API DocumentationOverviewImplementation StatusWebSocket APIConnectionEndpointsMessage FormatSubscriptionsOrder BookTradesTrading OperationsPlace OrderCancel OrderREST APIBase URLEndpointsGET /orderbook/:symbolPOST /ordersDELETE /orders/:order_idGET /tradesgRPC APIProto DefinitionConnectionJSON-RPC 2.0EndpointMethodsExampleAuthenticationAPI KeyJWTRate LimitingLimitsHeadersError HandlingError FormatError CodesJSON-RPC Error Codes