Skip to main content

Futures V3 REST API

Overview

The HTTP API allows read access to public market data through the public endpoints and read / write access to your private account via the private endpoints.

  • HTTP API: https://api.poloniex.com/v3

Authentication (API Signature) is not required for any public requests.

Private HTTP endpoints e.g. https://api.poloniex.com/v3/orders are authenticated using HMAC-SHA256 signed request. See details here Authentication.

Symbol convention is <baseCcy>_<quoteCcy>_PERP e.g. BTC_USDT_PERP

API Key Setup

  • After creating the API key, the default restrictions is Enable Reading.
  • To enable withdrawals via the API, the API key restriction needs to be modified through the Poloniex UI.
  • If you need to trade through the API, you need to modify the permissions in the UI and select the corresponding futures trading permissions.

Authentication

Authentication (API Signature) is not required for any public requests.

All private HTTP endpoints require authentication using HMAC-SHA256 signed request with the following headers:

  • key - entry whose value is api caller’s apiKey. e.g. A…-99…
  • signatureMethod - optional entry whose value is signature method. e.g. hmacSHA256
  • signatureVersion - optional entry whose value is signature version. e.g. 1
  • signTimestamp - entry whose value is a timestamp. e.g. 1649371360000
  • signature - entry whose value is the signature generated by API caller for the request. e.g. 4F…%3D.
  • recvWindow - optional entry whose value is duration in milliseconds. e.g. "1500". This field provides an additional layer of control, where if specified, the request will be rejected if the (poloniex system time - signTimestamp) is in excesss of recvWindow. Below are the error code responses:
    • 400: signTimestamp is more than 1 second from poloniex system time
    • 408: request timeout as recWindow threshold has been breached
tip

POST,DELETE requests should contain application/json type content and be in valid JSON format.

Signature Example Code

We provide signature codes in three languages, Java/Python/NodeJS, and examples of request codes, Here.

API Signature Generation

Steps:

  1. Compose a “Request String” to be used for the generation of the digital signature which would include:
    • Method type (GET/POST/DELETE/etc) followed "\n" e.g. GET\n
    • Access path, followed "\n" e.g. /orders\n
    • Add the timestamp parameter and List of parameters sorted by ASCII order delimited by & e.g.: limit=5&signTimestamp=1659259836247&symbol=ETH_USDT
    • NOTE: all parameters must be URL/UTF-8 encoded. i.e. space is encoded as "%20"
    • The final string for the signature generation, based on the example values above will be:
      GET\n
      /orders\n
      limit=5&symbol=ETH_USDT
    • DELETE or POST Method with http body, for example: To cancel orders by IDs: /orders/cancelByIds\n
      • Add requestBody and timestamp:
        requestBody={"orderIds":["1234567890"],"clientOrderIds": ["myId-1"]}
        signTimestamp=1631018760000
      • Timestamp needs to be added. Timestamps are valid for 1 minute. Connect the parameters in the above order with the character &:
        requestBody={"orderIds":["1234567890"],"clientOrderIds":["myId-1"]}&signTimestamp=1631018760000}
      • The final string to be used for signature calculation is composed as follows:
        DELETE\n
        /orders/cancelByIds/\n
    • DELETE or POST Method with no http body, for example : To Cancel Order by Id: /orders/1
      • Timestamp needs to be added. Timestamps are valid for 1 minute.
        signTimestamp=1631018760000
      • The final string to be used for signature calculation is composed as follows: DELETE\n
        /orders/1\n
        signTimestamp=1631018760000
  2. Generate a digital signature using the "Request String" generated in the previous step and your key (Secret Key):
    • Call the HmacSHA256 hash function to get the hash value with the request string and API private key obtained in the previous step as two parameters.
    • Encode this hash with base-64 and the resulting value is used as the digital signature for this interface call.
    • Example: 5g4Rx5A2bLyMWFgR3Aqp+B4w+iJkL7n5OD3SuYtCJK8=
  3. Request example using the above generated signature:

Note: POST\DELETE requests should contain application/json type content and be in valid JSON format.

Sample GET command:

curl -X GET \
--header 'key: A3xxxxxx-99xxxxxx-84xxxxxx-72xxxxxx' \
--header 'signatureMethod: HmacSHA256' \
--header 'signatureVersion: 2' \
--header 'signTimestamp: 1631018760000' \
--header 'signature: 5g4Rx5A2bLyMWFgR3Aqp+B4w+iJkL7n5OD3SuYtCJK8=' \

Rate Limits

You can use the following table and refer to the frequency limit rules to rationally use your trading strategy.

Email client services (api-support@poloniex.com) with any questions.

Note: Interfaces related to transactions, positions, and accounts are frequency limited based on the UID dimension. The market-related interfaces are frequency limited based on IP latitude.

TypeInterface NameUrlGeneral UserSilverGoldMarket MakerToken Market Maker
TradePlace Order/v3/trade/order508010010001000
Place Multiple Orders/v3/trade/orders5810100100
Cancel Order/v3/trade/order10016020010001000
Cancel Multiple Orders/v3/trade/batchOrders101620100100
Cancel All Orders/v3/trade/allOrders101620100100
Close At Market Price/v3/trade/position101620200200
Close All At Market Price/v3/trade/positionAll2481616
Get Current Orders/v3/trade/order/opens1020304050
Get Execution Details/v3/trade/order/trades1015152020
Get Order History/v3/trade/order/history1015152020
PositionGet Current Position/v3/trade/position/opens1020304050
Get Position History/v3/trade/position/history1015152020
Adjust Margin for Isolated Margin Trading Positions/v3/trade/position/margin1020304050
Switch Cross and Isolated Margin Modes/v3/position/switchIsolated1020304050
Get Margin Mode/v3/position/marginType1020304050
Get Leverage/v3/position/leverage1020304050
Set Leverage/v3/position/leverage1020304050
AccountGet Account Balance/v3/account/balance5080100200200
TypeInterface NameUrlRate Limit (per second)
Market DataCurrent Open positions/v3/market/openInterest300
Query Insurance fund information/v3/market/insurance
Get Index Price components/v3/market/indexPriceComponents
Get Order Book/v3/market/orderBook
Get Execution Info/v3/market/trades
Get Market Info/v3/market/tickers
Get Index Price/v3/market/indexPrice
Get Mark Price/v3/market/markPrice
Get Current Funding Rate/v3/market/fundingRate
Get Futures Risk Limit/v3/market/riskLimit
Get Product Info/v3/market/instruments
Get K-line Data/v3/market/candles20
Get Mark Price K-line Data/v3/market/markPriceCandlesticks
Get Index Price K-line Data/v3/market/indexPriceCandlesticks
Get Premium Index K-line Data/v3/market/premiumIndexCandlesticks
Get The Historical Funding Rates/v3/market/fundingRate/history