Websocket

danger

Poloniex futures v1/v2 API will be officially offline on November 30, 2024. You can access the V3 API to provide you with a better trading experience.

While there is a strict access frequency control for the REST API, we highly recommend that API users utilize the Websocket to get the real-time data.

The recommended way is to just create a websocket connection and subscribe to multiple channels.

Apply for Connection Token

You need to apply for one of the two tokens below to create a websocket connection.

Example:

  {
    "code": "200000",
    "data": {
        "instanceServers": [
            {
                "pingInterval": 50000,
                "endpoint": "wss://futures-apiws.poloniex.com/endpoint",
                "protocol": "websocket",
                "encrypt": true,
                "pingTimeout": 10000
            }
        ],
        "token": "vYNlCtbz4XNJ1QncwWilJnBtmmfe4geLQDUA62kKJsDChc6I4bRDQc73JfIrlFaVYIAE0Gv2--MROnLAgjVsWkcDq_MuG7qV7EktfCEIphiqnlfpQn4Ybg==.IoORVxR2LmKV7_maOR9xOg=="
    }
  }

Public Channels (No authentication is required):

If you only use public channels (e.g. all public market data), please make a request as follows to obtain the server list and temporary public token:

HTTP Request

POST https://futures-api.poloniex.com/api/v1/bullet-public

Private Channels (Authentication request required):

  {
    "code": "200000",
    "data": {
        "instanceServers": [
            {
                "pingInterval": 50000,
                "endpoint": "wss://futures-apiws.poloniex.com/endpoint",
                "protocol": "websocket",
                "encrypt": true,
                "pingTimeout": 10000
            }
        ],
        "token": "vYNlCtbz4XNJ1QncwWilJnBtmmfe4geLQDUA62kKJsDChc6I4bRDQc73JfIrlFaVYIAE0Gv2--MROnLAgjVsWkcDq_MuG7qV7EktfCEIphiqnlfpQn4Ybg==.IoORVxR2LmKV7_maOR9xOg=="
    }
  }

For private channels and messages (e.g. account balance notice), please make request as follows after authorization to obtain the server list and authorized token.

HTTP Request

POST https://futures-api.poloniex.com/api/v1/bullet-private

Response

Field	Description
pingInterval	Recommended to send ping interval in milliseconds
pingTimeout	After such a long time(milliseconds), if you do not receive pong, it will be considered disconnected.
endpoint	Websocket server address for establishing connection
protocol	Protocol supported
encrypt	Indicate whether SSL encryption is used
token	token

Create Connection

var socket = new WebSocket("wss://futures-apiws.poloniex.com/endpoint?token=xxx&[connectId=xxxxx]&[acceptUserMessage=true]");

When the connection is successfully established, the system will send a welcome message. To query via User Messages, please add “acceptUserMessage=true” in the wss link.

  {
    "id":"hQvf8jkno",
    "type":"welcome"
  } 

connectId: the connection id, a unique value taken from the client side. Both the id of the welcome message and the id of the error message are the connectId.

acceptUserMessage：if the value of acceptUserMessage equals true, the User Messages can be received.

Ping

  {
    "id":"1545910590801",
    "type":"ping"
  }

To prevent the TCP link being disconnected by the server, the client side needs to send ping messages to the server to keep the link alive.

After the ping message is sent to the server, the system would return a pong message to the client side.

If the server has not received the ping from the client for 60 seconds , the connection will be disconnected.

  {
    "id":"1545910590801",
    "type":"pong"
  }

Subscribe Topics

  {
    "id": 1545910660739,                          //The id should be an unique value
    "type": "subscribe",
    "topic": "/contractMarket/ticker:BTCUSDTPERP",  //Subscribed topic. Some topics support subscribe to the data of multiple trading pairs through ",".
    "privateChannel": false,                      //Adopt the private channel or not. Set as false by default.
    "response": true                              //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
  }

To subscribe to channel messages from a certain server, the client side should send subscription messages to the server.

If the subscription succeeds, the system will send ack messages to you, when the response is set as true.

  {
    "id":"1545910660739",
    "type":"ack"
  }

While there are topic messages generated, the system will send the corresponding messages to the client side. For details about the message format, please check the definitions of topics.

Parameters

ID

ID is a unique string to mark the request which is same as the id property of ack.

Topic

The topic you want to subscribe to.

Private Channel

For some specific topics (e.g. /contractMarket/level2), privateChannel is available. The default value of privateChannel is False. If the privateChannel is set to true, the user will only receive messages related to himself on the topic.

Response

If the response is set as true, the system will return the ack messages after the subscription succeeds.

Unsubscribe Topics

Unsubscribe from topics you have subscribed to.

  {
    "id": "1545910840805",                            //The id should be an unique value
    "type": "unsubscribe",
    "topic": "/contractMarket/ticker:BTCUSDTPERP",      //Topic needs to be unsubscribed. Some topics support unsubscribe from the data of multiple trading pairs through ",".
    "privateChannel": false, 
    "response": true,                                  //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
  }

  {
    "id": "1545910840805",
    "type": "ack"
  }

Parameters

ID

Unique string to mark the request.

Topic

The topic you want to subscribe.

PrivateChannel

For some specific public topics (e.g. /contractMarket/level2), privateChannel is available. The default value of privateChannel is False. If the privateChannel is set to true, the user will only receive messages related himself on the topic.

Response

If the response is set as true, the system would return the ack messages after the unsubscribe succeeds.

Multiplex

In one physical connection, you could open different multiplex tunnels to subscribe to different topics for different data.

For Example, enter the command below to open bt1 multiple tunnel : {"id": "1Jpg30DEdU", "type": "openTunnel", "newTunnelId": "bt1", "response": true}

Add “tunnelId” in the command: {"id": "1JpoPamgFM", "type": "subscribe", "topic": "/contractMarket/ticker:KCS-BTC"，"tunnelId": "bt1", "response": true}

You would then, receive messages corresponded to id tunnelIId: {"id": "1JpoPamgFM", "type": "message", "topic": "/contractMarket/ticker:KCS-BTC", "subject": "trade.ticker", "tunnelId": "bt1", "data": {...}}

To close the tunnel, you could enter command below: {"id": "1JpsAHsxKS", "type": "closeTunnel", "tunnelId": "bt1", "response": true}

Limitations

1. The multiplex tunnel is provided for API users only.
2. The maximum multiplex tunnels available: 5.

Sequence Number

The sequence field exists in order book, trade history and snapshot messages by default and the Level 3 and Level 2 data works to ensure the full connection of the sequence. If the sequence is non-sequential, please enable calibration logic.

General Logic for Message Assessment in Client Side

1. Assess message type. There are three types of messages at present: message (the commonly used messages for push), notice (the notices general used), and command (consecutive command).
2. Assess messages by userId. Messages with userId are private messages, messages without userId are common messages.
3. Assess messages by topic. You could assess the message type via topic.
4. Assess messages by subject. For the same type of messages with the same topic, you can assess the type of messages via their subjects.