Web Socket

Establishes a persistent, full-duplex connection to stream real-time market data and private account updates with low latency.

Overview

The WebSocket API provides a persistent, full-duplex connection for receiving real-time market data and user account updates. Unlike REST APIs, which require polling, WebSockets push data immediately when an event occurs. This results in lower latency and reduced network overhead, making it ideal for high-frequency trading, monitoring live prices, and tracking real-time order status.

Endpoint

wss://trading-api.flipster.io/api/v1/stream

Authentication & Connection

To connect, clients must perform a WebSocket handshake that includes authentication headers similar to private REST requests. The signature generation uses the GET method on the stream endpoint path.

Required Headers:

• api-key: Your API key ID.

• api-expires: Unix timestamp (seconds) when the request expires.

• api-signature: HMAC-SHA256 signature of GET + path + expires. (see Quick Tutorial)

Subscriptions & Topics

To receive data, send a JSON message with the subscribe operation and the desired topic.

{"op": "subscribe", "args": ["<topic_name>"]}

In the same way, you can unsubscribe from the data topic.

{"op": "unsubscribe", "args": ["<topic>"]}

The data structure received for each topic corresponds directly to the response schema of its respective REST API endpoint. Refer to the REST documentation for detailed field definitions.

Market Data Topics

ticker.{symbol}	Real-time ticker updates (price, volume) for a specific symbol.	Get Tickers
kline.{interval}.{symbol}	Candlestick data updates. Requires interval (e.g., 1, 15, 1D) and symbol.	Get Kline (Candlesticks)
orderbook.{symbol}	Real-time depth snapshots of the order book for a symbol.	Get Orderbook

Account Data Topics (Private)

account	General account information including total wallet balance and unrealized PnL.	Get Account Info
account.margin	Detailed margin information, including maintenance margin and available funds for Cross/Isolated modes.	Get Margin Info
account.balance	Asset balances for specific currencies in the wallet.	Get Account Balance
account.position	Updates on open positions, including entry price, leverage, and PnL.	Get Position Info

Response Structure

Data received from the WebSocket is wrapped in a standard JSON envelope. This wrapper identifies the stream topic and provides the timestamp, while the actual payload is contained within the rows array.

Response Fields:

• topic: The name of the subscribed stream (e.g., kline.1.BTCUSDT.PERP).

• ts: The high-precision timestamp of the message.

• data: An array containing the update details.

  • actionType: The type of data event (e.g., UPDATE).

  • rows: The actual data payload. The structure of this array matches the schema defined in the corresponding REST API endpoint.