BitMax Futures Trading API Documentation

In preparation for new Futures trading products, BitMax will stop supporting all API endpoints in this document on Feb 28, 2021. Please refer to Futures Pro (v2) API for our newest APIs.

Using BitMax Futures Trading API

The BitMax Futures API is based on RESTful and WebSocket.

The base URL for the RESTful API is https://bitmax.io/.
The URL for the WebSocket is: https://bitmax.io/<account-group>/api/pro/v1/stream. You will have to substitute <account-group> with your account group.

The RESTful API has JSON-encoded responses. All websocket messages are JSON-encoded.

Change Log

2020-07-09

From 2020-07-13 12:00 UTC onward, the List Futures Contracts API will include an additional field displayName. For BTC Contract settled in USDT (symbol=BTC-PERP), the displayName will be BTCUSDT. It is for display purposes only. API users should continue to use BTC-PERP when making API calls and parsing RESTful responses and WebSocket messages.

2020-04-05

Added three fields to WebSocket channel futures-collateral: requestId id, transactionType tp, and transaction number txNum.

2020-03-11

Added indexPrice and markPrice to futures/position RESTful API.

Added idxPx and markPx to the futures-position message (WebSocket).

2020-03-10

Added maxBuyNotional and maxSellNotional to futures/position RESTful API. The two existing fields maxBuyOrderSize and maxSellOrderSize are deprecated and will be removed in the next release.

Added mbn and msn to the futures-position message (WebSocket). The two existing fields mbos and msos are deprecated and will be removed in the next release.

Terminology

Asset / Collateral Asset

collateral asset refers to the cryptocurrency held in the account. Each collateral asset is uniquely identified by an asset code. For instance, Bitcoin is one collateral asset and has asset code BTC.

Symbol / Futures Contract

Futures contract are tradable products listed on the exchange. Each futures contract is uniquely identified by a symbol. For instance, the symbol of the BTC perpetrual contract is BTC-PERP.

Making REST API Calls

The RESTful APIs will always respond with JSON objects.

Authenticate a RESTful Request

Create Request

To access private data via RESTful APIs, you must include the following headers:

x-auth-key - required, the api key as a string.
x-auth-timestamp - required, the UTC timestamp in milliseconds of your request
x-auth-signature - required, the request signature (see Sign a Request)

The timestamp in the header will be checked against server time. If the difference is greater than 30 seconds, the request will be rejected.

Sign a Request

Signing a RESTful Request

# bash 
APIPATH=user/info
APIKEY=CEcrjGyipqt0OflgdQQSRGdrDXdDUY2x
SECRET=hV8FgjyJtpvVeAcMAgzgAFQCN36wmbWuN7o3WPcYcYhFd8qvE43gzFGVsFcCqMNk
TIMESTAMP=`date +%s%N | cut -c -13` # 1562952827927
MESSAGE=$TIMESTAMP+$APIPATH
SIGNATURE=`echo -n $MESSAGE | openssl dgst -sha256 -hmac $SECRET -binary | base64`
echo $SIGNATURE  # vBZf8OQuiTJIVbNpNHGY3zcUsK5gJpwb5lgCgarpxYI=

curl -X GET -i \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "x-auth-key: $APIKEY" \
  -H "x-auth-signature: $SIGNATURE" \
  -H "x-auth-timestamp: $TIMESTAMP" \
  https://bitmax.io/api/pro/v1/info

# python 3.6+
import time, hmac, hashlib, base64

api_path  = "user/info"
api_key   = "CEcrjGyipqt0OflgdQQSRGdrDXdDUY2x"
sec_key   = "hV8FgjyJtpvVeAcMAgzgAFQCN36wmbWuN7o3WPcYcYhFd8qvE43gzFGVsFcCqMNk"
timestamp = int(round(time.time() * 1e3)) # 1562952827927

message = bytes(f"{timestamp}+{api_path}", 'utf-8')
secret = bytes(sec_key, 'utf-8')

signature = base64.b64encode(hmac.new(secret, message, digestmod=hashlib.sha256).digest())

header = {
  "x-auth-key": api_key,
  "x-auth-signature": signature, 
  "x-auth-timestamp": timestamp,
}
print(signature)  # b'vBZf8OQuiTJIVbNpNHGY3zcUsK5gJpwb5lgCgarpxYI='

// java 1.8+
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;

public class SignatureExample {

  public static void main(String[] args) {
    try {
      long timestamp = System.currentTimeMillis(); // 1562952827927
      String api_path = "user/info";
      String secret = "hV8FgjyJtpvVeAcMAgzgAFQCN36wmbWuN7o3WPcYcYhFd8qvE43gzFGVsFcCqMNk";
      String message = timestamp + "+" + api_path;

      Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
      SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
      sha256_HMAC.init(secret_key);

      String hash = Base64.encodeBase64String(sha256_HMAC.doFinal(message.getBytes()));
      System.out.println(hash); // vBZf8OQuiTJIVbNpNHGY3zcUsK5gJpwb5lgCgarpxYI=
    }
    catch (Exception e) {
      System.out.println("Error");
    }
  }
}

To query APIs with private data, you must include a signature using base64 encoded HMAC sha256 algorithm. The prehash string is <timestamp>+<api-path>. The timestamp is the UTC timestamp in milliseconds.

API Permissions

You must specify permissions when setting up API keys. API permissions can never be changed. If you want different permissions, you would have to apply for new API keys.

There are three different permissions:

View
Trade
Transfer

Permissions - Bird's-eye View

RESTful APIs

API	Type	View	Trade	Transfer	Method / URL
Market Data	Public				`GET /api/pro/v1/futures/market-data`
Funding Rate History	Public				`GET /api/pro/v1/futures/funding-rates`
Futures Contract Info	Public				`GET /api/pro/v1/futures/contracts`
Futures Collateral Info	Public				`GET /api/pro/v1/futures/collateral`
Reference Prices	Public				`GET /api/pro/v1/futures/ref-px`
Account Info	Private				`GET /api/pro/v1/info`
Account Funding Payment History	Private	x			`GET <account-group>/api/pro/v1/futures/funding-payments`
Account Contract Positions	Private	x			`GET <account-group>/api/pro/futures/position`
Futures Collateral Balances	Private	x			`GET <account-group>/api/pro/v1/futures/collateral-balance`
Account Futures Risk Profile	Private	x			`GET <account-group>/api/pro/futures/risk`
Wallet Deposit/Withdrawal History	Private	x			`GET /api/pro/wallet/transactions`
List Open Orders	Private	x			`GET <account-group>/api/pro/v1/futures/order/open`
Place New Order	Private		x		`POST <account-group>/api/pro/v1/futures/order`
Cancel Order	Private		x		`DELETE <account-group>/api/pro/v1/futures/order`
Transfer Funds from Cash to Futures	Private			x	`POST /<account-group>/api/pro/v1/futures/transfer/deposit`
Transfer Funds from Futures to Cash	Private			x	`POST /<account-group>/api/pro/v1/futures/transfer/withdraw`

WebSocket Requests

API	Type	View	Trade	Action
Authenticate Session	Public		x	`auth`
Place New Order	Private		x	`place-order`
Cancel Order	Private		x	`cancel-order`
Cancel All Orders	Private		x	`cancel-all`
Account Contract Positions	Private	x		`futures-position`
Account Futures Risk Profile	Private	x		`futures-risk`

REST APIs - Futures

Market Data (Public)

Anyone can access public market data.

List Futures Collateral Assets

List Futures Collateral Assets

curl -X GET https://bitmax.io/api/pro/v1/futures/collateral

Sample Resonse

{
  "code": 0,
  "data": [
    {
      "asset":            "USDT",
      "assetName":        "Tether",
      "discountFactor":   "1"
    },
    {
      "asset":            "BTC",
      "assetName":        "Bitcoin",
      "discountFactor":   "0.98"
    }
  ]
}

You can get a list of assets eligible to be used as collateral with this API, along with other information needed to calculate the total collateral value of your account.

Permissions

This API is public.

HTTP Request

GET /api/pro/v1/futures/collateral

Response Content

Name	Type	Description	Sample Response
asset	`String`	asset code	`"BTC"`
assetName	`String`	full name of the asset	`"Bitcoin"`
discountFactor	`String`	the collateral discount factor	`"0.98"`

The exchange calculates the total collateral value of an account based on its adjusted USDT value (discount factor * reference price * collateral balance). The collateral value of the account is simply the sum of the adjusted USDT value of its all collateral assets.

List Futures Contracts

List Futures Contracts

curl -X GET https://bitmax.io/api/pro/v1/futures/contracts

Sample Resonse

{
  "code": 0,
  "data": [
    {
      "symbol":           "BTC-PERP",
      "tradingStartTime":  1574640000000,
      "collapseDecimals": "1,0.1,0.01",
      "minQty":           "0.000000001",
      "maxQty":           "1000000000",
      "minNotional":      "5",
      "maxNotional":      "100000",
      "statusCode":       "Normal",
      "statusMessage":    "",
      "tickSize":         "0.25",
      "lotSize":          "0.0001",
    }
  ]
}

Permissions

This API is public.

HTTP Request

GET /api/pro/v1/futures/contracts

Response Content

Name	Type	Description
symbol	`String`	contract symbol
tradingStartTime	Long	UTC timestamp when the contract is available for trading
collapseDecimals	`String`
minQty	`String`	minimum quantity allowed for an order
maxQty	`String`	maximum quantity allowed for an order
minNotional	`String`	minimum notional allowed for an order
maxNotional	`String`	maximum notional allowed for an order
tickSize	`String`	the tick size requirement for an order (a number in string format)
lotSize	`String`	the lot size requirement for an order (a number in string format)
statusCode	`String`	status code of the contract, e.g., `Normal`
statusMessage	`String`	When status code is not `Normal`, this message will contain the reason.

Response Content (New Schema, will be in effect at 2020-07-13 12:00 UTC)

Name	Type	Description
symbol	`String`	contract symbol, e.g. `BTC-PERP`
displayName	`String`	the name that will be displayed on the website, e.g. `BTCUSDT`
tradingStartTime	Long	UTC timestamp when the contract is available for trading
collapseDecimals	`String`
minQty	`String`	minimum quantity allowed for an order
maxQty	`String`	maximum quantity allowed for an order
minNotional	`String`	minimum notional allowed for an order
maxNotional	`String`	maximum notional allowed for an order
tickSize	`String`	the tick size requirement for an order (a number in string format)
lotSize	`String`	the lot size requirement for an order (a number in string format)
statusCode	`String`	status code of the contract, e.g., `Normal`
statusMessage	`String`	When status code is not `Normal`, this message will contain the reason.

Remark: from 2020-07-13 12:00 UTC onward, the BitMax.io website, the Andriod App, and the iOS App will be showing displayName (BTCUSDT) instead of symbol (BTC-PERP) as indicated in the response body of this API. This is for display purposes only. API users should continue to use symbol (BTC-PERP) to make API calls and to parse RESTful responses and WebSocket messages from the server.

Bar Info

Request

curl -X GET https://bitmax.io/pro/v1/barhist/info

Sample response

{
    "code": 0,
    "data": [
        {
            "name": "1",
            "intervalInMillis": 60000
        },
        {
            "name": "5",
            "intervalInMillis": 300000
        },
        {
            "name": "15",
            "intervalInMillis": 900000
        },
        {
            "name": "30",
            "intervalInMillis": 1800000
        },
        {
            "name": "60",
            "intervalInMillis": 3600000
        },
        {
            "name": "120",
            "intervalInMillis": 7200000
        },
        {
            "name": "240",
            "intervalInMillis": 14400000
        },
        {
            "name": "360",
            "intervalInMillis": 21600000
        },
        {
            "name": "720",
            "intervalInMillis": 43200000
        },
        {
            "name": "1d",
            "intervalInMillis": 86400000
        },
        {
            "name": "1w",
            "intervalInMillis": 604800000
        },
        {
            "name": "1m",
            "intervalInMillis": 2592000000
        }
    ]
}

HTTP Request

GET /api/pro/v1/barhist/info

This API returns a list of all bar intervals supported by the server.

Request Parameters

This API endpoint does not take any parameters.

Resposne

Name	Type	Description
`name`	`String`	name of the interval
`intervalInMillis`	`Long`	length of the interval

Plesae note that the one-month bar (1m) always resets at the month start. The intervalInMillis value for the one-month bar is only indicative.

The value in the name field should be your input to the Historical Bar Data API.

Historical Bar Data

Request

curl -X GET https://bitmax.io/api/pro/v1/barhist?symbol=BTC-PERP&interval=1

Sample response

{
  "code": 0,
  "data": [{
      "m": "bar",
      "s": "BTC-PERP",
      "data": {
        "c": "9700.00",
        "h": "9700.00",
        "i": "1",
        "l": "9700.00",
        "o": "9700.00",
        "ts": 1581981600000,
        "v": "0.0000"
      }
    },
    {
      "m": "bar",
      "s": "BTC-PERP",
      "data": {
        "c": "9700.00",
        "h": "9700.00",
        "i": "1",
        "l": "9700.00",
        "o": "9700.00",
        "ts": 1581981660000,
        "v": "0.0000"
      }
    }
  ]
}

HTTP Request

GET /api/pro/v1/barhist

This API returns a list of bars, with each contains the open/close/high/low prices of a symbol for a specific time range.

Request Parameters

Name	Type	Required	Value Range	Description
symbol	`String`	Yes	Contract Symbol	e.g. `"BTC-PERP"`
interval	`String`	Yes		a string representing the interval type.
to	`Long`	No	Timestamp	UTC timestamp in milliseconds. If not provided, this field will be set to the current time.
from	`Long`	No	Timestamp	UTC timestamp in milliseconds.
n	`Int`	No	> 0	default 10, number of bars to be returned, this number will be capped at 500

The requested time range is determined by three parameters - to, from, and n - according to rules below:

from/to each specifies the start timestamp of the first/last bar.
to is always honored. If not provided, this field will be set to the current system time.
For from and to:
- if only from is provided, then the request range is determined by [from, to], inclusive. However, if the range is too wide, the server will increase from so the number of bars in the response won't exceed 500.
- if only n is provided, then the server will return the most recent n data bars to time to. However, if n is greater than 500, only 500 bars will be returned.
- if both from and n are specified, the server will pick one that returns fewer bars.

Response

Name	Type	Description	Sample Value
m	String	message type	`"bar"`
s	String	symbol	`"BTC-PERP"`
data:ts	Long	bar start time in milliseconds	`1581981660000`
data:i	String	interval	`"1"`
data:o	String	open price
data:c	String	close price
data:h	String	high price
data:l	String	low price
data:v	String	volume in quote asset

Code Sample

Please refer python code to [get bar history]{https://github.com/bitmax-exchange/bitmax-futures-api-demo/blob/master/python/query-bar-hist.py}

Ticker

Ticker for one product

// curl -X GET 'https://bitmax.io/api/pro/v1/ticker?symbol=BTC-PERP'
{
    "code": 0,
    "data": {
        "ask": [ "11000", "0.0004" ],
        "bid": [ "9600", "0.012" ],
        "close":  "11000",
        "high":   "11000",
        "low":    "9692.75",
        "open":   "9745",
        "symbol": "BTC-PERP",
        "volume": "0.0152"
    }
}

List of Tickers for one or multiple products

// curl -X GET "https://bitmax.io/api/pro/v1/ticker?symbol=BTC-PERP,"
{
    "code": 0,
    "data": [
        {
            "ask": [ "11000", "0.0004" ],
            "bid": [ "9600", "0.012" ],
            "close":  "11000",
            "high":   "11000",
            "low":    "9692.75",
            "open":   "9745",
            "symbol": "BTC-PERP",
            "volume": "0.0152"
        }
    ]
}

HTTP Request

GET api/pro/v1/ticker

You can get summary statistics of one or multiple symbols with this API.

Request Parameters

Name	Type	Required	Value Range	Description
`symbol`	`String`	No		you may specify one, multiple, or all symbols of interest. See below.

This API endpoint accepts one optional string field symbol:

If you do not specify symbol, the API will responde with tickers of all symbols in a list.
If you set symbol to be a single symbol, such as BTC-PERP, the API will respond with the ticker of the target symbol as an object. If you want to wrap the object in a one-element list, append a comma to the symbol, e.g. BTC-PERP,.
(Not supported yet) You shall specify symbol as a comma separated symbol list, e.g. BTC-PERP,ETH-PERP. The API will respond with a list of tickers.

Respond Content

The API will respond with a ticker object or a list of ticker objects, depending on how you set the symbol parameter.

Each ticker object contains the following fields:

Field	Type	Description
`symbol`	`String`
`open`	`String`	the traded price 24 hour ago
`close`	`String`	the last traded price
`high`	`String`	the highest price over the past 24 hours
`low`	`String`	the lowest price over the past 24 hours
`volume`	`String`	the total traded volume in quote asset over the paste 24 hours
`ask`	`[String, String]`	the price and size at the current best ask level
`bid`	`[String, String]`	the price and size at the current best bid level

Code Sample

Please refer to python code to [query ticker info]{https://github.com/bitmax-exchange/bitmax-pro-api-demo/blob/master/python/query_pub_ticker.py}

Market Trades

Request

curl -X GET /api/pro/v1/trades?symbol=BTC-PERP

Sample response

{
  "code": 0,
  "data": {
    "m": "trades",
    "symbol": "BTC-PERP",
    "data": [{
        "bm": true,
        "p": "9800",
        "q": "0.0006",
        "seqnum": 180143985094828828,
        "ts": 1581955026966
      },
      {
        "bm": true,
        "p": "9700",
        "q": "0.00310",
        "seqnum": 180143985094828975,
        "ts": 1581957024856
      }
    ]
  }
}

HTTP Request

GET /api/pro/v1/trades

Request Parameters

Name	Type	Required	Value Range	Description
`symbol`	String	Yes	Valid symbol supported by exchange
`n`	Int	No	any positive integer, capped at 100	number of trades to return.

Response Content

data field in response contains trade data and meta info.

Trade record information in data:

Name	Type	Description
`seqnum`	`Long`	the sequence number of the trade record. `seqnum` is always increasing for each symbol, but may not be consecutive
`p`	`String`	trade price in string format
`q`	`String`	trade size in string format
`ts`	`Long`	UTC timestamp in milliseconds
`bm`	`Boolean`	If true, the maker of the trade is the buyer.

Code Sample

Please refer to python code to [query trades]{https://github.com/bitmax-exchange/bitmax-futures-api-demo/blob/master/python/query-trades.py}

Reference Prices

Reference Prices for Futures Collateral Assets

curl -X GET https://bitmax.io/api/pro/v1/futures/ref-px

Permissions

This API is public.

HTTP Request

GET /api/pro/v1/futures/ref-px

Futures Market Data

Futures Market Data for one Contract

# if only one symbol is provided, the API will respond with a single object
curl -X GET https://bitmax.io/api/pro/futures/market-data?symbol=BTC-PERP

Sample Resonse

{
  "code": 0,
  "data": {
    "symbol":                 "BTC-PERP",
    "openInterest":           "9000",
    "sourceTime":             1579876668235,
    "fundingRate":            "0.001",
    "fundingPaymentFlag":     false,
    "nextFundingPaymentTime": 1579874400000,
    "indexPrice":             "8495.01",
    "markPrice":              "8493.50"
  }
}

Futures Market Data for one or multiple Contracts

# Appending a comma (,) and the API will respond with a list of one or more objects
curl -X GET https://bitmax.io/futures/market-data?symbol=BTC-PERP,

Sample Resonse

{
  "code": 0,
  "data": [
    {
      "symbol":                 "BTC-PERP",
      "openInterest":           "9000",
      "sourceTime":             1579876668235,
      "fundingRate":            "0.001",
      "fundingPaymentFlag":     false,
      "nextFundingPaymentTime": 1579874400000,
      "indexPrice":             "8495.01",
      "markPrice":              "8493.50"
    }
  ]
}

Permissions

This API is public.

HTTP Request

GET /api/pro/v1/futures/market-data

Request Parameters

Name	Type	Required	Value Range	Description
symbol	`String`	No	symbols separated by comma

By default, the API returns data for all contracts traded on the exchange. You can provide an optional parameter symbol to taylor the result to a specific subset of contracts.

In most cases, this API will return a list of objects. However, it you set symbol to a single contract, such as symbol=BTC-PERP, the API will return the object itself instead. If you want the response to alaways be a list of objects, append a comma (e.g. symbol=BTC-PERP,).

Response Content

Name	Type	Description	Sample Value
symbol	`String`	Contract symbol	`"BTC-PERP"`
openInterest	`String`	Open interest	`"9000"`
sourceTime	`Long`	UTC timestamp when market data is generated	`1579876668235`
fundingRate	`String`	Current funding rate	`"0.01"`
fundingPaymentFlag	`Boolean`		`false`
nextFundingPaymentTime	`Long`	UTC timestamp of the next timestamp	`1579874400000`
indexPrice	`String`	the index price	`"8495.01"`
markPrice	`String`	the mark price	`"8493.50"`

Futures Funding Rates

Futures Funding Rates

curl -X GET https://bitmax.io/api/pro/v1/futures/funding-rates

{
    "code": 0,
    "data": {
        "page":     1,
        "pageSize": 20,
        "hasNext":  true,    
        "data": [
            {
              "timestamp":    1578182100000,
              "symbol":      "BTC-PERP",
              "fundingRate": "0.001"
            },
            {
              "timestamp":    1578181800000,
              "symbol":      "BTC-PERP",
              "fundingRate": "0.001"
            },
            ...
        ]
    }
}

Permissions

This API is public.

HTTP Request

GET /api/pro/v1/futures/funding-rates

Response Content

Name	Type	Description
timestamp	`Long`
symbol	`String`
fundingRate	`String`

Private Data

Account Info

Account Info - Sample response:

{
    "code": 0,
    "data": {
        "accountGroup": 0,
        "email": "yyzzxxz@email.com",
        "futuresAccount": [
            "fut1FfjKA3W1L7XZOipGKZNFBb34GRQ3"
        ],
        "tradePermission": true,
        "viewPermission":  true,
        "userUID":         "U0866943712"
    }
}

Permissions

This API doesn't need any permission to access.

HTTP Request

GET /api/pro/v1/info

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+info

Obtain the account information.

You can obtain your accountGroup from this API, which you will need to include in the URL for all your private RESTful requests.

Response Content

Name	Type	Description
accountGroup	`Int`	non-negative integer
email	`String`
futuresAccount	`List[String]`	contains a list of your futures accounts. At the moment, the list should contain exactly one element.
viewPermission	`Boolean`
tradePermission	`Boolean`
transferPermission	`Boolean`
userUID	`String`	an unique id associated with user

You will need accountGroup to access most private APIs. It never changes value for each account.

Collateral Balance

Futures Collateral Balance

{
  "code": 0,
  "data": [
    {
      "asset":            "BTC",
      "totalBalance":     "0",
      "availableBalance": "0",
      "maxTransferrable": "0",
      "priceInUSDT":      "8455.705"
    },
    {
      "asset":            "USDT",
      "totalBalance":     "0",
      "availableBalance": "0",
      "maxTransferrable": "0",
      "priceInUSDT":      "1"
    }
  ]
}

Permissions

You need view permission to access this API.

HTTP Request

GET <account-group>/api/pro/v1/futures/collateral-balance

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+futures/collateral-balance

Request Parameters

You don't need to specify any parameter for this API.

Response Content

Name	Type	Description	Sample Response
asset	`String`	asset code	`"USDT"`
totalBalance	`String`	total balance	`"0"`
availableBalance	`String`	available balance	`"0"`
maxTransferrable	`String`	maximum transferrable amount	`"0"`
priceInUSDT	`String`	reference price in USDT	`"1"`

Code Sample

Please refer to python code to query funding payments

Contract Position

Contract Position

{
    "code": 0,
    "data": [
        {
            "symbol":              "BTC-PERP",
            "position":            "0.0012",
            "positionNotional":    "9.392250374",
            "breakevenPrice":      "7921.3512875",
            "estLiquidationPrice": "7075.175014796",
            "positionPnl":         "-0.11337117",
            "collateralInUse":     "12.194125037",
            "maxBuyOrderSize":     "0.000225911",
            "maxSellOrderSize":    "0.016837925",
            "maxBuyNotional":      "1.768180713",
            "maxSellNotional":     "131.788346455",
            "indexPrice":          "7818.4225",
            "markPrice":           "7826.875312457"
        }
    ]
}

Permissions

You need view permission to access this API.

HTTP Request

GET <account-group>/api/pro/futures/position

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+futures/position

Request Parameters

You don't need to specify any parameter for this API.

Response Content (Current)

Name	Type	Description	Sample Response
symbol	`String`	contract symbol	`"BTC-PERP"`
breakevenPrice	`String`	break-even price	`"12805.265370586"`
estLiquidationPrice	`String`	estimated liquidation price	`"16365.898288993"`
collateralInUse	`String`	collateral in Use (in USDT)	`"1350.314802427"`
maxBuyOrderSize	`String`	maximum quantity allowed to buy (deprecated, use maxBuyNotional)	`"44.612137464"`
maxSellOrderSize	`String`	maximum quantity allowed to sell (deprecated, use maxSellNotional)	`"38.962207464"`
maxBuyNotional	`String`	maximum notional allowed to buy	`"44.612137464"`
maxSellNotional	`String`	maximum notional allowed to sell	`"38.962207464"`
position	`String`	contract position	`"-2.8535"`
positionNotional	`String`	contract position notional value in USDT	`"-27006.296048541"`
positionPnl	`String`	contract position profit/loss in USDT	`"9533.528686427"`
indexPrice	`String`	underlying index price	`"7818.4225"`
markPrice	`String`	contract mark price	`"7826.875312457"`

Code Sample

Please refer to python code to query funding payments

Account Risk Profile

Account Risk Profile

{
  "code": 0,
  "data": {
    "accountMarginRate":              "16.606386637",
    "accountValue":                   "13117.362712384",
    "accountMaxLeverage":             "20",
    "collateral":                     "12810.31775",
    "collateralInUse":                "38.570454939",
    "effectiveCollateral":            "12810.31775",
    "freeCollateral":                 "12771.74729506",
    "currentLeverage":                "0.060217795",
    "effectiveInitialMarginRate":     "0.05",
    "effectiveMaintenanceMarginRate": "0.006",
    "effectivePositionNotional":      "771.409098784",
    "positionNotional":               "771.409098784",
    "unsettledPnl":                   "137.126662384",
    "settledPnl":                     "0",
    "unrealizedPnlTotal":             "137.126662384",
    "takeoverMarginRate":             "0.003",
    "walletBalance":                  "12980.23605"
  }
}

You can obtain the status of the overall account from this API.

Permissions

You need view permission to access this API.

HTTP Request

GET <account-group>/api/pro/futures/risk

Response Content

Name	Type	Description
accountMarginRate	`String`	account marging rate
accountValue	`String`	account value
accountMaxLeverage	`String`	account maximum leverage
currentLeverage	`String`	account current leverage
effectiveInitialMarginRate	`String`
effectiveMaintenanceMarginRate	`String`
takeoverMarginRate	`String`	the minimum margin rate an account must be above to avoid been taking over
walletBalance	`String`	total USDT value of all collaterals
collateral	`String`	account total collateral value in USDT
collateralInUse	`String`	amount of collateral already in use
effectiveCollateral	`String`
freeCollateral	`String`
positionNotional	`String`
effectivePositionNotional	`String`
unsettledPnl	`String`	unsettled PnL that will be rolled into settled PnL.
settledPnl	`String`	settled profit/loss (PnL)

Collateral

You can only increase your exposure if have free collateral. You shall post more collaterals by depositing one or more collateral assets to you account.

Funding Payment History

Funding Payment History

{
  "code": 0,
  "data": {
    "data": [
      {
        "fundingRate":   "0.001",
        "paymentInUSDT": "26.800171872",
        "symbol":        "BTC-PERP",
        "timestamp":     1580328000000
      },
      {
        "fundingRate":   "-0.001",
        "paymentInUSDT": "-26.740689873",
        "symbol":        "BTC-PERP",
        "timestamp":     1580324400000
      }
    ],
    "hasNext":  false,
    "page":     1,
    "pageSize": 20
  }
}

Permissions

You need view permission to access this API.

HTTP Request

GET <account-group>/api/pro/v1/futures/funding-payments

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+futures/funding-payments

Request Parameters

Name	Type	Required	Value Range
symbol	`String`	No	symbols separated by comma
page	`Int`	No	zero or positive integer
pageSize	`Int`	No	positive integer

Response Content

The response contains a list of funding payment records along with meta data for the pagination.

Each funding payment record contains the following fields:

Name	Type	Description	Sample Response
fundingRate	`String`	funding rate applied	`"0.001"`
paymentInUSDT	`String`	funding payment in USDT	`"26.800171872"`
symbol	`String`	contract symbol	`"BTC-PERP"`
timestamp	`Long`	UTC Timestamp in milliseconds	`1580328000000`

Code Sample

Please refer to python code to query funding payments

Wallet Transaction History

Wallet Transaction History

{
  "code": 0,
  "data": {
    "data": [
      {
        "asset":                "USDT",
        "requestId":            "pliWaJuGmkIXfMP72VfFDp653WoNqNGc",
        "amount":               "500",
        "commission":           "0",
        "destAddress":          {"address": "0x19hKDKfziX6kdWv0jlwiiuDy8VKZfgpEem8CvBxW"},
        "networkTransactionId": "0xSeBSYwTBxPEvX8rfMrjbd0XPRZjwhMbKBURVyGLsGa8ZoI1hUb4X8Z7G89lc7xKm",
        "numConfirmations":     20,
        "numConfirmed":         20,
        "status":               "confirmed",
        "time":                 1580657103000,
        "transactionType":      "deposit"
      }
    ],
    "page"    : 1,
    "pageSize": 20,
    "hasNext" : false
  }
}

You can obtain history of wallet deposit/withdrawal transactions via this API.

Permissions

You need view permission to access this API.

HTTP Request

GET /api/pro/v1/wallet/transactions

You don't need to specify <account-group> for this API.

Request Parameters

You can specify the following parameters:

Name	Type	Default	Description
asset	`Optional[Int]`	Null	asset code
page	`Optional[Int]`	1	page number, must be greater than 0.
pageSize	`Optional[Int]`	20	page size, must be greater than 0.
startTs	`Optional[Long]`	Time.Min	start of the query range, UTC timestamp in milliseconds
endTs	`Optional[Long]`	Time.Max	end of the query range, UTC timestamp in milliseconds
txType	`Optional[String]`	Null	the transaction type filter: `deposit` / `withdrawal`

Response Content

The data field of the API response contains the paginated historical data. All records are sorted in reverse chronological order.

Name	Type	Description
page	`Int`	page number, must be greater than 0.
pageSize	`Int`	page size, must be greater than 0.
hasNext	`Boolean`	if True, there are more records to show
data	`List[Object]`	a list of transaction records. See below for details

Each transaction record contains the following fields:

Name	Type	Description
asset	`String`	asset code
requestId	`String`	an unique identifier for the transaction
amount	`String`	amount in transaction
commission	`String`	commission charged
destAddress	`Object`	destination address ID, it usually contains an `address` field and an optional `destTag` field
networkTransactionId	`String`	the id/hash of the transaction, for transactions among exchange users, this field is "-"
numConfirmations	`Int`	deposit will be viewd as final after the number of blocks confirmed reaches this value
numConfirmed	`Int`	currently number of blocks confirmed
status	`String`	reviewing / pending / confirmed / rejected
time	`Long`	UTC Timestamp in milliseconds
transactionType	`String`	deposit / withdrawal

Transfer Funds between Accounts

From Cash to Futures Account

Request Body - Transfer Fund from Cash to Futures Account

// URL https://bitmax.io/0/api/pro/v1/futures/transfer/deposit 
{
    "asset": "ETH",
    "amount": "1"
}

Sample response if the transfer was successful

{
    "code": 0
}

Sample response if the transfer failed

{
    "code": 300011,
    "message": "Not Enough Account Balance",
    "reason": "INVALID_BALANCE"
}

Permissions

You need transfer permission to access this API.

HTTP Request

POST /<account-group>/api/pro/v1/futures/transfer/deposit

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+futures/transfer/deposit

HTTP Request Body

The request body must be a JSON string with the following fields:

Name	Type	Description
asset	`String`	asset to transfer
amount	`String`	amount to transfer

Response

If the transfer request succeeded, the API will respond with a simple object with code=0. If the transfer request failed, the API will respond with code other than 0 along with an error message.

From Futures to Cash Account

Request Body - Transfer Fund from Futures to Cash Account

// URL https://bitmax.io/0/api/pro/v1/futures/transfer/withdraw
{
    "asset": "ETH",
    "amount": "1"
}

Sample response if the transfer was successful

{
    "code": 0
}

Sample response if the transfer failed

{
    "code": 300011,
    "message": "Not Enough Account Balance",
    "reason": "INVALID_BALANCE"
}

Permissions

You need transfer permission to access this API.

HTTP Request

POST /<account-group>/api/pro/v1/futures/transfer/withdraw

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+futures/transfer/withdraw

HTTP Request Body

The request body must be a JSON string with the following fields:

Name	Type	Description
asset	`String`	asset to transfer
amount	`String`	amount to transfer

Response

If the transfer request succeeded, the API will respond with a simple object with code=0. If the transfer request failed, the API will respond with code other than 0 along with an error message.

Order

Place an Order

Place Order - Successful ACK Response (Status 200, code 0)

{
    "code": 0,
    "data": {
        "ac":        "FUTURES",
        "accountId": "fut1FfjKA3W1L7XZOipGKZNFBb34GRQ3",
        "action":    "place-order",
        "info": {
            "id":        "16e607e2b83a8bXHbAwwoqDo55c166fa",
            "orderId":   "16e85b4d9b9a8bXHbAwwoqDoc3d66830",
            "orderType": "Market",
            "symbol":    "BTC-PERP",
            "timestamp":  1573576916201
        },
        "status": "Ack"
    }
}

Place Order with ACCEPT respInst

{
    "id":         "iGwzbzWxxcHwno4b8VCvh8aaYCJaPALm", 
    "time":       1575403713964, 
    "symbol":     "BTC-PERP", 
    "orderPrice": "7289.0", 
    "orderQty":   "0.00082", 
    "orderType":  "limit", 
    "side":       "sell", 
    "respInst":   "ACCEPT"
}

Successful ACCEPT Response (Status 200, code 0)

{
    "code": 0,
    "data": {
        "ac":        "FUTURES",
        "accountId": "fut1FfjKA3W1L7XZOipGKZNFBb34GRQ3",
        "action":    "place-order",          
        "info": {            
            "avgPx":        "0",
            "cumFee":       "0",
            "cumFilledQty": "0",
            "errorCode":    "",
            "feeAsset":     "USDT",
            "lastExecTime": 1575573998500,
            "orderId":      "a16ed787462fU9490877774N4KBHIVN0",
            "orderQty":     "0.1",
            "orderType":    "Limit",
            "price":        "7019",
            "seqNum":       2323407894,
            "side":         "Buy",
            "status":       "New",
            "stopPrice":    "",
            "symbol":       "BTC-PERP",
            "execInst":     "NULL_VAL"
        },
        "status": "ACCEPT"
    }
}

Place Order with DONE respInst

{
    "id":        "UHTe3uVB0KhNGatoRS10YgABwHW0fCYn", 
    "time":      1575348906131, 
    "symbol":    "BTC-PERP",
    "orderQty":  "0.00082", 
    "orderType": "market", 
    "side":      "buy", 
    "respInst":  "DONE"
}

Successful DONE Response (Status 200, code 0)

{"code": 0,
 "data": {
    "ac":        "FUTURES",
    "accountId": "MPXFNEYEJIJ93CREXT3LTCIDIJPCFNIX",
    "action":    "place-order",
    "info": {
        "avgPx":        "7399.99",
        "cumFee":       "0.003296696",
        "cumFilledQty": "0.1",
        "errorCode":    "",
        "feeAsset":     "USDT",
        "id":           "ROunD0hpprO2KEgkVK30FOIpPK3zuGGh",
        "lastExecTime": 1575646514077,
        "orderId":      "a16edbd9aefaU9490877774pPK3zuGGh",
        "orderQty":     "0.1",
        "orderType":    "Market",
        "price":        "",
        "seqNum":       2348421435,
        "side":         "Sell",
        "status":       "Filled",
        "stopPrice":    "",
        "symbol":       "BTC-PERP",
        "execInst":     "NULL_VAL"
    },
    "status": "DONE"}}

Place Order - Error Response (Status 200, code 300011)

{
    "code":      300011,
    "ac":        "FUTURES",
    "accountId": "fut1FfjKA3W1L7XZOipGKZNFBb34GRQ3",
    "action":    "place-order",
    "message":   "Not Enough Account Balance",
    "reason":    "INVALID_BALANCE",
    "status":    "Err",
    "info": {
        "id":     "JkpnjJRuBtFpW7F7PWDB7uwBEJtUOISZ", 
        "symbol": "BTC-PERP"
    }
}

Place a new order.

Permissions

You need trade permission to access this API.

HTTP Request

POST <account-group>/api/pro/v1/futures/order

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order

Request Parameters

Name	Type	Required	Value Range	Description
symbol	String	Yes
time	Long	Yes	milliseconds since UNIX epoch in UTC	We do not process request placed more than 30 seconds ago.
orderQty	String	Yes		Order size. Please set scale properly for each symbol.
orderType	String	Yes	["market", "limit"]	Order type
side	String	Yes	["buy", "sell"]
id	String	No	>=9 chars(letter and digit number only)	Optional but recommended. We echo it back to help you match response with request.
orderPrice	String	No		The limit price for limit order. Please set price scale properly.
stopPrice	String	No		Trigger price of stop limit order
postOnly	Boolean	No	[true, false]
timeInForce	String	No	["GTC", "IOC"]	GTC: good-till-canceled; IOC: immediate-or-cancel. GTC by default.
respInst	String	No	["ACK", "ACCEPT", "DONE"]	Response instruction. Refer to "Response" below. "ACK" by default.

The table below shows how to correctly configure order of different types: (o - required, x - optional)

Name	Market	Limit	StopMarket	StopLimit
id	x	x	x	x
time	o	o	o	o
symbol	o	o	o	o
orderPrice		o		o
orderQty	o	o	o	o
orderType	o	o	o	o
side	o	o	o	o
postOnly		x
stopPrice			o	o
timeInForce		x

Order Request Criteria

When placing a new limit order, the request parameters must meet all criteria defined in the Products API:

The order notional must be within range [minNotional, maxNotional]. For limit orders, the order notional is defined as the product of orderPrice and orderQty.
orderPrice and stopPrice must be multiples of tickSize.
orderQty must be a multiple of lotSize.

Response

In "Err" response, id is the id provided by user when placing order; for other responses, orderId is the id generated by server following "Order id generation method" above, and this is the id you should provide for future order query or cancel.

In case you want to cancel an order before response from server, you could figure out the orderId following Order id generation method above.

ACK

Response with 0 code and status Ack to indicate new order request received by our server and passed some basic order field check. This is the default response type. If awaiting async order (ACCEPT or DONE) numbers exceeds capacity 1000, then the rest async order will be ACK automatically.

data schema:

Name	Type	Description
avgPx	`String`	average fill price
cumFee	`String`	cumulated filled comission
cumFilledQty	`String`	cumulated filled qty
errorCode	`String`	Could be empty
feeAsset	`String`	Fee asset, e.g, `USDT`
id	`String`	id from request
lastExecTime	`String`	latest execution timestamp
orderId	`String`	order id
orderQty	`String`	order quantity
orderType	`String`	order type
price	`String`	order price
seqNum	`Long`	sequence number
side	`String`	order side
status	`String`	order status
stopPrice	`String`	stop price(could be empty)
symbol	`String`	symbol
execInst	`String`	execution instruction, `POST` for Post-Only orders, `Liquidation` for forced-liquidation orders, and `NULL_VAL` otherwise.

ACCEPT

Response with 0 code and status ACCEPT to indicate new order request is accepted by our match engine. Return normal 'Ack' response if no 'New' status update within 5 seconds. Order status in data could be New, or PendingNew.

DONE

Response with 0 code and status Done to indicate the order request is partially filled, fully filled, or rejected by matching engine. Return normal 'Ack' response if no order status update within 5 seconds. Order status in data could be Filled, PartiallyFilled, Cancelled, or Reject, and so on.

ERR

Response with code other than 0 and status Err to provide detailed error information on the order request.

Name	Type	Description
code	`Long`	non-zero value to indicate error
ac	`String`	`FUTURES`
accountId	`String`	account id
action	`String`	`place-order`
message	`String`	detail error message
reason	`String`	error info code, e.g. "INVALID_ORDER_ID"
status	`String`	"Err"
info	`Json`	See below for details

info schema:

Name	Type	Description
symbol	`String`	symbol
id	`String`	id from request if provided

Cancel an Order

Cancel Order - Successful ACK Response (Status 200, code 0)

{
    "code": 0,
    "data": {
        "accountId": "fut1FfjKA3W1L7XZOipGKZNFBb34GRQ3",
        "ac": "CASH",
        "action": "cancel-order",
        "status": "Ack",
        "info": {
            "id":        "sPWweX8baCYeFsKdmqZEmHdpliWaJuGm",
            "orderId":   "kIXfMP72VfFDp653WoNqNGcpZCK9W7ts",
            "orderType": "", // could be empty
            "symbol":    "BTC-PERP",
            "timestamp":  1573596082932
        }
    }
}

Cancel Order - Error Response (Status 200, code 0)

{
    "code": 300006,
    "accountId": "fut1FfjKA3W1L7XZOipGKZNFBb34GRQ3",
    "ac": "CASH",
    "action": "cancel-order",
    "status": "Err",
    "message": "Invalid Client Order Id: ku30AehuWoHzMeyGEAS8heeDXpb1heOS",
    "reason":  "INVALID_ORDER_ID",
    "info": {
        "id": "ku30AehuWoHzMeyGEAS8heeDXpb1heOS",
        "symbol":  "BTC-PERP"
    }
}

Cancel an existing open order.

Permissions

You need trade permission to access this API.

HTTP Request

DELETE <account-group>/api/pro/v1/futures/order

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order

Request Parameters

Name	Type	Required	Value Range	Description
id	String	Yes	32 chars(letter and digit number only)	Please generate unique ID for each trade; we will echo it back to help you identify the response.
orderId	String	Yes	32 chars order id responded by server when place order
symbol	String	Yes
time	Long	Yes	milliseconds since UNIX epoch in UTC	We do not process request placed more than 30 seconds ago.

Response

ACK

Response with status "Ack" to indicate the cancel order request is received by server. And you should use provided "orderId" to check cancel status in the future; we also echo back id from your request for reference purpose.

ERR

Response with status "Err" to indicate there is something wrong with the cancel order request. We echo back the coid field in your request.

Place Batch Orders

Place Batch Orders - Request Body

{
    "orders": [
        {
            "id"         : "ygpBSzn1ZKOGDQqwhwi9Jo0QWhMJIi4e",
            "orderPrice" : "6000",
            "orderQty"   : "1",
            "orderType"  : "limit",
            "side"       : "buy",
            "symbol"     : "BTC-PERP",
            "time"       : 1582140876351,
            "timeInForce": "GTC"
        },
        {
            "id"         : "FhvyPfmwUZjS4qFfPeABbgAnHmaUnphA",
            "orderPrice" : "5000",
            "orderQty"   : "1",
            "orderType"  : "limit",
            "side"       : "buy",
            "symbol"     : "BTC-PERP",
            "time"       : 1582140876351,
            "timeInForce": "GTC"
        }
    ]
}

Place Batch Orders - Successful ACK Response (Status 200, code 0)

{
    "code": 0,
    "data": {
        "ac": "FUTURES",
        "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
        "action": "batch-place-order",
        "info": [
            {
                "id"       : "ygpBSzn1ZKOGDQqwhwi9Jo0QWhMJIi4e",
                "orderId"  : "a1705ef9d2a25362614103sdUuPlzMW",
                "orderType": "Limit",
                "symbol"   : "BTC-PERP",
                "timestamp": 1582141396352
            },
            {
                "id"       : "FhvyPfmwUZjS4qFfPeABbgAnHmaUnphA",
                "orderId"  : "a1705ef9d2a25362614103Pf0MooywV",
                "orderType": "Limit",
                "symbol"   : "BTC-PERP",
                "timestamp": 1582141396361
            }
        ],
        "status": "Ack"
    }
}

Place Batch Orders - Error Response (Status 200, code 0)

{
    "ac": "FUTURES",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "action": "batch-place-order",
    "code": 300013,
    "info": [
        {
            "code"   : 300013,
            "id"     : "ygpBSzn1ZKOGDQqwhwi9Jo0QWhMJIi4e",
            "message": "Some invalid order in this batch.",
            "reason" : "INVALID_BATCH_ORDER",
            "symbol" : "BTC-PERP"
        },
        {
            "code"   : 300001,
            "id"     : "FhvyPfmwUZjS4qFfPeABbgAnHmaUnphA",
            "message": "Price is too low from market price.",
            "reason" : "INVALID_PRICE",
            "symbol" : "BTC-PERP"
        }
    ],
    "message": "Batch Order failed, please check each order info for detail.",
    "reason": "INVALID_BATCH_ORDER",
    "status": "Err"
}

Place multiple orders in a batch. If some order in the batch failed our basic check, then the whole batch request fail.

You may submit up to 10 orders at a time. Server will respond with error if you submit more than 10 orders.

HTTP Request

POST <account-group>/api/pro/v1/futures/order/batch

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order/batch

Response

ACK

0 for code and status Ack to indicate the batch order request is accepted by server. Field "info" includes server generated "order id" for each order in the batch request, and this is the id you should use for future status query.

data schema:

Name	Type	Description
`ac`	`String`	`FUTURES`
`accountId`	`String`	account Id
`action`	`String`	`batch-place-order`
`status`	`String`	`Ack`
`info`	`List`	See below for detail

info schema:

Name	Type	Description
`id`	`String`	echo back the `id` in request
`orderId`	`String`	server assigned order Id for this single order
`orderType`	`String`	order type
`symbol`	`String`	`symbol` in request
`timestamp`	`Long`	server received timestamp

ERR

Non 0 code and status ERR to indicate the batch order request is accepted by server. Field info includes detailed order information to explain why the batch request fail for each individual order. "order id" is original order id provided by user for each order.

Error schema

Name	Type	Description
`code`	`Long`	0
`ac`	`String`	`FUTURES`
`accountId`	`String`	account Id
`action`	`String`	`batch-place-order`
`message`	`String`	error message detail
`reason`	`String`	short error message
`status`	`String`	`Err`
`info`	`List`	See below for detail

info schema:

Name	Type	Description
`code`	`Long`	0
`id`	`String`	echo `id` in request
`orderId`	`String`	empty
`message`	`String`	error message detail
`reason`	`String`	short error message
`symbol`	`String`	symbol in order

Code Sample

Please refer to python code to place batch order

Cancel Batch Orders

Cancel Batch Orders - Request Body

{
    "orders": [
        {
            "orderId": "a1705f147f715362614103eMn3z3tpi",
            "symbol": "BTC-PERP",
            "time": 1582143186943
        },
        {
            "orderId": "a1705f147f715362614103tKdqi2kfP",
            "symbol": "BTC-PERP",
            "time": 1582143186943
        }
    ]
}

Cancel Batch Orders - Successful ACK Response (Status 200, code 0)

{
    "code": 0,
    "data": {
        "ac": "CASH",
        "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
        "action": "batch-cancel-order",
        "status": "Ack",
        "info": [
            {
                "id":        "0a8bXHbAwwoqDo3b485d7ea0b09c2cd8",
                "orderId":   "16e61d5ff43s8bXHbAwwoqDo9d817339",
                "orderType": "NULL_VAL",
                "symbol":    "BTC/USDT",
                "timestamp":  1573619097746
            },
            {
                "id":        "0a8bXHbAwwoqDo7d303e2edf6c26d1be",
                "orderId":   "16e61adeee5a8bXHbAwwoqDo100e364e",
                "orderType": "NULL_VAL",
                "symbol":    "ETH/USDT",
                "timestamp":  1573619098342
            }
        ]
    }
}

Cancel Batch Orders - Error Response (Status 200, code 0)

{
    "code": 300013,
    "ac": "CASH",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "action": "batch-place-order", 
    "message": "Batch Order failed, please check each order info for detail.",
    "reason": "INVALID_BATCH_ORDER",
    "status": "Err", 
    "info": [
        {
            "code":     300006,
            "id":      "NUty15oXcNt9JAngZ1D6q6jY15LOpKPC",
            "orderId": "16e61d5ff43s8bXHbAwwoqDo9d817339",
            "message": "The order is already filled or canceled.",
            "reason":  "INVALID_ORDER_ID",
            "symbol":   ""
        },
        {
            "code":     300006,
            "id":      "mpoL0q8cheL8PL2UstJFRzp6yuPk1sGc",
            "orderId": "16e61adeee5a8bXHbAwwoqDo100e364e",
            "message": "The order is already filled or canceled.",
            "reason":  "INVALID_ORDER_ID",
            "symbol":   ""
        }
    ]
}

Cancel multiple orders in a batch. If some order in the batch failed our basic check, then the whole batch request failed.

HTTP Request

DELETE <account-group>/api/pro/v1/futures/order/batch

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order/batch

Response

ACK

Response with code as 0 to indicate batch is successfuly received by server and pass some basic check. data field explains order ack detail. Order detail for each order is in info field list.

data schema:

Name	Type	Description
`ac`	`String`	`CASH`, `MARGIN`
`accountId`	`String`	account Id
`action`	`String`	`cancel-all`
`status`	`String`	`Ack`
`info`	`List`	See below for detail

info schema:

Name	Type	Description
`id`	`String`	echo back the `id` in request
`orderId`	`String`	orderId in request to cancel
`orderType`	`String`	empty
`symbol`	`String`	`symbol` in request
`timestamp`	`Long`	server received timestamp

ERR

Response with non 0 code and status "Err" to explain detailed failure reason for each order in the batch request. Error detail for each order is in info field.

Error schema

Name	Type	Description
`code`	`Long`	0
`ac`	`String`	`CASH`, `MARGIN`
`accountId`	`String`	account Id
`action`	`String`	`batch-cancel-order`
`message`	`String`	error message detail
`reason`	`String`	short error message
`status`	`String`	`Err`
`info`	`List`	See below for detail

info schema:

Name	Type	Description
`code`	`Long`	0
`id`	`String`	echo `id` in request
`orderId`	`String`	orderId in request to cancel
`message`	`String`	error message detail
`reason`	`String`	short error message
`symbol`	`String`	symbol in order

Code Sample

please refer to python code to cancel batch order

Cancel All Orders

Cancel All Orders - Successful ACK Response (Status 200, code 0)

{
    "code": 0,
    "data": {
        "ac": "FUTURES",
        "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
        "action": "cancel-all",
        "info": {
            "id": "",
            "orderId": "",
            "orderType": "NULL_VAL",
            "symbol": "",
            "timestamp": 1582144746160
        },
        "status": "Ack"
    }
}

Cancel all current open orders for the account specified, and optional symbol.

HTTP Request

DELETE <account-group>/api/pro/v1/futures/order/all

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order/all

Request Parameters

Name	Type	Required	Value Range	Description
symbol	String	No	Valid symbol supported by exchange	If provided, only cancel all orders on this symbol; otherwise, cancel all open orders under this account.

Response

Response include code and data, and status Ack (in field data) to indicate cancel all order request is received by server.

data schema:

Name	Type	Description
ac	`String`	`CASH`, `MARGIN`
accountId	`String`	account Id
action	`String`	`cancel-all`,
info	`Json`	See below for detail

info schema:

Name	Type	Description
id	`String`	echo back the `id` in request
orderId	`String`	empty
orderType	`String`	empty
symbol	`String`	`symbol` in request
timestamp	`Long`	server received timestamp

Code Sample

Refer to sample python code to cancel all order

Caveat

The server will process the cancel all request with best effort. Orders sent but un-acked will not be canceled. You should rely on websocket order update messages or the RESTful api to obtain the latest status of each order.

List Open Orders

Open Orders - Successful Response (Status 200, code 0)

{
  "accountCategory": "FUTURES",
  "accountId": "cshQtyfq8XLAA9kcf19h8bXHbAwwoqDo",
  "code": 0,
  "data": [
   {
     "avgPx":         "0",           // Average filled price of the order   
      "cumFee":       "0",           // cumulative fee paid for this order
      "cumFilledQty": "0",           // cumulative filled quantity
      "errorCode":    "",            // error code; could be empty
      "feeAsset":     "USDT",        // fee asset
      "lastExecTime": 1576019723550, //  The last execution time of the order
      "orderId":      "s16ef21882ea0866943712034f36d83", // server provided orderId
      "orderQty":     "0.0083",      // order quantity
      "orderType":    "Limit",       // order type
      "price":        "7105",        // order price
      "seqNum":       8193258,       // sequence number
      "side":         "Buy",         // order side
      "status":       "New",         // order status on matching engine
      "stopPrice":    "",            // only available for stop market and stop limit orders; otherwise empty 
      "symbol":       "BTC-PERP",          
      "execInst":     "NULL_VAL"     // execution instruction
    }
  ]
}

This API returns all current open orders for the account specified.

Permissions

You need view permission to access this API.

HTTP Request

GET <account-group>/api/pro/v1/futures/order/open

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order/open

Response

Return a list of order infomation in data field:

Name	Type	Description
avgPx	`String`	average fill price
cumFee	`String`	cumulated filled comission
cumFilledQty	`String`	cumulated filled qty
errorCode	`String`	Could be empty
feeAsset	`String`	Fee asset, e.g, `USDT`
lastExecTime	`String`	latest execution timestamp
orderId	`String`	order id
orderQty	`String`	order quantity
orderType	`String`	order type
price	`String`	order price
seqNum	`Long`	sequence number
side	`String`	order side
status	`String`	order status
stopPrice	`String`	stop price(could be empty)
symbol	`String`	symbol
execInst	`String`	execution instruction, `POST` for Post-Only orders, `Liquidation` for forced-liquidation orders, and `NULL_VAL` otherwise.

Code Sample

Please refer to python code to get open orders

Change from the previous version:

errorCode is no longer included in the open order response. It is still included in the historical order query response.

Query Order By ID

Query Order with a single order id - Successful Response (Status 200, code 0)

// request: GET <account-group>/api/pro/v1/futures/order/status?orderId=a1707df66b8fU924549015952eXV1Pnc
{
    "ac": "FUTURES",
    "accountId": "futob37bbDKmzK6BDIGzufXCtg0MZk3a",
    "code": 0,
    "data": {
        "symbol":       "BTC-PERP",
        "price":        "9000",
        "orderQty":     "0.001",
        "side":         "Buy",
        "status":       "New",
        "orderType":    "Limit",
        "avgPx":        "0",
        "cumFee":       "0",
        "cumFilledQty": "0",
        "errorCode":    "",
        "execInst":     "NULL_VAL",
        "feeAsset":     "USDT",
        "lastExecTime": 1582661266789,
        "orderId":      "a1707df66b8fU924549015952eXV1Pnc",
        "seqNum":       9327,
        "stopPrice":    ""
    }
}

Query Order with a list of order ids - Successful Response (Status 200, code 0)

// request: GET <account-group>/api/pro/v1/futures/order/status?orderId=a1707df66b8fU924549015952eXV1Pnc,
{
    "ac": "FUTURES",
    "accountId": "futob37bbDKmzK6BDIGzufXCtg0MZk3a",
    "code": 0,
    "data": [
        {
            "symbol":       "BTC-PERP",
            "price":        "9000",
            "orderQty":     "0.001",
            "side":         "Buy",
            "status":       "New",
            "orderType":    "Limit",
            "avgPx":        "0",
            "cumFee":       "0",
            "cumFilledQty": "0",
            "errorCode":    "",
            "execInst":     "NULL_VAL",
            "feeAsset":     "USDT",
            "lastExecTime": 1582661266789,
            "orderId":      "a1707df66b8fU924549015952eXV1Pnc",
            "seqNum":       9327,
            "stopPrice":    ""
        }
    ]
}

Query order status, either open or history order.

HTTP Request

GET <account-group>/api/pro/v1/futures/order/status

Request Parameters

Name	Type	Required	Value Range	Description
orderId	String	Yes	a single order id, or multiple order ids separated by `,`

The API will respond with a list of objects in the data field. Each object in the list contains information of a single order. There's one exception, if you use only a single orderId, the data field of the API response will be simplified to a single object. If you want the API to respond with a list of only one object in this case, add a comma , to the orderId.

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order/status

Response

Name	Type	Description
symbol	`String`	symbol
price	`String`	order price
orderQty	`String`	order quantity
side	`String`	order side
status	`String`	order status
orderType	`String`	order type
avgPx	`String`	average fill price
cumFee	`String`	cumulated filled comission
cumFilledQty	`String`	cumulated filled qty
errorCode	`String`	Could be empty
feeAsset	`String`	Fee asset, e.g, `USDT`
lastExecTime	`String`	latest execution timestamp
orderId	`String`	order id
seqNum	`Long`	sequence number
stopPrice	`String`	stop price(could be empty)
execInst	`String`	execution instruction, `POST` for Post-Only orders, `Liquidation` for forced-liquidation orders, and `NULL_VAL` otherwise.

Code Sample

Please refer to python code to get order status

Historical Orders

List Current History Orders

Current History Orders - Successful Response (Status 200, code 0)

{
    "ac": "CASH",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "code": 0,
    "data": [
        {
            "seqNum":         8159713,
            "symbol":        "BTC/USDT",
            "side":          "Buy",
            "price":         "7967.62",
            "orderQty":      "0.0083",
            "avgPx":         "7243.34",
            "cumFee":        "0.051101764",
            "cumFilledQty":  "0.0083",
            "errorCode":      "",
            "feeAsset":      "USDT",
            "lastExecTime":   1576019215402,
            "orderId":       "s16ef210b1a50866943712bfaf1584b",
            "orderType":     "Market",
            "status":        "Filled",
            "stopPrice":      "",
            "execInst":      "NULL_VAL"
        }
    ]
}

This API returns all current history orders for the account specified. This API will only respond with most recently closed orders cached by the server. To query the full history, please use the Historical Orders API.

HTTP Request

GET <account-group>/api/pro/v1/{account-category}/order/hist/current

Set account-category tocash for cash account and margin for margin account.

Signature

You should sign the message in header as specified in Authenticate a RESTful Request section.

Prehash String

<timestamp>+order/hist/current

Request Parameters

Name	Type	Required	Description
`n`	`Int`	No	maximum number of orders to be included in the response
`symbol`	`String`	No	symbol filter, e.g. `"BTMX/USDT"`
`executedOnly`	`Boolean`	No	if `True`, include orders with non-zero filled quantities only.

Response

Return a list of history orders in "data" field.

WebSocket

Guidelines

General Message Request/Handling Logic from Client Side

Client usually initiate request with op parameter (followed by other required parameters).
Server usually reply message with m value to indicate message topic, e.g., order, depth, auth.
Private data response usually has accountId field, such as order, balance; public data response usually contains symbol field.
Uniquie id parameter is recommended for your request. We will echo it back for you to track the requests. (The only exception is depth-snapshot, we do not include id)

WebSocket Request

WSS <account-group>/api/pro/v1/stream

In order to authorize the session you must include <account-group> in the URL. Without <account-group>, you can only subscribe to public data.

Keep the Connection Alive via Ping/Pong

In order to keep the websocket connection alive, you have two options, detailed below.

Method 1: Responding to Server ping messages

Method 1. keep the connection alive by responding to Server pushed ping message

<<< { "m": "ping", "hp": 3 }  # Server pushed ping message
>>> { "op": "pong" }   # Client responds with pong

If the server doesn't receive any client message after a while, it will send a ping message to the client. Once the ping message is received, the client should promptly send a pong message to the server. If you missed two consecutive ping messages, the session will be disconnected.

Server Ping Message Schema

Name	Type	Description
op	`String`	`ping`
hp	`Int`	health point: when this value decreases to 0, the session will be disconnected.

Method 2: Sending ping messages to Server

Method 2. keep the connection alive by sending ping message to the server

>>> { "op": "ping" }                                      # Client initiated ping message (every 30 seconds)
<<< { "m":"pong", "code":0, "ts":1574260701259, "hp": 2 } # Server responds to client ping

You can also send ping message to the server every 15 seconds to keep the connection alive. The server will stop sending ping message for 30 seconds if a client initiated ping message is received.

Server Pong Message Schema

Name	Type	Description
m	`String`	`pong`
code	`Int`	error code, for the pong mesage, the error code is always 0 (success)
ts	`Long`	server time in UTC miliseconds
hp	`Int`	health point: when this value decreases to 0, the session will be disconnected.

WebSocket Authentication

You must authenticate the websocket session in order to recieve private data and send account specific requests (e.g. placing new orders).

You have two options to authenticate a websocket session.

by adding authentication data in the request header when connecting to websocket.
by sending an op:auth message to the server after you have connected to websocket.

Once you successfully connect to the websocket, you will receive a connected message:

for authenticated websocket session: {"op":"connected","type":"auth"}
for unauthenticated websocket session: {"op":"connected","type":"unauth"}

If the session is disconnected for some reason, you will receive a disconnected message:

{"m":"disconnected","code":100005,"reason":"INVALID_WS_REQUEST_DATA","info":"Session is disconnected due to missing pong message from the client"}

Method 1 - WebSocket Authentication with Request Headers

Authenticate with Headers

# # Install wscat from Node.js if you haven't
# npm install -g wscat  

APIPATH=stream
APIKEY=BclE7dBGbS1AP3VnOuq6s8fJH0fWbH7r
SECRET=fAZcQRUMxj3eX3DreIjFcPiJ9UR3ZTdgIw8mxddvtcDxLoXvdbXJuFQYadUUsF7q
TIMESTAMP=`date +%s%N | cut -c -13`
MESSAGE=$TIMESTAMP+$APIPATH
SIGNATURE=`echo -n $MESSAGE | openssl dgst -sha256 -hmac $SECRET -binary | base64`

wscat -H "x-auth-key: $APIKEY" \
  -H "x-auth-signature: $SIGNATURE" \
  -H "x-auth-timestamp: $TIMESTAMP" \
  -c wss://bitmax.io/1/api/v1/t/stream -w 1 -x '{"op":"sub", "id": "abc123", "ch": "order:futZtmicU8Ls03xldo112uxpICXulxXd"}'

This is similar to the way you authenticate any RESTful request. You need to add the following header fields to the connection request:

x-auth-key
x-auth-timestamp
x-auth-signature

The server will then check if the data is correctly signed before upgrading the connection protocol to WebSocket.

Note that if you specify these header fields, the server will reject the websocket connection request if authentication fails.

Method 2 - WebSocket Authentication by Sending the Auth Message

Authenticate by Sending the auth Message

# # Install wscat from Node.js if you haven't
# npm install -g wscat  

APIPATH=stream
APIKEY=BclE7dBGbS1AP3VnOuq6s8fJH0fWbH7r
SECRET=fAZcQRUMxj3eX3DreIjFcPiJ9UR3ZTdgIw8mxddvtcDxLoXvdbXJuFQYadUUsF7q
TIMESTAMP=`date +%s%N | cut -c -13`
MESSAGE=$TIMESTAMP+$APIPATH
SIGNATURE=`echo -n $MESSAGE | openssl dgst -sha256 -hmac $SECRET -binary | base64`

wscat -c wss://bitmax.io/1/api/pro/stream -w 1 -x "{\"op\":\"auth\", \"id\": \"abc123\", \"t\": $TIMESTAMP, "key": \"$APIKEY\", \"sig\": \"$SIGNATURE\"}"

You can also authenticate a live websocket session by sending an op:auth message to the server.

Name	Type	Required	Description
op	`String`	Yes	`"auth"`
id	`String`	No	optional id field, you may safely skip it
t	`Long`	Yes	UTC timestamp in milliseconds, use this timestamp to generate signature
key	`String`	Yes	your api key
sig	`String`	Yes	the signature is generated by signing `"<timestamp>+stream"`

More comprehensive examples can be found at:

Python for websocket auth

Authentication Response

Auth success message

{  
  "m": "auth",
  "id": "abc123",
  "code": 0
}

Auth error message

{
  "m":"auth",
  "id": "abc123",
  "code": 200006,
  "err": "Unable to find User Account Data"
}

You will receive a message for authentication result after you send authentication request.

Field	Type	Description
m	`String`	`"auth"`
id	`String`	echo back the id if you provide one in the request
code	`Long`	Any code other than 0 indicate an error in authentication
err	`Optional[String]`	Provide detailed error message if code is not 0

Use wscat from Node.js to connect to websocket data.

# # Install wscat from Node.js if you haven't
# npm install -g wscat  
npm install -g wscat

# Connect to websocket
wscat -c wss://bitmax.io/0/api/pro/v1/stream -x '{"op":"sub", "ch": "depth:BTC-PERP"}'

You can also setup authorized session

@ToDo

You can subscribe/unsubscribe to one or multiple data channels.

If the subscription is successful, you will receive at least one ack message confirming the request is successful and you will start receiving data streams.
If the subscription is unsuccessful, you will receive one ack message with text explaining why the subscription failed.

Request Body Schema

The standard messages to subscribe to / unsubscribe from data channels is an JSON object with fields:

Name	Type	Description
op	`String`	`sub` to subscribe and `unsub` to unsubscribe
id	`Optional[String]`	user specified UUID, if provided, the server will echo back this value in the response message
ch	`String`	name of the data channel with optional arguments, see below for details

Subscribe to bbo stream for symbol BTC-PERP

{ "op": "sub", "id": "abcd1234", "ch": "bbo:BTC-PERP" }

Subscribe to ref-px stream for symbol BTC

{ "op": "sub", "id": "abcd1234", "ch": "ref-px:BTC" }

Subscribe to trade stream for one contract

{ "op": "sub", "id": "abcd1234", "ch": "trades:BTC-PERP" }

Unsubscribes from the depth stream for all symbols (method 1)

{ "op": "unsub", "id": "abcd1234", "ch": "depth:*" }

Unsubscribes from the depth stream for all symbols (methond 2)

{ "op": "unsub", "id": "abcd1234", "ch": "depth" }

Unsubscribes from the 1 minute bar streams for all symbols (method 1)

{ "op": "unsub", "id": "abcd1234", "ch": "bar:1:*" }

Unsubscribes from the 1 minute bar streams for all symbols (method 2)

{ "op": "unsub", "id": "abcd1234", "ch": "bar:1" }

Unsubscribes from bar streams of all frequencies for BTC-PERP

{ "op": "unsub", "id": "abcd1234", "ch": "bar:*:BTC-PERP" }

Customize Channel content with `ch`

You can customize the channel content by setting ch according to the table below:

Type	Value	Description
public	`depth:<symbol>`	Updates to order book levels.
public	`bbo:<symbol>`	Price and size at best bid and ask levels on the order book.
public	`trades:<symbol>`	Market trade data
public	`bar:<interval>:<symbol>`	Bar data containing O/C/H/L prices and volume for specific time intervals
public	`ref-px:<symbol>`	Reference prices used by margin risk Calculation.
public	`ticker:<symbol>`	Ticker ???
public	`futures-market-data`	Futures market data ???
Private	`order:<account>`	Order Update Stream: "futures", or actual accountId for account.

Symbol in ref-px is single asset symbol(e.g. BTC), not trading pair symbol (e.g. BTC-PERP), which is different from other channels.

Unsubscribe with Wildcard Character `*`

Using the wildcard character *, you can unsubscribe from multiple channels with the same channel name.

Channel: Bar Data

Subscribe to BTC-PERP 1 minute bar stream

{ "op": "sub", "id": "abc123", "ch":"bar:1:BTC-PERP" }

Unsubscribe to BTC-PERP 1 minute bar stream

{ "op": "unsub", "id": "abc123", "ch":"bar:1:BTC-PERP" }

//  Alternatively, you can unsubscribe all bar streams for BTC-PERP
{ "op": "unsub", "id": "abc123", "ch":"bar:*:BTC-PERP" }

// Or unsubscribe all 1 minute bar stream
{ "op": "unsub", "id": "abc123", "ch":"bar:1" }

// Or unsubscribe all bar stream
{ "op": "unsub", "id": "abc123", "ch":"bar" }

Bar Data Sample Message

{
    "m": "bar",
    "s": "BTC-PERP",    
    "data": {
        "i":  "1",
        "ts": 1575398940000,
        "o":  "8500.25",
        "c":  "8510.75",
        "h":  "8519",
        "l":  "8500.25",
        "v":  "54.12"
    }
}

Channel

bar

Message Schema

The data field is a list containing one or more trade objects. The server may combine consecutive trades with the same price and bm value into one aggregated item. Each trade object contains the following fields:

Name	Type	Description
seqnum	`Long`	the sequence number of the trade record. `seqnum` is always increasing for each symbol, but may not be consecutive
p	`String`	the executed price expressed as a string
q	`String`	the aggregated traded amount expressed as string
ts	`Long`	the UTC timestamp in milliseconds of the first trade
bm	`Boolean`	if true, the buyer of the trade is the maker.

Channel: Level 1 Order Book Data (BBO)

Subscribe to BTC-PERP quote stream

{ "op": "sub", "id": "abc123", "ch":"bbo:BTC-PERP" }

Unsubscribe to BTC-PERP quote stream

{ "op": "unsub", "id": "abc123", "ch":"bbo:BTC-PERP" }

BBO Message

{
    "m": "bbo",
    "symbol": "BTC-PERP",
    "data": {
    "ts": 1573068442532,
        "bid": [
            "9309.11",
            "0.25"
        ],
        "ask": [
            "9309.12",
            "0.5"
        ]
    }
}

You can subscribe to updates of best bid/offer data stream only. Once subscribed, you will receive BBO message whenever the price and/or size changes at the top of the order book.

Each BBO message contains price and size data for exactly one bid level and one ask level.

Channel: Level 2 Order Book Updates

Subscribe to BTC-PERP depth updates stream

{ "op": "sub", "id": "abc123", "ch":"depth:BTC-PERP" }

Unsubscribe to BTC-PERP depth updates stream

{ "op": "unsub", "id": "abc123", "ch":"depth:BTC-PERP" }

The Depth Message

{
    "m": "depth",
    "symbol": "BTC-PERP",
    "data": {
        "ts": 1573069021376,
        "seqnum": 2097965,
        "asks": [
            [
                "0.06844",
                "10760"
            ]
        ],
        "bids": [
            [
                "0.06777",
                "562.4"
            ],
            [
                "0.05",
                "221760.6"
            ]
        ]
    }
}

If you want to keep track of the most recent order book snapshot in its entirety, the most efficient way is to subscribe to the depth channel.

Each depth message contains a bids list and an asks list in its data field. Each list contains a series of [price, size] pairs that you can use to update the order book snapshot. In the message, price is always positive and size is always non-negative.

if size is positive and the price doesn't exist in the current order book, you should add a new level [price, size].
if size is positive and the price exists in the current order book, you should update the existing level to [price, size].
if size is zero, you should delete the level at price.

See Orderbook Snapshot for code examples.

Channel: Futures Market Data

Subscribe to Futures Market Data

# Subscribe to all symbols
{"op":"sub", "ch":"futures-market-data"}
{"op":"sub", "ch":"futures-market-data:*"}

# Subscribe to one symbol
{"op":"sub", "ch":"futures-market-data:BTC-PERP"}

Futures Market Data Sample Message

{
  "m": "futures-market-data",
  "s": "BTC-PERP",
  "data": {
    "oi":   "9000",
    "fr":   "-0.001",
    "fpf":  false,
    "ip":   "8777.155",
    "mp":   "8432.514108733",
    "srct": 1580147455260,
    "fpt":  1580144400000
  }
}

Channel

futures-market-data

Message Schema

The data field is an object with following fields:

Name	Type	Description
s	`String`	symbol
oi	`String`	open interest
fr	`String`	funding rate
fpf	`Boolean`	funding payment flag
ip	`String`	index price
mp	`String`	mark price
srct	`Long`	source time
fpt	`Long`	next funding payment time

Order Channels

You can subscribe/unsubscribe to all order-related channels with one message.

To subscribe:

{"op":"sub", "id": "abcd1234", "ch":"order:futures"}

To unsubscribe:

{"op":"unsub", "id": "abcd1234", "ch":"order:futures"}

In both messages above, the id field is optional.

Once subscribed, you will start to receive balance update messages from all the following channels:

order - order updates
futures-collateral - updates in collateral balance
futures-position - updates in contract position along with other contract-specifc data

In addition, you will also receive futures-risk with information about the overall account risk profile.

The general format for the three balance update messages is:

    {
        "m": "order",  // order, futures-position, or futures-collateral
        "accountId": "futNodf11Cos9iKQXAaE2Oukctj3jdMA",
        "ac":     "FUTURES",  // account category
        "execId":  229,       // use this to query transaction details with RESTful APIs
        "txNum":   0,         // transaction number used to identify balance update batches
        "rid":    "r1715630020d5362614103bbtcpwxnh",
        "data": {
            ... // data fields 
    }

Please refer to WebSocket - Futures Balance Update Messages for implementation details.

tp - Transaction Type

The tp field in the message shows the reason of the balance update. Below are some common :

ExecutionUpdate - message about order status update
TakeOver - the account has been taken over due to hightened risk exposure.
PositionInjectionBLP - position injected to Backstop Liquidity Providers (BLPs), you will only see this message if your account is registered as a BLP with the exchange.
PositionInjection - position injected to regular accounts.
FundingPayment - funding payment made to the account.
FuturesPnlSettlement - rolling position PnL into realized PnL
FuturesTransfer - fund is transferred in/out.

Identifying Balance Update Batches by execId (execution Id) and txNum (Transaction Number)

Some balance updates, such as position injection, are done in batches. The txNum can help you identify such updates. For a batch of n update messages, the i-th message will have txNum = n-i - that is, the first message will have txNum = n-1 and the last message will have txNum = 0.

Retrieve Transaciton Details

You can use execId to retrieve balance update details using the RESTful API. See Lookup Balance Update Records by Id

Channel: Order

Order Message

{
    "m": "order",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "ac":     "FUTURES",  // account category
    "execId":  229,       // use this to query transaction details with RESTful APIs
    "txNum":   0,         // order messages will always have txNum = 0
    "rid":    "r1715630020d5362614103bbtcpwxnh",
    "data": {
        "sn":       229,           // deprected, use execId
        "orderId": "r1715630020d5362614103bbtcpwxnh",
        "ot":      "Limit",        // order type
        "s":       "BTC-PERP",     // symbol 
        "t":        1586288919298, // sending time (UTC)
        "p":       "8000",         // order price 
        "q":       "0.1",          // order quantity
        "sd":      "Buy",          // side 
        "st":      "Filled",       // status 
        "ap":      "8000",         // average filled price
        "cfq":     "0.1",          // cummulative filled quantity
        "sp":      "",             // stop price
        "err":     "",             // error code
        "cf":      "0.52",         // cummulative commission (fee)
        "fa":      "USDT",         // fee asset
        "ei":      "NULL_VAL",     // execution instruction 
        "lq":      "0.1",          // last filled quantity 
        "lp":      "8000",         // last filled price 
        "lf":      "0.52",         // fee/rebate of the last fill
        "pos":     "0.1",          // contract position 
        "rc":      "-800.52"       // reference cost 
    }
}

Channel

order:futures

Message Schema

The data field is an object with following fields:

Name	Type	Description
sn	`Long`	deprecated, use execId
orderId	`String`	order Id
ot	`String`	order type
s	`String`	symbol
t	`Long`	sending time (UTC)
p	`String`	order price
q	`String`	order quantity
sd	`String`	side
st	`String`	status
ap	`String`	average filled price
cfq	`String`	cummulative filled quantity
sp	`String`	stop price
err	`String`	error code
cf	`String`	cummulative commission (fee)
fa	`String`	fee asset
ei	`String`	execution instruction
lq	`String`	last filled quantity
lp	`String`	last filled price
lf	`String`	fee/rebate of the last fill
pos	`String`	contract position
rc	`String`	reference cost

Channel: Contract Position Updates

Futures Position (per-symbol data)

{
    "m":         "futures-position",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "ac":        "FUTURES",
    "execId":     413208,
    "txNum":      0,
    "tp":        "FuturePnlSettlement",
    "rid":       "6F31ICSCpd7yYYeG",
    "data": {
        "s":      "BTC-PERP",
        "sn":      413208,        // deprecated, use execId 
        "pos":    "0",            // contract position 
        "rc":     "0",            // reference cost 
        "posn":   "0",            // position notional 
        "liq":    "-1",           // Estimated liquidation price
        "bepx":   "0",            // breakeven price 
        "pnl":    "0",            // contract position profit/loss in USDT
        "ucol":   "319.5",        // collateral in use (in USDT)
        "mbn":    "5804.865",     // maximum notional allowed to buy
        "msn":    "0",            // maximum notional allowed to sell
        "mbos":   "0.762994873",  // deprecated, use mbn instead
        "msos":   "0",            // deprecated, use msn instead
        "idxPx":  "7102.68",      // index price of the underlying (BTC/USDT in this case)
        "markPx": "7608",         // market price of the futures contract 
        "posdlt": "0",            // change in position
        "rcdlt":  "428.785"       // change in reference cost
    }
}

Channel

order:futures

Message Schema

The data field is an object with following fields:

Name	Type	Description
s	`String`	symbol
sn	`Long`	deprecated, use execId instead
pos	`String`	contract position
rc	`String`	reference cost
posn	`String`	position notional
liq	`String`	Estimated liquidation price
bepx	`String`	breakeven price
pnl	`String`	contract position profit/loss in USDT
ucol	`String`	collateral in use (in USDT)
mbn	`String`	maximum notional allowed to buy
msn	`String`	maximum notional allowed to sell
mbos	`String`	deprecated, use mbn instead
msos	`String`	deprecated, use msn instead
idxPx	`String`	index price of the underlying (BTC/USDT in this case)
markPx	`String`	market price of the futures contract
posdlt	`String`	change in position
rcdlt	`String`	change in reference cost

Channel: Futures Collateral Updates

Futures Collateral

{
    "m"        : "futures-collateral",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "ac"       : "FUTURES",
    "execId"   : 110,
    "txNum"    : 0,
    "tp"       : "FuturesTransfer",
    "rid"      : "t4t3h0CkIMx91zMzNzWuzmpUcQx4aCvE", // request Id
    "data": {
        "a"  : "USDT",    // asset code 
        "sn" : 110,       // deprected, use execId
        "tb" : "196.344", // total balance 
        "ab" : "196.344", // available balance. This field is deprecated, for futures collaterals, ab always equals to tb. 
        "mt" : "0",       // maximum transferrable balance
        "dlt": "-10"      // negative if transferring out of the futures account, positive when adding funds to the futures account
    }
}

Channel

order:futures

Message Schema

The data field is an object with following fields:

Name	Type	Description
a	`String`	asset code
sn	`Long`	deprected, use `execId` instead
tb	`String`	total balance
ab	`String`	available balance. This field is deprecated, for futures collaterals, ab always equals to tb.
mt	`String`	maximum transferrable balance
dlt	`String`	negative if transferring out of the futures account, positive when adding funds to the futures account

Channel: Futures Account Risk

Futures Risk (overall account data)

{
    "m": "futures-risk",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "ac": "FUTURES",
    "data": {
        "col":    "12800.39525",
        "effcol": "12800.39525",
        "ucol":   "68.133212928",
        "frcol":  "12732.262037071",
        "walbal": "12970.11105",
        "actval": "13099.258147865",
        "posn":   "762.664258566",
        "epn":    "1362.664258566",
        "clv":    "0.106454857",
        "amar":   "9.393653036",
        "tmar":   "0.003",
        "emmar":  "0.006",
        "eimar":  "0.05",
        "alv":    "20",
        "pnltot": "129.147097865",  
        "upnl":   "129.147097865",
        "spnl":   "0"
    }
}

Channel

order:futures

Message Schema

The data field is an object with following fields:

Name	Type	Description
col	`String`	total collateral value in USDT
effcol	`String`	effective collateral value in USDT
ucol	`String`	account overall collateral in use (in USDT)
frcol	`String`	account overall free collateral (in USDT)
walbal	`String`	total wallet balance in USDT
actval	`String`
posn	`String`	account overall position notional value in USDT
epn	`String`	account overall effective position notional in USDT
clv	`String`	account leverage
alv	`String`	account maximum leverage
amar	`String`	account margin rate
tmar	`String`	takeover margin rate
emmar	`String`	effective maintenance margin rate
eimar	`String`	effective initial margin rate
pnl	`String`	position notional in USDT
larMaxLev	`Int`	largestOptionalMaxLeverage ???
upnl	`String`	unrealized pnl
rpnl	`String`	realized pnl

WebSocket - Data Request

WS: Orderbook Snapshot

Requesting the current order book snapshot

{ "op": "req", "id": "abcdefg", "action": "depth-snapshot", "args": { "symbol": "BTC-PERP" } }

Depth snapshot message

{
    "m": "depth-snapshot",
    "symbol": "BTC-PERP",
    "id": "abcd1234",
    "data": {
        "seqnum": 3167819629,
        "ts": 1573142900389,
        "asks": [
            [
                "0.06758",
                "585"
            ],
            [
                "0.06773",
                "8732"
            ]
        ],
        "bids": [
            [
                "0.06733",
                "667"
            ],
            [
                "0.06732",
                "750"
            ]
        ]
    }
}

You can request the current order book via websocket by an depth-snapshot request.

The args schema:

Name	Data Type	Description
op	`String`	`req`
action	`String`	`depth-snapshot`
id	`String`	for result match purpose
args:symbol	`String`	Symbol, e.g. `BTC-PERP`

The response schema:

Name	Data Type	Description
m	`String`	`depth-snapshot`
symbol	`String`	Symbol, e.g. `BTC-PERP`
id	`String`	echo back `id` in request
data:seqnum	`Long`
data:ts	`Long`	UTC Timestamp in milliseconds
data:asks	`[[String, String]]`	List of (price, size) pair
data:bids	`[[String, String]]`	List of (price, size) pair

You can following the steps below to keep track of the the most recent order book:

Connecting to WebSocket Stream
Subscribe to the depth update stream, see Level 2 Order Book Updates (Depth).
Send a depth-snapshot request to the server.
Once you obtain the snapshot message from the server, initialize the snapshot.
Using consequent depth messages to update the order book.

Please note that field seqnum should strictly increase by 1 for each new depth update (each symbol maintain its own seqnum). If you see a larger than 1 gap from previous seqnum (for the same symbol), then there might be data loss, you need to repeat above steps to maintain a new order book.

The depth-snapshot message is constructed in a consistent way with all depth message.

Please note that the depth-snapshot API has higher latency. The response time is usually between 1000 - 2000 milliseconds. It is intended to help you initialize the orderbook, not to be used to obtain the timely order book data.

WS: Futures Account Risk

Request futures risk

{
  "op":      "req", 
  "action":  "futures-risk", 
  "id":      "abcd1234", 
}

Futures Risk Response

{
    "m":         "futures-risk",
    "accountId": "futZrwfTaL4Py6M05X0SnJ9QFIuj6k2Q",
    "ac":        "FUTURES",
    "id":        "abcd1234",
    "data": {
        "col":    "12800.39525",
        "effcol": "12800.39525",
        "ucol":   "68.133212928",
        "frcol":  "12732.262037071",
        "walbal": "12970.11105",
        "actval": "13099.258147865",
        "posn":   "762.664258566",
        "epn":    "1362.664258566",
        "clv":    "0.106454857",
        "amar":   "9.393653036",
        "tmar":   "0.003",
        "emmar":  "0.006",
        "eimar":  "0.05",
        "alv":    "20",
        "pnltot": "129.147097865",  
        "upnl":   "129.147097865",
        "spnl":   "0"
    }
}

You can request margin risk for a symbol via websocket by an futures-risk request.

The args schema:

Name	Data Type	Description
op	`String`	`req`
action	`String`	`futures-risk`
id	`String`	for result match purpose

The response schema:

Name	Data Type	Description
m	`String`	`depth-snapshot`
accountId	`String`	futures accountId
ac	`String`	`FUTURES`
symbol	`String`	Symbol, e.g. `BTC-PERP`
id	`String`	echo back `id` in request
data	`Json`	See `data` detail below

data field detail

Name	Data Type	Description
col	`String`
effcol	`String`
ucol	`String`	collateral in use
frcol	`String`	free collateral
walbal	`String`
actval	`String`
posn	`String`
epn	`String`
clv	`String`	current leverage
amar	`String`
tmar	`String`
emmar	`String`
eimar	`String`
alv	`String`
pnltot	`String`
upnl	`String`	unsettled profit/loss
spnl	`String`	settled profit/loss

WS: Place Order

Request to place new order

{
    "op": "req",
    "action": "place-Order",
    "account": "FUTURES",
    "args": {
        "time":       1573772908483,
        "id":         "11eb9a8355fc41bd9bf5b08bc0d18f6b",
        "symbol":     "BTC-PERP",
        "orderPrice": "8500",
        "orderQty":   "0.12",
        "orderType":  "limit",
        "side":       "buy",
        "postOnly":    false,
        "respInst":   "ACK"
    }
}

Successful ACK message

{
    "m": "order", 
    "accountId": "cshQtyfq8XLAA9kcf19h8bXHbAwwoqDo", 
    "accountCategory": "FUTURES", 
    "action": "place-order", 
    "status": "Ack", 
    "info": {
        "symbol": "BTC-PERP", 
        "orderType": "Limit", 
        "timestamp": 1576015701441, 
        "id": "17e1f6809122469589ffc991523b505d", 
        "orderId": "s16ef1daefbe08669437121523b505d"
    }
}

Error response message

{
    "m": "order",
    "accountId": "cshQtyfq8XLAA9kcf19h8bXHbAwwoqDo",
    "accountCategory": "FUTURES", 
    "action": "place-order",
    "status": "Err",
    "info": {
        "id":      "69c482a3f29540a0b0d83e00551bb623",
        "symbol":  "BTC-PERP",
        "code":     300011,
        "message": "Not Enough Account Balance",
        "reason":  "INVALID_BALANCE"
    }
}

Place order via websocket

Request

Make new order request follow the general websocket request rule, with proper place new order parameters as specified in rest api for args field.

see placing order via RESTful API.

Response

Respond with m field as order, and action field as place-order; status field to indicate if this is a successful Ack or failed Err.

ACK

With status field as Ack to indicate this new order request pass some basic sanity check, and has been sent to matching engine.

info field provide some detail: if you provide id in your request, it will be echoed back as id to help you identify; we also provide server side generated orderId, which is the id you should use for future track or action on the order.

ERR

With status field as Err to indicate there is some obvisous errors in your order.

info field provide some detail: if you provide id in your request, it will be echoed back as id to help you identify; we also provide error code, reason, and message detail.

WS: Cancel Order

Request to cancel existing open order

{
  "op": "req",
  "action": "cancel-order",
  "account": "futures",
  "args": {
    "time":    1574165050128,
    "id":      "2d4c3fa1e5c249e49f990ce86aebb607",
    "orderId": "16e83845dcdsimtrader00008c645f67",
    "symbol":  "BTC-PERP"
  }
}

Successful ACK message

{
  "m": "order",
  "accountId": "cshQtyfq8XLAA9kcf19h8bXHbAwwoqDo",
  "accountCategory": "FUTURES",
  "action": "cancel-order",
  "status": "Ack",
  "info": {
    "symbol":    "BTC-PERP",
    "orderType": "NULL_VAL",
    "timestamp":  1574165050147,
    "id":        "7b73dcd8e8c847d5a99df5ef5ae5088b",
    "orderId":   "16e83845dcdsimtrader00008c645f67"
  }
}

Error response message

{
  "m": "order",
  "accountId": "cshQtyfq8XLAA9kcf19h8bXHbAwwoqDo",
  "accountCategory": "FUTURES",
  "action": "cancel-order",
  "status": "Ack",
  "info": {
    "code":     300006,
    "id":      "x@fabs",
    "message": "Invalid Client Order Id: x@fabs",
    "symbol":  "BTC-PERP",
    "reason":  "INVALID_ORDER_ID"
  }
}

Cancel an existing open order via websocket

Request

Make order cancelling request follow the general websocket request rule by setting action to be cancel-orde, with proper cancel order parameters as specified in rest api for args field.

Response

ACK

With status field as Ack to indicate this cancel order request pass some basic sanity check, and has been sent to matching engine.

info field provide some detail: if you provide id in your request, it will be echoed back as id to help you idintify; we also echo back target orderId to be cancelled.

Err

With status field as Err to indicate there is some obvisous errors in your cancel order request.

info field provide some detail: if you provide id in your request, it will be echoed back as id to help you identify; we also provide error code, reason, and message detail.

WS: Cancel All Orders

Request to cancel all existing open orders

{
    "op": "req",
    "action": "cancel-all",
    "args": {}
}

Request to cancel existing open order related to symbol "BTC-PERP"

{
    "op": "req",
    "action": "cancel-all",
    "account": "futures",
    "args": {
        "symbol": "BTC-PERP"
    }
}

Successful ACK message

{
    "m": "order",
    "accountId": "futQtyfq8XLAA9kcf19h8bXHbAwwoqDo",
    "ac": "FUTURES",
    "action": "cancel-all",
    "status": "Ack",
    "info": {
        "symbol":    "",
        "orderType": "NULL_VAL",
        "timestamp":  1574165159732,
        "id":        "69c482a3f29540a0b0d83e00551bb623",
        "orderId":   ""
    }
}

Cancel all open orders on account level via websocket with optional symbol.

Request

Make general websocket request with action field as cancel-All and set proper account value (futures), and provide time value in args.

Response

With status field as Ack to indicate this cancel all order request has been received by server and sent to matching engine.

info field provide some detail: if you provide id in your request, it will be echoed back as id to help you match ack with request.