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:
- 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
- Add requestBody and timestamp:
- 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
- Timestamp needs to be added. Timestamps are valid for 1 minute.
- Method type (GET/POST/DELETE/etc) followed
- 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=
- 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.
| Type | Interface Name | Url | General User | Silver | Gold | Market Maker | Token Market Maker |
|---|---|---|---|---|---|---|---|
| Trade | Place Order | /v3/trade/order | 50 | 80 | 100 | 1000 | 1000 |
| Place Multiple Orders | /v3/trade/orders | 5 | 8 | 10 | 100 | 100 | |
| Cancel Order | /v3/trade/order | 100 | 160 | 200 | 1000 | 1000 | |
| Cancel Multiple Orders | /v3/trade/batchOrders | 10 | 16 | 20 | 100 | 100 | |
| Cancel All Orders | /v3/trade/allOrders | 10 | 16 | 20 | 100 | 100 | |
| Close At Market Price | /v3/trade/position | 10 | 16 | 20 | 200 | 200 | |
| Close All At Market Price | /v3/trade/positionAll | 2 | 4 | 8 | 16 | 16 | |
| Get Current Orders | /v3/trade/order/opens | 10 | 20 | 30 | 40 | 50 | |
| Get Execution Details | /v3/trade/order/trades | 10 | 15 | 15 | 20 | 20 | |
| Get Order History | /v3/trade/order/history | 10 | 15 | 15 | 20 | 20 | |
| Position | Get Current Position | /v3/trade/position/opens | 10 | 20 | 30 | 40 | 50 |
| Get Position History | /v3/trade/position/history | 10 | 15 | 15 | 20 | 20 | |
| Adjust Margin for Isolated Margin Trading Positions | /v3/trade/position/margin | 10 | 20 | 30 | 40 | 50 | |
| Switch Cross and Isolated Margin Modes | /v3/position/switchIsolated | 10 | 20 | 30 | 40 | 50 | |
| Get Margin Mode | /v3/position/marginType | 10 | 20 | 30 | 40 | 50 | |
| Get Leverage | /v3/position/leverage | 10 | 20 | 30 | 40 | 50 | |
| Set Leverage | /v3/position/leverage | 10 | 20 | 30 | 40 | 50 | |
| Account | Get Account Balance | /v3/account/balance | 50 | 80 | 100 | 200 | 200 |
| Type | Interface Name | Url | Rate Limit (per second) |
|---|---|---|---|
| Market Data | Current Open positions | /v3/market/openInterest | 300 |
| 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/candles | 20 | |
| 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 |