Spot Info Queries

All spot info queries are sent as POST /info with the appropriate type field. No authentication is required.

Get Spot Metadata

Returns the complete list of spot trading pairs and token information.

POST /info
Content-Type: application/json

{ "type": "spotMeta" }

Response

Field	Type	Description
`universe`	`Array`	List of spot trading pairs
`universe[].tokens`	`[int, int]`	Base and quote token indices
`universe[].name`	`string`	Pair identifier (e.g., `"BTC-USDC"`)
`universe[].index`	`int`	Spot pair index
`tokens`	`Array`	Token metadata array
`tokens[].name`	`string`	Token symbol
`tokens[].szDecimals`	`int`	Size decimal places
`tokens[].weiDecimals`	`int`	Wei (on-chain) decimal places
`tokens[].index`	`int`	Token index

{
  "universe": [
    { "tokens": [10000, 10001], "name": "BTC-USDC", "index": 10000 },
    { "tokens": [10002, 10001], "name": "ETH-USDC", "index": 10002 }
  ],
  "tokens": [
    { "name": "BTC", "szDecimals": 8, "weiDecimals": 8, "index": 10000 },
    { "name": "USDC", "szDecimals": 6, "weiDecimals": 6, "index": 10001 },
    { "name": "ETH", "szDecimals": 5, "weiDecimals": 18, "index": 10002 }
  ]
}

Token Index Ranges

Spot token indices start at 10000 and are assigned sequentially as new tokens are listed.

Range	Description
`0` — `9999`	Reserved for perpetual asset indices
`10000`+	Spot token indices

Get Spot Markets (REST)

An alternative REST endpoint is available for spot market data:

GET /v1/spot/markets

No authentication required.

Response

{
  "markets": [
    {
      "pair": "BTC-USDC",
      "base_asset": "BTC",
      "quote_asset": "USDC",
      "price_decimals": 2,
      "size_decimals": 6,
      "min_order_size": "0.0001",
      "tick_size": "0.01",
      "status": "active"
    },
    {
      "pair": "ETH-USDC",
      "base_asset": "ETH",
      "quote_asset": "USDC",
      "price_decimals": 2,
      "size_decimals": 5,
      "min_order_size": "0.001",
      "tick_size": "0.01",
      "status": "active"
    }
  ]
}

Get Spot Orderbook

GET /v1/spot/orderbook/:pair?depth=20

No authentication required.

Path Parameters

Parameter	Type	Description
`pair`	`string`	Trading pair (e.g., `BTC-USDC`)

Query Parameters

Parameter	Type	Default	Description
`depth`	`int`	`20`	Number of price levels per side

Response

{
  "pair": "BTC-USDC",
  "timestamp": "2026-03-30T12:00:00.123Z",
  "bids": [
    { "price": "67480.00", "size": "1.250" },
    { "price": "67475.50", "size": "0.800" },
    { "price": "67470.00", "size": "3.100" }
  ],
  "asks": [
    { "price": "67500.00", "size": "0.500" },
    { "price": "67505.25", "size": "1.100" },
    { "price": "67510.00", "size": "2.400" }
  ]
}

Spot User State

To query a user’s spot balances, use the clearinghouse state endpoint and inspect the spot positions:

POST /info
{ "type": "clearinghouseState", "user": "0x1234...abcd" }

Spot balances are included in the assetPositions array alongside perpetual positions.

Spot vs Perpetual Ordering

When placing spot orders through the /exchange endpoint, use the spot asset index (10000+) in the a field:

{
  "type": "order",
  "orders": [
    {
      "a": 10000,
      "b": true,
      "p": "67000.0",
      "s": "0.001",
      "r": false,
      "t": { "limit": { "tif": "Gtc" } }
    }
  ],
  "grouping": "na"
}

Code Examples

TypeScript

import { GxClient } from "@gx-exchange/sdk";
 
const client = new GxClient();
await client.connect("https://api.gx.exchange");
 
// Get spot metadata
const spotMeta = await client.info({ type: "spotMeta" });
 
// Build token lookup
const tokenMap = new Map<string, any>();
spotMeta.tokens.forEach((t: any) => tokenMap.set(t.name, t));
 
console.log("BTC spot decimals:", tokenMap.get("BTC")?.szDecimals);
console.log("Available pairs:", spotMeta.universe.map((u: any) => u.name));

Python

from gx_exchange.info import Info
from gx_exchange.utils.constants import MAINNET_API_URL
 
info = Info(MAINNET_API_URL, skip_ws=True)
 
# Get spot metadata
spot_meta = info.spot_meta()
 
# Build token lookup
token_map = {t["name"]: t for t in spot_meta["tokens"]}
print(f"BTC spot decimals: {token_map['BTC']['szDecimals']}")
print(f"Available pairs: {[u['name'] for u in spot_meta['universe']]}")

Perpetuals Exchange Endpoint