Lux Exchange API - GraphQL Proxy and Token Data Service

Overview

Lux Exchange API (github.com/luxfi/exchange-api) is a TypeScript Express server that serves as a GraphQL proxy for the Lux DEX frontend. It intercepts Uniswap-compatible GraphQL queries, handles LUX/ZOO chain queries natively using Blockscout and subgraph data sources, and proxies all other chain queries to the upstream Uniswap API. Works alongside exchange-proxy (Go CORS proxy for raw Uniswap endpoints) and exchange-sdk (TypeScript order matching engine library).

When to use

• Adding new token metadata to the Lux DEX token list
• Modifying how LUX/ZOO chain data is fetched or presented
• Adjusting cache TTLs for price/volume data
• Adding new GraphQL operation handlers for native chains
• Debugging token price display issues in the exchange frontend

Hard requirements

1. ALWAYS use github.com/luxfi/* package paths -- NEVER go-ethereum or luxfi
2. Native chain handling is determined by NATIVE_CHAINS set: LUX and ZOO
3. Stablecoins (USDT, USDC, LUSD, DAI, BUSD) are force-priced to $1.00
4. Prices and volumes exceeding 1e12 are capped to 0 (subgraph overflow artifacts)
5. Unhandled native chain operations fall through to Uniswap proxy

Quick reference

Core Concepts

Three-Service Architecture

Request Flow

DEX Frontend
    |
    v
exchange-api :4000
    POST /v1/graphql
    |
    +-- chain=LUX or ZOO? --> Native handler (Blockscout + Subgraph V2/V3)
    |
    +-- other chain? -------> Proxy to Uniswap API (with caching)

Native GraphQL Operations

Data Sources

Cache TTLs

Environment Variables

Known Tokens (lux-tokens.ts)

20 LUX mainnet tokens with verified on-chain addresses:

Plus LUSD, LZOO, LLUX, LBLAST, LBNB, LBOME, LBONK, LCELO, LDOGS, LPOL, LTON, CYRUS, MELANIA, TRUMP, Z.

Exchange Proxy (Go, :8088)

CORS reverse proxy that forwards requests to Uniswap upstream APIs with Origin: https://app.uniswap.org header injection:

In-memory SHA256-keyed cache with tiered TTLs (5s quotes, 30s pools, 5min tokens, 10s GraphQL).

Exchange SDK (TypeScript, npm)

Order matching engine library (@hanzo/matching-engine@1.0.1):

• Book: AVL tree + Fibonacci heap order book with bid/ask heaps
• Order: Limit/market orders with side (ASK/BID) and status tracking
• Trade: Fill execution with matched/rejected/new orders
• Candle: OHLCV candlestick aggregation (1min, 1hr, 1day, 1week)
• Servers: HTTP REST + Socket.IO WebSocket transports

File Structure

exchange-api/
  src/
    index.ts          -- Express server, routes, CORS
    graphql.ts        -- GraphQL handler, operation dispatch, Uniswap proxy
    blockscout.ts     -- Blockscout + subgraph V2/V3 data fetchers
    cache.ts          -- In-memory TTL cache with periodic cleanup
    lux-tokens.ts     -- 20 known LUX mainnet tokens with metadata
  Dockerfile          -- Multi-stage Node 22 alpine
  package.json        -- @luxfi/exchange-api@0.1.0
  tsconfig.json       -- ES2022, strict, commonjs

exchange-proxy/
  main.go             -- HTTP server with graceful shutdown
  proxy/proxy.go      -- CORS proxy, in-memory cache, upstream routing
  go.mod              -- github.com/luxfi/exchange-proxy, Go 1.23

exchange-sdk/
  src/
    Book.ts           -- Order book (AVL + Fibonacci heap)
    Order.ts          -- Order model (limit/market, bid/ask)
    Trade.ts          -- Trade execution model
    Candle.ts         -- OHLCV candlestick builder
    server.ts         -- Demo server with random order generation
    servers/          -- HTTP and Socket.IO transports
    clients/          -- Client implementations
  package.json        -- @hanzo/matching-engine@1.0.1

Troubleshooting

Related Skills

• lux/lux-exchange.md -- DEX frontend and omnichain routing
• lux/lux-dex.md -- CLOB engine (high-performance order matching)
• lux/lux-evm.md -- EVM with DEX precompiles