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

# WebSocket endpoint (subscribe / unsubscribe)

> Open a WebSocket and manage subscriptions on it. One socket carries many subscriptions.

## Endpoint and authentication

```text
wss://api.hypedexer.com/ws
```

Authenticate during the handshake with `X-API-Key: <key>`, `Authorization: Bearer <key>` or the `api_key` query parameter (the only option from a browser). Without a valid key the handshake is refused with `401`.

On connect the server sends `{"type": "connected"}`.

## Heartbeat

The server sends `{"type": "ping", "ts": <ms>}` every 60 seconds. Reply `{"method": "pong"}`. A client that never answers is closed after about 180 seconds with close code `4000` (`timeout`).

## Client messages

```json
{"method": "subscribe",   "subscription": {"type": "<name>"}}
{"method": "unsubscribe", "subscription": {"type": "<name>"}}
```

An unsupported name is answered with `{"type": "error", "message": "Unsupported subscription: <name>"}` and the connection stays open.

## Subscriptions served on this endpoint

- `liquidations` (plural on subscribe, frames carry `"type": "liquidation"`), with the optional filters `user` and `amount_dollars`. See [Liquidations](/websocket/ws-liquidations).
- Every live-data channel, documented under [Live data](/live-data/websocket).

`completed_trades`, `fills_spot` and `recent_activity` are refused by the public endpoint today.

Checked against production on 19 September 2026.



## OpenAPI

````yaml /api-reference/ws-openapi.final2.json get /ws
openapi: 3.1.0
info:
  title: 'Hypedexer API: WebSocket'
  version: 1.0.0
  description: >-
    Realtime WebSocket streams for live trading data from Hypedexer.


    **Base URL (EU)**: `wss://api.hypedexer.com/ws`


    This OpenAPI spec documents the **multiplex WebSocket endpoint** `/ws`.

    All streams (completed trades, fills, recent activity, liquidations, echo,
    etc.) use the **same endpoint** and are selected via JSON `subscribe`
    messages.


    For stream-specific guides (examples, filters, best practices), see the
    dedicated WebSocket pages in the docs:

    - WS – Completed Trades

    - WS – Fills (Spot)

    - WS – Recent Activity

    - WS – Liquidations

    - WS – Echo


    Use your `X-API-Key` from the dashboard on every connection.
servers:
  - url: wss://api.hypedexer.com/ws
    description: EU WebSocket base
security:
  - X-API-Key: []
tags:
  - name: WS-Overview
    description: >-
      Multiplex `/ws` endpoint with dynamic subscribe/unsubscribe to multiple
      streams.
paths:
  /ws:
    get:
      tags:
        - WS-Overview
      summary: WebSocket endpoint (subscribe / unsubscribe)
      description: >-
        Open a WebSocket and manage subscriptions on it. One socket carries many
        subscriptions.


        ## Endpoint and authentication


        ```text

        wss://api.hypedexer.com/ws

        ```


        Authenticate during the handshake with `X-API-Key: <key>`,
        `Authorization: Bearer <key>` or the `api_key` query parameter (the only
        option from a browser). Without a valid key the handshake is refused
        with `401`.


        On connect the server sends `{"type": "connected"}`.


        ## Heartbeat


        The server sends `{"type": "ping", "ts": <ms>}` every 60 seconds. Reply
        `{"method": "pong"}`. A client that never answers is closed after about
        180 seconds with close code `4000` (`timeout`).


        ## Client messages


        ```json

        {"method": "subscribe",   "subscription": {"type": "<name>"}}

        {"method": "unsubscribe", "subscription": {"type": "<name>"}}

        ```


        An unsupported name is answered with `{"type": "error", "message":
        "Unsupported subscription: <name>"}` and the connection stays open.


        ## Subscriptions served on this endpoint


        - `liquidations` (plural on subscribe, frames carry `"type":
        "liquidation"`), with the optional filters `user` and `amount_dollars`.
        See [Liquidations](/websocket/ws-liquidations).

        - Every live-data channel, documented under [Live
        data](/live-data/websocket).


        `completed_trades`, `fills_spot` and `recent_activity` are refused by
        the public endpoint today.


        Checked against production on 19 September 2026.
      parameters:
        - name: X-API-Key
          in: header
          required: true
          description: Your Hypedexer API key.
          schema:
            type: string
            example: hl_live_ABCDEF.123456
      responses:
        '101':
          description: Switching Protocols, the WebSocket is established
        '401':
          description: >-
            Missing or invalid API key, the handshake is refused before the
            connection opens
      security:
        - X-API-Key: []
      x-codeSamples:
        - lang: bash
          label: wscat, liquidations above 50k USD
          source: >
            wscat -H "X-API-Key: $HYPEDEXER_API_KEY" -c
            wss://api.hypedexer.com/ws

            # then:

            #
            {"method":"subscribe","subscription":{"type":"liquidations","amount_dollars":50000}}
        - lang: bash
          label: wscat, top of book for BTC
          source: >
            wscat -H "X-API-Key: $HYPEDEXER_API_KEY" -c
            wss://api.hypedexer.com/ws

            # then:

            # {"method":"subscribe","subscription":{"type":"bbo","coin":"BTC"}}
components:
  securitySchemes:
    X-API-Key:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Your Hypedexer API key. Generate it from the dashboard and send it as
        `X-API-Key: <your_key>`.

````