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

# Real-time overview

> Stream live market data and chat over Socket.IO with the same API key.

Murmo exposes two real-time gateways over [Socket.IO](https://socket.io). Both accept your `murmo_`
API key, so a bot can stream live data without polling.

| Namespace | URL                                | Purpose                                                          |
| --------- | ---------------------------------- | ---------------------------------------------------------------- |
| `/perps`  | `wss://api.alpha-labs.trade/perps` | Live perp market ticks (mark/mid/oracle price, funding, volume). |
| `/chat`   | `wss://api.alpha-labs.trade/chat`  | Group chat messages and per-user notifications.                  |

## Connecting

Pass your key in the Socket.IO handshake `auth.token`. It may also be sent as an
`Authorization: Bearer` header. It is **never** read from the query string (query strings leak into
logs).

<CodeGroup>
  ```javascript JavaScript (socket.io-client) theme={null}
  import { io } from "socket.io-client";

  const socket = io("wss://api.alpha-labs.trade/perps", {
    transports: ["websocket"],
    auth: { token: process.env.MURMO_API_KEY }, // "murmo_..."
  });

  socket.on("connected", ({ userId }) => console.log("connected as", userId));
  socket.on("error", (e) => console.error("ws error:", e.message));
  ```

  ```python Python (python-socketio) theme={null}
  import socketio

  sio = socketio.Client()

  @sio.event(namespace="/perps")
  def connected(data):
      print("connected as", data["userId"])

  sio.connect(
      "wss://api.alpha-labs.trade",
      namespaces=["/perps"],
      transports=["websocket"],
      auth={"token": MURMO_API_KEY},
  )
  sio.wait()
  ```
</CodeGroup>

## Connection lifecycle

<Steps>
  <Step title="Connect with your key">
    On success the server emits `connected`. For `/chat` it also auto-joins you to all your group
    rooms and a private `user:{userId}` room.
  </Step>

  <Step title="Subscribe to what you need">
    On `/perps`, emit `subscribe_market { symbol }` per market. On `/chat`, you already receive your
    groups' messages after connecting.
  </Step>

  <Step title="Handle `error` and reconnects">
    Auth failures emit `error` then disconnect. Socket.IO reconnects automatically; re-subscribe on
    reconnect.
  </Step>
</Steps>

<Warning>
  An invalid or missing token emits `error` (`Authentication required` / `Invalid token`) and the
  socket is disconnected. Make sure `auth.token` is your `murmo_` key.
</Warning>

## Which gateway to use

<CardGroup cols={2}>
  <Card title="Market data" icon="bolt" href="/websockets/market-data">
    `/perps` — subscribe per symbol, receive throttled `market_tick` pushes.
  </Card>

  <Card title="Chat & notifications" icon="comments" href="/websockets/chat">
    `/chat` — messages, reactions, pins, and per-user notifications.
  </Card>
</CardGroup>

<Note>
  Need exact decimal prices (the REST money-string contract)? Read `GET /api/v1/perps/markets`. The
  `market_tick` stream optimizes for latency and sends numeric fields (see the next page).
</Note>