Market Data WebSocket API

The Market Data WebSocket API provides real-time market data for stocks and options.

System Status & Development Notice

This WebSocket API backend is currently under active development. The entire backend system, including all message handling, data delivery, and response models, is considered unstable. Breaking changes may occur frequently across: Authentication flow, Subscription and unsubscription mechanics, Field and data schema consistency, Request/Response and metadata retrieval endpoints. Use this integration in sandbox or development environments only until a stable release is announced.

Connection Details

Endpoint: /v1/marketdata/ws
Protocol: WebSocket (wss://)
Ping: Required from client-side.

Authentication

Clients must authenticate upon connection. The first message sent must be an auth message.

Authentication Request

Client to Server authentication message.

REQUEST

{
"action": "auth",
"token": "YOUR_USER_ACCESS_TOKEN",
"xAPIKey": "YOUR_API_KEY"
}

Authentication Response

Server to Client authentication success response.

RESPONSE

{
"action": "auth",
"message": "success"
}

Ping Messages (Keep-Alive Support)

To keep the WebSocket connection alive, clients must periodically send a ping message.

This is compulsory.

Client Ping Message

Message sent by the client to keep the connection alive.

MESSAGE

{
"action": "ping"
}

Server Pong Response

Response from the server to a ping message.

MESSAGE

{
"action": "ping",
"message": "pong"
}

Subscriptions

Subscribe to Equity Quotes

Request to subscribe to equity data. You can specify multiple symbols and their desired fields. Use '*' to subscribe to all available fields for a symbol.

REQUEST

{
"action": "subscribe",
"type": "equityComposite",
"data": [
  {
    "symbol": "AAPL",
    "fields": ["askPrice", "bidPrice", "askSize", "bidSize"]
  },
  {
    "symbol": "GOOGL",
    "fields": ["*"]
  }
]
}

Equity Data Stream (Example)

Example of a real-time data update for a subscribed equity.

RESPONSE

{
"type": "equityComposite",
"data": {
  "symbol": "AAPL",
  "bidPrice": "1234.00",
  "askPrice": "1234.50"
  // ... other subscribed fields
}
}

Subscribe to Option Quotes

Request to subscribe to option contract data.

REQUEST

{
"action": "subscribe",
"type": "optionComposite",
"data": [
  {
    "symbol": "SPXW250606P04200000", 
    "fields": ["askPrice", "bidPrice", "askSize", "bidSize", "lastPrice", "volume"]
  }
]
}

Option Data Stream (Example)

Example of a real-time data update for a subscribed option.

RESPONSE

{
"type": "optionComposite",
"data": {
  "symbol": "SPXW250606P04200000",
  "bidPrice": "15.50",
  "askPrice": "15.75"
  // ... other subscribed fields
}
}

Unsubscriptions

Unsubscribe from Stock Composite

Request to unsubscribe from specific fields or all fields ('*') for one or more equity symbols.

REQUEST

{
"action": "unsubscribe",
"type": "equityComposite",
"data": [
  {
    "symbol": "AAPL",
    "fields": ["askSize", "bidSize"] 
  },
  {
    "symbol": "MSFT",
    "fields": ["*"] 
  }
]
}

Unsubscribe from Option Quotes

Request to unsubscribe from specific fields or all fields for one or more option symbols.

REQUEST

{
"action": "unsubscribe",
"type": "optionComposite",
"data": [
  {
    "symbol": "SPXW250606P04200000",
    "fields": ["askSize", "bidSize"]
  }
]
}

Error Response

Error Response Example

Example of an error message from the server if a request is malformed or an issue occurs.

MESSAGE

{
"type": "equityComposite", 
"error": "invalid_symbol",
"message": "The symbol 'XYZ123' is not recognized."
}

Request/Response Model

The Request/Response model allows clients to make REST-like HTTP calls over an active WebSocket connection. This is useful for fetching non-streaming, point-in-time data such as expiry dates or option chains without needing to open separate HTTP requests.

Key Points

Used for on-demand queries via WebSocket.
Integrates seamlessly into the same connection used for streaming quotes.
Response is matched to request using the unique id provided by the client in the request.

Client Request Structure (Request/Response Model)

General structure for a client request when using the Request/Response model.

REQUEST

{
"action": "request",
"id": "unique_request_id_123", 
"data": {
  "method": "get", 
  "url": "/v1/options/AAPL/expiryDates", 
  "body": {
    // JSON body if required by the endpoint (e.g., for POST/PUT)
  }
}
}

Server Response Structure (Request/Response Model)

General structure for a server response when using the Request/Response model.

RESPONSE

{
"action": "response",
"id": "unique_request_id_123", 
"data": {
  "status": 200, 
  "content": {
    // JSON response body from the equivalent HTTP endpoint
  }
}
}

Example 1: Get Expiry Dates for a symbol

Get Expiry Dates Request

Request to fetch expiry dates for a symbol (e.g., AAPL).

REQUEST

{
"action": "request",
"id": "expiry_dates_aapl_001",
"data": {
  "method": "get",
  "url": "/v1/options/AAPL/expiryDates"
}
}

Get Expiry Dates Response

Response containing expiry dates for the symbol.

RESPONSE

{
"action": "response",
"id": "expiry_dates_aapl_001",
"data": {
  "status": 200,
  "content": {
    "symbol": "AAPL",
    "expiryDates": [
      "2026-01-16",
      "2026-02-20", 
      "2026-03-20"
    ]
  }
}
}

Example 2: Get option symbol’s calls & puts

Get Option Chain Request

Request to fetch the option chain (calls and puts) for a symbol and specific expiry date.

REQUEST

{
"action": "request",
"id": "option_chain_goog_001",
"data": {
  "method": "get",
  "url": "/v1/options/GOOG/expiryDates/2025-05-23"
}
}

Get Option Chain Response

Response containing calls and puts for the specified option chain.

RESPONSE

{
"action": "response",
"id": "option_chain_goog_001",
"data": {
  "status": 200,
  "content": {
    "calls": [
      "GOOG250523C00080000",
      "GOOG250523C00085000",
      "GOOG250523C00090000"
    ],
    "puts": [
      "GOOG250523P00080000",
      "GOOG250523P00085000"
    ]
  }
}
}

Example 3: Get Time and Sales for a symbol

Get Time and Sales Request

Request to fetch time and sales (tape) data for a symbol.

REQUEST

{
"action": "request",
"id": "tns_aapl_001",
"data": {
  "method": "get",
  "url": "/v1/tns/AAPL" 
}
}

Get Time and Sales Response

Response containing time and sales data.

RESPONSE

{
"action": "response",
"id": "tns_aapl_001",
"data": {
  "status": 200,
  "content": {
    "tns": [
      {
        "lastPrice": "123.45",
        "tradeTimestamp": "HH:MM:SS.mmm" 
      }
    ]
  }
}
}

Allowed common fields for equity and options

Field Name	Description
`symbol`	Ticker or option symbol
`instrumentType`	Type of instrument (e.g., equity = e, option = o)
`exchange`	Exchange code and name
`price`	Current price
`size`	Trade size
`totalVolume`	Total traded volume
`tickVolume`	Number of ticks
`openPrice`	Opening price of the session
`highPrice`	Session high price
`lowPrice`	Session low price
`lastPrice`	Last traded price
`netChange`	Net change from previous close
`tradeTimestamp`	Exchange-provided trade’s timestamp (e.g., HH:MM:SS.mmm)
`askPrice`	Ask price
`askChange`	Change in ask price
`askSize`	Ask size
`askSizeChange`	Change in ask size
`bidPrice`	Bid price
`bidChange`	Change in bid price
`bidSize`	Bid size
`bidSizeChange`	Change in bid size
`quoteTimestamp`	Exchange-provided quote’s timestamp (e.g., HH:MM:SS.mmm)
`high52Week`	Highest price in 52 week
`low52Week`	Lowest price in 52 week
`openInterest`	Open interest (typically for options)
`dividend`	Latest ex-dividend amount (typically for equities)
`*`	Wildcard to subscribe to all available fields for the instrument type

Important Notes

All symbols are automatically converted to uppercase by the server.
The first message after connection MUST be an authentication message.
Ping messages are required from the client to keep the connection alive.
Multiple symbols and field combinations can be subscribed/unsubscribed in a single message.
Connection will be terminated if authentication fails or if there's a prolonged period of inactivity without pings.
Real-time updates for subscriptions are pushed as they occur.
The Request/Response model is for point-in-time data retrieval over the same WebSocket.
Ensure unique ids for each request in the Request/Response model for proper correlation.