# Realtime WebSocket Quickstart

> Validate OptionData WebSocket parsing in test mode, then connect to the authenticated realtime option-trades stream with safe retry behavior.

Use test mode first to validate your WebSocket client without an API key, then switch to the authenticated live stream.

## 1. Validate the client in test mode

Connect to:

```text
wss://ws.optiondata.io?test_mode=true&aggregation_mode=AGGREGATED&symbols=AAPL
```

![Annotated OptionData realtime page showing the WebSocket endpoint card and full documentation link](/docs/realtime-websocket-quickstart/realtime-demo-page-annotated.png)

*The product page exposes the endpoint and links to the full filter and response reference.*

Test mode sends a finite sample snapshot and closes the connection. It proves that your client can connect, parse messages, and handle closure; it does not prove subscription entitlement or live market data.

## 2. Connect with Node.js

Install the WebSocket package:

```bash
npm install ws
```

Store your key in `OPTIONDATA_API_KEY`, then run:

```javascript
import WebSocket from 'ws';

const token = process.env.OPTIONDATA_API_KEY;
if (!token) throw new Error('OPTIONDATA_API_KEY is required');

const params = new URLSearchParams({
  token,
  symbols: 'AAPL,SPY',
  aggregation_mode: 'AGGREGATED',
});

const ws = new WebSocket(`wss://ws.optiondata.io?${params}`);

ws.on('open', () => console.log('Connected'));
ws.on('message', (raw) => {
  const message = JSON.parse(raw.toString());
  console.log(message);
});
ws.on('close', (code, reason) => {
  console.log('Closed', code, reason.toString());
});
ws.on('error', (error) => console.error('WebSocket error', error.message));
```

Do not log the full connection URL because it contains the API key.

## 3. Interpret the handshake

- HTTP `101` means the WebSocket upgrade succeeded.
- HTTP `401` means the token is missing, invalid, or stale.
- HTTP `403` means the customer was recognized but lacks active/trialing entitlement.
- HTTP `429` means the token reached a connection or rate limit; honor `Retry-After`.

Each token supports up to five concurrent WebSocket connections. Reuse connections and apply exponential backoff rather than opening connection loops.

During closed market hours, a successful live connection can have little or no new trade traffic. Connection success and message volume are separate checks.

For every filter and response field, use the [Realtime Option Trades API reference](/docs/realtime-option-trades-api).