# WebSocket API Overview

The Collective2 API provides a WebSocket endpoint for receiving real-time trading signals and position updates
as they are published. Use WebSocket when you need low-latency push updates — instead of
polling the REST API on a schedule such as GetStrategyActiveOrders, GetStrategyHistoricalOrders
or GetStrategyHistoricalClosedTrades.

## When to Use WebSocket

Use the WebSocket API when you need signals & positions delivered to your application as soon as they
are published. For historical data, use the REST endpoints.

## Base URL


```
wss://api4-general.collective2.com/ws
```

## Authentication

Pass your API key as a Bearer token in the `Authorization` header during the HTTP upgrade
handshake:


```
Authorization: Bearer YOUR_API_KEY
```

Authentication happens at connection time. If your API key is invalid or missing, the
server returns HTTP 401 before the WebSocket upgrade completes.

## Available Channels

| Channel | Description |
|  --- | --- |
| `strategy.signal` | Real-time trading signals for a strategy |
| `strategy.positions` | Real-time position updates for a strategy |


See [Subscribing to Channels](/guides/websocket-subscribe) for details on how to use channels.

## Limits

| Limit | Value |
|  --- | --- |
| Connections per API key | 10 |
| Channel subscriptions per connection | 100 |


## Message Envelope

Every message — sent or received — uses the same JSON envelope:


```json
{
  "msg_type": "string",
  "id": "msg_a1b2c3d4e5f64a2b8c3d4e5f6a7b8",
  "seq_id": 98765,
  "request_id": "my-req-1",
  "timestamp": "2024-01-01T12:00:00Z",
  "v": 4,
  "payload": {}
}
```

| Field | Type | Description |
|  --- | --- | --- |
| msg_type | string | Message type identifier |
| id | string | Unique message ID assigned by the server |
| seq_id | integer | Monotonically increasing sequence number for ordered streams. `null` or absent on non-stream messages (heartbeats, acks). |
| request_id | string | Optional. Echoes the client's `request_id` for correlating requests to responses. Max 50 characters. |
| timestamp | string | UTC timestamp in ISO 8601 format |
| v | string | Protocol version |
| payload | object | Message-specific data |


### Client Message Types

Your application may only send two message types to the server:

| msg_type | Purpose |
|  --- | --- |
| subscription.request | Subscribe or unsubscribe from a channel |
| heartbeat.ack | Acknowledge a server heartbeat |


All other message types are server-only. Sending an unknown type returns an error.