Futures Rest API

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.

The REST API provides endpoints for users and trades as well as market data.

A Request URL is made by a Base URL and a specified endpoint of the interface. Base URL: https://futures-api.poloniex.com

Endpoint of the Interface

Each interface has its own endpoint, which is provided under the HTTP REQUEST module.

For GET requests, please append the queried parameters to the endpoint.

E.G. For "Position", the default endpoint of this API is /api/v1/position. If you pass the symbol parameter (BTCUSDTPERP), the endpoint will become /api/v1/position?symbol=BTCUSDTPERP and the final request URL will be https://futures-api.poloniex.com/api/v1/position?symbol=BTCUSDTPERP.

Requests

All requests and responses are application/json content type.

Unless otherwise stated, all timestamp parameters should be in Unix time milliseconds. e.g. 1544657947759

Parameters

For GET and DELETE requests, all queried parameters need to be included in the request URL. (e.g. /api/v1/position?symbol=BTCUSDTPERP)

For POST and PUT requests, all queried parameters need to be included in the request body in JSON format. (e.g. {"side":"buy"}). Do NOT include any space in JSON strings.

Errors

When errors occur, the HTTP error code or system error code will be returned. The body will also contain a message parameter indicating the cause.

HTTP Error Code

{
  "code": "400100",
  "msg": "Invalid Parameter."
}

Code	Meaning
400	Bad Request -- Invalid request format
401	Unauthorized -- Invalid API Key
403	Forbidden -- The request is forbidden
404	Not Found -- The specified resource could not be found
405	Method Not Allowed -- You tried to access the resource with an invalid method.
415	Content-Type -- application/json
429	Too Many Requests -- Access limit breached
500	Internal Server Error -- We had a problem with our server. Please try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

System Error Code

Code	Meaning
400001	Any of PF-API-KEY, PF-API-SIGN, PF-API-TIMESTAMP, PF-API-PASSPHRASE is missing in your request header.
400002	PF-API-TIMESTAMP Invalid -- Time differs from server time by more than 5 seconds
400003	PF-API-KEY not exists
400004	PF-API-PASSPHRASE error
400005	Signature error -- Please check your signature
400006	The IP address is not in the API whitelist
400007	Access Denied -- Your API key does not have sufficient permissions to access the URI
404000	URL Not Found -- The requested resource could not be found
400100	Parameter Error -- You tried to access the resource with invalid parameters
411100	User is frozen -- Please contact us via support center
500000	Internal Server Error -- We had a problem with our server. Try again later.

If the returned HTTP status code is not 200, the error code will be included in the returned results. If the interface call is successful, the system will return the code and data fields. If not, the system will return the code and msg fields. You can check the error code for details.

Success

A successful response is indicated by an HTTP status code 200 and system code 200000. The success response is as follows:

{
  "code": "200000"
}

Pager

Poloniex Futures uses Triple form or Pagination or HasMore for all REST requests which return arrays.

Triple form

{
  "from": 1,
  "direct": "NEXT",
  "limit": 50,
  "data": ...
}

The data in the corresponding direction can be accurately queried through the starting id and direct. The starting id can be queried forward or backward. Endpoints like /api/v2/orders, /api/v2/fills

Example GET https://futures-api.poloniex.com/api/v1/orders?from=0&direct=PREV&limit=50

Parameters

Parameter	Default	Description
from	0	The starting id of the query, use the nextId in the response result, and pass 0 for the first time
direct	NEXT	PREV - page forward; means starting from the starting id, querying in ascending order NEXT - page forward; means starting from the starting id, querying in descending order
limit	50	Limit of items per page

Pagination

{
  "currentPage": 1,
  "pageSize": 50,
  "totalNum": 6,
  "totalPage": 1,
  "data": ...
}

Pagination allows for fetching results with the current page and is well suited for real time data. Endpoints like /api/v1/orders, /api/v1/fills, return the latest items by default. To retrieve more results, users should specify the currentPage number in the subsequent requests to turn the page based on the data previously returned.

Example

GET https://futures-api.poloniex.com/api/v1/orders?currentPage=1&pageSize=50

Parameters

Parameter	Default	Description
currentPage	1	Current request page.
pageSize	50	Number of results per request.

HasMore

The HasMore pager uses a sliding window scheme to obtain paged data by sliding a fixed-sized window on the data stream. The returned results will provide field HasMore to show if there are more data. The HasMore pager is efficient and takes the same amount of time for each sliding which makes the HasMore pager well suited for real-time streaming data queries.

Parameters

Parameter	type	Description
offset	-	Start offset. The unique attribute of the last returned result of the last request. The data of the first page will be returned by default.
forward	boolean	Slide direction. Set to “TRUE” to look up data of the next page
maxCount	int	The maximum amount for each sliding

Example

GET https://futures-api.poloniex.com/api/v1/interest/query?symbol=.XBTINT&offset=1558079160000&forward=true&maxCount=10

Types

Timestamps

Unless otherwise specified, all timestamps from API are returned in Unix time milliseconds(e.g. 1546658861000).