Integration area
Perpetuals
Use the perpetuals APIs for market discovery, orderbook snapshots, live market data, authenticated order entry, private account state, and drop-copy recovery.
Discovery and snapshots
Use REST for markets, trades, candles, ticker, and L2 orderbook snapshots. The snapshot sequence must gate subsequent WebSocket deltas.
Gateway authentication
Connect to the trading gateway and authenticate the session before sending order, cancel, amend, or account-state commands.
Private streams
Subscribe to one authenticated wallet per session for balance, positions, PnL, orders, and drop-copy. Drop-copy replay is wallet-scoped.
Market-data recovery
orderbook:{market_id}:0 sends a current snapshot followed by sequenced deltas. On orderbook_gap, rebuild from a fresh snapshot before quoting.
Omen Perps API
Client-facing REST API for the Omen perpetuals exchange. This API exposes public market data plus authenticated account endpoints used by perps clients for wallet linking and position lookups. Monetary values are serialized as decimal strings. Market-level price and size fields are 1e18-scaled fixed-point values rendered as plain decimal strings. Orderbook snapshots are exposed through `GET /api/v1/orderbook/{market_
Environment endpoints
https://api.perps.test.omen.tradeTest environmenthttp://localhost:8083Local developmentAuthentication
JWT issued by omen-auth. Authenticated endpoints expect a standard `Authorization: Bearer <token>` header with an `aud` of `authenticated`.
Endpoints
| Method | Path | Summary | Tags |
|---|---|---|---|
| GET | /health | Health check | Health |
| GET | /readyz | Readiness check | Readiness |
| GET | /api/v1/markets | List live perps markets | Markets |
| GET | /api/v1/trades/{market_id} | Get trade history for a market | Trades |
| GET | /api/v1/candles/{market_id} | Get OHLCV candles for a market | Candles |
| GET | /api/v1/ticker/{market_id} | Get 24h ticker stats for a market | Ticker |
| GET | /api/v1/orderbook/{market_id} | Get an L2 orderbook snapshot for a market | Orderbook |
| GET | /api/v1/wallet | Get the caller's linked wallet | Wallet |
| POST | /api/v1/wallet/link | Link a wallet to the authenticated perps account | Wallet |
| DELETE | /api/v1/wallet/link | Unlink the authenticated account's wallet | Wallet |
| GET | /api/v1/risk/bad-debt | Get bad-debt summary | Risk |
| GET | /api/v1/positions/{account} | Get open positions for the caller's linked wallet | Positions |
Data models
Omen Perps Gateway WebSocket API
Client-facing trading and account-stream WebSocket API for Omen perps. Clients connect to a single WebSocket endpoint and exchange MessagePack-encoded messages. Examples in this document are shown in JSON for readability, but the wire format is MessagePack maps. The normal first application message is `auth`, but the gateway does not require it to be literally first on the wire. Trading commands and wallet-scoped sub
Environment endpoints
wss://ws.perps.test.omen.trade/Public test gatewayws://localhost:8080/Local development gatewayChannels and messages
gatewayConnection
/
Single WebSocket connection used for authentication, trading commands, and wallet-scoped account subscriptions.
Data models
Omen Perps Market Data WebSocket API
Client-facing market data WebSocket API for Omen perps. Clients connect to a single WebSocket endpoint and exchange MessagePack-encoded command maps. Server events are MessagePack arrays using the positional layouts documented below. Examples are shown as JSON arrays for readability. Market data subscriptions are public. No in-band authentication step is required. The REST API also exposes `GET /api/v1/orderbook/{mar
Environment endpoints
wss://stream.perps.test.omen.trade/Public test market data streamws://localhost:8082/Local development market data streamChannels and messages
marketDataConnection
/
Single WebSocket connection used for subscribing to orderbook, trade, funding, and spot-price channels.