NAV
shell python java

BitMax Futures Trading API Documentation

Using BitMax Futures Trading API

The BitMax Futures API is based on RESTful and WebSocket.

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:

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:

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 Transfer 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:

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:

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.

Name | Type | Description m | String | trades symbol | String | trade symbol data | Json | A list of trade record; see below for detail.

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 Description
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:

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:

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

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.

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

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

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:

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:

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

Subscribe to Data Channels

How to Subscribe

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.

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",
    "ts": 1573068442532,
    "symbol": "BTC-PERP",
    "data": {
        "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.

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:

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 :

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:

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.