Websockets API

General Description

• 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. Pings are done automatically after connection by python api.

• Private API: wss://api.poloniex.com/ws/private

• Public API: wss://api.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 5 simultaneous connections on each of the public and private channels.

• Once a connection has been established, each session is limited to 10 requests per second.

Messages

Message	Description
ping (request)	Client can ping the server to maintain connection is 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 automatically by the websockets client after connection. The server will not send ping requests.

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

Subscriptions

Subscribe

Subscription Request + Initial Response

Subscription Errors

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

Example:

#Request

#Subscribe to channel for symbol(s)
await ws_client.subscribe(['<channel>'], ['<symbol>'], limit='<limit>')

or

#Subscribe to all symbols for a given channel
await ws_client.subscribe(['<channel>'], ['all'])

#Response

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

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

Unsubscribe

Unsubscribe / Unsubscribe All

Un-subscription Errors

• Request failed (generic)
• Not subscribed

Example Unsubscribe:

#Request

#Unsubscribe the specified symbol from the channel
await ws_client.unsubscribe(['<channel>'], ['<symbol>'])


#Unsubscribe from the entire channel
await ws_client.unsubscribe(['<channel>'], ['all'])

#Response

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

#Not subscribed
{
  "message": "Error Message",
  "event": "error"
}

Example Unsubscribe:

#Request
await ws_client.unsubscribe_all()

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

List Subscriptions

List all current subscriptions

Example:

#Request
await ws_client.list_subscriptions()

#Response
{
  "subscriptions": ['<channel>']
}