Poloniex Futures provides both REST APIs and Websocket Feeds for interacting with our futures exchange. Both allow read access to public market data and private read access to your account. Private write access to your account is available via the private REST API. This documentation provides a detailed explanation of transaction functions and how to get market data from Poloniex Futures.
Our documentation is divided into two parts: 1) REST API and 2) Websocket Feed.
To get started with your Poloniex Futures API please create an API key within your account Settings,[https://poloniex.com/settings/futures-api-keys].
If you will be performing high-frequency trading, you may wish to locate your bots as close to our servers as possible. As Poloniex Futures uses Cloudflare for all requests, you can minimize network latency by positioning your client near the Cloudflare gateway in Tokyo, Japan. You can identify which Cloudflare gateway your client is accessing by running this command on the same machine as your bot:
curl -s https://www.cloudflare.com/cdn-cgi/trace
Cloudflare's Tokyo data center will return a "colo" field of "NRT". If you get a different "colo" value, you can look up the location at https://www.cloudflarestatus.com.
When a rate limit is exceeded, a status of 429 Too Many Requests will be returned.
The limit strategy of private endpoints will restrict account by userid. The limit strategy of public endpoints will restrict IP.
ratelimit-limit: the upper limit of requests per time, unit: times
ratelimit-interval: reset interval (reset the number of request), unit: second
ratelimit-remaining: the left available request number for this round, unit: times
If you are a professional trader or market maker and need a higher limit, please send your Poloniex Futures account, reason and approximate trading volume to api-support@poloniex.com.
Number of Connections
Connection Times
Number of Uplink Messages
Topic Subscription Limit
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
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.
All requests and responses are application/json content type.
Unless otherwise stated, all timestamp parameters should be in Unix time milliseconds. e.g. 1544657947759
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.
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.
{
"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. |
| 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.
A successful response is indicated by an HTTP status code 200 and system code 200000. The success response is as follows:
{
"code": "200000"
}
Poloniex Futures uses Pagination or HasMore for all REST requests which return arrays.
{
"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 /api/v1/orders?currentPage=1&pageSize=50
Parameters
| Parameter | Default | Description |
|---|---|---|
| currentPage | 1 | Current request page. |
| pageSize | 50 | Number of results per request. |
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 /api/v1/interest/query?symbol=.XBTINT&offset=1558079160000&forward=true&maxCount=10
Unless otherwise specified, all timestamps from API are returned in Unix time milliseconds(e.g. 1546658861000).
Before being able to sign any requests, you must create an API key via the Poloniex Settings. Upon creating a key you need to write down 3 pieces of information:
The Key and Secret are generated and provided by Poloniex Futures and the Passphrase refers to the one you used to create the Poloniex Futures API. Please note that these three pieces of information cannot be recovered once lost. If you lost this information, please create a new API KEY.
You can manage your API permissions in your Poloniex Settings account. The permissions are:
All REST requests must contain the following headers:
<?php
class API {
public function __construct($key, $secret, $passphrase) {
$this->key = $key;
$this->secret = $secret;
$this->passphrase = $passphrase;
}
public function signature($request_path = '', $body = '', $timestamp = false, $method = 'GET') {
$body = is_array($body) ? json_encode($body) : $body; // Body must be in json format
$timestamp = $timestamp ? $timestamp : time() * 1000;
$what = $timestamp . $method . $request_path . $body;
return base64_encode(hash_hmac("sha256", $what, $this->secret, true));
}
}
?>
#Example for get user position in python
api_key = "api_key"
api_secret = "api_secret"
api_passphrase = "api_passphrase"
url = 'https://futures-api.poloniex.com/api/v1/position?symbol=BTCUSDTPERP'
now = int(time.time() * 1000)
str_to_sign = str(now) + 'GET' + '/api/v1/position?symbol=BTCUSDTPERP'
signature = base64.b64encode(
hmac.new(api_secret.encode('utf-8'), str_to_sign.encode('utf-8'), hashlib.sha256).digest())
headers = {
"PF-API-SIGN": signature,
"PF-API-TIMESTAMP": str(now),
"PF-API-KEY": api_key,
"PF-API-PASSPHRASE": api_passphrase
}
response = requests.request('get', url, headers=headers)
print(response.status_code)
print(response.json())
#Example for update auto deposit status in python
url = 'https://futures-api.poloniex.com/api/v1/position/margin/auto-deposit-status'
now = int(time.time() * 1000)
data = {"symbol": "BTCUSDTPERP", "status": true}
data_json = json.dumps(data)
str_to_sign = str(now) + 'POST' + '/api/v1/position/margin/auto-deposit-status' + data_json
signature = base64.b64encode(
hmac.new(api_secret.encode('utf-8'), str_to_sign.encode('utf-8'), hashlib.sha256).digest())
headers = {
"PF-API-SIGN": signature,
"PF-API-TIMESTAMP": str(now),
"PF-API-KEY": api_key,
"PF-API-PASSPHRASE": api_passphrase,
"Content-Type": "application/json" # specifying content type or using json=data in request
}
response = requests.request('post', url, headers=headers, data=data_json)
print(response.status_code)
print(response.json())
For the header of PF-API-KEY,
Notice:
#Example for update to auto deposit status in python
curl -H "Content-Type:application/json" -H "PF-API-KEY:5c2db93503aa674c74a31734" -H "PF-API-TIMESTAMP:1547015186532" -H "PF-API-PASSPHRASE:Abc123456" -H "PF-API-SIGN:7QP/oM0ykidMdrfNEUmng8eZjg/ZvPafjIqmxiVfYu4="
-X POST -d '{"symbol":"BTCUSDTPERP","status":true}' http://futures-api.poloniex.com/api/v1/position/margin/auto-deposit-status
PF-API-KEY = 5c2db93503aa674c74a31734
PF-API-SECRET = f03a5284-5c39-4aaa-9b20-dea10bdcf8e3
PF-API-PASSPHRASE = Abc123456
TIMESTAMP = 1547015186532
METHOD = POST
ENDPOINT = /api/v1/position/margin/auto-deposit-status
STRING-TO-SIGN = 1547015186532POST/api/v1/position/margin/auto-deposit-status{"symbol":"BTCUSDTPERP","status":true}
PF-API-SIGN = 7QP/oM0ykidMdrfNEUmng8eZjg/ZvPafjIqmxiVfYu4=
The PF-API-TIMESTAMP header MUST be number of milliseconds since Unix Epoch in UTC. e.g. 1547015186532
The difference between your timestamp and the API service time must be less than 5 seconds , or your request will be considered expired and rejected. We recommend using the time endpoint to query for the API server time if you believe there may be time skew between your server and the API server.
Signature is required for this part.
{
"code": "200000",
"data": {
"accountEquity": 99.8999305281, //Account equity = marginBalance + Unrealised PNL
"unrealisedPNL": 0, //Unrealised profit and loss
"marginBalance": 99.8999305281, //Margin balance = positionMargin + orderMargin + frozenFunds + availableBalance
"positionMargin": 0, //Position margin
"orderMargin": 0, //Order margin
"frozenFunds": 0, //Frozen funds
"availableBalance": 99.8999305281 //Available balance
"currency": "USDT", //currency code
"pnl":-1 //Realised profit and loss
}
}
GET /api/v1/account-overview
GET /api/v1/account-overview?currency=USDT
| Param | Type | Description |
|---|---|---|
| currency | String | [Optional] Currency, XBT or USDT, Default USDT |
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 3 times/3s.
{
"code": "200000",
"data": {
"hasMore": false,//Whether there are more pages
"dataList": [{
"ts": 1558596284040, //Event time
"type": "RealisedPNL", //Type
"amount": 0, //Transaction amount
"fee": null,//Fees
"accountEquity": 8060.7899305281, //Account equity
"status": "Pending", //Status. If you have held a position in the current 8-hour settlement period.
"remark": "BTCUSDTPERP",//Ticker symbol of the contract
"offset": -1, //Offset
"currency": "XBT" //Currency
},
{
"ts": 1557997200000,
"type": "RealisedPNL",
"amount": -0.000017105,
"fee": 0,
"accountEquity": 8060.7899305281,
"status": "Completed",//Status. Status. Funding period that has been settled.
"remark": "BTCUSDTPERP",
"offset": 1,
"currency": "XBT"
}]
}
}
If there are open positions, the status of the first page returned will be Pending, indicating the realized profit and loss in the current 8-hour settlement period. Please specify the minimum offset number of the current page into the offset field to turn the page.
GET /api/v1/transaction-history
GET /api/v1/transaction-history?offset=1&forward=true&maxCount=50
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 9 times/3s.
| Param | Type | Description |
|---|---|---|
| startAt | long | [Optional] Start time (millisecond) |
| endAt | long | [Optional] End time (millisecond) |
| type | String | [Optional] Type RealisedPNL-Realised profit and loss, Transferin-Transfer in, TransferOut-Transfer out |
| offset | long | [Optional] Start offset |
| maxCount | long | [Optional] Displayed size per page. The default size is 50 |
| currency | String | [Optional] Currency of transaction history XBT or USDT |
| Field | Description |
|---|---|
| type | RealisedPNL, Deposit, TransferIn, TransferOut |
| status | Completed, Pending |
Signature is required for this part.
{
"code": "200000",
"data": {
"maxOrder": 300, //Maximum number of unsolved active orders
"maxStopOrder": 300 //Maximum number of profit stop and loss stop orders
}
}
You can query this endpoint to get the maximum active order and stop order quantity limit.
GET /api/v1/maxActiveOrders
GET /api/v1/maxActiveOrders
This endpoint requires the General permission.
No
{
"code": "200000",
"data": [
{ "maxLot":5000, //maximum risk limit
"symbol":"BTCUSDTPERP" //symbol of the contract
}]
}
You can query this endpoint to get the maximum of risk limit.
GET /api/v1/maxRiskLimit
GET /api/v1/maxRiskLimit?symbol=BTCUSDTPERP
This endpoint requires the General permission.
| Param | Type | Description |
|---|---|---|
| symbol | String | [optional] Symbol of the contract |
{
"code": "200000",
"data": {
"makerFeeRate": 0.0001, // maker 0.01%
"takerFeeRate": 0.0004 // taker 0.04%
}
}
You can query this endpoint to get the user fee rate.
GET /api/v1/userFeeRate
GET /api/v1/userFeeRate
This endpoint requires the General permission.
No
{
"code": "200000",
"data": 1 // Margin Mode 0(Isolated) 1(Cross)
}
GET /api/v1/marginType/query
GET /api/v1/marginType/query?symbol=BTCUSDTPERP
This endpoint requires the Trade permission
| Param | type | Description |
|---|---|---|
| symbol | String | a valid contract code. e.g. BTCUSDTPERP |
{
"code": "200000"
}
POST /api/v1/marginType/change
This endpoint requires the Trade permission
| Param | type | Description |
|---|---|---|
| symbol | String | a valid contract code. e.g. BTCUSDTPERP |
| marginType | Number | 0 (Isolated) or 1 (Cross) |
{
"code": "200000",
"data": {
"orderId": "5bd6e9286d99522a52e458de"
}
}
You can place two types of orders: limit and market. Orders can only be placed if your account has sufficient funds. Once an order is placed, your funds will be put on hold for the duration of the order. The amount of funds on hold depends on the order type and parameters specified.
Please note that the system will hold the fees from the orders entered in the orderbook in advance. Read Get Fills to learn more.
Do NOT include extra spaces in JSON strings.
The maximum limit orders for a single contract is 100 per account, and the maximum stop orders for a single contract is 50 per account.
POST /api/v1/orders
This endpoint requires the Trade permission
This API is restricted for each account, the request rate limit is 30 times/3s.
| Param | type | Description |
|---|---|---|
| clientOid | String | Unique order id created by users to identify their orders, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-) |
| side | String | buy or sell |
| symbol | String | a valid contract code. e.g. BTCUSDTPERP |
| type | String | [optional] Either limit or market |
| leverage | String | Leverage of the order |
| remark | String | [optional] remark for the order, length cannot exceed 100 utf8 characters |
| stop | String | [optional] Either down or up. Requires stopPrice and stopPriceType to be defined |
| stopPriceType | String | [optional] Either TP, IP or MP, Need to be defined if stop is specified. |
| stopPrice | String | [optional] Need to be defined if stop is specified. |
| reduceOnly | boolean | [optional] A mark to reduce the position size only. Set to false by default. |
| closeOrder | boolean | [optional] A mark to close the position. Set to false by default. |
| forceHold | boolean | [optional] A mark to forcely hold the funds for an order, even though it's an order to reduce the position size. This helps the order stay on the order book and not get canceled when the position size changes. Set to false by default. |
See Advanced Description for more details.
| Param | type | Description |
|---|---|---|
| price | String | Limit price |
| size | Integer | Order size. Must be a positive number |
| quantity | String | [optional] Order quantity. Must be a positive number. Only takes effect when size is empty |
| timeInForce | String | [optional] GTC, IOC(default is GTC), read Time In Force |
| postOnly | boolean | [optional] Post only flag, invalid when timeInForce is IOC. When postOnly chose, not allowed choose hidden or iceberg. |
| hidden | boolean | [optional] Orders not displaying in order book. When hidden chose, not allowed choose postOnly. |
| iceberg | boolean | [optional] Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly. |
| visibleSize | Integer | [optional] The maximum visible size of an iceberg order |
| Param | type | Description |
|---|---|---|
| size | Integer | [optional] amount of contract to buy or sell |
| quantity | String | [optional] Order quantity. Must be a positive number. Only takes effect when size is empty |
POST /api/v1/orders
{
"clientOid": "5c52e11203aa677f33e493fb",
"reduceOnly": false,
"closeOrder": false,
"forceHold": false,
"hidden": false,
"iceberg": false,
"leverage": 20,
"postOnly": false,
"price": 8000,
"remark": "remark",
"side": "buy",
"size": 20,
"stop": "",
"stopPrice": 0,
"stopPriceType": "",
"symbol": "BTCUSDTPERP",
"timeInForce": "",
"type": "limit",
"visibleSize": 0
}
The symbol must match a contract symbol, e.g. BTCUSDTPERP
Generated by yourself, the optional clientOid field must be a unique id (e.g UUID). Only numbers, characters, underline(_) and separator(-) are allowed. The value will be returned in the order detail. You can use this field to identify your orders via the public feed. The client_oid is different from the server-assigned order id. Please do not send a repeated client_oid. The length of the client_oid cannot exceed 40 characters. You should record the server-assigned order_id as it will be used for future queries of your order status.
The order type you specify may decide whether other optional parameters are required, as well as how your order will be executed by the matching engine. If order type is not specified, the order will be a limit order by default.
Price and size are required to be specified for a limit order. The order will be filled at the price specified or better, depending on the market condition. If a limit order cannot be filled immediately, it will be outstanding in the open order book until matched by another order, or canceled by the user.
A market order differs from a limit order in that the execution price is not guaranteed. Market order, however, provides a way to buy or sell a specific size of contract without having to specify the price. Market orders will be executed immediately, and no orders will enter the open order book afterwards. Market orders are always considered takers and incur taker fees.
The “leverage” parameter is used to calculate the margin to be frozen for the order. If you are to close the position, this parameter is not required.
A stop order is an order to buy or sell at the market or pre-specified limit price once the contact has traded at or through a pre-specified stopPrice. There are two types of stop orders, down and up.
Stop Order Types
down: Triggers when the price reaches or goes below the stopPrice.
up: Triggers when the price reaches or goes above the stopPrice.
stopPriceType: There are three types of stop prices for a contract, including: TP for trade price, MP for mark price, and IP for index price. The last trade price is the last price at which an order was filled. This price can be found in the latest match message. The mark price and the index price can be obtained through relevant OPEN API for index services.
Note that when triggered, stop orders will be executed as either market or limit orders, depending on the pre-specified type.
When placing a stop order, the system will not pre-freeze the funds in your account. Do note that when triggered, a stop order may be canceled if the available balance is not enough.
The price specified must be a multiple number of the contract tickSize, otherwise the system will report an error when you place the order. The tick size is the smallest price increment in which the prices are quoted. A valid price shall not be higher than the maxPrice in the contract specification. Poloniex Futures implements IEPR(Immediately Executable Price Range) rule, in which the price of a buy order cannot be higher than 1.05 * mark price, and the price of a sell order cannot be lower than 0.95 * mark price.
Price field is not required for market orders.
The order quantity is the number of contracts, and the unit of measurement for order quantity is the minimum lot size of the contract. The order quantity cannot be less than the minimum order quantity or greater than the maximum order quantity, and must be a multiple of the lot size, otherwise a system error will occur when placing an order. The order quantity represents the size of the contract to be bought or sold. Each BTCUSDTPERP contract corresponds to 0.001BTC.
Time in force is a special instruction used when placing an order to indicate how long an order will remain active before it is executed or expires. There are two types, Good Till Canceled GTC and Immediate Or Cancel IOC.
GTC Good Till Canceled: order remains open on the order book until canceled. This is the default type if the field is left empty.
IOC Immediate Or Cancel: being matched or not, the remaining size of the order will be instantly canceled instead of entering the order book.
Note that self trades belong to match as well.
The post-only flag ensures that the trader always pays the maker fee and provides liquidity to the order book. If any part of the order is going to pay taker fees, the order will be fully rejected.
The Hidden and iceberg Orders are two options in advanced settings (note: the iceberg order is a special form of the hidden order). You may select “Hidden” or “Iceberg” when placing a limit or stop limit order.
A hidden order will enter but not display on the orderbook.
Different from the hidden order, an iceberg order is divided into visible portion and invisible portion. When placing an iceberg order, you need to set the visible size. The minimum visible size is 1/20 of the order size. The minimum visible size shall be greater than the minimum order size, or an error will occur.
In a matching event, the visible portion of an iceberg order will be executed first, and another visible portion will pop up until the order is fully filled.
Note: 1)The system will charge taker fees for Hidden and iceberg Orders. 2)If both "Iceberg" and "Hidden" are selected, your order will be filled as an iceberg Order by default.
When placing an order, the system will freeze a certain amount of funds in your account for position margin and transaction fees based on the order price and quantity. If not, the order can only be one to reduce the position. If the total amount of these orders exceeds the position size, the system will cancel the extra no-fund-frozen orders to ensure they won’t be executed.
Actual fees are determined when the order is executed. If you cancel a partially filled or unfilled order, any remaining funds will be released from hold and become available.
Different from when an order reduces the position size, certain amount of funds need to be frozen when an order increases the position size. No funds need to be frozen when closeOrder is set to TRUE, or when reduceOnly is set to TRUE.
The execution of the order will incur transaction fees. If a partially filled or unfilled order is canceled, the system will unfreeze the remained frozen funds in your account.
If closeOrder is set to TRUE, the system will close the position and the position size will become 0. Side, Size and Leverage fields can be left empty and the system will determine the side and size automatically.
If set to TRUE, only the orders reducing the position size will be executed. If the reduce-only order size exceeds the position size, the extra size will be canceled.
The system will force freeze certain amount of funds for this order, including orders whose direction is opposite to the current positions. This feature is to ensure that the order won’t be canceled by the matching engine in such a circumstance that not enough funds are frozen for the order.
The HTTP Request will respond when an order is either rejected (insufficient funds, invalid parameters, etc) or received (accepted by the matching engine). A success response with order id indicates that the order has been received. Orders may be execute either partially or fully. After a partial execution, the remaining size of the order will be in active state (excluding IOC orders). A completely filled order will be in done state.
Users listening to streaming market data are encouraged to use the order id and clientOid field to identify their received messages in the feed.
A successful order will be assigned an order id. A successful order is defined as one that has been accepted by the matching engine.
Open orders will remain open until they are either filled or canceled.
{
"code": "200000",
"data": [
{
"clientOid": "87445124124342",
"code": "200000",
"orderId": "5bd6e9286d99522a52e458de"
},
{
"clientOid": "87445124124343",
"code": "100001",
"msg": "Price parameter invalid"
},
{
"clientOid": "87445124124344",
"code": "200000",
"orderId": "5bd6e9286d99522a52e458dg"
}
]
}
POST /api/v1/batchOrders
This endpoint requires the Trade permission
| Param | type | Description |
|---|---|---|
| batchOrders | List | order list. 10 orders at most |
| Param | type | Description |
|---|---|---|
| clientOid | String | Unique order id created by users to identify their orders, e.g. UUID, Only allows numbers, characters, underline(_), and separator(-) |
| side | String | buy or sell |
| symbol | String | a valid contract code. e.g. BTCUSDTPERP |
| type | String | [optional] Either limit or market |
| leverage | String | Leverage of the order |
| remark | String | [optional] remark for the order, length cannot exceed 100 utf8 characters |
| stop | String | [optional] Either down or up. Requires stopPrice and stopPriceType to be defined |
| stopPriceType | String | [optional] Either TP, IP or MP, Need to be defined if stop is specified. |
| stopPrice | String | [optional] Need to be defined if stop is specified. |
| reduceOnly | boolean | [optional] A mark to reduce the position size only. Set to false by default. |
| closeOrder | boolean | [optional] A mark to close the position. Set to false by default. |
| forceHold | boolean | [optional] A mark to forcely hold the funds for an order, even though it's an order to reduce the position size. This helps the order stay on the order book and not get canceled when the position size changes. Set to false by default. |
See Advanced Description for more details.
| Param | type | Description |
|---|---|---|
| price | String | Limit price |
| size | Integer | Order size. Must be a positive number |
| quantity | String | [optional] Order quantity. Must be a positive number. Only takes effect when size is empty |
| timeInForce | String | [optional] GTC, IOC(default is GTC), read Time In Force |
| postOnly | boolean | [optional] Post only flag, invalid when timeInForce is IOC. When postOnly chose, not allowed choose hidden or iceberg. |
| hidden | boolean | [optional] Orders not displaying in order book. When hidden chose, not allowed choose postOnly. |
| iceberg | boolean | [optional] Only visible portion of the order is displayed in the order book. When iceberg chose, not allowed choose postOnly. |
| visibleSize | Integer | [optional] The maximum visible size of an iceberg order |
| Param | type | Description |
|---|---|---|
| size | Integer | [optional] amount of contract to buy or sell |
| quantity | String | [optional] Order quantity. Must be a positive number. Only takes effect when size is empty |
POST /api/v1/batchOrders
{
"batchOrders":
[
{
"clientOid": "5c52e11203aa677f33e493fb",
"reduceOnly": false,
"closeOrder": false,
"forceHold": false,
"hidden": false,
"iceberg": false,
"leverage": 20,
"postOnly": false,
"price": 8000,
"remark": "remark",
"side": "buy",
"size": 20,
"stop": "",
"stopPrice": 0,
"stopPriceType": "",
"symbol": "BTCUSDTPERP",
"timeInForce": "",
"type": "limit",
"visibleSize": 0
},
{
"clientOid": "5c52e11203aa677f33e493fc",
"reduceOnly": false,
"closeOrder": false,
"forceHold": false,
"hidden": false,
"iceberg": false,
"leverage": 20,
"postOnly": false,
"price": 1200,
"remark": "remark",
"side": "buy",
"size": 20,
"stop": "",
"stopPrice": 0,
"stopPriceType": "",
"symbol": "ETHUSDTPERP",
"timeInForce": "",
"type": "limit",
"visibleSize": 0
}
]
}
{
"code": "200000",
"data": {
"cancelFailedOrderIds": [],
"cancelledOrderIds": [
"5bd6e9286d99522a52e458de"
]
}
}
{
"code": "100004",
"data": {
"cancelFailedOrderIds": [{
"orderId": "5bd6e9286d99522a52e458de",
"orderState": -1
}],
"cancelledOrderIds": []
}
}
Cancel an order (including a stop order).
You will receive a success message once the system has received the cancellation request. The cancellation request will be processed by the matching engine in sequence. To know if the request has been processed, you may check the order status or update message from the pushes.
The order id is the server-assigned order id，not the specified clientOid.
If the order can not be canceled (already filled or previously canceled, etc), then an error response will indicate the reason in the message field.
DELETE /api/v1/orders/{order-id}
DELETE /api/v1/orders/5cdfc120b21023a909e5ad52
This endpoint requires the Trade permission.
This API is restricted for each account, the request rate limit is 40 times/3s.
The possible values of "orderState" includes -
| orderState | Description |
|---|---|
| -1 | Error validation parameter invalid |
| -3 | Order not found |
| -4 | Contract not found |
| -5 | Order cancellation Paused Temporarily |
| -6 | Contract has been closed or cannot be cancelled |
| -7 | Please terminate the existing grid under this symbol first |
{
"code": "200000",
"data": {
"cancelFailedOrderIds": [],
"cancelledOrderIds": [
"5c52e11203aa677f33e493fb",
"5c52e12103aa677f33e493fe",
"5c6265c503aa676fee84129c",
"5c6269e503aa676fee84129f",
"5c626b0803aa676fee8412a2"
]
}
}
Cancel all open orders (excluding stop orders). The response is a list of orderIDs of the canceled orders.
DELETE /api/v1/orders
DELETE /api/v1/orders?symbol=BTCUSDTPERP
This endpoint requires the Trade permission.
This API is restricted for each account, the request rate limit is 1 times/3s.
| Param | Type | Description |
|---|---|---|
| symbol | String | [optional] Cancel all limit orders for a specific contract only |
| side | String | [optional] buy or sell |
You can delete specific symbols using query parameters. If not specified, all the limit orders will be deleted.
The possible values of "orderState" includes -
| orderState | Description |
|---|---|
| -1 | Error validation parameter invalid |
| -3 | Order not found |
| -4 | Contract not found |
| -5 | Order cancellation Paused Temporarily |
| -6 | Contract has been closed or cannot be cancelled |
| -7 | Please terminate the existing grid under this symbol first |
{
"code": "200000",
"data": {
"cancelFailedOrders": [{
"orderId": "5bd6e9286d99522a52e458de",
"clientOid": "5c52e11203aa677f33e493fc",
"orderState": -1
}],
"cancelledIds": [
"5c52e11203aa677f33e493fb",
"5c52e12103aa677f33e493fe",
"5c6265c503aa676fee84129c",
"5c6269e503aa676fee84129f",
"5c626b0803aa676fee8412a2"
]
}
}
Cancel multiple open orders (excluding stop orders). The response is a list of orderIDs (or clientOids) of the canceled orders.
DELETE /api/v1/batchOrders
DELETE /api/v1/batchOrders
{
"orderIds": [
"5c52e11203aa677f33e493fb",
"5c52e12103aa677f33e493fe",
"5c6265c503aa676fee84129c",
"5c6269e503aa676fee84129f",
"5c626b0803aa676fee8412a2"
]
}
This endpoint requires the Trade permission.
This API is restricted for each account, the request rate limit is 3 times/3s.
| Param | Type | Description |
|---|---|---|
| orderIds | List |
[optional] system order id, supports up to 10 orders |
| clientOids | List |
[optional] client order id, supports up to 10 orders |
orderIds and clientOids must be filled at least one, if both are set, the default is orderIds to cancel the order.
The possible values of "orderState" includes -
| orderState | Description |
|---|---|
| -1 | Error validation parameter invalid |
| -3 | Order not found |
| -4 | Contract not found |
| -5 | Order cancellation Paused Temporarily |
| -6 | Contract has been closed or cannot be cancelled |
| -7 | Please terminate the existing grid under this symbol first |
{
"code": "200000",
"data": {
"cancelFailedOrderIds": [],
"cancelledOrderIds": [
"5c52e11203aa677f33e49311",
"5c52e12103aa677f33e49322"
]
}
}
Cancel all untriggered stop orders. The response is a list of orderIDs of the canceled stop orders. To cancel triggered stop orders, please use 'Limit Order Mass Cancelation'.
DELETE /api/v1/stopOrders
DELETE /api/v1/stopOrders?symbol=BTCUSDTPERP
This endpoint requires the Trade permission.
This API is restricted for each account, the request rate limit is 2 times/10s.
You can delete specific symbols using query parameters.
| Param | Type | Description |
|---|---|---|
| symbol | String | [optional] Cancel all untriggered stop orders for a specific contract only |
The possible values of "orderState" includes -
| orderState | Description |
|---|---|
| 2 | Order was already closed in the long past (order state = canceled) |
| 3 | Order was already closed in the long past (order state = partial-canceled) |
| 4 | Order was already closed in the long past (order state = filled) |
| 5 | Order was already closed in the long past (order state = partial-filled) |
| -1 | Error validation parameter invalid |
| -3 | Order not found |
| -4 | Contract not found |
| -5 | Order cancellation Paused Temporarily |
| -6 | Contract has been closed or cannot be cancelled |
{
"code": "200000",
"data": {
"currentPage": 1,
"pageSize": 100,
"totalNum": 1000,
"totalPage": 10,
"items": [
{
"id": "5cdfc138b21023a909e5ad55", //Order ID
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"type": "limit", //Order type, market order or limit order
"side": "buy", //Transaction side
"price": "3600", //Order price
"size": 20000, //Order quantity
"value": "56.1167227833", //Order value
"filledValue": "0", //Value of the executed orders
"filledSize": 0, //Executed order quantity
"stp": "", //Self trade prevention types
"stop": "", //Stop order type (stop limit or stop market)
"stopPriceType": "", //Trigger price type of stop orders
"stopTriggered": false, //Mark to show whether the stop order is triggered
"stopPrice": null, //Trigger price of stop orders
"timeInForce": "GTC", //Time in force policy type
"postOnly": false, // Mark of post only
"hidden": false, //Mark of the hidden order
"iceberg": false, //Mark of the iceberg order
"visibleSize": null, //Visible size of the iceberg order
"leverage": "20", //Leverage of the order
"forceHold": false, //A mark to forcely hold the funds for an order
"closeOrder": false, //A mark to close the position
"reduceOnly": false, //A mark to reduce the position size only
"clientOid": "5ce24c16b210233c36ee321d", //Unique order id created by users to identify their orders
"remark": null, //Remark of the order
"isActive": true, //Mark of the active orders
"cancelExist": false, //Mark of the canceled orders
"createdAt": 1558167872000, //Time the order created
"settleCurrency": "XBT", //settlement currency
"status": "open", //order status: “open” or “done”
"updatedAt": 1558167872000, //last update time
"orderTime": 1558167872000000000 //order create time in nanosecond
}
]
}
}
List your current orders.
GET /api/v1/orders
GET /api/v1/orders?status=active
Submit the request to get all the active orders.
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 30 times/3s.
You can request data for specific orders using query parameters.
| Param | Type | Description |
|---|---|---|
| status | String | [optional] active or done, done as default. Only list orders for a specific status |
| symbol | String | [optional] Symbol of the contract |
| side | String | [optional] buy or sell |
| type | String | [optional] limit, market, limit_stop or market_stop |
| startAt | long | [optional] Start time (millisecond) |
| endAt | long | [optional] End time (millisecond) |
| marginType | Number | [optional] 0 (Isolated) or 1 (Cross) |
This request is paginated.
Any limit order on the exchange order book is in active status. Orders removed from the order book will be marked with done status. After an order becomes done, there may be a few milliseconds latency before it’s fully settled.
You can check the orders in any status. If the status parameter is not specified, orders of done status will be returned by default.
When you query orders in active status, there is no time limit. However, when you query orders in done status, the start and end time range cannot exceed 24*7 hours. An error will occur if the specified time window exceeds the range. If you specify the end time only, the system will automatically calculate the start time as end time minus 24 hours, and vice versa.
For high-volume trading, it is highly recommended that you maintain your own list of open orders and use one of the streaming market data feeds to keep it updated. You should poll the open orders endpoint to obtain the current state of any open order.
If you need to get your recent trade history with low latency, you may query the endpoint Get List of Orders Completed in 24h.
{
"code": "200000",
"data": {
"currentPage": 1,
"pageSize": 100,
"totalNum": 1000,
"totalPage": 10,
"items": [
{
"id": "5cdfc138b21023a909e5ad55", //Order ID
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"type": "limit", //Order type, market order or limit order
"marginType": 0, //Margin Mode, 0 (Isolated) or 1 (Cross)
"side": "buy", //Transaction side
"price": "3600", //Order price
"size": 20000, //Order quantity
"value": "56.1167227833", //Order value
"filledValue": "0", //Value of the executed orders
"filledSize": 0, //Executed order quantity
"stp": "", //Self trade prevention types
"stop": "", //Stop order type (stop limit or stop market)
"stopPriceType": "", //Trigger price type of stop orders
"stopTriggered": false, //Mark to show whether the stop order is triggered
"stopPrice": null, //Trigger price of stop orders
"timeInForce": "GTC", //Time in force policy type
"postOnly": false, //Mark of post only
"hidden": false, //Mark of the hidden order
"iceberg": false, //Mark of the iceberg order
"visibleSize": null, //Visible size of the iceberg order
"leverage": "20", //Leverage of the order
"forceHold": false, //A mark to forcely hold the funds for an order
"closeOrder": false, //A mark to close the position
"reduceOnly": false, //A mark to reduce the position size only
"clientOid": "5ce24c16b210233c36ee321d", //Unique order id created by users to identify their orders
"remark": null, //Remark of the order
"isActive": true, //Mark of the active orders
"cancelExist": false, //Mark of the canceled orders
"createdAt": 1558167872000, //Time the order created
"settleCurrency": "XBT", //settlement currency
"status": "open", //order status: “open” or “done”
"updatedAt": 1558167872000 //last update time
}
]
}
}
Get the un-triggered stop orders list.
GET /api/v1/stopOrders
GET /api/v1/stopOrders?symbol=BTCUSDTPERP
Query this endpoint to get the untriggered stop orders of the position in BTCUSDTPERP.
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 9 times/3s.
You can request for specific orders using query parameters.
| Param | Type | Description |
|---|---|---|
| symbol | String | [optional] Symbol of the contract |
| side | String | [optional] buy or sell |
| type | String | [optional] limit, market |
| startAt | long | [optional] Start time (millisecond) |
| endAt | long | [optional] End time (millisecond) |
| marginType | Number | [optional] 0 (Isolated) or 1 (Cross) |
This request is paginated.
{
"code": "200000",
"data":[
{
"id": "5cdfc138b21023a909e5ad55", //Order ID
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"type": "limit", //Order type, market order or limit order
"marginType": 0, //Margin Mode, 0 (Isolated) or 1 (Cross)
"side": "buy", //Transaction side
"price": "3600", //Order price
"size": 20000, //Order quantity
"value": "56.1167227833", //Order value
"filledValue": "56.1167227833", //Value of the executed orders
"filledSize": 20000, //Executed order quantity
"stp": "", //Self trade prevention types
"stop": "", //Stop order type (stop limit or stop market)
"stopPriceType": "", //Trigger price type of stop orders
"stopTriggered": true, //Mark to show whether the stop order is triggered
"stopPrice": null, //Trigger price of stop orders
"timeInForce": "GTC", //Time in force policy type
"postOnly": false, //Mark of post only
"hidden": false, //Mark of the hidden order
"iceberg": false, //Mark of the iceberg order
"visibleSize": null, // Visible size of the iceberg order
"leverage": "20", //Leverage of the order
"forceHold": false, //A mark to forcely hold the funds for an order
"closeOrder": false, //A mark to close the position
"reduceOnly": false, //A mark to reduce the position size only
"clientOid": "5ce24c16b210233c36ee321d", //Unique order id created by users to identify their orders
"remark": null, //Remark of the order
"isActive": false, //Mark of the active orders
"cancelExist": false, //Mark of the canceled orders
"createdAt": 1558167872000, //Time the order created
"settleCurrency": "XBT", //settlement currency
"status": "done", //order status: “open” or “done”
"updatedAt": 1558167872000, //last update time
"orderTime": 1558167872000000000 //order create time in nanosecond
}
]
}
Get a list of recent 1000 orders in the last 24 hours.
If you need to get your recent traded order history with low latency, you may query this endpoint.
GET /api/v1/recentDoneOrders
GET /api/v1/recentDoneOrders
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 3 times/3s.
{
"code": "200000",
"data": {
"id": "5cdfc138b21023a909e5ad55", //Order ID
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"type": "limit", //Order type, market order or limit order
"side": "buy", //Transaction side
"price": "3600", //Order price
"size": 20000, //Order quantity
"value": "56.1167227833", //Order value
"filledValue": "56.1167227833", //Value of the executed orders
"filledSize": 20000, //Executed order quantity
"stp": "", //Self trade prevention types
"stop": "", //Stop order type (stop limit or stop market)
"stopPriceType": "", //Trigger price type of stop orders
"stopTriggered": true, //Mark to show whether the stop order is triggered
"stopPrice": null, //Trigger price of stop orders
"timeInForce": "GTC", //Time in force policy types
"postOnly": false, //Mark of post only
"hidden": false, //Mark of the hidden order
"iceberg": false, //Mark of the iceberg order
"visibleSize": null, //Visible size of the iceberg order
"leverage": "20", //Leverage of the order
"forceHold": false, //A mark to forcely hold the funds for an order
"closeOrder": false, //A mark to close the position
"reduceOnly": false, //A mark to reduce the position size only
"clientOid": "5ce24c16b210233c36ee321d", //Unique order id created by users to identify their orders
"remark": null, //Remarks of the order
"isActive": false, //Mark of the active orders
"cancelExist": false, //Mark of the canceled orders
"createdAt": 1558167872000, //Time the order created
"settleCurrency": "XBT", //settlement currency
"status": "done", //order status: “open” or “done” or “invalid”
"updatedAt": 1558167872000, //last update time
"orderTime": 1558167872000000000, //order create time in nanosecond
"trades": [
{
"feePay": 0.184,//Transaction Service fee
"tradeId": "63be8bfde9edc70006715958"
}
]
}
}
Get a single order by order id (including a stop order).
GET /api/v1/orders/{order-id}
GET /api/v1/orders/5cdfc138b21023a909e5ad55
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 40 times/3s.(share the rate limit with the Get Single Order by clientOid)
{
"code": "200000",
"data": {
"id": "5cdfc138b21023a909e5ad55", //Order ID
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"type": "limit", //Order type, market order or limit order
"side": "buy", //Transaction side
"price": "3600", //Order price
"size": 20000, //Order quantity
"value": "56.1167227833", //Order value
"filledValue": "56.1167227833", //Value of the executed orders
"filledSize": 20000, //Executed order quantity
"stp": "", //Self trade prevention types
"stop": "", //Stop order type (stop limit or stop market)
"stopPriceType": "", //Trigger price type of stop orders
"stopTriggered": true, //Mark to show whether the stop order is triggered
"stopPrice": null, //Trigger price of stop orders
"timeInForce": "GTC", //Time in force policy types
"postOnly": false, //Mark of post only
"hidden": false, //Mark of the hidden order
"iceberg": false, //Mark of the iceberg order
"visibleSize": null, //Visible size of the iceberg order
"leverage": "20", //Leverage of the order
"forceHold": false, //A mark to forcely hold the funds for an order
"closeOrder": false, //A mark to close the position
"reduceOnly": false, //A mark to reduce the position size only
"clientOid": "5ce24c16b210233c36ee321d", //Unique order id created by users to identify their orders
"remark": null, //Remarks of the order
"isActive": false, //Mark of the active orders
"cancelExist": false, //Mark of the canceled orders
"createdAt": 1558167872000, //Time the order created
"settleCurrency": "XBT", //settlement currency
"status": "done", //order status: “open” or “done”or “invalid”
"updatedAt": 1558167872000, //last update time
"orderTime": 1558167872000000000, //order create time in nanosecond
"trades": [
{
"feePay": 0.184,//Transaction Service fee
"tradeId": "63be8bfde9edc70006715958"
}
]
}
}
Get Single Order by clientOid (including a stop order).
GET /api/v1/clientOrderId/{clientOid}
GET /api/v1/clientOrderId/5cdfc138b21023a909e5ad55
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 40 times/3s.(share the rate limit with the Get Details of a Single Order)
{
"code": "200000",
"data": {
"currentPage":1,
"pageSize":1,
"totalNum":251915,
"totalPage":251915,
"items":[
{
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"tradeId": "5ce24c1f0c19fc3c58edc47c", //Trade ID
"orderId": "5ce24c16b210233c36ee321d", // Order ID
"side": "sell", //Transaction side
"liquidity": "taker", //Liquidity- taker or maker
"price": "8302", //Filled price
"size": 10, //Filled amount
"value": "0.001204529", //Order value
"feeRate": "0.0005", //Floating fees
"fixFee": "0.00000006", //Fixed fees
"feeCurrency": "XBT", //Charging currency
"stop": "", //A mark to the stop order type
"fee": "0.0000012022", //Transaction fee
"orderType": "limit", //Order type
"tradeType": "trade", //Trade type (trade, liquidation, ADL or settlement)
"createdAt": 1558334496000, //Time the order created
"settleCurrency": "XBT", //settlement currency
"tradeTime": 1558334496000000000 //trade time in nanosecond
}
]
}
}
Get a list of recent fills.
GET /api/v1/fills
GET /api/v1/fills
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 9 times/3s.
You can request fills for specific orders using query parameters. If you need to get your recent trade history with low latency, please query endpoint Get List of Orders Completed in 24H. The requested data is not real-time.
| Param | Type | Description |
|---|---|---|
| orderId | String | [optional] List fills for a specific order only (If you specify orderId, other parameters can be ignored) |
| symbol | String | [optional] Symbol of the contract |
| side | String | [optional] buy or sell |
| type | String | [optional] limit, market, limit_stop or market_stop |
| startAt | long | [optional] Start time (millisecond) |
| endAt | long | [optional] End time (millisecond) |
This request uses pagination.
Data Time Range The system allows you to retrieve data for up to one week (starting from the last day by default). If the time period of the queried data exceeds one week (time range from the start time to end time exceeds 24*7 hours), the system will send a prompt to remind you that you have exceeded the time limit. If you only specified the start time, the system will automatically calculate the end time (end time = start time + 24 hours). On the contrary, if you only specified the end time, the system will calculate the start time (start time= end time - 24 hours) the same way.
Fee
Orders on Poloniex Futures platform are classified into two types, taker and maker. A taker order matches other resting orders on the exchange order book, and gets executed immediately after order entry. A maker order, on the contrary, stays on the exchange order book and awaits to be matched. Taker orders will be charged taker fees, while maker orders will receive maker rebates. Please note that market orders, iceberg orders and hidden orders are always charged taker fees.
The system will pre-freeze a predicted taker fee when you place an order. The liquidity field indicates if the fill was charged taker or maker fees.
The system will pre-freeze the predicted fees (including the maintenance margin needed for the position, entry fees and fees to close positions) if you added the position, and will not pre-freeze fees if you reduced the position. After the order is executed, if you added positions, the system will deduct entry fees from your balance, if you closed positions, the system will deduct the close fees.
Fills are returned sorted by descending fill time.
This request is paginated.
{
"code": "200000",
"data": {
"openOrderBuySize": 20, //Total number of the unexecuted buy orders
"openOrderSellSize": 0, //Total number of the unexecuted sell orders
"openOrderBuyCost": "0.0025252525", //Value of all the unexecuted buy orders
"openOrderSellCost": "0", //Value of all the unexecuted sell orders
"settleCurrency": "XBT" //settlement currency
}
}
You can query this endpoint to get the the total number and value of the all your active orders.
GET /api/v1/openOrderStatistics
GET /api/v1/openOrderStatistics?symbol=BTCUSDTPERP
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 9 times/3s.
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
{
"id": "5ce3cda60c19fc0d4e9ae7cd", //Position ID
"symbol": "BTCUSDTPERP", //Symbol
"autoDeposit": true, //Auto deposit margin or not
"maintMarginReq": 0.005, //Maintenance margin requirement
"riskLimit": 200, //Risk limit
"realLeverage": 1.06, //Leverage of the order
"marginType": 0, //Margin Mode 0(Isolated) 1(Cross)
"delevPercentage": 0.1, //ADL ranking percentile
"openingTimestamp": 1558433191000, //Open time
"currentTimestamp": 1558507727807, //Current timestamp
"currentQty": -20, //Current position
"currentCost": 0.00266375, //Current position value
"currentComm": 0.00000271, //Current commission
"unrealisedCost": 0.00266375, //Unrealised value
"realisedGrossCost": 0, //Accumulated realised gross profit value
"realisedCost": 0.00000271, //Current realised position value
"isOpen": true, //Opened position or not
"markPrice": 7933.01, //Mark price
"markValue": 0.00252111, //Mark value
"posCost": 0.00266375, //Position value
"posCross": 1.2e-7, //Manually added margin
"posInit": 0.00266375, //Leverage margin
"posComm": 0.00000392, //Bankruptcy cost
"posLoss": 0, //Funding fees paid out
"posMargin": 0.00266779, //Position margin
"posMaint": 0.00001724, //Maintenance margin
"maintMargin": 0.00252516, //Position margin
"realisedGrossPnl": 0, //Accumulated realised gross profit value
"realisedPnl": -0.00000253, //Realised profit-loss of the position
"unrealisedPnl": -0.00014264, //Unrealised profit and loss
"unrealisedPnlPcnt": -0.0535, //Profit-loss ratio of the position
"unrealisedRoePcnt": -0.0535, //Rate of return on investment
"avgEntryPrice": 7508.22, //Average entry price
"liquidationPrice": 1000000, //Liquidation price
"bankruptPrice": 1000000, //Bankruptcy price
"settleCurrency": "XBT" //Currency used to clear and settle the trades
}
Get the position details of a specified position.
GET /api/v1/position
GET /api/v1/position?symbol=BTCUSDTPERP
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 9 times/3s.
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
{
"id": "5ce3cda60c19fc0d4e9ae7cd", //Position ID
"symbol": "BTCUSDTPERP", //Symbol
"autoDeposit": true, //Auto deposit margin or not
"maintMarginReq": 0.005, //Maintenance margin requirement
"riskLimit": 200, //Risk limit
"realLeverage": 1.06, //Leverage of the order
"marginType": 0, //Margin Mode 0(Isolated) 1(Cross)
"delevPercentage": 0.1, //ADL ranking percentile
"openingTimestamp": 1558433191000, //Open time
"currentTimestamp": 1558507727807, //Current timestamp
"currentQty": -20, //Current position
"currentCost": 0.00266375, //Current position value
"currentComm": 0.00000271, //Current commission
"unrealisedCost": 0.00266375, //Unrealised value
"realisedGrossCost": 0, //Accumulated realised gross profit value
"realisedCost": 0.00000271, //Current realised position value
"isOpen": true, //Opened position or not
"markPrice": 7933.01, //Mark price
"markValue": 0.00252111, //Mark value
"posCost": 0.00266375, //Position value
"posCross": 1.2e-7, //Manually added margin
"posInit": 0.00266375, //Leverage margin
"posComm": 0.00000392, //Bankruptcy cost
"posLoss": 0, //Funding fees paid out
"posMargin": 0.00266779, //Position margin
"posMaint": 0.00001724, //Maintenance margin
"maintMargin": 0.00252516, //Position margin
"realisedGrossPnl": 0, //Accumulated realised gross profit value
"realisedPnl": -0.00000253, //Realised profit-loss of the position
"unrealisedPnl": -0.00014264, //Unrealised profit and loss
"unrealisedPnlPcnt": -0.0535, //Profit-loss ratio of the position
"unrealisedRoePcnt": -0.0535, //Rate of return on investment
"avgEntryPrice": 7508.22, //Average entry price
"liquidationPrice": 1000000, //Liquidation price
"bankruptPrice": 1000000, //Bankruptcy price
"settleCurrency": "XBT" //Currency used to clear and settle the trades
}
Get the position details of a specified position.
GET /api/v1/positions
GET /api/v1/positions
This endpoint requires the General permission.
POST /api/v1/position/margin/auto-deposit-status
POST /api/v1/position/margin/auto-deposit-status
This endpoint requires the General permission.
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| status | boolean | Status |
POST /api/v1/position/margin/deposit-margin
POST /api/v1/position/margin/deposit-margin
This endpoint requires the General permission.
| Param | Type | Description |
|---|---|---|
| symbol | String | Ticker symbol of the contract |
| margin | Number | Margin amount (min. margin amount≥0.00001667XBT） |
| bizNo | String | A unique ID generated by the user, to ensure the operation is processed by the system only once |
POST /api/v1/position/margin/withdraw-margin
POST /api/v1/position/margin/withdraw-margin
This endpoint requires the General permission.
| Param | Type | Description |
|---|---|---|
| symbol | String | Ticker symbol of the contract |
| margin | Number | Margin amount |
| bizNo | String | A unique ID generated by the user, to ensure the operation is processed by the system only once |
{
"dataList": [
{
"id": 36275152660006, //id
"symbol": "BTCUSDTPERP", //Symbol
"timePoint": 1557918000000, //Time point (millisecond)
"fundingRate": 0.000013, //Funding rate
"markPrice": 8058.27, //Mark price
"positionQty": 10, //Position size
"positionCost": -0.001241, //Position value at settlement period
"funding": -0.00000464, //Settled funding fees. A positive number means that the user received the funding fee, and vice versa.
"settleCurrency": "XBT" //settlement currency
},
{
"id": 36275152660004,
"symbol": "BTCUSDTPERP",
"timePoint": 1557914400000,
"fundingRate": 0.00375,
"markPrice": 8079.65,
"positionQty": 10,
"positionCost": -0.0012377,
"funding": -0.00000465,
"settleCurrency": "XBT"
},
{
"id": 36275152660002,
"symbol": "BTCUSDTPERP",
"timePoint": 1557910800000,
"fundingRate": 0.00375,
"markPrice": 7889.03,
"positionQty": 10,
"positionCost": -0.0012676,
"funding": -0.00000476,
"settleCurrency": "XBT"
}
],
"hasMore": true //Whether there are more pages
}
Submit request to get the funding history.
GET /api/v1/funding-history
GET /api/v1/funding-history?symbol=BTCUSDTPERP
This endpoint requires the General permission.
This API is restricted for each account, the request rate limit is 9 times/3s.
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| startAt | long | [optional] Start time (millisecond) |
| endAt | long | [optional] End time (millisecond) |
| reverse | boolean | [optional] This parameter functions to judge whether the lookup is forward or not. True means “yes” and False means “no”. This parameter is set as true by default |
| offset | long | [optional] 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 | [optional] This parameter functions to judge whether the lookup is forward or not. True means “yes” and False means “no”. This parameter is set as true by default |
| maxCount | int | [optional] Max record count. The default record count is 10 |
Signature is not required for this part.
{
"code": "200000",
"data": {
"baseCurrency": "XBT", //Base currency
"fairMethod": "FundingRate", //Fair price marking method
"fundingBaseSymbol": ".XBTINT8H", //Ticker symbol of the based currency
"fundingQuoteSymbol": ".USDINT8H", //Ticker symbol of the quote currency
"fundingRateSymbol": ".BTCUSDTPERPFPI8H", //Funding rate symbol
"indexSymbol": ".PXBT", //Index symbol
"initialMargin": 0.01, //Initial margin requirement
"isDeleverage": true, //Enabled ADL or not
"isInverse": true, //Reverse contract or not
"isQuanto": false, //Whether quanto or not
"lotSize": 1, //Minimum lot size
"maintainMargin": 0.005, //Maintenance margin requirement
"makerFeeRate": -0.00025, //Maker fees
"makerFixFee": -0.0000000200, //Fixed maker fees
"markMethod": "FairPrice", //Marking method
"maxOrderQty": 1000000, //Maximum order quantity
"maxPrice": 1000000.0000000000, //Maximum order price
"maxRiskLimit": 200, //Maximum risk limit (unit: XBT)
"minRiskLimit": 200, //Minimum risk limit (unit: XBT)
"multiplier": -1, //Contract multiplier
"quoteCurrency": "USD", //Quote currency
"riskStep": 100, //Risk limit increment value (unit: XBT)
"rootSymbol": "XBT", //Contract group
"status": "Open", //Contract status
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"takerFeeRate": 0.0005, //Taker fees
"takerFixFee": 0.0000000600, //Fixed taker fees
"tickSize": 1, //Minimum price changes
"type": "FFWCSX", //Type of the contract
"maxLeverage": 100, //maximum leverage
"volumeOf24h": 14848115, //volume of 24 hours
"turnoverOf24h": 1590.20278373, //turnover of 24 hours
"openInterest": "10621721" //open interest
}
}
Submit request to get the info of all open contracts.
GET /api/v1/contracts/active
GET /api/v1/contracts/active
N/A
{
"code": "200000",
"data": {
"baseCurrency": "XBT", //Base currency
"fairMethod": "FundingRate", //Fair price marking method
"fundingBaseSymbol": ".XBTINT8H", //Ticker symbol of the based currency
"fundingQuoteSymbol": ".USDINT8H", //Ticker symbol of the quote currency
"fundingRateSymbol": ".BTCUSDTPERPFPI8H", //Funding rate symbol
"indexSymbol": ".PXBT", //Index symbol
"initialMargin": 0.01, //Initial margin requirement
"isDeleverage": true, //Enabled ADL or not
"isInverse": true, //Reverse contract or not
"isQuanto": false, //Whether quanto or not
"lotSize": 1, //Minimum lot size
"maintainMargin": 0.005, //Maintenance margin requirement
"makerFeeRate": -0.00025, //Maker fees
"makerFixFee": -0.0000000200, //Fixed maker fees
"markMethod": "FairPrice", //Marking method
"maxOrderQty": 1000000, //Maximum order quantity
"minOrderQty": 1, //Minimum order quantity
"maxPrice": 1000000.0000000000, //Maximum order price
"maxRiskLimit": 200, //Maximum risk limit (unit: XBT)
"minRiskLimit": 200, //Minimum risk limit (unit: XBT)
"multiplier": -1, //Contract multiplier
"quoteCurrency": "USD", //Quote currency
"riskStep": 100, //Risk limit increment value (unit: XBT)
"rootSymbol": "XBT", //Contract group
"status": "Open", //Contract status
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"takerFeeRate": 0.0005, //Taker fees
"takerFixFee": 0.0000000600, //Fixed taker fees
"tickSize": 1, //Minimum price changes
"type": "FFWCSX", //Type of the contract
"maxLeverage": 100 //maximum leverage
}
}
Submit request to get info of the specified contract.
GET /api/v1/contracts/{symbol}
GET /api/v1/contracts/BTCUSDTPERP
| Param | Type | Description |
|---|---|---|
| symbol | String | Path Parameter. Symbol of the contract |
{
"code": "200000",
"data": {
"sequence": 1001, //Sequence number
"symbol": "BTCUSDTPERP", //Symbol
"side": "buy", //Side of liquidity taker
"size": 10, //Filled quantity
"price": "7000.0", //Filled price
"bestBidSize": 20, //Best bid size
"bestBidPrice": "7000.0", //Best bid price
"bestAskSize": 30, //Best ask size
"bestAskPrice": "7001.0", //Best ask price
"tradeId": "5cbd7377a6ffab0c7ba98b26", //Transaction ID
"ts": 1550653727731 //Filled time - nanosecond
}
}
The real-time ticker 1.0 includes the last traded price, the last traded size, transaction ID, the side of the liquidity taker, the best bid price and size, the best ask price and size as well as the transaction time of the orders. These messages can also be obtained through the Websocket. The Sequence Number is used to judge whether the messages pushed by the Websocket is continuous.
GET /api/v1/ticker
GET /api/v1/ticker?symbol=BTCUSDTPERP
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
{
"code": "200000",
"data": {
"sequence": 1001, //Sequence number
"symbol": "BTCUSDTPERP", //Symbol
"side": "buy", //Side of liquidity taker
"size": 10, //Filled quantity
"price": "7000.0", //Filled price
"bestBidSize": 20, //Best bid size
"bestBidPrice": "7000.0", //Best bid price
"bestAskSize": 30, //Best ask size
"bestAskPrice": "7001.0", //Best ask price
"tradeId": "5cbd7377a6ffab0c7ba98b26", //Transaction ID
"ts": 1550653727731 //Filled time - nanosecond
}
}
The real-time ticker 2.0 includes the last traded price, the last traded size, transaction ID, the side of the liquidity taker, the best bid price and size, the best ask price and size as well as the transaction time of the orders. Version 2.0 has lower latency than version 1.0. Version 2.0 is recommended. These messages can also be obtained through the Websocket. The Sequence Number is used to judge whether the messages pushed by the Websocket is continuous.
GET /api/v2/ticker
GET /api/v2/ticker?symbol=BTCUSDTPERP
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
{
"code": "200000",
"data": [
{
"sequence": 1216084, //Sequence number
"symbol": "BTCUSDTPERP", //Symbol
"side": "buy", //Side of liquidity taker
"size": 2, //Filled quantity
"price": "57959.0", //Filled price
"bestBidSize": 362, //Best bid size
"bestBidPrice": "57921.0", //Best bid price
"bestAskPrice": "58004.0", //Best ask price
"tradeId": "606d5fd5d49eb222ee3f70ee" , //Transaction ID
"bestAskSize": 690, //Best ask size
"ts": 1617780689343866803 //Filled time - nanosecond
},
{
"sequence": 1078314, //Sequence number
"symbol": "ETHUSDTPERP", //Symbol
"side": "buy", //Side of liquidity taker
"size": 2, //Filled quantity
"price": "2080.9", //Filled price
"bestBidSize": 707, //Best bid size
"bestBidPrice": "2080.15", //Best bid price
"bestAskPrice": "2081.1", //Best ask price
"tradeId": "606d5fd5d49eb25bfaae2783", //Transaction ID
"bestAskSize": 600, //Best ask size
"ts": 1617780693401774615 //Filled time - nanosecond
}
]
}
The real-time tickers includes tickers of all trading symbols.
GET /api/v2/tickers
GET /api/v2/tickers
{
"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 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.
GET /api/v1/level2/snapshot
GET /api/v1/level2/snapshot?symbol=BTCUSDTPERP
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
{
"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 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.
GET /api/v1/level2/depth
GET /api/v1/level2/depth?symbol=BTCUSDTPERP&depth=depth5
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| depth | String | depth5, depth10, depth20 , depth30 , depth50 or depth100 |
{
"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
}
]
}
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.
GET /api/v1/level2/message/query
GET /api/v1/level2/message/query?symbol=BTCUSDTPERP&start=100&end=200
| 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) |
{
"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
}
}
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.
GET /api/v2/level3/snapshot
GET /api/v2/level3/snapshot?symbol=BTCUSDTPERP
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
{
"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
}
]
}
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.
{
"code": "200000",
"data": {
"sequence": 102, //Sequence number
"tradeId": "5cbd7377a6ffab0c7ba98b26", //Transaction ID
"takerOrderId": "5cbd7377a6ffab0c7ba98b27", //Taker order ID
"makerOrderId": "5cbd7377a6ffab0c7ba98b28", //Maker order ID
"price": "7000.0", //Filled price
"size": 1, //Filled quantity
"side": "buy", //Side-taker "ts": 1545904567062140823 //Filled time - nanosecond
}
}
List the last 100 trades for a symbol.
GET /api/v1/trade/history
GET /api/v1/trade/history?symbol=BTCUSDTPERP
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
SIDE The trade side indicates the taker order side. A taker order is the order that was matched with orders opened on the order book.
{
"dataList": [
{
"symbol": ".XBTINT", //Symbol of the Bitcoin Lending Rate
"granularity": 60000, //粒Granularity (millisecond)
"timePoint": 1557996300000, //Time point (millisecond)
"value": 0.0003 //Interest rate value
},
{
"symbol": ".XBTINT",
"granularity": 60000,
"timePoint": 1557996240000,
"value": 0.0003
},
{
"symbol": ".XBTINT",
"granularity": 60000,
"timePoint": 1557996180000,
"value": 0.0003
}
],
"hasMore": true //Whether there are more pages
}
Check interest rate list.
GET /api/v1/interest/query
GET /api/v1/interest/query?symbol=.XBTINT
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| startAt | long | [optional] Start time (millisecond) |
| endAt | long | [optional] End time (millisecond) |
| reverse | boolean | [optional] This parameter functions to judge whether the lookup is reverse. True means “yes”. False means no. This parameter is set as True by default. |
| offset | long | [optional] 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 | [optional] This parameter functions to judge whether the lookup is forward or not. True means “yes” and False means “no”. This parameter is set as true by default |
| maxCount | int | [optional] Max record count. The default record count is 10 |
{
"dataList": [
{
"symbol": ".PXBT", //Symbol of Bitcoin spot
"granularity": 1000, //Granularity (millisecond)
"timePoint": 1557998570000, //Time point (millisecond)
"value": 8016.24, //Index Value
"decomposionList": [ //Component List
{
"exchange": "gemini", //Exchange
"price": 8016.24, //Last traded price
"weight": 0.08042611 //Weight
},
{
"exchange": "kraken",
"price": 8016.24,
"weight": 0.02666502
},
{
"exchange": "coinbase",
"price": 8016.24,
"weight": 0.03847059
},
{
"exchange": "liquid",
"price": 8016.24,
"weight": 0.20419723
},
{
"exchange": "bittrex",
"price": 8016.24,
"weight": 0.29848962
},
{
"exchange": "bitstamp",
"price": 8016.24,
"weight": 0.35175143
}
]
}
],
"hasMore": true //Whether there are more pages
}
Check index list
GET /api/v1/index/query
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| startAt | long | [optional] Start time (millisecond) |
| endAt | long | [optional] End time (millisecond) |
| reverse | boolean | [optional] This parameter functions to judge whether the lookup is reverse. True means “yes”. False means no. This parameter is set as True by default |
| offset | long | [optional] 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 | [optional] This parameter functions to judge whether the lookup is forward or not. True means “yes” and False means “no”. This parameter is set as true by default |
| maxCount | int | [optional] Max record count. The default record count is 10 |
{
"symbol": "BTCUSDTPERP", //Symbol
"granularity": 1000, //Granularity (millisecond)
"timePoint": 1557999585000, //Time point (millisecond)
"value": 8052.51, //Mark price
"indexPrice": 8041.95 //Index price
}
Check the current mark price.
GET /api/v1/mark-price/{symbol}/current
GET /api/v1/mark-price/BTCUSDTPERP/current
| Param | Type | Description |
|---|---|---|
| symbol | String | Path Parameter. Symbol of the contract |
{
"dataList": [
{
"symbol": ".BTCUSDTPERPPI", //Premium index symbol
"granularity": 60000, //Granularity (millisecond)
"timePoint": 1558000320000, //Time point (millisecond)
"value": 0.022585 //Premium index
},
{
"symbol": ".BTCUSDTPERPPI",
"granularity": 60000,
"timePoint": 1558000260000,
"value": 0.022611
},
{
"symbol": ".BTCUSDTPERPPI",
"granularity": 60000,
"timePoint": 1558000200000,
"value": 0.021421
}
],
"hasMore": true //Whether there are more pages
}
Submit request to get premium index.
GET /api/v1/premium/query
GET /api/v1/premium/query?symbol=BTCUSDTPERP
| Param | Type | Description |
|---|---|---|
| symbol | String | Symbol of the contract |
| startAt | long | [optional] Start time (millisecond) |
| endAt | long | [optional] End time (millisecond) |
| reverse | boolean | [optional] This parameter functions to judge whether the lookup is reverse. True means “yes”. False means no. This parameter is set as True by default |
| offset | long | [optional] 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 | [optional] This parameter functions to judge whether the lookup is forward or not. True means “yes” and False means “no”. This parameter is set as true by default |
| maxCount | int | [optional] Max record count. The default record count is 10 |
{
"symbol": ".BTCUSDTPERPFPI8H", //Funding Rate Symbol
"granularity": 28800000, //Granularity (millisecond)
"timePoint": 1558000800000, //Time point (millisecond)
"value": 0.00375, //Funding rate
"predictedValue": 0.00375 //Predicted funding rate
}
Submit request to check the current mark price.
GET /api/v1/funding-rate/{symbol}/current
GET /api/v1/funding-rate/BTCUSDTPERP/current
| Param | Type | Description |
|---|---|---|
| symbol | String | Path Parameter. Symbol of the contract. |
{
"code":"200000",
"msg":"success",
"data":1546837113087
}
Get the API server time. This is the Unix timestamp.
GET /api/v1/timestamp
{
"code": "200000",
"data": {
"status": "open", //open, close, cancelonly
"msg": "upgrade match engine" //remark for operation
}
}
Get the service status.
GET /api/v1/status
GET /api/v1/kline/query
GET/api/v1/kline/query?symbol=.PXBT&granularity=480&from=1535302400000&to=1559174400000
| Param | Type | Description |
|---|---|---|
| symbol | String | [Required]Symbol |
| granularity | int | [Required]Granularity (minute) |
| from | long | [Optional]Start time (millisecond) |
| to | long | [Optional]End time (millisecond) |
{
"code": "200000",
"data": [
[
1575331200000,//Time
7495.01, //Entry price
8309.67, //Highest price
7250, //Lowest price
7463.55, //Close price
0 //Trading volume
],
[
1575374400000,
7464.37,
8297.85,
7273.02,
7491.44,
0
]
]
}
The granularity (granularity parameter of K-line) represents the number of minutes, and the available granularity scope is: 1,5,15,30,60,120,240,480,720,1440,10080. Requests beyond the above range will be rejected.
The maximum size per request is 200. If the specified start/end time and the time granularity exceeds the maximum size allowed for a single request, the system will only return 200 pieces of data for your request. If you want to get fine-grained data in a larger time range, you will need to specify the time ranges and make multiple requests for multiple times.
If you’ve specified only the start time in your request, the system will return 200 pieces of data from the specified start time to the current time of the system; If only the end time is specified, the system will return 200 pieces of data closest to the end time; If neither the start time nor the end time is specified, the system will return the 200 pieces of data closest to the current time of the system.
While there is a strict access frequency control for the REST API, we highly recommend that API users utilize the Websocket to get the real-time data.
The recommended way is to just create a websocket connection and subscribe to multiple channels.
{
"code": "200000",
"data": {
"instanceServers": [
{
"pingInterval": 50000,
"endpoint": "wss://futures-apiws.poloniex.com/endpoint",
"protocol": "websocket",
"encrypt": true,
"pingTimeout": 10000
}
],
"token": "vYNlCtbz4XNJ1QncwWilJnBtmmfe4geLQDUA62kKJsDChc6I4bRDQc73JfIrlFaVYIAE0Gv2--MROnLAgjVsWkcDq_MuG7qV7EktfCEIphiqnlfpQn4Ybg==.IoORVxR2LmKV7_maOR9xOg=="
}
}
You need to apply for one of the two tokens below to create a websocket connection.
If you only use public channels (e.g. all public market data), please make a request as follows to obtain the server list and temporary public token:
POST /api/v1/bullet-public
{
"code": "200000",
"data": {
"instanceServers": [
{
"pingInterval": 50000,
"endpoint": "wss://futures-apiws.poloniex.com/endpoint",
"protocol": "websocket",
"encrypt": true,
"pingTimeout": 10000
}
],
"token": "vYNlCtbz4XNJ1QncwWilJnBtmmfe4geLQDUA62kKJsDChc6I4bRDQc73JfIrlFaVYIAE0Gv2--MROnLAgjVsWkcDq_MuG7qV7EktfCEIphiqnlfpQn4Ybg==.IoORVxR2LmKV7_maOR9xOg=="
}
}
For private channels and messages (e.g. account balance notice), please make request as follows after authorization to obtain the server list and authorized token.
POST /api/v1/bullet-private
| Field | Description |
|---|---|
| pingInterval | Recommended to send ping interval in milliseconds |
| pingTimeout | After such a long time(milliseconds), if you do not receive pong, it will be considered disconnected. |
| endpoint | Websocket server address for establishing connection |
| protocol | Protocol supported |
| encrypt | Indicate whether SSL encryption is used |
| token | token |
var socket = new WebSocket("wss://futures-apiws.poloniex.com/endpoint?token=xxx&[connectId=xxxxx]&[acceptUserMessage=true]");
When the connection is successfully established, the system will send a welcome message. To query via User Messages, please add “acceptUserMessage=true” in the wss link.
{
"id":"hQvf8jkno",
"type":"welcome"
}
connectId: the connection id, a unique value taken from the client side. Both the id of the welcome message and the id of the error message are the connectId.
acceptUserMessage：if the value of acceptUserMessage equals true, the User Messages can be received.
{
"id":"1545910590801",
"type":"ping"
}
To prevent the TCP link being disconnected by the server, the client side needs to send ping messages to the server to keep the link alive.
After the ping message is sent to the server, the system would return a pong message to the client side.
If the server has not received the ping from the client for 60 seconds , the connection will be disconnected.
{
"id":"1545910590801",
"type":"pong"
}
{
"id": 1545910660739, //The id should be an unique value
"type": "subscribe",
"topic": "/contractMarket/ticker:BTCUSDTPERP", //Subscribed topic. Some topics support subscribe to the data of multiple trading pairs through ",".
"privateChannel": false, //Adopt the private channel or not. Set as false by default.
"response": true //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
}
To subscribe to channel messages from a certain server, the client side should send subscription messages to the server.
If the subscription succeeds, the system will send ack messages to you, when the response is set as true.
{
"id":"1545910660739",
"type":"ack"
}
While there are topic messages generated, the system will send the corresponding messages to the client side. For details about the message format, please check the definitions of topics.
ID is a unique string to mark the request which is same as the id property of ack.
The topic you want to subscribe to.
For some specific topics (e.g. /contractMarket/level2), privateChannel is available. The default value of privateChannel is False. If the privateChannel is set to true, the user will only receive messages related to himself on the topic.
If the response is set as true, the system will return the ack messages after the subscription succeeds.
Unsubscribe from topics you have subscribed to.
{
"id": "1545910840805", //The id should be an unique value
"type": "unsubscribe",
"topic": "/contractMarket/ticker:BTCUSDTPERP", //Topic needs to be unsubscribed. Some topics support unsubscribe from the data of multiple trading pairs through ",".
"privateChannel": false,
"response": true, //Whether the server needs to return the receipt information of this subscription or not. Set as false by default.
}
{
"id": "1545910840805",
"type": "ack"
}
Unique string to mark the request.
The topic you want to subscribe.
For some specific public topics (e.g. /contractMarket/level2), privateChannel is available. The default value of privateChannel is False. If the privateChannel is set to true, the user will only receive messages related himself on the topic.
If the response is set as true, the system would return the ack messages after the unsubscribe succeeds.
In one physical connection, you could open different multiplex tunnels to subscribe to different topics for different data.
For Example, enter the command below to open bt1 multiple tunnel : {"id": "1Jpg30DEdU", "type": "openTunnel", "newTunnelId": "bt1", "response": true}
Add “tunnelId” in the command: {"id": "1JpoPamgFM", "type": "subscribe", "topic": "/contractMarket/ticker:KCS-BTC"，"tunnelId": "bt1", "response": true}
You would then, receive messages corresponded to id tunnelIId:
{"id": "1JpoPamgFM", "type": "message", "topic": "/contractMarket/ticker:KCS-BTC", "subject": "trade.ticker", "tunnelId": "bt1", "data": {...}}
To close the tunnel, you could enter command below: {"id": "1JpsAHsxKS", "type": "closeTunnel", "tunnelId": "bt1", "response": true}
The sequence field exists in order book, trade history and snapshot messages by default and the Level 3 and Level 2 data works to ensure the full connection of the sequence. If the sequence is non-sequential, please enable calibration logic.
{
"id": 1545910660740,
"type": "subscribe",
"topic": "/contractMarket/ticker:BTCUSDTPERP",
"response": true
}
Topic: /contractMarket/ticker:{symbol}
{
"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.
{
"id": 1545910660740,
"type": "subscribe",
"topic": "/contractMarket/level2:BTCUSDTPERP",
"response": true
}
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.
{
"subject": "level2",
"topic": "/contractMarket/level2:BTCUSDTPERP",
"type": "message",
"data": {
"sequence": 18, //Sequence number which is used to judge the continuity of pushed messages
"change": "5000.0,sell,83" //Price, side, quantity
"timestamp": 1551770400000
}
}
Calibration procedure：
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:
| Price | Size | Side |
|---|---|---|
| 3988.62 | 8 | Sell 4 |
| 3988.61 | 32 | Sell 3 |
| 3988.60 | 47 | Sell 2 |
| 3988.59 | 3 | Sell 1 |
| 3988.51 | 56 | Buy 1 |
| 3988.50 | 15 | Buy 2 |
| 3988.49 | 100 | Buy 3 |
| 3988.48 | 10 | Buy 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:
| Price | Size | Side |
|---|---|---|
| 3988.62 | 8 | Sell 3 |
| 3988.60 | 47 | Sell 2 |
| 3988.59 | 3 | Sell 1 |
| 3988.51 | 56 | Buy 1 |
| 3988.50 | 44 | Buy 2 |
| 3988.49 | 100 | Buy 3 |
| 3988.48 | 10 | Buy 4 |
{
"id": 1545910660741,
"type": "subscribe",
"topic": "/contractMarket/execution:BTCUSDTPERP",
"response": true
}
Topic: /contractMarket/execution:{symbol}
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
}
}
{
"id": 1545910660742,
"type": "subscribe",
"topic": "/contractMarket/level3v2:{symbol}",
"response": true
}
Topic: /contractMarket/level3v2:{symbol}
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.
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
{
"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.
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
}
}
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
}
}
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
}
}
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
}
}
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.
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
{
"id": 1545910660742,
"type": "subscribe",
"topic": "/contract/instrument:BTCUSDTPERP",
"response": true
}
Topic: /contract/instrument:{symbol}
Subscribe this topic to get the market data of the contract.
//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
{
"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
}
}
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
{
"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
{
"type":"message",
"topic": "/contract/announcement",
"subject": "funding.end",
"data": {
"symbol": "BTCUSDTPERP", //Symbol
"fundingTime": 1551770400000, //Funding time
"fundingRate": -0.002966, //Funding rate
"timestamp": 1551770410000
}
}
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)
}
}
{
"type": "message",
"topic": "/contractMarket/tradeOrders",
"subject": "orderChange",
"channelType": "private",
"data": {
"orderId": "5cdfc138b21023a909e5ad55", //Order ID
"symbol": "BTCUSDTPERP", //symbol
"type": "match", // Message Type: "open", "match", "filled", "canceled", "update"
"marginType": 0, //Margin Mode 0(Isolated) 1(Cross)
"status": "open", // Order Status: "match", "open", "done"
"matchSize": "", // Match Size (when the type is "match")
"matchPrice": "",// Match Price (when the type is "match")
"orderType": "limit", // Order Type, "market" indicates market order, "limit" indicates limit order
"side": "buy", // Trading direction,include buy and sell
"price": "3600", // Order Price
"size": "20000", // Order Size
"remainSize": "20001", // Remaining Size for Trading
"filledSize":"20000", // Filled Size
"canceledSize": "0", // Cancelled Size
"tradeId": "5ce24c16b210233c36eexxxx", // Trade ID (when the type is "match")
"clientOid": "5ce24c16b210233c36ee321d", // clientOid
"orderTime": 1545914149935808589, // Order Time
"oldSize ": "15000", // Size Before Update (when the type is "update")
"liquidity": "maker", // Trading direction, buy or sell in taker
"ts": 1545914149935808589 // Timestamp
}
}
Order Status “match”: when the taker order executes with orders in the order book, the taker order status is “match”; “open”: the order is in the order book; “done”: the order is fully executed successfully;
Message Type “open”: when the order enters into the order book; “match”: when the order has been executed; “filled”: when the order has been executed and its status was changed into DONE; “canceled”: when the order has been cancelled and its status was changed into DONE; “update”: when the order has been updated;
Topic: /contractMarket/advancedOrders
{
"topic": "/contractMarket/advancedOrders",
"subject": "stopOrder",
"channelType": "private",
"data": {
"orderId": "5cdfc138b21023a909e5ad55", //Order ID
"symbol": "BTCUSDTPERP", //Ticker symbol of the contract
"type": "open", // Message type: open (place order), triggered (order triggered), cancel (cancel order)
"marginType": 0, //Margin Mode 0(Isolated) 1(Cross)
"orderType":"stop", // Order type: stop order
"side":"buy", // Buy or sell
"size":"1000", //Quantity
"orderPrice":"9000", //Order price. For market orders, the value is null
"stop":"up", //Stop order types
"stopPrice":"9100", //Trigger price of stop orders
"stopPriceType":"TP", //Trigger price type of stop orders
"triggerSuccess": true, //Mark to show whether the order is triggered. Only for triggered type of orders
"error": "error.createOrder.accountBalanceInsufficient", //error code, which is used only when the trigger of the triggered type of orders fails
"createdAt": 1558074652423, //Time the order created
"ts":1558074652423004000 // timestamp - nanosecond
}
}
Topic: /contractAccount/wallet
//Order Margin Event
{
"topic": "/contractAccount/wallet",
"subject": "orderMargin.change",
"channelType": "private",
"data": {
"orderMargin": 5923,//Current order margin
"currency":"USDT",//Currency
"timestamp": 1553842862614
}
}
//Available Balance Event
{
"topic": "/contractAccount/wallet",
"subject": "availableBalance.change",
"channelType": "private",
"data": {
"availableBalance": 5923, //Current available amount
"currency":"USDT",//Currency
"timestamp": 1553842862614
}
}
Topic: /contract/position:{symbol}
//Position Changes Caused Operations
{
"topic": "/contract/position:BTCUSDTPERP",
"subject": "position.change",
"channelType": "private",
"data": {
"realisedGrossPnl": 0E-8, //Accumulated realised profit and loss
"marginType": 0, //Margin Mode 0(Isolated) 1(Cross)
"liquidationPrice": 1000000.0, //Liquidation price
"posLoss": 0E-8, //Manually added margin amount
"avgEntryPrice": 7508.22, //Average entry price
"unrealisedPnl": -0.00014735, //Unrealised profit and loss
"markPrice": 7947.83, //Mark price
"posMargin": 0.00266779, //Position margin
"riskLimit": 200, //Risk limit
"unrealisedCost": 0.00266375, //Unrealised value
"posComm": 0.00000392, //Bankruptcy cost
"posMaint": 0.00001724, //Maintenance margin
"posCost": 0.00266375, //Position value
"maintMarginReq": 0.005, //Maintenance margin rate
"bankruptPrice": 1000000.0, //Bankruptcy price
"realisedCost": 0.00000271, //Currently accumulated realised position value
"markValue": 0.00251640, //Mark value
"posInit": 0.00266375, //Position margin
"realisedPnl": -0.00000253, //Realised profit-losts of the position
"maintMargin": 0.00252044, //Position margin
"realLeverage": 1.06, //Leverage of the order
"currentCost": 0.00266375, //Current position value
"openingTimestamp": 1558433191000, //Open time
"currentQty": -20, //Current position
"delevPercentage": 0.52, //ADL ranking percentile
"currentComm": 0.00000271, //Current commission
"realisedGrossCost": 0E-8, //Accumulated reliased gross profit value
"isOpen": true, //Opened position or not
"posCross": 1.2E-7, //Manually added margin
"currentTimestamp": 1558506060394, //Current timestamp
"unrealisedRoePcnt": -0.0553, //Rate of return on investment
"unrealisedPnlPcnt": -0.0553, //Position profit and loss ratio
"settleCurrency": "XBT" //Currency used to clear and settle the trades
}
}
//Position Changes Caused by Mark Price
{
"topic": "/contract/position:BTCUSDTPERP",
"subject": "position.change",
"channelType": "private",
"data": {
"marginType": 0, //Margin Mode 0(Isolated) 1(Cross)
"markPrice": 7947.83, //Mark price
"markValue": 0.00251640, //Mark value
"maintMargin": 0.00252044, //Position margin
"realLeverage": 10.06, //Leverage of the order
"unrealisedPnl": -0.00014735, //Unrealised profit and lost
"unrealisedRoePcnt": -0.0553, //Rate of return on investment
"unrealisedPnlPcnt": -0.0553, //Position profit and loss ratio
"delevPercentage": 0.52, //ADL ranking percentile
"currentTimestamp": 1558087175068, //Current timestamp
"settleCurrency": "XBT" //Currency used to clear and settle the trades
}
}
//Funding Settlement
{
"topic": "/contract/position:BTCUSDTPERP",
"subject": "position.settlement",
"channelType": "private",
"data": {
"fundingTime": 1551770400000, //Funding time
"qty": 100, //Position size
"markPrice": 3610.85, //Settlement price
"fundingRate": -0.002966, //Funding rate
"fundingFee": -296, //Funding fees
"ts": 1547697294838004923, //Current time (nanosecond)
"settleCurrency": "XBT" //Currency used to clear and settle the trades
}
}
{
"topic": "/contract/positionCross",
"subject": "positionCross.change",
"channelType": "private",
"data": {
"maintainMargin" : 100.99, //Maintenance margin
"marginAvailable" : 30.98, //Position margin
"maintainRate" : 0.38, //Margin rate
"unreleaseSum" : 1.5, //Unrealised profit and lost
"fundingSum" : -0.3, //Funding fees profit and loss
"accountAvailable" : 100.1 //Cross balance
}
}