Futures Websocket API
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/v3/private
- Public API:
wss://ws.poloniex.com/ws/v3/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"} |
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"
}
Un-subscription Errors
- Request failed (generic)
- Not subscribed
List Subscriptions
List all current subscriptions
Request:
{
"event": "list_subscriptions"
}```
Response:
```json
{
"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
}
]
}
Rate Limits
Public Endpoints
Public requests are limited per IP address and set of endpoints
Authenticated Endpoints
- Authenticated requests for non-resource intensive endpoints as listed below are limited based on user's ID and MVP status. Rate limits are applied across all these endpoints.
- Authenticated requests for resource intensive endpoints as listed below are limited based on user's ID and MVP status. Rate limits are applied across all these endpoints.