Navbar

General

Introduction

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].

Minimize Latency

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.

Upcoming Changes

2022.03.21

2022.10.11

2023.01.04

Request Rate Limit

When a rate limit is exceeded, a status of 429 Too Many Requests will be returned.

REST API

The limit strategy of private endpoints will restrict account by userid. The limit strategy of public endpoints will restrict IP.

Will response following string for "header" via api

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

Apply for Higher Request Rate Limit

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.

WEBSOCKET

Number of Connections

Connection Times

Number of Uplink Messages

Topic Subscription Limit


REST API

Request

API Server Address

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

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

Endpoint of the Interface

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

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

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

Requests

All requests and responses are application/json content type.

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

Parameters

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

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

Errors

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

HTTP Error Code

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

System Error Code

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

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

Success

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

  {
    "code": "200000"
  }

Pager

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

Pagination

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

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

Example

GET /api/v1/orders?currentPage=1&pageSize=50

Parameters

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

HasMore

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

Parameters

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

Example

GET /api/v1/interest/query?symbol=.XBTINT&offset=1558079160000&forward=true&maxCount=10

Types

Timestamps

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

Authentication

Create API KEY

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.

Permissions

You can manage your API permissions in your Poloniex Settings account. The permissions are:

Create a Request

All REST requests must contain the following headers:

Signing a Message

    <?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,

  1. Use API-Secret to encrypt the prehash string {timestamp+method+endpoint+body} with sha256 HMAC. The request body is a JSON string and need to be the same with the parameters passed by the API.
  2. After that, use base64-encode to encrypt the result in step 1 again.

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=























































Selecting Timestamp

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.


User

Signature is required for this part.

Account

Get Account Overview

  { 
    "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
    }
  }

HTTP Request

GET /api/v1/account-overview

Example

GET /api/v1/account-overview?currency=USDT

Parameters

Param Type Description
currency String [Optional] Currency, XBT or USDT, Default USDT

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 3 times/3s.

Get Transaction History

  {
    "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.

HTTP Request

GET /api/v1/transaction-history

Example

GET /api/v1/transaction-history?offset=1&forward=true&maxCount=50

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 9 times/3s.

Parameters

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

Returned Data Types

Field Description
type RealisedPNL, Deposit, TransferIn, TransferOut
status Completed, Pending

Trade

Signature is required for this part.


Config

Query Maximum Active Order Limit

{
 "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.

HTTP Request

GET /api/v1/maxActiveOrders

Example

GET /api/v1/maxActiveOrders

API Permission

This endpoint requires the General permission.

PARAMETERS

No

Query Maximum Risk Limit

{
 "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.

HTTP Request

GET /api/v1/maxRiskLimit

Example

GET /api/v1/maxRiskLimit?symbol=BTCUSDTPERP

API Permission

This endpoint requires the General permission.

PARAMETERS

Param Type Description
symbol String [optional] Symbol of the contract

Query User Fee Rate

{
  "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.

HTTP Request

GET /api/v1/userFeeRate

Example

GET /api/v1/userFeeRate

API Permission

This endpoint requires the General permission.

PARAMETERS

No

Margin Mode

Query Margin Mode

  {
    "code": "200000",
    "data": 1 // Margin Mode 0(Isolated) 1(Cross)
  }

HTTP Request

GET /api/v1/marginType/query

Example

GET /api/v1/marginType/query?symbol=BTCUSDTPERP

API Permission

This endpoint requires the Trade permission

Parameters

Param type Description
symbol String a valid contract code. e.g. BTCUSDTPERP

Change Margin Mode

  {
    "code": "200000"
  }

HTTP Request

POST /api/v1/marginType/change

API Permission

This endpoint requires the Trade permission

Parameters

Param type Description
symbol String a valid contract code. e.g. BTCUSDTPERP
marginType Number 0 (Isolated) or 1 (Cross)

Orders

Place an Order

  {
    "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.

Place Order Limit:

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.

HTTP Request

POST /api/v1/orders

API Permission

This endpoint requires the Trade permission

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 30 times/3s.

Parameters

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.

LIMIT ORDER PARAMETERS

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

MARKET ORDER PARAMETERS

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

Example

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
  }



















Advanced Description

SYMBOL

The symbol must match a contract symbol, e.g. BTCUSDTPERP

CLIENT ORDER ID

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.

TYPE

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.

LEVERAGE

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.

STOP ORDERS

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.

PRICE

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.

SIZE

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

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.

POST ONLY

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.

HIDDEN AND ICEBERG

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.

HOLDS

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.

CLOSE ORDER

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.

CLOSE ONLY

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.

FORCE HOLD

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.

ORDER LIFECYCLE

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.

RESPONSE

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.

Place Multiple Orders

  {
    "code": "200000",
    "data": [
      {
        "clientOid": "87445124124342",
        "code": "200000",
        "orderId": "5bd6e9286d99522a52e458de"
      },
      {
        "clientOid": "87445124124343",
        "code": "100001",
        "msg": "Price parameter invalid"
      },
      {
        "clientOid": "87445124124344",
        "code": "200000",
        "orderId": "5bd6e9286d99522a52e458dg"
      }
    ]
  }

HTTP Request

POST /api/v1/batchOrders

API Permission

This endpoint requires the Trade permission

Parameters

Param type Description
batchOrders List order list. 10 orders at most

batchOrders object detail

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.

LIMIT ORDER PARAMETERS

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

MARKET ORDER PARAMETERS

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

Example

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
      }
    ]
  }










































Cancel an Order

  {
    "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.

HTTP Request

DELETE /api/v1/orders/{order-id}

Example

DELETE /api/v1/orders/5cdfc120b21023a909e5ad52

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 40 times/3s.

State Code

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

Cancel All Limit Order

  {
    "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.

HTTP Request

DELETE /api/v1/orders

Example

DELETE /api/v1/orders?symbol=BTCUSDTPERP

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 1 times/3s.

PARAMETERS

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.

State Code

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

Cancel Multiple Limit Orders

  {
    "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.

HTTP Request

DELETE /api/v1/batchOrders

Example

DELETE /api/v1/batchOrders

  {
     "orderIds": [
       "5c52e11203aa677f33e493fb",
       "5c52e12103aa677f33e493fe",
       "5c6265c503aa676fee84129c",
       "5c6269e503aa676fee84129f",
       "5c626b0803aa676fee8412a2"
     ]
  }

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 3 times/3s.

PARAMETERS

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.

State Code

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

Cancel All Stop Order

  {
    "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'.

HTTP Request

DELETE /api/v1/stopOrders

Example

DELETE /api/v1/stopOrders?symbol=BTCUSDTPERP

API Permission

This endpoint requires the Trade permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 2 times/10s.

PARAMETERS

You can delete specific symbols using query parameters.

Param Type Description
symbol String [optional] Cancel all untriggered stop orders for a specific contract only

State Code

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

Get Order List

  {
   "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.

HTTP Request

GET /api/v1/orders

Example

GET /api/v1/orders?status=active
Submit the request to get all the active orders.

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 30 times/3s.

PARAMETERS

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.

Order Status and Settlement

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.

POLLING

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.

Get Untriggered Stop Order List

  {
    "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.

HTTP Request

GET /api/v1/stopOrders

Example

GET /api/v1/stopOrders?symbol=BTCUSDTPERP

Query this endpoint to get the untriggered stop orders of the position in BTCUSDTPERP.

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 9 times/3s.

PARAMETERS

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.







Get List of Orders Completed in 24h

  {
    "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.

HTTP Request

GET /api/v1/recentDoneOrders

Example

GET /api/v1/recentDoneOrders

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 3 times/3s.

















Get Details of a Single Order

  {
    "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).

HTTP Request

GET /api/v1/orders/{order-id}

Example

GET /api/v1/orders/5cdfc138b21023a909e5ad55

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

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)















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).

HTTP Request

GET /api/v1/clientOrderId/{clientOid}

Example

GET /api/v1/clientOrderId/5cdfc138b21023a909e5ad55

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

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)

















Fills

Get Fills

  {
    "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.

HTTP Request

GET /api/v1/fills

Example

GET /api/v1/fills

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 9 times/3s.

PARAMETERS

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.

PAGINATION

Fills are returned sorted by descending fill time.

This request is paginated.

Active Order Value Calculation

{
  "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.

HTTP Request

GET /api/v1/openOrderStatistics

Example

GET /api/v1/openOrderStatistics?symbol=BTCUSDTPERP

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 9 times/3s.

PARAMETERS

Param Type Description
symbol String Symbol of the contract

Positions

Get Position Details

  {
    "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.

HTTP Request

GET /api/v1/position

Example

GET /api/v1/position?symbol=BTCUSDTPERP

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 9 times/3s.

PARAMETERS

Param Type Description
symbol String Symbol of the contract









Get Position List

    {
      "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.

HTTP Request

GET /api/v1/positions

Example

GET /api/v1/positions

API Permission

This endpoint requires the General permission.





















Enable/Disable of Auto-Deposit Margin

HTTP Request

POST /api/v1/position/margin/auto-deposit-status

Example

POST /api/v1/position/margin/auto-deposit-status

API Permission

This endpoint requires the General permission.

PARAMETERS

Param Type Description
symbol String Symbol of the contract
status boolean Status

Add Margin Manually

HTTP Request

POST /api/v1/position/margin/deposit-margin

Example

POST /api/v1/position/margin/deposit-margin

API Permission

This endpoint requires the General permission.

PARAMETERS

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

Remove Margin Manually

HTTP Request

POST /api/v1/position/margin/withdraw-margin

Example

POST /api/v1/position/margin/withdraw-margin

API Permission

This endpoint requires the General permission.

PARAMETERS

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

Funding Fees

Get Funding History

  {
    "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.

HTTP Request

GET /api/v1/funding-history

Example

GET /api/v1/funding-history?symbol=BTCUSDTPERP

API Permission

This endpoint requires the General permission.

REQUEST RATE LIMIT

This API is restricted for each account, the request rate limit is 9 times/3s.

PARAMETERS

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

Market Data

Signature is not required for this part.

Symbol

Get Open Contract List

  {
    "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.

HTTP Request

GET /api/v1/contracts/active

Example

GET /api/v1/contracts/active

PARAMETERS

N/A























Get Order Info. of the Contract

  {
    "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.

HTTP Request

GET /api/v1/contracts/{symbol}

Example

GET /api/v1/contracts/BTCUSDTPERP

PARAMETERS

Param Type Description
symbol String Path Parameter. Symbol of the contract























Get Ticker

Get Real-Time Ticker 1.0

  {
    "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.

HTTP Request

GET /api/v1/ticker

Example

GET /api/v1/ticker?symbol=BTCUSDTPERP

PARAMETERS

Param Type Description
symbol String Symbol of the contract

Get Real-Time Ticker 2.0

  {
    "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.

HTTP Request

GET /api/v2/ticker

Example

GET /api/v2/ticker?symbol=BTCUSDTPERP

PARAMETERS

Param Type Description
symbol String Symbol of the contract

Get Real-Time Ticker of all symbols

  {
    "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.

HTTP Request

GET /api/v2/tickers

Example

GET /api/v2/tickers

Order Book

Get Full Order Book - Level 2

  {
    "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.

HTTP Request

GET /api/v1/level2/snapshot

Example

GET /api/v1/level2/snapshot?symbol=BTCUSDTPERP

Parameters

Param Type Description
symbol String Symbol of the contract

Get Partial Order Book - Level 2

  {
    "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.

HTTP Request

GET /api/v1/level2/depth

Example

GET /api/v1/level2/depth?symbol=BTCUSDTPERP&depth=depth5

Parameters

Param Type Description
symbol String Symbol of the contract
depth String depth5, depth10, depth20 , depth30 , depth50 or depth100

Level 2 Pulling Messages

  {
    "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.

HTTP Request

GET /api/v1/level2/message/query

Example

GET /api/v1/level2/message/query?symbol=BTCUSDTPERP&start=100&end=200

Parameters

Param Type Description
symbol String Symbol of the contract
start long Start sequence number (included in the returned data)
end long End sequence number (included in the returned data)

Get Full Order Book- Level 3

 {
   "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.

HTTP REQUEST

GET /api/v2/level3/snapshot

EXAMPLE

GET /api/v2/level3/snapshot?symbol=BTCUSDTPERP

PARAMETERS

Param Type Description
symbol String Symbol of the contract

Level 3 Pulling Messages

  {
    "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.

Historical Data

Transaction History

  {
    "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.

HTTP Request

GET /api/v1/trade/history

Example

GET /api/v1/trade/history?symbol=BTCUSDTPERP

Parameters

Param Type Description
symbol String Symbol of the contract

Description

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.

Index

Get Interest Rate List

  {
    "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.

HTTP Request

GET /api/v1/interest/query

Example

GET /api/v1/interest/query?symbol=.XBTINT

PARAMETERS

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

Get Index List

{ 
    "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

HTTP Request

GET /api/v1/index/query

PARAMETERS

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











Get Current Mark Price

  {
    "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.

HTTP Request

GET /api/v1/mark-price/{symbol}/current

Example

GET /api/v1/mark-price/BTCUSDTPERP/current

PARAMETERS

Param Type Description
symbol String Path Parameter. Symbol of the contract

Get Premium Index

  {
    "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.

HTTP Request

GET /api/v1/premium/query

Example

GET /api/v1/premium/query?symbol=BTCUSDTPERP

PARAMETERS

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

Get Current Funding Rate

  {
    "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.

HTTP Request

GET /api/v1/funding-rate/{symbol}/current

Example

GET /api/v1/funding-rate/BTCUSDTPERP/current

PARAMETERS

Param Type Description
symbol String Path Parameter. Symbol of the contract.

Time

Server Time

  {  
    "code":"200000",
    "msg":"success",
    "data":1546837113087
  }

Get the API server time. This is the Unix timestamp.

HTTP Request

GET /api/v1/timestamp

Service Status

Get the service status

  {    
    "code": "200000",     
    "data": {
        "status": "open",                //open, close, cancelonly
        "msg":  "upgrade match engine"   //remark for operation
      }
  }

Get the service status.

HTTP Request

GET /api/v1/status

K Chart

Get K Line Data of Contract

HTTP Request

GET /api/v1/kline/query

Example

GET/api/v1/kline/query?symbol=.PXBT&granularity=480&from=1535302400000&to=1559174400000

Parameters

Param Type Description
symbol String [Required]Symbol
granularity int [Required]Granularity (minute)
from long [Optional]Start time (millisecond)
to long [Optional]End time (millisecond)

Response

{
    "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
        ]
    ]
}

Notice

  1. 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.

  2. 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.

  3. 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.

Websocket

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.

Apply for Connection Token

  {
    "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.

Public Channels (No authentication is required):

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:

HTTP Request

POST /api/v1/bullet-public

Private Channels (Authentication request required):

  {
    "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.

HTTP Request

POST /api/v1/bullet-private

Response

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

Create Connection

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.

Ping

  {
    "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"
  }

Subscribe Topics

  {
    "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.

Parameters

ID

ID is a unique string to mark the request which is same as the id property of ack.

Topic

The topic you want to subscribe to.

Private Channel

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.

Response

If the response is set as true, the system will return the ack messages after the subscription succeeds.

Unsubscribe Topics

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"
  }

Parameters

ID

Unique string to mark the request.

Topic

The topic you want to subscribe.

PrivateChannel

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.

Response

If the response is set as true, the system would return the ack messages after the unsubscribe succeeds.

Multiplex

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}

Limitations
  1. The multiplex tunnel is provided for API users only.
  2. The maximum multiplex tunnels available: 5.

Sequence Number

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.

General Logic for Message Assessment in Client Side

  1. Assess message type. There are three types of messages at present: message (the commonly used messages for push), notice (the notices general used), and command (consecutive command).
  2. Assess messages by userId. Messages with userId are private messages, messages without userId are common messages.
  3. Assess messages by topic. You could assess the message type via topic.
  4. Assess messages by subject. For the same type of messages with the same topic, you can assess the type of messages via their subjects.

Public Channels

Get Real-Time Symbol Ticker

  {
    "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.















Level 2 Market Data

  {
    "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:

  1. After receiving the websocket Level 2 data flow, cache the data.
  2. Initiate REST Level 2 snapshot request to get the snapshot data of Level 2 order book.
  3. Playback the cached Level 2 data flow.
  4. Apply the new Level 2 data flow to the local snapshot to ensure that the sequence of the new Level 2 update lines up with the sequence of the previous Level 2 data. Discard all the message prior to that sequence, and then playback the change to snapshot.
  5. Update the Level 2 full data based on the sequence according to the size. If the size equals to 0, you can update the sequence and remove the price of which the size is 0 out of Level 2. For other cases, please update the price and size.
  6. If the sequence of the newly pushed message does not line up to the sequence of the last message, you can pull through REST Level 2 message request to get the updated messages. Please note that the difference between the start and end parameters cannot exceed 500.

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

Execution data

  {
    "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
    }
 }

Full matching engine data:Level 3

 {
   "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.

  1. Send a subscribe message for a symbol of which you want to build the order book.
  2. Queue every message received over the websocket stream.
  3. Make a REST request to [Get Full Order Book - Level 3] and get the snapshot data of the order book.
  4. Playback queued messages, and discard sequence numbers before or equal to the snapshot sequence number.
  5. Apply playback messages to the snapshot as needed (see below).
  6. After playback is complete, apply real-time stream messages as they arrive.
  7. If the sequence of the received message is not constant with the previous message, please retry 1-6 to rebuild the orderbook.

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

//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.









OPEN

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
   }
 }














UPDATE

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
   }
 }














MATCH

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
   }
 }














DONE

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
   }
 }













Message channel for the 5 best ask/bid full data of Level 2

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.









Message channel for the 50 best ask/bid full data of Level 2

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

  //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

  //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

//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
    }
  }









System Annoucements

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

 //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

  //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          
    }
  }









Transaction Statistics Timer Event

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)
    }  
  }

























User Messages

Private Messages

{
   "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;

























Stop Order Lifecycle Event

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
       }
  }









Account Balance Events

Topic: /contractAccount/wallet

Order Margin Event

  //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

//Available Balance Event
  { 
    "topic": "/contractAccount/wallet",
    "subject": "availableBalance.change",
    "channelType": "private",
    "data": {
      "availableBalance": 5923, //Current available amount
      "currency":"USDT",//Currency
      "timestamp": 1553842862614
    }
  }









Position Change Events

Topic: /contract/position:{symbol}

Position Changes Caused Operations

  //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

  //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

  //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
    }
  }

Cross Position Information

  {
       "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
       }
  }