Common Definitions & Terms

Order types, symbol formats, margin modes, decimal precision, and key trading terms used throughout the GaiaEx API.

Order Types

Value	Description
`market`	Executes immediately at the best available price. No `price` field needed.
`limit`	Placed at a specific price. Sits on the order book until filled or cancelled.

Order Side

Orders use a boolean is_buy field:

Value	Meaning
`true`	Buy / Long
`false`	Sell / Short

Margin Modes

Mode	`is_cross` value	Description
Cross	`true`	Shares margin across all positions. Unrealized PnL from other positions can prevent liquidation.
Isolated	`false`	Each position has its own dedicated margin. Liquidation risk is contained to that position.

INFO

Some symbols (particularly RWA deployer symbols) only support isolated margin. The backend will automatically correct cross to isolated if required — you don't need to handle this.

Symbol Format

Standard Perpetuals

Standard crypto perpetual symbols use plain uppercase tickers:

BTC, ETH, SOL, DOGE, ARB, OP, ...

Deployer Symbols (RWA, Ventures, Index)

Real-world asset (RWA), pre-IPO venture, and index symbols use a prefix format:

Prefix	Asset Class	Examples
`xyz:`	Equities, commodities, forex	`xyz:AAPL`, `xyz:TSLA`, `xyz:GOLD`, `xyz:EUR`
`vntl:`	Pre-IPO venture tokens	`vntl:OPENAI`, `vntl:ANTHROPIC` (SpaceX is `xyz:SPCX` on the `xyz:` deployer)
`cash:`	Index products	`cash:USA500`

TIP

Use GET /symbols/list to retrieve all currently supported symbols with their asset class, max leverage, and margin mode.

Collateral

GaiaEx uses USDC as the sole user-facing collateral. When trading deployer symbols that internally require different settlement tokens (USDT0 for cash: or USDH for vntl:), the backend automatically handles conversion. Users only deposit, withdraw, and see USDC.

Decimal Handling

All monetary values (price, size, balance, etc.) use string-encoded decimals in request bodies to avoid floating-point precision issues.
Response values may be returned as either strings or numbers depending on the field.
Prices must conform to the symbol's tick size. Use GET /symbols/list to determine valid price increments.

Timestamps

All timestamps in the API are Unix epoch milliseconds (int64).

1743508800000  →  2026-04-01T12:00:00.000Z

Pagination

Endpoints that return lists support pagination via query parameters:

Parameter	Type	Description
`limit`	int	Maximum number of items to return
`offset`	int	Number of items to skip (where supported)
`start_time`	int	Filter by start timestamp in ms (where supported)
`end_time`	int	Filter by end timestamp in ms (where supported)

Address Format

User addresses are Ethereum-style hex addresses (EIP-55 checksummed):

0xA6E3B41a6776cd7207DEFd76871DAbEceDf72DE1

The user_address field in request bodies and {address} path parameter must match the authenticated user's address.