API Overview

The GX Exchange API provides programmatic access to the GX Chain L1 decentralized exchange. It supports perpetual futures trading, spot markets, real-time market data streaming, and on-chain asset management through three complementary interfaces.

Architecture

Base URLs

All connections require TLS 1.3 on mainnet and testnet.

Public Stats API

The Stats API provides protocol-level analytics data without authentication. Used by stats.gx.exchange, CoinGecko, DeFiLlama, and third-party dashboards.

Base URL: https://api.gx.exchange/stats

Example:

curl https://api.gx.exchange/stats/total_users
# {"total_users": 15432}
 
curl https://api.gx.exchange/stats/asset_ctxs
# [{"coin":"BTC-USD","mark_price":65000,"open_interest":1234567,"volume_24h":98765432,...}]

No authentication required. Rate limited to 100 requests/minute per IP.

Request Format

All REST requests and responses use JSON. Set the Content-Type: application/json header on every request that includes a body.

The API exposes two primary REST endpoints:

• POST /info — Public data queries. No authentication required. The type field in the request body determines which data is returned.
• POST /exchange — Authenticated exchange actions (orders, cancels, transfers). Requires an EIP-712 signature.

Additional RESTful endpoints are available for specific resources:

Authentication Model

GX Exchange uses EIP-712 typed data signatures for all authenticated exchange operations. Every exchange action is signed with an Ethereum private key, providing cryptographic proof of authorization without transmitting secrets.

Direct Wallet Signing

Sign each request with the private key of the trading address. This is the simplest approach but requires the main wallet key to be available at signing time.

API Wallets (Agent Delegation)

For automated trading, authorize a secondary keypair (an “agent”) to sign on your behalf:

1. Generate a fresh Ethereum keypair
2. Authorize it via the approveAgent exchange action signed by your main wallet
3. Use the agent’s private key for all subsequent request signatures
4. Revoke the agent at any time

See Nonces and API Wallets and Signing for implementation details.

HMAC-SHA256 Authentication (API Keys)

API key endpoints use a separate HMAC-SHA256 signing scheme with three headers:

The signature is computed as:

message   = timestamp + method + path + body
signature = base64( HMAC-SHA256( secret, message ) )

The server enforces a 30-second replay window on the timestamp.

EIP-712 Domain

All EIP-712 signatures use the following domain:

Response Format

Successful responses return HTTP 200 with a JSON body.

Exchange endpoint responses include a status field:

{ "status": "ok", "response": { "type": "order", "data": { "statuses": [...] } } }

{ "status": "err", "response": "Insufficient margin" }

Info endpoint responses return the requested data directly as the response body.

Quick Start

import { GxClient } from "@gx-exchange/sdk";
 
const client = new GxClient();
await client.connect("https://api.gx.exchange");
 
// Public data -- no auth required
const mids = await client.getAllMids();
console.log("BTC mid:", mids["BTC"]);
 
// Authenticated trading -- requires wallet
client.setWallet("0xYourPrivateKey...");
const result = await client.placeOrder([{
  coin: "BTC",
  isBuy: true,
  sz: 0.001,
  limitPx: 60000,
  tif: "Gtc",
  reduceOnly: false,
}]);

from gx_exchange.info import Info
from gx_exchange.utils.constants import MAINNET_API_URL
 
info = Info(MAINNET_API_URL, skip_ws=True)
mids = info.all_mids()
print(f"BTC mid: {mids.get('BTC')}")

SDKs

Source: github.com/GX-EXCHANGE