Real-time market data and private account updates via WebSocket. ## Connection Connect to `wss://api.forum.market/ws/v1` to establish a WebSocket connection. You must send a `subscribe` command within **10 seconds** of connecting or the connection will be closed. ## Connection Limits - **32 connections per IP address** - **10 inbound messages per second** per connection (exceeding this disconnects the client) ## Ping/Pong The server sends a WebSocket ping every **30 seconds**. You must respond with a pong within 10 seconds or the connection is terminated. ## Subscription Management Subscriptions are **additive** — sending a new subscribe command does not replace existing subscriptions. Use the `unsubscribe` command to remove subscriptions. ### Subscribe ```json { "id": 1, "cmd": "subscribe", "params": { "channels": ["bookUpdates", "tickerUpdates"], "tickers": ["OPENAI"] } } ``` ### Unsubscribe ```json { "id": 2, "cmd": "unsubscribe", "params": { "channels": ["tickerUpdates"], "tickers": ["OPENAI"] } } ``` ### List Subscriptions ```json { "id": 3, "cmd": "listSubscriptions" } ``` ## Authentication Private channels (`userOrders`, `userFills`, `userPositions`, `userAccount`) require authentication. ### In-Band HMAC Auth (recommended) ```json { "id": 1, "cmd": "auth", "params": { "key": "", "timestamp": "", "signature": "" } } ``` The signature signs the string: `timestamp + "GET" + "/ws/v1"`. ### URL-Based Auth ``` wss://api.forum.market/ws/v1?key=×tamp=&signature= ``` ### Auth Response Success: `{ "event": "authOk" }` Failure: `{ "type": "error", "error": { "code": "INVALID_SIGNATURE", "message": "..." } }`
View SpecView on GitHubCompanyTradingExchangePerpetual FuturesMarket DataAttention EconomyFintechWebSocketReal TimeAsyncAPIWebhooksEvents
Channels
subscribe
Subscribe to one or more channels for the specified tickers. Subscriptions are additive — they do not replace existing subscriptions.
unsubscribe
Unsubscribe from one or more channels for the specified tickers.
listSubscriptions
List all current subscriptions on this connection.
auth
Authenticate the connection for private channel access using HMAC-SHA256. The signature signs: `timestamp + "GET" + "/ws/v1"`.
logout
Log out the authenticated user and remove all private channel subscriptions.
errors
General error responses sent when a command fails validation or cannot be processed.
bookUpdates
Real-time order book updates. On subscribe, the server sends a full book snapshot, then incremental updates. **Sequence numbers:** Each message includes `data.seq` for gap detection. Verify that `seq` increments by 1. If a gap is detected, re-subscribe to get a fresh snapshot. **Quantity model:** The `qty` field is the **absolute size** at a price level. A `qty` of `0` means the level has been removed.
tickerUpdates
Level 1 market data updates including last price, best bid/ask, volume, funding rates, and index data.
trades
Real-time public trade feed. Each message represents a single executed trade.
indexUpdates
Live attention index value updates, including changes to underlying metrics.
fundingEvents
Funding events. Emitted daily when funding occurs.
candleUpdates1m
Live 1-minute candlestick updates. The `active` field indicates whether the candle is still open.
candleUpdates5m
Live 5-minute candlestick updates. The `active` field indicates whether the candle is still open.
candleUpdates1d
Live 1-day candlestick updates. The `active` field indicates whether the candle is still open.
heartbeat
Application-level heartbeat. Emitted every 1 second per subscribed ticker. Useful for low-volume markets to confirm the connection and server are alive.
userOrders
Real-time order lifecycle updates for the authenticated user. Streams all order state transitions (resting, partially filled, filled, cancelled). **Requires authentication.**
userFills
Real-time trade execution notifications for the authenticated user. **Requires authentication.**
userPositions
Real-time position updates for the authenticated user. Includes `prevQty` to track position size changes. **Requires authentication.**
userAccount
Real-time account margin and PnL updates for the authenticated user. **Requires authentication.**