> For the full documentation index, see: https://massive.com/docs/llms.txt

# WebSocket Quickstart

WebSocket API Quickstart Guide

![A screenshot displaying a JSON response with options data on one side and a graphical user interface presenting the same information, illustrating the types of applications you can build with Massive data](https://massive.com/docs/img/quickstart_ws_transparent.png "Demonstration of JSON data powering a options data UI")

The Massive WebSocket API streams real-time market data over a persistent connection — ideal for event-driven dashboards, trading systems, and any application that needs live updates. For bulk historical downloads, use [Flat Files](https://massive.com/docs/flat-files/quickstart.md); for on-demand queries, use the [REST API](https://massive.com/docs/rest/quickstart.md).

This guide walks through connecting and exchanging messages manually with `wscat` so you understand what our [official client libraries](#explore-client-libraries) handle on your behalf.

## Browse Our Data

Select a category to see its WebSocket channels, message formats, and code examples.

- [Stocks](https://massive.com/docs/websocket/stocks/overview.md): Real-time stock trades, quotes, and aggregates.
- [Options](https://massive.com/docs/websocket/options/overview.md): Real-time OPRA trades, quotes, and aggregates.
- [Futures](https://massive.com/docs/websocket/futures/overview.md): Real-time futures trades and quotes across CME venues.
- [Indices](https://massive.com/docs/websocket/indices/overview.md): Real-time values and aggregates for U.S. indices.
- [Forex](https://massive.com/docs/websocket/forex/overview.md): Real-time currency pair quotes and aggregate bars.
- [Crypto](https://massive.com/docs/websocket/crypto/overview.md): Real-time global crypto trades, quotes, and aggregates.

## Requirements & Approach

In a production environment, you will likely never manually manage WebSocket connections and message flows as shown here. Instead, you would use one of our official client libraries, which encapsulate these details, handling tasks such as:

- Establishing and maintaining the WebSocket connection.
- Sending authentication messages automatically.
- Subscribing and unsubscribing to feeds.
- Efficiently parsing and handling incoming data.

By following along with the steps below using `wscat`, you'll gain insight into how our WebSocket streams operate under the hood, giving you confidence in what our client libraries are doing on your behalf.

**Preparing Your Environment:**
1. Ensure you have [Node.js](https://nodejs.org/) installed.
2. At your terminal, install `wscat`, a handy tool for interacting with WebSocket endpoints:

  **Install wscat**

  ```bash
  npm install -g wscat
  ```

## Connecting to the WebSocket
Massive offers both delayed and real-time data feeds depending on your needs.

- **15-minute Delayed Data**:

  **Connect to 15-minute delayed feed**

  ```bash
  wscat -c wss://delayed.massive.com/stocks
  ```


- **Real-Time Data**:

  **Connect to real-time feed**

  ```bash
  wscat -c wss://socket.massive.com/stocks
  ```


**Server to Client (Upon Successful Connection):**

  **Receive Successful Connection Message**

  ```json
  [{
    "ev":"status",
    "status":"connected",
    "message":"Connected Successfully"
  }]
  ```


**Note on Connections:** By default, one concurrent WebSocket connection per asset class is allowed. If you require multiple simultaneous connections for the same asset class, please [contact support](https://massive.com/contact).

## Authentication
After connecting, you must authenticate with your [API key](https://massive.com/dashboard/keys) before subscribing to data feeds.

**Client to Server (Send Your API Key):**

  **Send Authentication Request**

  ```json
  {
    "action":"auth",
    "params":"YOUR_API_KEY"
  }
  ```


**Server to Client (Successful Authentication):**

  **Receive Successful Authentication Message**

  ```json
  [{
    "ev":"status",
    "status":"auth_success",
    "message":"authenticated"
  }]
  ```

## Subscribing to Data Feeds
Once authenticated, you can subscribe to various channels. Below is an example subscribing to Stocks Aggregates (Per Minute) updates for `AAPL` and `MSFT`:

**Client to Server (Subscription Request):**

  **Send Subscription Request**

  ```json
  {
    "action":"subscribe",
    "params":"AM.AAPL,AM.MSFT"
  }
  ```


**Server to Client (Data Messages):** After subscribing, you will receive updates as they occur. For example, a real-time aggregate per minute (AM) message might look like this:

**Receive Data Messages for Your Subscription**

```json
[
  {
    "ev": "AM",
    "sym": "AAPL",
    "v": 12345,
    "o": 150.85,
    "c": 152.90,
    "h": 153.17,
    "l": 150.50,
    "a": 151.87,
    "s": 1611082800000,
    "e": 1611082860000
  }
]
```

**Field Explanations:**
- **ev**: Event type (e.g., "AM" for aggregate minute bars)
- **sym**: Symbol (e.g., "AAPL")
- **v**: Volume in the aggregate period
- **o, c, h, l**: Open, Close, High, Low prices
- **a**: VWAP (Volume Weighted Average Price)
- **s**: Start timestamp of the aggregate period (Unix ms)
- **e**: End timestamp of the aggregate period (Unix ms)

## Message Formats & Multiple Events
During high-volume periods, the server may bundle multiple events into a single JSON array.

**Example with Multiple Trade Events:**

**Server to Client (Data Messages)**

```json
[
  {
    "ev": "T",        
    "sym": "MSFT",    
    "i": "50578",     
    "x": 4,           
    "p": 215.9721,    
    "s": 100,         
    "t": 1611082428813,
    "z": 3            
  },
  {
    "ev": "T",
    "sym": "MSFT",
    "i": "12856",
    "x": 4,
    "p": 215.989,
    "s": 1,
    "c": [37],        
    "t": 1611082428814,
    "z": 3
  }
]
```

By examining the `ev` field and other attributes, you can distinguish event types and integrate the data into your application logic.

## Performance & Latency Considerations
Handling streaming market data efficiently is key:
- Process messages quickly to avoid server-side buffering.
- If you consistently receive more data than you can handle, reduce subscriptions.
- Use a wired connection and avoiding Wifi and VPNs can help reduce latency.

If the server detects slow message consumption, it may disconnect to maintain overall system performance.

## Explore Client Libraries
In practice, you’ll likely rely on our client libraries for handling these details automatically. They simplify:
- Authentication
- Subscription management
- Message parsing
- Error handling and reconnect logic

Available libraries:
- **Python**: [GitHub - Python Client](https://github.com/massive-com/client-python)
- **Go**: [GitHub - Go Client](https://github.com/massive-com/client-go)
- **Kotlin**: [GitHub - JVM Client](https://github.com/massive-com/client-jvm)
- **JavaScript**: [GitHub - JavaScript Client](https://github.com/massive-com/client-js)

## Using Massive with AI

Connecting an AI agent or assistant to Massive? Our [AI Tools](https://massive.com/docs/ai-tools/quickstart.md) area covers everything you need to give LLMs reliable access to market data: a remote MCP server for the REST API, LLM-friendly `llms.txt` files, and Markdown versions of every documentation page (just append `.md` to any URL). It includes step-by-step setup for Claude, ChatGPT, Cursor, Codex, and more.

## Next Steps
By following this guide and understanding the underlying message flow, you can appreciate what happens when you connect, authenticate, and subscribe to data feeds. While this manual approach is useful for learning, our client libraries are the recommended choice for actual development and production use. With this knowledge in hand, explore the rest of our documentation to discover more channels, event types, and advanced capabilities.