dex/docs/SDK.md

LX SDK Documentation

Overview

LX provides multiple SDKs and APIs for integration:

• JSON-RPC 2.0 - Standard HTTP API for web and mobile clients
• gRPC - High-performance binary protocol for internal Lux Network IPC
• QZMQ - Quantum-secure ZeroMQ for node-to-node communication
• WebSocket - Real-time market data streaming

Quick Start

1. Start the DEX Node

# Build the node
make build

# Run the node
./bin/luxd

This starts:

• JSON-RPC API on port 8080
• gRPC server on port 50051
• WebSocket server on port 8081
• P2P networking on port 5000

API Protocols

JSON-RPC API (Port 8080)

The JSON-RPC API is the primary interface for trading operations.

Endpoint

POST http://localhost:8080/rpc

Available Methods

Method	Description	Parameters
lx_ping	Test connectivity	{}
lx_getInfo	Get node information	{}
lx_placeOrder	Place a new order	{symbol, type, side, price, size, userID}
lx_cancelOrder	Cancel an order	{orderId}
lx_getOrder	Get order details	{orderId}
lx_getOrderBook	Get order book snapshot	{depth}
lx_getBestBid	Get best bid price	{}
lx_getBestAsk	Get best ask price	{}
lx_getTrades	Get recent trades	{limit}

Example: Place Order

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,        # 0=Limit, 1=Market, 2=Stop
      "side": 0,        # 0=Buy, 1=Sell
      "price": 50000,
      "size": 1.0,
      "userID": "trader1"
    },
    "id": 1
  }'

gRPC API (Port 50051)

The gRPC API provides high-performance binary protocol for internal services.

Proto Definition

See proto/lxdex.proto for the complete service definition.

Key Services

• Order Management: PlaceOrder, CancelOrder, GetOrder
• Market Data: GetOrderBook, StreamOrderBook, GetTrades, StreamTrades
• Account Management: GetBalance, GetPositions
• Node Management: GetNodeInfo, GetPeers, Ping

Example: gRPC Client (Go)

import (
    "context"
    "google.golang.org/grpc"
    pb "github.com/luxfi/dex/pkg/grpc/pb"
)

// Connect to gRPC server
conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure())
defer conn.Close()

client := pb.NewLXDEXServiceClient(conn)

// Place an order
resp, err := client.PlaceOrder(context.Background(), &pb.PlaceOrderRequest{
    Symbol: "BTC-USD",
    Type:   pb.OrderType_LIMIT,
    Side:   pb.OrderSide_BUY,
    Price:  50000,
    Size:   1.0,
    UserId: "trader1",
})

WebSocket API (Port 8081)

Real-time market data streaming.

Connection

const ws = new WebSocket('ws://localhost:8081');

Subscribe to Market Data

ws.send(JSON.stringify({
    type: 'subscribe',
    symbols: ['BTC-USD'],
    depth: 10
}));

SDK Libraries

TypeScript/JavaScript SDK

npm install @luxfi/trading

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

const client = new Client({
    rpcUrl: 'http://localhost:8080/rpc',
    wsUrl: 'ws://localhost:8081'
});

// Place an order
const order = await client.placeOrder({
    symbol: 'BTC-USD',
    type: 'limit',
    side: 'buy',
    price: 50000,
    size: 1.0
});

// Subscribe to order book
client.subscribeOrderBook('BTC-USD', (book) => {
    console.log('Best bid:', book.bids[0]);
    console.log('Best ask:', book.asks[0]);
});

Python SDK

pip install luxfi-dex

from luxfi_dex import Client

client = Client(
    json_rpc_url='http://localhost:8080/rpc',
    ws_url='ws://localhost:8081'
)

# Place an order
order = client.place_order(
    symbol='BTC-USD',
    order_type='limit',
    side='buy',
    price=50000,
    size=1.0
)

# Get order book
book = client.get_order_book('BTC-USD', depth=10)
print(f"Best bid: {book['bids'][0]}")
print(f"Best ask: {book['asks'][0]}")

Go SDK

go get github.com/luxfi/dex/sdk/go

import (
    "github.com/luxfi/dex/sdk/go/lxdex"
)

client := lxdex.NewClient(
    lxdex.WithJSONRPC("http://localhost:8080/rpc"),
    lxdex.WithGRPC("localhost:50051"),
)

// Place an order
order, err := client.PlaceOrder(ctx, &lxdex.Order{
    Symbol: "BTC-USD",
    Type:   lxdex.OrderTypeLimit,
    Side:   lxdex.Buy,
    Price:  50000,
    Size:   1.0,
})

// Stream order book
stream, err := client.StreamOrderBook(ctx, "BTC-USD")
for {
    update, err := stream.Recv()
    if err != nil {
        break
    }
    fmt.Printf("Order book update: %+v\n", update)
}

Order Types

Type	Value	Description
LIMIT	0	Order with specific price
MARKET	1	Immediate execution at best price
STOP	2	Trigger at stop price
STOP_LIMIT	3	Stop that becomes limit
ICEBERG	4	Hidden quantity order
PEG	5	Pegged to best bid/ask

Order Sides

Side	Value	Description
BUY	0	Buy order
SELL	1	Sell order

Time in Force

TIF	Description
GTC	Good Till Cancelled
IOC	Immediate Or Cancel
FOK	Fill Or Kill
DAY	Day Order

Error Codes

JSON-RPC Error Codes

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

gRPC Status Codes

• OK Success
• CANCELLED Operation cancelled
• INVALID_ARGUMENT Invalid parameters
• NOT_FOUND Resource not found
• ALREADY_EXISTS Resource already exists
• PERMISSION_DENIED Permission denied
• RESOURCE_EXHAUSTED Rate limit exceeded
• INTERNAL Internal server error

Rate Limits

• Orders: 100 per second per user
• Cancellations: 100 per second per user
• Market Data: 1000 requests per minute
• WebSocket Connections: 10 per IP

Authentication

Currently, the DEX uses userID for identification. In production:

• JWT tokens for API authentication
• API keys for programmatic access
• Signature verification for orders

Testing

Test Network

# Start test node
./bin/luxd --testnet

# Use test endpoints
JSON-RPC: http://localhost:18080/rpc
gRPC: localhost:15051
WebSocket: ws://localhost:18081

Example Test Script

# Run comprehensive tests
./curl-examples.sh

# Run SDK tests
npm test           # TypeScript
python -m pytest   # Python
go test ./...      # Go

Performance

• Order Matching: 169 ns avg match (C++, 10 threads; p50 125 ns, p99 292 ns)
• Throughput: 11.88M orders/sec (C++, 10 threads) / 2.2M (pure Go) on the CPU default build; up to 12.76B orders/sec on the GPU-native per-book matcher (CGO_ENABLED=1, lux-gpu, parity-verified GPU==CPU; AMD 8060S) / 9.13B (GB10)
• Block Time: 1ms finality
• Network: Quantum-secure with BLS signatures

Architecture

┌─────────────────────────────────────────────┐
│              Client Applications             │
├─────────────────────────────────────────────┤
│     JSON-RPC │ gRPC │ WebSocket │ QZMQ     │
├─────────────────────────────────────────────┤
│              LX Core Engine              │
│  • Order Matching (Go/C++/GPU)              │
│  • Risk Management                          │
│  • State Management (BadgerDB)              │
├─────────────────────────────────────────────┤
│           Lux Consensus Layer                │
│  • K=3 Validators                           │
│  • 1ms Block Finality                       │
│  • Quantum-Resistant Signatures             │
└─────────────────────────────────────────────┘

Support

• GitHub: https://github.com/luxfi/dex
• Documentation: https://docs.luxfi.com/dex
• Discord: https://discord.gg/luxfi

License

MIT License - See LICENSE file for details