Skip to main content

Public Channels

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.

Get Real-Time Symbol Ticker​

Topic: /contractMarket/ticker:{symbol}

  {
    "id": 1545910660740,                          
    "type": "subscribe",
    "topic": "/contractMarket/ticker:BTCUSDTPERP",
    "response": true                              
  }
  {
    "subject": "ticker",
    "topic": "/contractMarket/ticker:BTCUSDTPERP",
    "data": {
      "symbol": "BTCUSDTPERP",					//Market of the symbol
      "sequence": 45,						//Sequence number which is used to judge the continuity of the pushed messages
      "side": "sell",						//Transaction side of the last traded taker order
      "price": 3600.00,					//Filled price
      "size": 16,							//Filled quantity
      "tradeId": "5c9dcf4170744d6f5a3d32fb",    //Order ID
      "bestBidSize": 795,					//Best bid size
      "bestBidPrice": 3200.00,			//Best bid 
      "bestAskPrice": 3600.00,			//Best ask size
      "bestAskSize": 284,					//Best ask
      "ts": 1553846081210004941		//Filled time - nanosecond
   }
  }

Subscribe this topic to get the realtime push of BBO changes.

The ticker channel provides real-time price updates whenever a match happens. If multiple orders are matched at the same time, only the last matching event will be pushed.

Please note that more information maybe added to messages from this channel in the near future.

Level 2 Market Data​

Topic: /contractMarket/level2:{symbol}

Subscribe to this topic to get Level 2 order book data.

The websocket system will send the incremental feed to you.

  {
    "id": 1545910660740,                          
    "type": "subscribe",
    "topic": "/contractMarket/level2:BTCUSDTPERP",
    "response": true                              
  }
  {
    "subject": "level2",
    "topic": "/contractMarket/level2:BTCUSDTPERP",
    "type": "message",
    "data": {
      "lastSequence": 8,                //After receiving the current message, if the lastSequence of the current message = the sequence of the previous message, the incremental push is complete.  
      "sequence": 18,					//Sequence number which is used to judge the continuity of pushed messages 
      "change": "5000.0,sell,83",		//[deprecated]Price, side, quantity
      "changes": ["5000.0,sell,83","5001.0,sell,3"],   //Price, side, quantity。incremental change in multiple gears
      "timestamp": 1551770400000 

      }
  }

Calibration procedure:

  1. After receiving the websocket Level 2 data flow, cache the data.
  2. Initiate REST Level 2 snapshot request to get the snapshot data of Level 2 order book.
  3. Playback the cached Level 2 data flow.
  4. Apply the new Level 2 data flow to the local snapshot to ensure that the sequence of the new Level 2 update lines up with the sequence of the previous Level 2 data. Discard all the message prior to that sequence, and then playback the change to snapshot.
  5. Update the Level 2 full data based on the sequence according to the size. If the size equals to 0, you can update the sequence and remove the price of which the size is 0 out of Level 2. For other cases, please update the price and size.
  6. If the sequence of the newly pushed message does not line up to the sequence of the last message, you can pull through REST Level 2 message request to get the updated messages. Please note that the difference between the start and end parameters cannot exceed 500.

The change property of Level 2 updates is a string value of "price,size,sequence". Please note that size is the updated size at that price Level. A size of "0" indicates that the price Level can be removed.

Example

Get the snapshot of the order book through REST request Level 2 snapshot to build a local order book. Suppose we get the data as following:

Sequence：16

  {
    "sequence": 16,
    "asks":[
      ["3988.59",3],
      ["3988.60",47],
      ["3988.61",32],
      ["3988.62",8]
    ],
    "bids":[
      ["3988.51",56],
      ["3988.50",15],
      ["3988.49",100],
      ["3988.48",10]
    ]
  }

Thus, the current order book is as following:

PriceSizeSide
3988.628Sell 4
3988.6132Sell 3
3988.6047Sell 2
3988.593Sell 1
3988.5156Buy 1
3988.5015Buy 2
3988.49100Buy 3
3988.4810Buy 4

After subscribing you will receive a change message as follows:

  "data": {
    "sequence": 17,
    "change": "3988.50,buy,44"     //Price, side, quantity

  }
  "data": {
    "sequence": 18,
    "change": "3988.61,sell,0"     //Price, side, quantity

  }

In the beginning, the sequence of the order book is 16. Discard the feed data of a sequence that is below or equals to 16, and apply playback to the sequence [17,18] to update the snapshot of the order book. Now the sequence of your order book is 18 and your local order book is up-to-date.

Diff:

  1. Update size of 3988.50 to 44 (Sequence 17)
  2. Remove 3988.61 (Sequence 18)

Now your order book is up-to-date and the final data is as follows:

PriceSizeSide
3988.628Sell 3
3988.6047Sell 2
3988.593Sell 1
3988.5156Buy 1
3988.5044Buy 2
3988.49100Buy 3
3988.4810Buy 4

Execution data​

Topic: /contractMarket/execution:{symbol}

  {
    "id": 1545910660741,                          
    "type": "subscribe",
    "topic": "/contractMarket/execution:BTCUSDTPERP",
    "response": true                              
  }

For each order executed, the system will send you the match messages in the format as following.

 {
   "topic": "/contractMarket/execution:BTCUSDTPERP",
   "subject": "match",
   "data": {
        "symbol": "BTCUSDTPERP",				//Symbol
        "sequence": 36,						//Sequence number which is used to judge the continuity of the pushed messages  
        "side": "buy",						// Side of liquidity taker
        "matchSize": 1,            //Filled quantity
        "size": 1,							//unFilled quantity
        "price": 3200.00,					// Filled price
        "takerOrderId": "5c9dd00870744d71c43f5e25",  //Taker order ID
        "ts": 1553846281766256031,		             //Filled time - nanosecond
        "makerOrderId": "5c9d852070744d0976909a0c",  //Maker order ID
        "tradeId": "5c9dd00970744d6f5a3d32fc"        //Transaction ID
    }
 }

Full matching engine data：Level 3​

Topic: /contractMarket/level3v2:{symbol}

 {
   "id": 1545910660742,                         
   "type": "subscribe",
   "topic": "/contractMarket/level3v2:{symbol}",  
   "response": true                             
 }

Subscribe to this topic to get the full data for Level 3 orders and trades. After subscription, you will receive the Level 3 real-time order and trading data, and you can use the data to maintain and update your local Level 3 order book data.

Note: please subscribe to the topic for Level 2 if Level 2 order book data needs to be maintained.

The process to maintain an up-to-date Level 3 order book is described below.

  1. Send a subscribe message for a symbol of which you want to build the order book.
  2. Queue every message received over the websocket stream.
  3. Make a REST request to Get Full Order Book - Level 3 and get the snapshot data of the order book.
  4. Playback queued messages, and discard sequence numbers before or equal to the snapshot sequence number.
  5. Apply playback messages to the snapshot as needed (see below).
  6. After playback is complete, apply real-time stream messages as they arrive.
  7. If the sequence of the received message is not constant with the previous message, please retry 1-6 to rebuild the orderbook.

Any Open and Match messages will result in changes to the order book. The following messages(RECEIVED, OPEN, UPDATE, MATCH, DONE) are sent over the websocket stream in JSON format after subscribing to this channel:

RECEIVED​

//RECEIVED
 {
   "topic": "/contractMarket/level3v2:BTCUSDTPERP",
   "subject": "received",
   "data": {
       "symbol": "BTCUSDTPERP",                        // symbol
       "sequence": 3262786900,                 // sequence
       "orderId": "5c0b520032eba53a888fd02x",  // order ID
       "clientOid": "ad123ad",                 // optional, for you to identify your order
       "ts": 1545914149935808589
   }
 }

When the matching engine receives an order command, the system will send a received message to you. Please specify the clientOid in your request to assess if the order is your own in the public channel.

OPEN​

When the remaining part in a limit order enters the order book, the system will send an OPEN message to the user.

 //OPEN
 {
   "topic": "/contractMarket/level3v2:BTCUSDTPERP",
   "subject": "open",
   "data": {
       "symbol": "BTCUSDTPERP",                // symbol
       "sequence": 3262786900,              // sequence
       "side": "buy",                    // buy or sell
       "price": "3634.5",                        // price
       "size": "10",                             // size
       "orderId": "5c0b520032eba53a888fd02x",  // order ID
       "orderTime": 1547697294838004923,       // time
       "ts": 1547697294838004923,              // time when the order enters the order book
   }
 }

UPDATE​

If the order is updated, the system will send an UPDATE message to the user.

 //UPDATE
 {
 "topic": "/contractMarket/level3v2:BTCUSDTPERP",
 "subject": "update",
 "data": {
   "symbol": "BTCUSDTPERP",                 // symbol
   "sequence": 3262786897,               // sequence
   "orderId": "5c0b520032eba53a888fd01f",  // order ID
   "size": "100",                            // updated size
   "ts": 1547697294838004923               // update time - nanosecond
   }
 }

MATCH​

If the order is matched, the system will send a MATCH message to the user. Level 3 here means buy/sell of the taker order.

 //MATCH
 {
   "topic": "/contractMarket/level3v2:BTCUSDTPERP",
   "subject": "match",
   "data": {
     "symbol": "BTCUSDTPERP",                  // symbol
     "sequence": 3262786901,                // sequence
     "side": "buy",                   // buy or sell of taker
     "price": "3634",                     // filled price
     "size": "10",                                // filled size
     "makerOrderId": "5c0b520032eba53a888fd01e",   // maker order ID
     "takerOrderId": "5c0b520032eba53a888fd01f",   // taker order ID
     "tradeId": "6c23b5454353a8882d023b3o",   // trade ID
     "ts": 1547697294838004923              // transaction time - nanosecond
   }
 }

DONE​

When the matching life cycle of an order ends, the order will no longer be displayed on the order book and the system will send a DONE message to the user.

 //DONE
 {
   "topic": "/contractMarket/level3v2:BTCUSDTPERP",
   "subject": "done",
   "data": {
     "symbol": "BTCUSDTPERP",                       // symbol
     "sequence": 3262786901,                   // sequence
     "reason": "filled",                      // filled or canceled
       "orderId": "5c0b520032eba53a888fd02x",    // order ID
     "ts": 1547697294838004923,          // completion time
   }
 }

Message channel for the 5 best ask/bid full data of Level 2​

Topic: /contractMarket/level2Depth5:{symbol}

{
   "type": "message",
   "topic": "/contractMarket/level2Depth5:BTCUSDTPERP",
   "subject": "level2",
   "data": {
       "asks":[
         ["9993", "3"],
         ["9992", "3"],
         ["9991", "47"],
         ["9990", "32"],
         ["9989", "8"]
       ],
       "bids":[
         ["9988", "56"],
         ["9987", "15"],
         ["9986", "100"],
         ["9985", "10"],
         ["9984", "10"]
  
       ],
         "ts": 1590634672060667000
    }
 }

Returned for every 100 milliseconds at most.

Message channel for the 50 best ask/bid full data of Level 2​

Topic: /contractMarket/level2Depth50:{symbol}

{
   "type": "message",
   "topic": "/contractMarket/level2Depth50:BTCUSDTPERP",
   "subject": "level2",
   "data": {
       "asks":[
         ["9993",3],
         ["9992",3],
         ["9991",47],
         ["9990",32],
         ["9989",8]
       ],
       "bids":[
         ["9988",56],
         ["9987",15],
         ["9986",100],
         ["9985",10],
         ["9984",10]
       ],
        "ts": 1590634672060667000
    }
}

Returned for every 100 milliseconds at most.

Contract Market Data​

Topic: /contract/instrument:{symbol}

  //Contract Market Data 
  {
    "id": 1545910660742,                          
    "type": "subscribe",
    "topic": "/contract/instrument:BTCUSDTPERP",   
    "response": true                              
  }

Subscribe this topic to get the market data of the contract.

Mark Price & Index Price​

  //Mark Price & Index Price
  { 
    "topic": "/contract/instrument:BTCUSDTPERP",
    "subject": "mark.index.price",
    "data": {
        "granularity": 1000,           //Granularity
        "indexPrice": 4000.23,            //Index price
        "markPrice": 4010.52,           //Mark price
        "timestamp": 1551770400000
    }
  }

Funding Rate​

//Funding Rate
  { 
    "topic": "/contract/instrument:BTCUSDTPERP",
    "subject": "funding.rate",
    "data": {
        "granularity": 60000,  //Granularity (predicted funding rate: 1-min granularity: 60000; Funding rate: 8-hours granularity: 28800000. )
        "fundingRate": -0.002966,     //Funding rate
        "timestamp": 1551770400000
    }
  }

System Annoucements​

Subscribe this topic to get the system announcements. topic: /contract/announcement

  //System Annoucements
  { 
    "id": 1545910660742,                          
    "type": "subscribe",
    "topic": "/contract/announcement",   
    "response": true                              
  }

Start Funding Fee Settlement​

 //Start Funding Fee Settlement
  { 
    "topic": "/contract/announcement",
    "subject": "funding.begin",
    "data": {
        "symbol": "BTCUSDTPERP",                   //Symbol
        "fundingTime": 1551770400000,          //Funding time
        "fundingRate": -0.002966,             //Funding rate
        "timestamp": 1551770400000
    }
  }

End Funding Fee Settlement​

  //End Funding Fee Settlement
  { 
    "type":"message",
    "topic": "/contract/announcement",
    "subject": "funding.end",
    "data": {
        "symbol": "BTCUSDTPERP",                   //Symbol
        "fundingTime": 1551770400000,          //Funding time
        "fundingRate": -0.002966,            //Funding rate
        "timestamp": 1551770410000          
    }
  }

Transaction Statistics Timer Event​

The transaction statistics will be pushed to users every 3 seconds. Topic: /contractMarket/snapshot:{symbol}

//Transaction Statistics Timer Event
  { 
    "topic": "/contractMarket/snapshot:BTCUSDTPERP",
    "subject": "snapshot.24h",
    "data": {
        "volume": 30449670,            //24h Volume
        "turnover": 845169919063,      //24h Turnover
        "lastPrice": 3551,           //Last price
        "priceChgPct": 0.0043,         //24h Change
        "ts": 1547697294838004923      //Snapshot time (nanosecond)
    }  
  }