Order Book
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 Full Order Book - Level 2
Get a snapshot of aggregated open orders for a symbol.
Level 2 order book includes all bids and asks (aggregated by price). This level returns only one aggregated size for each price (as if there was only one single order for that price).
This API will return data with full depth.
It is generally used by professional traders because it uses more server resources and traffic, and we have strict access frequency control.
To maintain an up-to-date Order Book, please use Websocket incremental feed after retrieving the Level 2 snapshot.
In the returned data, the sell side is sorted low to high by price and the buy side is sorted high to low by price.
HTTP Request
GET https://futures-api.poloniex.com/api/v1/level2/snapshot
Example
GET https://futures-api.poloniex.com/api/v1/level2/snapshot?symbol=BTCUSDTPERP
Parameters
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
Example:
{
"code": "200000",
"data": {
"symbol": "BTCUSDTPERP", //Symbol
"sequence": 100, //Ticker sequence number
"asks": [
["5000.0", 1000], //Price, quantity
["6000.0", 1983] //Price, quantity
],
"bids": [
["3200.0", 800], //Price, quantity
["3100.0", 100] //Price, quantity
]
}
}
Get Partial Order Book - Level 2
Get a partial snapshot of aggregated open orders for a symbol.
Level 2 order book includes all bids and asks (aggregated by price). This level returns only one aggregated size for each price (as if there was only one single order for that price).
This API will return data with partial depth.
It is generally used by professional traders because it uses more server resources and traffic, and we have strict access frequency control.
To maintain an up-to-date Order Book, please use Websocket incremental feed after retrieving the Level 2 snapshot.
In the returned data, the sell side is sorted low to high by price and the buy side is sorted high to low by price.
HTTP Request
GET https://futures-api.poloniex.com/api/v1/level2/depth
Example
GET https://futures-api.poloniex.com/api/v1/level2/depth?symbol=BTCUSDTPERP&depth=depth5
Parameters
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| depth | String | depth5, depth10, depth20 , depth30 , depth50 or depth100 |
Example:
{
"code": "200000",
"data": {
"symbol": "BTCUSDTPERP", //Symbol
"sequence": 100, //Ticker sequence number
"asks": [
["5000.0", 1000], //Price, quantity
["6000.0", 1983] //Price, quantity
],
"bids": [
["3200.0", 800], //Price, quantity
["3100.0", 100] //Price, quantity
]
}
}
Level 2 Pulling Messages
If the messages pushed by Websocket are not continuous, you can submit the following request and re-pull the data to ensure that the sequence is not missing. In the request, the start parameter is the sequence number of your last received message plus 1, and the end parameter is the sequence number of your current received message minus 1. After re-pulling the messages and applying them to your local exchange order book, you can continue to update the order book via the Websocket incremental feed. If the difference between the end and start parameter is more than 500, please stop using this request and we suggest you to rebuild the Level 2 orderbook.
Level 2 message pulling method: Take price as the key value and overwrite the local order quantity with the quantity in messages. If the quantity of a certain price in the pushed message is 0, please delete the corresponding data of that price.
HTTP Request
GET https://futures-api.poloniex.com/api/v1/level2/message/query
Example
GET https://futures-api.poloniex.com/api/v1/level2/message/query?symbol=BTCUSDTPERP&start=100&end=200
Parameters
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| start | long | Start sequence number (included in the returned data) |
| end | long | End sequence number (included in the returned data) |
Example:
{
"code": "200000",
"data": [
{
"symbol": "BTCUSDTPERP", //Symbol
"sequence": 1, //Message sequence number
"change": "7000.0,sell,10" //Price, side, quantity
},
{
"symbol": "BTCUSDTPERP", //Symbol
"sequence": 2, //Message sequence number
"change": "7000.0,sell,0" //Price, side, quantity
}
]
}
Get Full Order Book- Level 3
Get a snapshot of all the open orders for a symbol. The Level 3 order book includes all bids and asks (the data is non-aggregated, and each item means a single order).
To ensure your local orderbook data is the latest one, please use Websocket incremental feed after retrieving the level 3 snapshot.
In the orderbook, the selling data is sorted low to high by price and orders with the same price are sorted in time sequence. The buying data is sorted high to low by price and orders with the same price are sorted in time sequence. The matching engine will match the orders according to the price and time sequence.
The returned data is not sorted, you may sort the data yourselves.
HTTP REQUEST
GET https://futures-api.poloniex.com/api/v2/level3/snapshot
EXAMPLE
GET https://futures-api.poloniex.com/api/v2/level3/snapshot?symbol=BTCUSDTPERP
PARAMETERS
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
Example:
{
"code": "200000",
"data": {
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"sequence": 100, // Sequence number of the last message pulled through Level 3
"bids": [[5567483701231, "dfa123124", "123.12312", "10", 5567483701231], ...], // Selling data: order palcing time - nanosecond, order ID, price, quantity, time at which the order enters the order book - nanosecond
"asks": [[5567483701231, "dfa123124", "123.12312", "10", 5567483701231], ...], // Buying data: order placing time - nanosecond, order ID, price, quantity, time at which the order enters the order book - nanosecond
"ts": 1590634672060667000 // Nanosecond
}
}
Level 3 Pulling Messages
If the messages pushed by the Websocket is not continuous, you can submit the following request and re-pull the data to ensure that the sequence is not missing. In the request, the start parameter is the sequence number of your last received message plus 1, and the end parameter is the sequence number of your current received message minus 1. After re-pulling the messages and applying them to your local exchange order book, you can continue to update the order book via the Websocket incremental feed. If the difference between the end and start parameter is more than 500, please stop using this request and we suggest you to rebuild the Level 3 orderbook.
Example:
{
"code": "200000",
"data": [
{
"symbol": "BTCUSDTPERP", //Symbol
"sequence": 1, //Message sequence number
"side": "sell", //Order side
"orderTime": 1558074650840002300, //Order placing time
"size": 10, //Order quantity
"orderId": "5cde551aa14a9cad7e454374", //Order ID
"price": "7000.0", //Order price
"type": "open", //Message type
"clientOid": "xxxxxxxxxx", //Optional, this is a user-defined parameter which is used to identify the order
"ts": 1558074652423004000 //Time at which the order enters the order book- nanosecond
},
{
"symbol": "BTCUSDTPERP", //Symbol
"reason": "canceled", //Reason: canceld or filled
"sequence": 2, //Message sequence number
"orderId": "5cde551aa14a9cad7e454374", //Order ID
"type": "done", //Message type
"ts": 1558075303543002400 //Time at which the order is removed- nanosecond
}
]
}