> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orica.markets/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Overview

> Introduction to Orica's real-time WebSocket API.

Orica provides WebSocket endpoints for real-time data streaming. Use WebSockets when you need live updates without polling.

***

## Available Streams

> [card] [Market Data](https://docs.orica.markets/api-reference/websocket/market-data.md)
>
> Real-time price updates, market cap changes, and volume for a specific market.

> [card] [Activity Feed](https://docs.orica.markets/api-reference/websocket/activity-feed.md)
>
> Live trade notifications filtered by market or user.

***

## Base URL

```
wss://api.orica.markets/ws
```

***

## Connection Lifecycle

**1. Connect**

Open a WebSocket connection to the appropriate endpoint.

**2. Initialize**

Some endpoints require a filter message after connecting (e.g., Activity Feed).

**3. Receive Data**

The server sends initial data (market state, history) followed by live updates.

**4. Stay Alive**

Send periodic pings to keep the connection open.

**5. Disconnect**

Close the connection when done or handle reconnection on errors.

***

## Message Format

All messages are JSON. Server messages include a `type` field:

| Type | Description |
| - | - |
| `market` | Full market data (on connect) |
| `history` | Historical data points |
| `update` | Live price/state update |
| `trade` | New trade notification |
| `pong` | Response to ping |
| `error` | Error message |

***

## Client Actions

| Action | Description |
| - | - |
| `ping` | Keep connection alive |
| `set_interval` | Change data interval (Market Data) |
| `history` | Request historical data (Activity Feed) |

***

## Connection Limits

| Limit | Value |
| - | - |
| Connections per IP | 10 |
| Messages per second | 5 |
| Idle timeout | 5 minutes |
| Max connection duration | 1 hour |

***

## Example: Basic Connection

```typescript theme={"dark"}
const ws = new WebSocket("wss://api.orica.markets/ws/markets/ABC123...");

ws.onopen = () => {
  console.log("Connected");
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log("Received:", message.type);
};

ws.onerror = (error) => {
  console.error("WebSocket error:", error);
};

ws.onclose = (event) => {
  console.log("Disconnected:", event.code, event.reason);
};

// Keep alive
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ action: "ping" }));
  }
}, 30000);
```

***

## Reconnection Strategy

Implement automatic reconnection for robustness:

```typescript theme={"dark"}
function createReconnectingWebSocket(url: string) {
  let ws: WebSocket;
  let reconnectAttempts = 0;
  const maxReconnectAttempts = 5;
  
  function connect() {
    ws = new WebSocket(url);
    
    ws.onopen = () => {
      reconnectAttempts = 0;
      console.log("Connected");
    };
    
    ws.onclose = (event) => {
      if (event.code !== 1000 && reconnectAttempts < maxReconnectAttempts) {
        const delay = Math.pow(2, reconnectAttempts) * 1000;
        reconnectAttempts++;
        console.log(`Reconnecting in ${delay}ms...`);
        setTimeout(connect, delay);
      }
    };
    
    ws.onerror = () => {
      ws.close();
    };
  }
  
  connect();
  return () => ws;
}
```

***

## When to Use WebSockets

> [card] Use WebSockets For
>
> * Live price displays
> * Real-time trade feeds
> * Notifications
> * Low-latency updates

> [card] Use REST For
>
> * One-time data fetches
> * Historical queries
> * Large data exports
> * Simple integrations


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.