Subscription Channels

The Paradex WebSocket API allows you to subscribe to various channels to receive real-time updates. This page explains how to subscribe and unsubscribe from channels.

Subscribing to Channels

To receive updates from a specific channel, you need to subscribe to it. Multiple calls to subscribe can be made, each for a different channel.

Note: Subscribing to the same channel more than once will return an error.

Subscribe Request

To subscribe to a channel, send a message with the following format:

{
  "jsonrpc": "2.0",
  "method": "subscribe",
  "params": {
    "channel": "CHANNEL_NAME"
  },
  "id": 1
}

Subscribe Parameters

Subscribe Response

Upon successful subscription, you will receive a response similar to:

{
  "jsonrpc": "2.0",
  "result": {
    "channel": "CHANNEL_NAME"
  },
  "usIn": 1682556415569005368,
  "usDiff": 1291796,
  "id": 1
}

Subscribe Response Parameters

Unsubscribing from Channels

To stop receiving updates from a specific channel, you need to unsubscribe from it.

Note: Unsubscribing from a channel that you are not subscribed to will return an error.

Unsubscribe Request

To unsubscribe from a channel, send a message with the following format:

{
  "jsonrpc": "2.0",
  "method": "unsubscribe",
  "params": {
    "channel": "CHANNEL_NAME"
  },
  "id": 2
}

Unsubscribe Parameters

Unsubscribe Response

Upon successful unsubscription, you will receive a response similar to:

{
  "jsonrpc": "2.0",
  "result": {
    "channel": "CHANNEL_NAME"
  },
  "usIn": 1682556415569005368,
  "usDiff": 1291796,
  "id": 2
}

Unsubscribe Response Parameters

Example: Subscribing to a Channel

Public channel payloads are SBE binary frames, so a subscriber needs a decoder as well as a socket. The Paradex Python SDK handles both:

import asyncio
from paradex_py.api.ws_client import ParadexWebsocketChannel, ParadexWebsocketClient
from paradex_py.environment import TESTNET
async def on_message(channel, message):
    print(channel, message["params"]["data"])
async def main():
    ws_client = ParadexWebsocketClient(env=TESTNET, sbe_enabled=True)
    await ws_client.connect()
    await ws_client.subscribe(
        ParadexWebsocketChannel.TRADES,
        callback=on_message,
        params={"market": "ETH-USD-PERP"},
    )
    await asyncio.sleep(30)
asyncio.run(main())

The subscribe request and its acknowledgement above are JSON-RPC text frames; the trade updates that follow are binary. See Code Examples for authentication and unsubscribing, and Binary Encoding (SBE) to generate a decoder in another language.

Example: Unsubscribing from a Channel

await ws_client.unsubscribe_by_name("trades.ETH-USD-PERP")

Refer to the WebSocket Channels documentation for a list of supported channels.