General Information

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.