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:

1{
2 "jsonrpc": "2.0",
3 "method": "subscribe",
4 "params": {
5 "channel": "CHANNEL_NAME"
6 },
7 "id": 1
8}

Subscribe Parameters

ParameterTypeDescriptionRequired
channelstringChannel nameYes

Subscribe Response

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

1{
2 "jsonrpc": "2.0",
3 "result": {
4 "channel": "CHANNEL_NAME"
5 },
6 "usIn": 1682556415569005368,
7 "usDiff": 1291796,
8 "id": 1
9}

Subscribe Response Parameters

ParameterTypeDescriptionRequired
channelstringChannel nameYes

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:

1{
2 "jsonrpc": "2.0",
3 "method": "unsubscribe",
4 "params": {
5 "channel": "CHANNEL_NAME"
6 },
7 "id": 2
8}

Unsubscribe Parameters

ParameterTypeDescriptionRequired
channelstringChannel nameYes

Unsubscribe Response

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

1{
2 "jsonrpc": "2.0",
3 "result": {
4 "channel": "CHANNEL_NAME"
5 },
6 "usIn": 1682556415569005368,
7 "usDiff": 1291796,
8 "id": 2
9}

Unsubscribe Response Parameters

ParameterTypeDescriptionRequired
channelstringChannel nameYes

Example: Subscribing to a Channel

Here’s a complete example of how to subscribe to the trades.ETH-USD-PERP channel using Python:

1import websocket
2import json
3
4websocket_url = "wss://ws.api.testnet.paradex.trade/v1"
5
6# Define the message to send
7auth = {
8 "jsonrpc": "2.0",
9 "method": "auth",
10 "params": {
11 "bearer": "JWcgwMbK0bx1uFFef0Lri35ZDwypmCG0isuBv"
12 },
13 "id": 0
14}
15message = {
16 "jsonrpc": "2.0",
17 "method": "subscribe",
18 "params": {
19 "channel": "trades.ETH-USD-PERP"
20 },
21 "id": 1
22}
23
24# Define a callback to check connection success
25def on_open(ws):
26 # Auth first
27 ws.send(json.dumps(auth))
28 # Send the message
29 ws.send(json.dumps(message))
30
31# Define a callback to handle the response
32def on_message(ws, message):
33 response = json.loads(message)
34 print(response)
35
36# Connect to the WebSocket server
37ws = websocket.WebSocketApp(websocket_url, on_open=on_open, on_message=on_message)
38
39# Wait for a response
40ws.run_forever()

Example: Unsubscribing from a Channel

Here’s a complete example of how to unsubscribe from the trades.ETH-USD-PERP channel using Python:

1import websocket
2import json
3
4websocket_url = "wss://ws.api.testnet.paradex.trade/v1"
5
6# Define the message to send
7auth = {
8 "jsonrpc": "2.0",
9 "method": "auth",
10 "params": {
11 "bearer": "JWcgwMbK0bx1uFFef0Lri35ZDwypmCG0isuBv"
12 },
13 "id": 0
14}
15message = {
16 "jsonrpc": "2.0",
17 "method": "unsubscribe",
18 "params": {
19 "channel": "trades.ETH-USD-PERP"
20 },
21 "id": 2
22}
23
24# Define a callback to check connection success
25def on_open(ws):
26 # Auth first
27 ws.send(json.dumps(auth))
28 # Send the message
29 ws.send(json.dumps(message))
30
31# Define a callback to handle the response
32def on_message(ws, message):
33 response = json.loads(message)
34 print(response)
35
36# Connect to the WebSocket server
37ws = websocket.WebSocketApp(websocket_url, on_open=on_open, on_message=on_message)
38
39# Wait for a response
40ws.run_forever()

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