API Servers

GX Core exposes three API interfaces for different use cases: a REST API for standard operations, a WebSocket server for real-time streaming, and an EVM JSON-RPC endpoint for smart contract interaction.

REST API (Port 4001)

The REST API is the primary interface for placing orders, querying account state, and retrieving market data. It is built on axum (Rust async HTTP framework) and follows a format compatible with common DEX indexer standards.

Endpoints

Authentication

All state-changing endpoints (POST /v1/orders, POST /v1/orders/cancel, POST /v1/withdraw) require an EIP-712 typed data signature in the request body. The signature is verified against the sender’s Ethereum address.

For programmatic access, API key authentication via HMAC-SHA256 is also supported, enabling high-frequency trading bots to submit orders without per-request wallet signing.

Rate Limiting

Example: Place an Order

curl -X POST https://api.gx.exchange/v1/orders \
  -H "Content-Type: application/json" \
  -d '{
    "market": "BTC-USD",
    "side": "buy",
    "size": "1.0",
    "price": "67400",
    "type": "limit",
    "timeInForce": "GTC",
    "signature": "0x...",
    "address": "0x..."
  }'

Example: Get Order Book

curl https://api.gx.exchange/v1/orderbooks/perpetualMarket/BTC-USD

Response:

{
  "bids": [
    { "price": "67400", "size": "2.5" },
    { "price": "67390", "size": "5.0" }
  ],
  "asks": [
    { "price": "67410", "size": "1.8" },
    { "price": "67420", "size": "3.2" }
  ]
}

WebSocket Server (Port 4000)

The WebSocket server provides real-time streaming of order book updates, trades, positions, and account state changes. It is designed for low-latency consumption by trading interfaces and bots.

Channels

Connection

const ws = new WebSocket("wss://ws.gx.exchange");
 
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "subscribe",
    channel: "orderbook",
    market: "BTC-USD"
  }));
};
 
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  // Process real-time orderbook updates
};

Message Format

All WebSocket messages are JSON-encoded. Updates include a sequence number for gap detection:

{
  "channel": "orderbook",
  "market": "BTC-USD",
  "sequence": 42,
  "data": {
    "bids": [["67400", "2.5"]],
    "asks": [["67410", "1.8"]]
  }
}

EVM JSON-RPC (Port 3001)

The EVM JSON-RPC endpoint provides standard Ethereum JSON-RPC compatibility for the GX EVM execution environment. Any Ethereum tooling (MetaMask, Hardhat, Foundry, ethers.js) can connect to this endpoint.

Supported Methods

Connection

# Using cast (Foundry)
cast chain-id --rpc-url https://rpc.gx.exchange
 
# Using curl
curl -X POST https://rpc.gx.exchange \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

Port Summary