dex/client/python/README.md

LX DEX Python Trading Client

Multi-protocol trading client for LX DEX. Supports WebSocket and gRPC protocols with async/await.

Installation

pip install -r requirements.txt

Or with uv:

uv pip install -r requirements.txt

Programmatic Usage

The client can be imported as a module for programmatic trading:

import asyncio
from lx_client import WebSocketClient, GrpcClient, create_client

async def main():
    # Using WebSocket client
    async with WebSocketClient("ws://localhost:8081") as client:
        # Place an order
        order = await client.place_order(
            symbol="BTC-USD",
            side="buy",
            order_type="limit",
            price=50000.0,
            size=0.1,
        )
        print(f"Order placed: {order.order_id}")

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

        # Get positions
        positions = await client.get_positions()
        for pos in positions:
            print(f"{pos.symbol}: {pos.size} @ {pos.entry_price}")

asyncio.run(main())

Using gRPC Client

import asyncio
from lx_client import GrpcClient

async def main():
    async with GrpcClient("localhost", 50051) as client:
        # Authenticate
        await client.authenticate("api_key", "api_secret")

        # Place order
        order = await client.place_order(
            symbol="ETH-USD",
            side="sell",
            order_type="limit",
            price=3500.0,
            size=1.0,
        )

        # Ping server
        latency = await client.ping()
        print(f"Latency: {latency}ms")

        # Get node info
        info = await client.get_node_info()
        print(f"Node: {info['node_id']}")

asyncio.run(main())

Factory Function

from lx_client import create_client

# Create WebSocket client
ws_client = create_client("ws", url="ws://localhost:8081")

# Create gRPC client
grpc_client = create_client("grpc", host="localhost", port=50051)

Streaming Data

import asyncio
from lx_client import WebSocketClient

async def stream_orderbook():
    async with WebSocketClient("ws://localhost:8081") as client:
        async for book in client.stream_orderbook("BTC-USD"):
            print(f"Bid: {book.bids[0].price} Ask: {book.asks[0].price}")

asyncio.run(stream_orderbook())

Command Line Interface

Interactive Mode

# WebSocket (default)
python main.py -i

# gRPC
python main.py --protocol grpc -i

Single Commands

# Place a limit buy order
python main.py place_order BTC-USD buy limit 50000 0.1

# Cancel an order
python main.py cancel_order 12345

# Get order book
python main.py get_orderbook BTC-USD

# Get positions
python main.py get_positions

# Get balance
python main.py get_balance USD

# Using gRPC protocol
python main.py -p grpc ping
python main.py -p grpc info

CLI Options

Flag	Description
-p, --protocol	Protocol: ws (default) or grpc
-u, --url	WebSocket URL (default: ws://localhost:8081)
--host	gRPC host (default: localhost)
--port	gRPC port (default: 50051)
--tls	Enable TLS for gRPC
-k, --key	API key
-s, --secret	API secret
-i, --interactive	Interactive mode
-v, --verbose	Verbose output

Environment Variables

Variable	Description
LX_API_KEY	API key for authentication
LX_API_SECRET	API secret for authentication

Interactive Commands

Command	Description
place_order <symbol> <side> <type> <price> <size>	Place order
cancel_order <order_id>	Cancel order
get_order <order_id>	Get order details
get_orders [symbol] [status]	List orders
get_orderbook <symbol> [depth]	Get order book
get_positions	List positions
get_balance <asset>	Get balance
auth <key> <secret>	Authenticate
ping	Ping server (gRPC only)
info	Node info (gRPC only)
help	Show help
quit	Exit

Order Types

• limit - Limit order
• market - Market order
• stop - Stop order
• stop_limit - Stop-limit order

Data Types

Order

@dataclass
class Order:
    order_id: int
    symbol: str
    order_type: OrderType
    side: OrderSide
    price: float
    size: float
    filled: float
    remaining: float
    status: OrderStatus
    user_id: str
    client_id: str
    timestamp: int
    time_in_force: TimeInForce
    post_only: bool
    reduce_only: bool

OrderBook

@dataclass
class OrderBook:
    symbol: str
    bids: List[PriceLevel]
    asks: List[PriceLevel]
    timestamp: int

@dataclass
class PriceLevel:
    price: float
    size: float
    count: int

Position

@dataclass
class Position:
    symbol: str
    size: float
    entry_price: float
    mark_price: float
    pnl: float
    margin: float

Balance

@dataclass
class Balance:
    asset: str
    available: float
    locked: float
    total: float

Protocol Comparison

Feature	WebSocket	gRPC
Streaming	Yes	Yes
Latency	Low	Lower
Binary protocol	No	Yes
Connection overhead	Higher	Lower
Ping/Info	No	Yes
TLS support	wss://	--tls

Examples

Authenticated Trading

export LX_API_KEY="your-key"
export LX_API_SECRET="your-secret"
python main.py -i

Custom Endpoint

# WebSocket
python main.py -u ws://testnet.lux.exchange:8081 -i

# gRPC
python main.py -p grpc --host testnet.lux.exchange --port 50051 --tls -i

Verbose Mode

python main.py -v place_order BTC-USD buy limit 50000 0.1

Project Structure

client/python/
  main.py              # CLI entry point
  requirements.txt     # Dependencies
  README.md            # This file
  lx_client/
    __init__.py        # Package exports
    base.py            # Abstract base class and types
    websocket_client.py # WebSocket implementation
    grpc_client.py     # gRPC implementation

Related

• Python SDK - Full SDK with additional features
• Go SDK - Go client library
• TypeScript Engine - TypeScript implementation