Overview

General Description

• WebSockets can be read by any standard websocket library. Data is organized into Public and Private Channels to which an API client may subscribe.
• All messages sent and received via WebSockets are encoded in JSON format.
• Only supported json tags will be processed, everything else will be ignored with basic error response.
• The WebSockets server expects a message or a ping every 30 seconds or it will end the client’s session without warning.
• Private API: wss://ws.poloniex.com/ws/private
• Public API: wss://ws.poloniex.com/ws/public

Restrictions

• Websockets access is divided into 2 endpoints, the private endpoint only allows access to private channels, not to public channels. The public endpoint only allows access to the public channel, not the private channel. Endpoint restrictions are only valid for 'subscribe' events; other events such as 'ping, unsubscribe' are not specially restricted.
• A single IP is limited to 2000 simultaneous connections on each of the public and private channels.
• Once a connection has been established, each connection is limited to 500 requests per second.

Messages

Message	Description
ping (request)	Client can ping the server to keep the connection alive
pong (response)	Server response to a ping message
subscribe (request)	Subscribe to a channel or set of channels for single or many instruments
unsubscribe (request)	Unsubscribe from a channel for all or specified instruments
unsubscribe_all (request)	Removes all user’s current subscriptions
list_subscriptions (request)	List current subscriptions

Heartbeats

Note, ping request are issued by clients only. The server will not send ping requests.

Command
{"event": "ping"}
{"event": "pong"}

In order to be compatible with some traditional trading programs, we also support plain text ping messages sent by the client, which are case-insensitive.

Subscriptions

Subscribe

Subscription Request + Initial Response

Request:

# Subscribe to channel for symbol(s)

{
  "event": "subscribe",
  "channel": ["<channel>"],
  "symbols": [
    "<symbol1>",
    "<symbol2>",
    "<symbol3>"
  ]
}

or 

# Subscribe to all symbols for a given channel

{
  "event": "subscribe",
  "channel": ["<channel>"],
  "symbols": ["all"]
}

Response:

# OK

{
  "event": "subscribe",
  "channel": <channel>
}

# Failure 

{
  "event": "error",
  "message": "Error Message"
}

Subscription Errors

• Subscription failed (generic)
• Already subscribed
• Bad request (generic)

Unsubscribe

Unsubscribe / Unsubscribe All

Request:

# Unsubscribe the specified symbol from the channel

{
  "event": "unsubscribe",
  "channel": ["<channel>"],
  "symbols": [
    "<symbol>"
  ]
}

# Unsubscribe from the entire channel

{
  "event": "unsubscribe",
  "channel": ["<channel>"],
  "symbols": ["all"]
}

Response:

# OK

{
  "channel": "<channel>",
  "event": "UNSUBSCRIBE"
}

# not subscribed

{
  "message": "Error Message",
  "event": "error"
}

Request:

{
  "event": "unsubscribe_all"
}

Response:

{
  "channel": "ALL",
  "event": "UNSUBSCRIBE_ALL"
}

Un-subscription Errors

• Request failed (generic)
• Not subscribed

List Subscriptions

List all current subscriptions

Request:

{
  "event": "list_subscriptions"
}

Response:

{
  "subscriptions": [<channel>]
}

Subscribing to Multiple Channels

# --> Request
{
  "event": "subscribe",
  "channel": ["orders","balances"],
  "symbols": ["all"]
}

# <-- Receipt Confirmation
{
  "channel": "orders",
  "event": "subscribe",
  "symbols": ["all"]
}

# <-- Receipt Confirmation
{
  "channel": "balances",
  "event": "subscribe",
  "symbols": ["all"]
}

# <-- Stream
{
    "channel":"orders",
    "data":[
        {
            "symbol":"LINK_USDC",
            "type":"LIMIT",
            "quantity":"10",
            "orderId":"32482887660077056",
            "tradeFee":"0",
            "clientOrderId":"4436176",
            "accountType":"SPOT",
            "feeCurrency":"",
            "eventType":"place",
            "source":"API",
            "side":"SELL",
            "filledQuantity":"0",
            "filledAmount":"0",
            "state":"NEW",
            "tradeTime":0,
            "tradeAmount":"0",
            "orderAmount":"0",
            "createTime":1648710923921,
            "price":"3",
            "tradeQty":"0",
            "tradePrice":"0",
            "tradeId":"0",
            "ts":1648710923948
        }
    ]
}


# <-- Stream (continued)
{
  "channel": "balances",
  "data": [{
    "changeTime": 1657312008411,
    "accountId": "1234",
    "eventType": "place_order",
    "available": "9999999983.668",
    "currency": "BTC",
    "id": 60018450912695040,
    "userId": 12345,
    "hold": "16.332",
    "ts": 1657312008443
  }]
}