Changelogs

version	time	content
V0.1.6.0	2023 MAR 15	* Use feerate class. Deprecate fee rates in following endpoints. `GET /linear/v1/configs` `GET /linear/v1/account_configs` * Add feerate class info in `GET /linear/v1/account_configs`
V0.1.5.6	2023 FEB 17	* `GET /um/v1/accounts` response add fields `total_future_value`, `total_option_value`, `future_value`
V0.1.5.5	2022 JAN 18	* Add display name of instrument_id/currency, for UI page only
V0.1.5.4	2022 DEC 15	* Add leverage ratio API: `GET /linear/v1/leverage_ratio` `POST /linear/v1/leverage_ratio` * add `trigger_type` in `POST /linear/v1/orders` * API order returned by query add internal fields "tp_price" & "sl_price"
V0.1.5.3	2022 NOV 2	* Support USD-M blocktrade: `POST /linear/v1/blocktrades` `GET /linear/v1/blocktrades` `GET /linear/v1/platform_blocktrades` `GET /linear/v1/user/info` * Support USD-M mmp control: Support mmp field when placing order `GET /linear/v1/mmp_state` `POST /linear/v1/update_mmp_config` `POST /linear/v1/reset_mmp` * Add USD-M websocket `mmp_frozen` channel
V0.1.5.2	2022 OCT 30	Remove USDT-M contents
V0.1.5.1	2022 SEP 29	Query um account with pair margin info
V0.1.5	2022 JUL 29	USD option changes: * Data is stored in different sharding. so order_id/trade_id/transaction id are not globally unique.(instrument+id is unique, See sharding page) * Support USD option auto_price order * Add `GET /linear/v1/option_pairs` * Paging query `has_more` field is deprecated due to db sharding * `GET /linear/v1/user/settlements`: parameter `currency` changed to `settlement_currency` and remove `category`(only futures have settlements) * Add `GET /linear/v1/user/deliveries` * Add `GET /linear/v1/market/deliveries`
V0.1.4	2022 JUL 18	* `POST /linear/v1/amend_orders`: instrument_id is required `POST /linear/v1/amend_batchorders`: instrument_id is required `POST /linear/v1/cancel_orders`: change format of `order_id_list`; if `order_id` is provided, `instrument_id` is required
V0.1.3	2022 JUL 8	* Support USD futures. * /linear/v1/cancel_orders: for conditional order, `instrument_id` is required. * Add `total_position_pnl` in `GET /um/v1/accounts` and websocket `um_account` channel.
V0.1.2	2022 JUN 2	* Add Kline resolutions(minutes): 360, 720
V0.1.1	2022 APR 22	* Add USD-M/USDT-M conditional order; * `GET /um/v1/accounts` amount fields converted to `USD`, the original `USDT` fields are still there for compatibility; USDC fields are no longer exists.
V0.1.0	2022 MAR 2	* Release
V0.0.1	2022 JAN 27	* Init version

Introduction

Welcome to bit.com API. You can retrieve market data, execute trades and manage your bit.com account through bit.com API.

API hosts (production)

REST API base url: https://api.bit.com
WS API base url: wss://ws.bit.com

API hosts (testnet)

REST API base url: https://betaapi.bitexch.dev
WS API base url: wss://betaws.bitexch.dev

API rate limits

USDT futures endpoints are divided into three types of rate limit: public, private (trade) and private (others).It Separate rate limits from Coin-M futures&options and spot endpoints.The public interface implements IP-specified frequency limitation , and the private interface implements user-specified frequency limitation. When a breach happens, a prompt will be returned: “429 too many requests”. About the type of API rate limits, please refer to API summary.

Rest API rate limits:
Public API: 10 requests per second per IP.
Private API(trade): 5 requests per second per user.
Private API(Others): 5 requests second per user.

Authentication

Private API mandatory fields

User must put Access Key in http request header X-Bit-Access-Key.
User must add timestamp (epoch in millisecond) field in request parameter (query string for GET, json body for POST),API server will check this timestamp, if abs(server_timestamp - request_timestamp) > 5000, the request will be rejected.
timestamp must be integer, not quoted string.
User must add signature field in request parameter (query string for GET, json body for POST).
For POST request, Header Content-Type should be set as application/json.

If authentication fails, a prompt will be returned: “AkId is invalid” and http status code is 412

Signature algorithm

    #########
    # Python code to calc BIT.COM API signature
    #########
    import hashlib
    import hmac

    def encode_list(self, item_list):
        list_val = []
        for item in item_list:
            obj_val = self.encode_object(item)
            list_val.append(obj_val)
        output = '&'.join(list_val)
        output = '[' + output + ']'
        return output

     def encode_object(self, obj):
        if isinstance(obj, (str, int)):
            return obj

        # treat obj as dict
        sorted_keys = sorted(obj.keys())
        ret_list = []
        for key in sorted_keys:
            val = obj[key]
            if isinstance(val, list):
                list_val = self.encode_list(val)
                ret_list.append(f'{key}={list_val}')
            elif isinstance(val, dict):
                # call encode_object recursively
                dict_val = self.encode_object(val)
                ret_list.append(f'{key}={dict_val}')
            elif isinstance(val, bool):
                bool_val = str(val).lower()
                ret_list.append(f'{key}={bool_val}')
            else:
                general_val = str(val)
                ret_list.append(f'{key}={general_val}')

        sorted_list = sorted(ret_list)
        output = '&'.join(sorted_list)
        return output

    def get_signature(self, http_method, api_path, param_map):
        str_to_sign = api_path + '&' + self.encode_object(param_map)
        print('str_to_sign = ' + str_to_sign)
        sig = hmac.new(self.secret_key.encode('utf-8'), str_to_sign.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
        return sig

    #########
    # END
    #########

Request parameters: JSON Body for POST, query string for the rest
Encode string to sign, for simple json object, sort your parameter keys alphabetically, and join them with '&' like 'param1=value1&param2=value2', then get str_to_sign = api_path + '&' + 'param1=value1&param2=value2'
For nested array objects, encode each object and sort them alphabetically, join them with '&' and embraced with '[', ']', e.g. str_to_sign = api_path + '&' + 'param1=value1&array_key1=[array_item1&array_item2]', see example below.
Signature = hex(hmac_sha256(str_to_sign, secret_key))
Add signature field to request parameter:
for query string, add '&signature=YOUR_SIGNATURE' for JSON body, add {'signature':YOUR_SIGNATURE}

Example for `GET` request

Secret Key: eabc3108-dd2b-43df-a98d-3e2054049b73
HTTP method: GET
API Path: /v1/margins
Query string: price=8000&qty=30&instrument_id=BTC-PERPETUAL&timestamp=1588242614000

Then str_to_sign = /v1/margins&instrument_id=BTC-PERPETUAL&price=8000&qty=30&timestamp=1588242614000

> echo -n "/v1/margins&instrument_id=BTC-PERPETUAL&price=8000&qty=30&timestamp=1588242614000" | openssl dgst -sha256 -hmac "eabc3108-dd2b-43df-a98d-3e2054049b73"

> e3be96fdd18b5178b30711e16d13db406e0bfba089f418cf5a2cdef94f4fb57d

sig = hex(hmac_sha256(str_to_sign, secret_key)) = e3be96fdd18b5178b30711e16d13db406e0bfba089f418cf5a2cdef94f4fb57d

Final query string: price=8000&qty=30&instrument_id=BTC-PERPETUAL&timestamp=1588242614000&signature=e3be96fdd18b5178b30711e16d13db406e0bfba089f418cf5a2cdef94f4fb57d

Example for `POST` request

Secret Key: eabc3108-dd2b-43df-a98d-3e2054049b73
HTTP Method: POST
API Path: /v1/orders
JSON body:
{ "instrument_id": "BTC-27MAR20-9000-C", "order_type": "limit", "price": "0.021", "qty": "3.14", "side": "buy", "time_in_force": "gtc", "stop_price": "", "stop_price_trigger": "", "auto_price": "", "auto_price_type": "", "timestamp": 1588242614000 }

Then str_to_sign = /v1/orders&auto_price=&auto_price_type=&instrument_id=BTC-27MAR20-9000-C&order_type=limit&price=0.021&qty=3.14&side=buy&stop_price=&stop_price_trigger=&time_in_force=gtc&timestamp=1588242614000

> echo -n "/v1/orders&auto_price=&auto_price_type=&instrument_id=BTC-27MAR20-9000-C&order_type=limit&price=0.021&qty=3.14&side=buy&stop_price=&stop_price_trigger=&time_in_force=gtc&timestamp=1588242614000" | openssl dgst -sha256 -hmac "eabc3108-dd2b-43df-a98d-3e2054049b73"

> 34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817

sig = hex(hmac_sha256(str_to_sign, secret_key)) = 34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817

Final JSON body:
{ "instrument_id": "BTC-27MAR20-9000-C", "order_type": "limit", "price": "0.021", "qty": "3.14", "side": "buy", "time_in_force": "gtc", "stop_price": "", "stop_price_trigger": "", "auto_price": "", "auto_price_type": "", "timestamp": 1588242614000, "signature": "34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817" }

POST request json body with boolean field

For example, When calling POST /v1/orders with boolean fields:

Take post_only as example,

In json body, use following format, a real json boolean field, no quoted string: {"post_only": true}
In string payload before making signature: post_only=true

Example

request

curl -X POST "https://betaapi.bitexch.dev/v1/orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" -d '{"instrument_id": "BTC-26JUN20-3500-P", "price": "15", "qty": "1", "side": "sell", "time_in_force": "gtc", "order_type": "limit", "post_only": true, "timestamp": 1592587664652, "signature": "cf2d8fe95b71764056a4f707e2388ce84a82ed2915cbe92b58f37c26ea0eda97"}'

string to sign

str_to_sign = /v1/orders&instrument_id=BTC-26JUN20-3500-P&order_type=limit&post_only=true&price=15&qty=1&side=sell&time_in_force=gtc&timestamp=1592587664652

POST request json body with array field

Algo

for item in object_array:
str_list.add(encode(item))
str_to_sign = '&'.join(str_list)

For example, When calling POST /v1/blocktrades with array fields:

Take trades as example,

In json body, use following format {"trades": [{"instrument_id": "BTC-25SEP20-9000-C", "price": "0.21", "qty": "50", "side": "sell"}, {"instrument_id": "BTC-PERPETUAL", "price": "9000", "qty": "500000", "side": "buy"}]}

And secret key is eabc3108-dd2b-43df-a98d-3e2054049b73

Example

request

curl -X POST "https://betaapi.bitexch.dev/v1/trades" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" -d '{"label": "A0627-1", "role": "taker", "trades": [{"instrument_id": "BTC-25SEP20-9000-C", "price": "0.21", "qty": "50", "side": "sell"}, {"instrument_id": "BTC-PERPETUAL", "price": "9000", "qty": "500000", "side": "buy"}], "timestamp": 1593239722621, "signature": "9636f1850e33557c03a499bb5c1aed9a36be340f3dbfd22a3f066438b3987d6b"}'

string to sign

str_to_sign = /v1/trades&label=A0627-1&role=taker&timestamp=1593239722621&trades=[instrument_id=BTC-25SEP20-9000-C&price=0.21&qty=50&side=sell&instrument_id=BTC-PERPETUAL&price=9000&qty=500000&side=buy]

Sharding

Trading instruments are stored across different database shardings.

Id uniqueness

Since data is stored in different sharding. order_id/trade_id/transaction id are not globally unique

Query pagination

Due to sharding, data is gather from different shard db, offset is not available. We keep limit parameter to indicate return record count.

API summary

User defined string fields(label etc): valid characters are [A-Z], [a-z], [0-9], "-", "_"

Path	Method	Description	Scope	Rate Limit Type	Permission
/linear/v1/orders	POST	Place new order	private	trade	USD-M trade
/linear/v1/cancel_orders	POST	Cancel order	private	trade	USD-M trade
/linear/v1/close_positions	POST	Close positions	private	trade	USD-M trade
/linear/v1/amend_orders	POST	Amend order	private	trade	USD-M trade
/linear/v1/batchorders	POST	Place multiple orders	private	trade	USD-M trade
/linear/v1/amend_batchorders	POST	Amend multiple orders	private	trade	USD-M trade
/linear/v1/update_mmp_config	POST	Update MMP config	private	trade	USD-M trade
/linear/v1/reset_mmp	POST	Reset MMP state	private	trade	USD-M trade
/linear/v1/open_orders	GET	Query open orders	private	others	read
/linear/v1/orders	GET	Query order history	private	others	read
/linear/v1/margins	GET	Query estimated margins	private	others	read
/linear/v1/user/trades	GET	Query user trades	private	others	read
/um/v1/account_mode	GET	Query Account mode	private	others	read
/um/v1/accounts	GET	Query um account information	private	others	read
/um/v1/transactions	GET	Query um transaction logs	private	others	read
/um/v1/interest_records	GET	Query um interest records	private.	others	read
/linear/v1/positions	GET	Query positions	private	others	read
/linear/v1/user/deliveries	GET	Query user deliveries	private	others	read
/linear/v1/user/settlements	GET	Query user settlements	private	others	read
/linear/v1/mmp_state	GET	Query Mmp State	private	others	read
/linear/v1/leverage_ratio	GET	Query user leverage ratio	private	others	read
/linear/v1/leverage_ratio	POST	Update user leverage ratio	private	others	USD-M trade
/linear/v1/blocktrades	POST	New block trade	private	futures&options block_trade	block_trade
/linear/v1/blocktrades	GET	Get block trades of current user	private	futures&options block_trade	block_trade
/linear/v1/platform_blocktrades	GET	Get block trades of platform	private	futures&options block_trade	block_trade
/linear/v1/user/info	GET	Get user info with blocktrade permission	private	futures&options block_trade	block_trade
/linear/v1/system/time	GET	Get server time	public	public	/
/linear/v1/system/version	GET	Get system version	public	public	/
/linear/v1/system/cancel_only_status	GET	Get cancel only status	public	public	/
/linear/v1/instruments	GET	Query instruments	public	public	/
/linear/v1/market/summary	GET	Query instrument summary	public	public	/
/linear/v1/tickers	GET	Query instrument ticker	public	public	/
/linear/v1/orderbooks	GET	Query orderbook	public	public	/
/linear/v1/market/trades	GET	Query market trades	public	public	/
/linear/v1/klines	GET	Query kline data	public	public	/
/linear/v1/funding_rate	GET	Get latest perpetual funding rate	public	public	/
/linear/v1/funding_rate_history	GET	Get perpetual funding rate history	public	public	/
/linear/v1/settlement_prices	GET	Get settlement/delivery prices	public	public	/
/linear/v1/total_volumes	GET	Get total volumes for all currencies	public	public	/
/linear/v1/option_pairs	GET	Get pairs with active option	public	public	/
/um/v1/index_price	GET	Query index price	public	public	/
/um/v1/loan_rates	GET	Query loan rate	public	public	/

System

Get server timestamp

GET /linear/v1/system/time

curl "https://betaapi.bitexch.dev/linear/v1/system/time"

{
  "code": 0,
  "message": "",
  "data": 1587884283175
}

Get server timestamp

Query Parameters

None

Response

Name	Type	Description
data	integer	Server timestamp

Get system version

GET /linear/v1/system/version

curl "https://betaapi.bitexch.dev/linear/v1/system/version"

{
  "code": 0,
  "message": "",
  "data": "v1.0"
}

Get API version

Query Parameters

None

Response

Name	Type	Description
data	string	Api server version

Get cancel only status

GET /linear/v1/system/cancel_only_status

curl "https://betaapi.bitexch.dev/linear/v1/system/cancel_only_status"


{
    "code": 0,
    "message": "",
    "data": {
        "status": 0,
        "remain_ms": 0
    }
}

Get cancel-only status after system maintenance.

status
status=1: means cancel-only is in effective.
status=0: means cancel-only period is finished, the system is ready to accept orders.

remain_ms
Remain time (in milliseconds) for the cancel-only period to finish. when status=0, remain_ms is 0.

Query parameters

None

Response

Name	Type	Description
status	integer	Cancel-only status.
remain_ms	integer	Remain time (in milliseconds) for the cancel-only period to finish.

Market

Get index

GET /um/v1/index_price

curl "https://betaapi.bitexch.dev/um/v1/index_price?currency=BTC&quote_currency=USD"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "index_name": "BTC-USD",
            "index_price": "50000"
        }
    ]
}

Get index price.

currency: base currency of active spot pairs;

quote_currency: quote currency of active spot pairs;

If currency is empty, return all pair index prices associated with quote_currency.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	false	""	Currency
quote_currency	string	true	""	Quote currency

Response

Name	Type	Description
index_name	string	Index name
index_price	string	Index price

Get configs

GET /linear/v1/configs

curl "https://betaapi.bitexch.dev/linear/v1/configs"

{
    "code": 0,
    "message": "",
    "data": {
        "pairs": [
            {
                "base_ccy": "BTC",
                "quote_ccy": "USD",
                "base_display_name": "BTC",
                "quote_display_name": "USD",
                "perpetual_liquidation_fee_rate": "0.00100000",
                "option_liquidation_fee_rate": "0.01000000",
                "option_max_delivery_fee_rate": "0.00125000",
                "future_min_order_price": "0.00050000",
                "future_max_order_price": "1000000.00000000",
                "future_min_order_qty": "0.00010000",
                "future_max_order_qty": "1000000.00000000",
                "future_price_step": "0.01000000",
                "future_size_step": "0.00010000",
                "order_book_groups": "1,10,100,1000",
                "option_min_order_price": "1.00000000",
                "option_max_put_price": "900000.00000000",
                "option_min_order_qty": "0.01000000",
                "option_max_order_qty": "100000.00000000",
                "option_price_step_base": "0.00100000",
                "option_price_step_quote": "1.00000000",
                "option_size_step": "0.01000000",
                "perpetual_taker_fee_rate": "0.00080000",
                "perpetual_maker_fee_rate": "-0.00020000",
                "option_taker_fee_rate": "0.00100000",
                "option_maker_fee_rate": "0.00050000",
                "option_max_order_fee_rate": "0.12500000",
                "future_pos_limit_by_pair": "500000.00000000",
                "option_pos_limit_by_pair": "1000000.00000000",
                "option_range_factor": "0.02000000",
                "iv_min_value": "0.00000000",
                "iv_max_value": "500.00000000",
                "blocktrade_future_min_order_price": "0.00010000",
                "blocktrade_future_max_order_price": "1000000.00000000",
                "blocktrade_future_min_order_qty": "0.00010000",
                "blocktrade_future_max_order_qty": "1000000.00000000",
                "blocktrade_future_price_step": "0.00010000",
                "blocktrade_future_size_step": "0.00010000",
                "blocktrade_option_min_order_price": "0.00010000",
                "blocktrade_option_max_put_price": "1000000.00000000",
                "blocktrade_option_min_order_qty": "0.00010000",
                "blocktrade_option_max_order_qty": "1000000.00000000",
                "blocktrade_option_price_step": "0.00010000",
                "blocktrade_option_size_step": "0.00010000",
                "non_pm_linear_im_rate": "0.02000000",
                "non_pm_linear_mm_rate": "0.01500000",
                "non_pm_linear_scaling_rate": "0.00015000",
                "mi_perp_limit_price_floating_rate": "0.01500000",
                "mi_perp_mark_anchored_upper_limit_rate": "0.00500000",
                "mi_perp_mark_anchored_lower_limit_rate": "0.00500000",
                "mi_max_funding_rate": "0.00500000",
                "option_im_lower_rate": "0.10000000",
                "option_im_upper_rate": "0.15000000",
                "option_mm_rate": "0.07500000",
                "option_mm_coeff": "0.07500000",
                "is_display": true,
                "allow_for_pm": true,
                "option_precision": ""
            }
            // ....
        ],
        "ccy_open_order_params": [
            {
                "ccy": "USD",
                "ccy_display_name": "USD",
                "regular_max_open_count": 1000,
                "regular_max_option_open_count_by_ccy": 1000,
                "regular_max_option_open_count_by_instrument": 50,
                "regular_max_future_open_count_by_ccy": 1000,
                "regular_max_future_open_count_by_instrument": 100,
                "regular_max_option_total_usd_pos_by_ccy": "10000000.00000000",
                "regular_max_future_total_usd_pos_by_ccy": "10000000000.00000000",
                "regular_max_total_usd_pos_by_ccy": "10000000.00000000",
                "regular_max_stop_open_count": 50,
                "pm_max_open_count": 1000,
                "pm_max_option_open_count_by_ccy": 1000,
                "pm_max_option_open_count_by_instrument": 20,
                "pm_max_future_open_count_by_ccy": 1000,
                "pm_max_future_open_count_by_instrument": 100,
                "pm_max_option_total_usd_pos_by_ccy": "5000000000.00000000",
                "pm_max_future_total_usd_pos_by_ccy": "5000000000.00000000",
                "pm_max_total_usd_pos_by_ccy": "5000000000.00000000",
                "pm_max_stop_open_count": 50
            },
            {
                "ccy": "USDT",
                "ccy_display_name": "USDT",
                "regular_max_open_count": 50,
                "regular_max_option_open_count_by_ccy": 50,
                "regular_max_option_open_count_by_instrument": 20,
                "regular_max_future_open_count_by_ccy": 50,
                "regular_max_future_open_count_by_instrument": 50,
                "regular_max_option_total_usd_pos_by_ccy": "10000000.00000000",
                "regular_max_future_total_usd_pos_by_ccy": "10000000.00000000",
                "regular_max_total_usd_pos_by_ccy": "10000000.00000000",
                "regular_max_stop_open_count": 50,
                "pm_max_open_count": 50,
                "pm_max_option_open_count_by_ccy": 50,
                "pm_max_option_open_count_by_instrument": 20,
                "pm_max_future_open_count_by_ccy": 50,
                "pm_max_future_open_count_by_instrument": 50,
                "pm_max_option_total_usd_pos_by_ccy": "10000000.00000000",
                "pm_max_future_total_usd_pos_by_ccy": "10000000.00000000",
                "pm_max_total_usd_pos_by_ccy": "10000000.00000000",
                "pm_max_stop_open_count": 50
            }
        ]
    }
}

Get USD-M system configs in margin currency and pair level.

Query parameters

NONE

Response

Name	Type	Description
pairs	array	Pair configs
ccy_open_order_params	array	Margin currency level open order configs

Pair config

Name	Type	Description
base_ccy	string	Base ccy
quote_ccy	string	Quote ccy
base_display_name	string	Base display name
quote_display_name	string	Quote display name
perpetual_liquidation_fee_rate	string	Perpetual liquidation fee rate
option_liquidation_fee_rate	string	Option liquidation fee rate
option_max_delivery_fee_rate	string	Option max delivery fee rate
future_min_order_price	string	Future min order price
future_max_order_price	string	Future max order price
future_min_order_qty	string	Future min order qty
future_max_order_qty	string	Future max order qty
future_price_step	string	Future price step
future_size_step	string	Future size step
order_book_groups	string	Order book groups
option_min_order_price	string	Option min order price
option_max_put_price	string	Option max put price (max call = underlying)
option_min_order_qty	string	Option min order qty
option_max_order_qty	string	Option max order qty
option_price_step_base	string	Option price step base
option_price_step_quote	string	Option price step quote
option_size_step	string	Option size step
perpetual_taker_fee_rate	string	Perpetual taker fee rate(deprecated, Use feerate class now)
perpetual_maker_fee_rate	string	Perpetual maker fee rate(deprecated, Use feerate class now)
option_taker_fee_rate	string	Option taker fee rate(deprecated, Use feerate class now)
option_maker_fee_rate	string	Option maker fee rate(deprecated, Use feerate class now)
option_max_order_fee_rate	string	Option max order fee rate
future_pos_limit_by_pair	string	Future pos limit by pair
option_pos_limit_by_pair	string	Option pos limit by pair
option_range_factor	string	Option range factor
iv_min_value	string	Iv min value
iv_max_value	string	Iv max value
blocktrade_future_min_order_price	string	Blocktrade future min order price
blocktrade_future_max_order_price	string	Blocktrade future max order price
blocktrade_future_min_order_qty	string	Blocktrade future min order qty
blocktrade_future_max_order_qty	string	Blocktrade future max order qty
blocktrade_future_price_step	string	Blocktrade future price step
blocktrade_future_size_step	string	Blocktrade future size step
blocktrade_option_min_order_price	string	Blocktrade option min order price
blocktrade_option_max_put_price	string	Blocktrade option max put price
blocktrade_option_min_order_qty	string	Blocktrade option min order qty
blocktrade_option_max_order_qty	string	Blocktrade option max order qty
blocktrade_option_price_step	string	Blocktrade option price step(quote_ccy)
blocktrade_option_size_step	string	Blocktrade option size step
non_pm_linear_im_rate	string	Non pm linear im rate(internal use)
non_pm_linear_mm_rate	string	Non pm linear mm rate(internal use)
non_pm_linear_scaling_rate	string	Non pm linear scaling rate(internal use)
mi_perp_limit_price_floating_rate	string	Mi perp limit price floating rate(internal use)
mi_perp_mark_anchored_upper_limit_rate	string	Mi perp mark anchored upper limit rate(internal use)
mi_perp_mark_anchored_lower_limit_rate	string	Mi perp mark anchored lower limit rate(internal use)
mi_max_funding_rate	string	Mi max funding rate(internal use)
option_im_lower_rate	string	Option im lower rate(internal use)
option_im_upper_rate	string	Option im upper rate(internal use)
option_mm_rate	string	Option mm rate(internal use)
option_mm_coeff	string	Option mm coeff(internal use)
is_display	bool	Is display
allow_for_pm	bool	Allow for pm
option_precision	string	Option precision

Currency open order config

Name	Type	Description
ccy	string	Ccy
ccy_display_name	string	Ccy display name
regular_max_open_count	integer	Regular max open count
regular_max_option_open_count_by_ccy	integer	Regular max option open count by ccy
regular_max_option_open_count_by_instrument	integer	Regular max option open count by instrument
regular_max_future_open_count_by_ccy	integer	Regular max future open count by ccy
regular_max_future_open_count_by_instrument	integer	Regular max future open count by instrument
regular_max_option_total_usd_pos_by_ccy	string	Regular max option total usd pos by ccy
regular_max_future_total_usd_pos_by_ccy	string	Regular max future total usd pos by ccy
regular_max_total_usd_pos_by_ccy	string	Regular max total usd pos by ccy （future + option)
regular_max_stop_open_count	integer	Regular max stop open count
pm_max_open_count	integer	Pm max open count
pm_max_option_open_count_by_ccy	integer	Pm max option open count by ccy
pm_max_option_open_count_by_instrument	integer	Pm max option open count by instrument
pm_max_future_open_count_by_ccy	integer	Pm max future open count by ccy
pm_max_future_open_count_by_instrument	integer	Pm max future open count by instrument
pm_max_option_total_usd_pos_by_ccy	string	Pm max option total usd pos by ccy
pm_max_future_total_usd_pos_by_ccy	string	Pm max future total usd pos by ccy
pm_max_total_usd_pos_by_ccy	string	Pm max total usd pos by ccy
pm_max_stop_open_count	integer	Pm max stop open count

Get instruments

GET /linear/v1/instruments

curl "https://betaapi.bitexch.dev/linear/v1/instruments?currency=USD"

{
  "code": 0,
  "message": "",
  "data": [
    {
      "instrument_id": "BTC-USD-PERPETUAL",
      "created_at": 1640944328750,
      "updated_at": 1640944328750,
      "base_currency": "BTC",
      "quote_currency": "USD",
      "strike_price": "",
      "expiration_at": 4102444800000,
      "option_type": "",
      "category": "future",
      "min_price": "0.00050000",
      "max_price": "1000000.00000000",
      "price_step": "0.01000000",
      "min_size": "0.00010000",
      "size_step": "0.00010000",
      "delivery_fee_rate": "",
      "contract_size": "",
      "contract_size_currency": "BTC",
      "active": true,
      "status": "online",
      "groups": [
        1,
        10,
        100,
        10000
      ],
      "group_steps": [
        "0.01000000",
        "0.10000000",
        "1.00000000",
        "100.00000000"
      ],
      "display_at": 1640944328422,
      "is_display": true
    }
  ]
}

Get instrument list by currency or category

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
category	string	false	"future"	Category, input "option" to query option instruments
active	boolean	false	true	Set true to query active instruments
count	int	false	5000	Max return count, only apply for expiration futures/options contracts, not for perpetual

Response

Name	Type	Description
instrument_id	string	Instrument ID
category	string	Category
created_at	integer	Created timestamp
updated_at	integer	Updated timestamp
expiration_at	integer	Expiration timestamp (for perpetual, is timestamp of 2100-01-01)
base_currency	string	Base currency
quote_currency	string	Quote currency
option_type	string	Call/put, option only
strike_price	string	Strike price, option only
min_price	string	System-wise minimum order price, (order price also restricted to min sell/max buy)
max_price	string	System-wise maximum order price, (order price also restricted to min sell/max buy)
price_step	string	Order price should be multiple of price_step
min_size	string	System-wise minimum order size
size_step	string	Order size should be multiple of size_step
delivery_fee_rate	string	Instrument delivery fee rate,option only
contract_size	string	Contract size of the instrument
contract_size_currency	string	Contract size currency
active	bool	Instrument is allowed to trade or not
status	string	Instrument status
groups	array	orderbook output config
group_steps	array	orderbook output config
display_at	integer	For internal use
is_display	bool	For internal use

Get active option pairs

GET /linear/v1/option_pairs

curl "https://betaapi.bitexch.dev/linear/v1/option_pairs?currency=USD"


{
    "code": 0,
    "message": "",
    "data": [
        "BTC-USD",
        "ETH-USD"
    ]
}

Get pairs with active option instruments.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency

Response

Name	Type	Description
data	array	pair list

Get tickers

GET /linear/v1/tickers

curl "https://betaapi.bitexch.dev/linear/v1/tickers?instrument_id=BTC-USD-PERPETUAL"


{
  "code": 0,
  "message": "",
  "data": {
    "time": 1642994479231,
    "instrument_id": "BTC-USD-PERPETUAL",
    "best_bid": "35310.40000000",
    "best_ask": "35311.15000000",
    "best_bid_qty": "4.46000000",
    "best_ask_qty": "3.10000000",
    "ask_sigma": "",
    "bid_sigma": "",
    "last_price": "35310.00000000",
    "last_qty": "5.85000000",
    "open24h": "35064.40000000",
    "high24h": "36480.60000000",
    "low24h": "34688.50000000",
    "price_change24h": "0.00700426",
    "volume24h": "2329.37000000",
    "volume_usd24h": "82236990.06700000",
    "open_interest": "94.21840000",
    "funding_rate": "0.00000000",
    "funding_rate8h": "0.00017589",
    "underlying_price": "0.00000000",
    "mark_price": "35310.69417074",
    "index_price": "35313.68900000",
    "min_sell": "34781.03000000",
    "max_buy": "35840.36000000"
  }
}

Get ticker information by instrument

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID

Response

Name	Type	Description
instrument_id	string	Instrument ID
last_price	string	Most recent traded price
last_qty	string	Most recent traded volume
open24h	string	Open price during previous 24 hour
high24h	string	Highest price during previous 24 hour
low24h	string	Lowest price during previous 24 hour
volume24h	string	Sum volume(Base ccy) during previous 24 hour
volume_usd24h	string	Sum volume(USD) during previous 24 hour
price_change24h	string	Price change% during previous 24 hour
open_interest	string	Open interest
best_bid	string	Best bid price
best_ask	string	Best ask price
best_bid_qty	string	Best bid quantity
best_ask_qty	string	Best ask quantity
bid_sigma	string	Top of book bid implied vol, option only
ask_sigma	string	Top of book ask implied vol, option only
underlying_name	string	Underlying index name, option only
underlying_price	string	Underlying price, option only
funding_rate	string	Funding rate, perpetual only
funding_rate8h	string	Past 8H avg funding rate, perpetual only
mark_price	string	Mark price
index_price	string	Index price
sigma	string	Mark price implied vol, option only
delta	string	Mark price delta, option only
vega	string	Mark price vega, option only
theta	string	Mark price theta, option only
gamma	string	Mark price gamma, option only
max_buy	string	Maximum price of buy order
min_sell	string	Minimum price of sell order

Get orderbooks

GET /linear/v1/orderbooks

curl "https://betaapi.bitexch.dev/linear/v1/orderbooks?instrument_id=BTC-USD-PERPETUAL"

{
  "code": 0,
  "message": "",
  "data": {
    "instrument_id": "BTC-USD-PERPETUAL",
    "timestamp": 1642994567453,
    "bids": [
      ["35324.15000000","0.47000000"],
      ["35324.10000000","1.67000000"],
      ["35321.95000000","2.40000000"],
      ["35321.90000000","4.36000000"],
      ["35321.85000000","1.24000000"]
    ],
    "asks": [
      ["35325.15000000","4.68000000"],
      ["35327.80000000","0.53000000"],
      ["35351.00000000","1.00000000"],
      ["35352.00000000","1.00000000"],
      ["35353.00000000","1.00000000"]
    ]
  }
}

Get orderbook by instrument

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
level	int	false	5	No. of depth, value range [1,50]

Response

Name	Type	Description
instrument_id	string	Instrument ID
timestamp	integer	Timestamp (data time)
asks	string	Asks array [price, qty]
bids	string	Bids array [price, qty]

Get market trades

GET /linear/v1/market/trades

curl "https://betaapi.bitexch.dev/linear/v1/market/trades?currency=USD"

{
  "code": 0,
  "message": "",
  "data": [
    {
      "created_at": 1642994704633,
      "trade_id": 1005483402,
      "instrument_id": "ETH-USD-PERPETUAL",
      "price": "2449.20000000",
      "qty": "1.00000000",
      "side": "sell",
      "sigma": "0.00000000",
      "index_price": "2447.79750000",
      "underlying_price": "0.00000000",
      "is_block_trade": false
    },
    {
      "created_at": 1642994704241,
      "trade_id": 1005483400,
      "instrument_id": "ETH-USD-PERPETUAL",
      "price": "2449.20000000",
      "qty": "1.00000000",
      "side": "sell",
      "sigma": "0.00000000",
      "index_price": "2447.79750000",
      "underlying_price": "0.00000000",
      "is_block_trade": false
    }
  ]
}

Get market trades by currency, category, option_type, instrument_id

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	true	""	Pair
category	string	false	""	Category
option_type	string	false	""	Option type
instrument_id	string	false	""	Instrument ID
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
count	int	false	100	Return record count(max 500)

Response

Name	Type	Description
trade_id	integer	Trade ID
instrument_id	string	Instrument ID
created_at	integer	Creation timestamp of the trade
price	string	Price
qty	string	Quantity
side	string	Order side
index_price	string	Index price
sigma	string	Implied volatility (option only)
underlying_price	string	Underlying price (option only)
is_block_trade	bool	Is block trade or not

Get klines

GET /linear/v1/klines

curl "https://betaapi.bitexch.dev/linear/v1/klines?instrument_id=BTC-USD-PERPETUAL&timeframe_min=1d"

{
  "code": 0,
  "message": "",
  "data": {
    "volume": [
      61311.6006,
      162957.1496,
      170906.31,
      167930.3642,
      57211.0637,
      95668.4807,
      129106.4048,
      87194.38,
      108983.3256,
      47231.55,
      2616.79
    ],
    "timestamps": [
      1642118400000,
      1642204800000,
      1642291200000,
      1642377600000,
      1642464000000,
      1642550400000,
      1642636800000,
      1642723200000,
      1642809600000,
      1642896000000,
      1642982400000
    ],
    "open": [
      42440,
      43069.2,
      43084.9,
      43074.6,
      42208.6,
      41637.7,
      41673.7,
      40705.05,
      36476.35,
      35068,
      36257.45
    ],
    "low": [
      42440,
      42588.3,
      42606.7,
      41557.9,
      41482.2,
      41000,
      40587,
      35556.25,
      34000.45,
      34688.5,
      35194.6
    ],
    "high": [
      43426.5,
      43773.4,
      43451.3,
      43170.9,
      42413.5,
      42538.2,
      43486.65,
      41093.2,
      36797.7,
      36480.6,
      36255.1
    ],
    "close": [
      43069.2,
      43084.9,
      43074.6,
      42208.6,
      41637.7,
      41673.7,
      40705.05,
      36476.35,
      35068,
      36257.45,
      35216.55
    ]
  }
}

Get klines by instrument. klines endpoint returns 6 time series of data: open price array, high price array, low price array, close price array, timestamp array of each kline, and volume array.

Support timeframes:

Timeframe	Name Desc
1	1 minute
3	3 minute
5	5 minute
15	15 minute
30	30 minute
60	60 minute
240	240 minute
1d	daily
1w	weekly
1m	monthly

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument Id
start_time	integer	true		Start timestamp millisecond
end_time	integer	true		End timestamp millisecond
timeframe_min	string	true	""	Timeframe
count	int	false	100	Result count (default 100, max 1000)

Response

Name	Type	Description
open	float array	Open price series
high	float array	High price series
low	float array	Low price series
close	float array	Close price series
timestamps	float array	Timestamp series
volume	float array	Volume series

Get market deliveries

GET /linear/v1/market/deliveries

curl "https://betaapi.bitexch.dev/linear/v1/market/deliveries?currency=USD"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-110-C",
            "position": "1.00000000",
            "exercise": true,
            "delivery_price": "115.63000000",
            "delivery_pnl": "5.63000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-110-P",
            "position": "1.00000000",
            "exercise": false,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.00000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-115-C",
            "position": "1.00000000",
            "exercise": true,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.63000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USD-26JUL22-115-P",
            "position": "1.00000000",
            "exercise": false,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.00000000"
        }
    ]
}

Get market delivery position information(delivered positions/pnl, exercise or not).

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID
limit	int	false	100	Return record count

Response

Name	Type	Description
type	string	delivery type("delivery")
timestamp	integer	Delivery time.
instrument_id	string	Instrument Id
position	string	Total delivered position of all long side users.
exercise	bool	Exercise or not
delivery_price	string	Delivery price
delivery_pnl	string	Delivery pnl of all long side users.

Get market settlement price info

GET /linear/v1/settlement_prices

curl "https://betaapi.bitexch.dev/linear/v1/settlement_prices?currency=USD&start_time=1600421456435&end_time=1603013456435"


{
  "code": 0,
  "message": "",
  "data": {
    "data": {
      "1642204800000": [
        {
          "date": 1642204800000,
          "currency": "USD",
          "instrument_id": "BCH-USD-PERPETUAL",
          "settlement_type": "settlement",
          "price": "389.66802679"
        },
        {
          "date": 1642204800000,
          "currency": "USD",
          "instrument_id": "BTC-USD-PERPETUAL",
          "settlement_type": "settlement",
          "price": "43076.50631543"
        },
        {
          "date": 1642204800000,
          "currency": "USD",
          "instrument_id": "ETH-USD-PERPETUAL",
          "settlement_type": "settlement",
          "price": "3313.20469611"
        }
      ]
    }
  }
}

Get settlement/delivery price history.
Time range filter is within 30 days.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
instrument_id	string	false	""	Instrument ID
start_time	integer	true		Start timestamp
end_time	integer	true		End timestamp

Response

Dictionary key is date in milliseconds, value is delivery/settlement record list

Name	Type	Description
date	integer	Delivery/settlement date in ms
currency	string	Currency
instrument_id	string	Instrument Id
settlement_type	string	`delivery` or `settlement`
price	string	Delivery/settlement price

Get market summary

GET /linear/v1/market/summary

curl "https://betaapi.bitexch.dev/linear/v1/market/summary?currency=USD&category=future"


{
  "code": 0,
  "message": "",
  "data": [
    {
      "instrument_id": "BTC-USD-PERPETUAL",
      "timestamp": 1642995368000,
      "best_bid": "35273.15000000",
      "best_ask": "35274.20000000",
      "best_bid_qty": "6.36000000",
      "best_ask_qty": "3.54000000",
      "last_price": "35274.20000000",
      "last_qty": "2.01000000",
      "open24h": "35064.40000000",
      "high24h": "36480.60000000",
      "low24h": "34688.50000000",
      "volume24h": "35162.74000000",
      "open_interest": "94.21840000",
      "mark_price": "35276.43209068",
      "max_buy": "35805.58000000",
      "min_sell": "34747.28000000",
      "delta": "",
      "gamma": "",
      "vega": "",
      "theta": ""
    }
  ]
}

Get market summary by instrument

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
category	string	true	""	Category
instrument_id	string	false	""	Instrument ID

Response

Name	Type	Description
instrument_id	string	Instrument ID
timestamp	integer	Timestamp
best_bid	string	Best bid price
best_ask	string	Best ask price
best_bid_qty	string	Best bid quantity
best_ask_qty	string	Best ask quantity
last_price	string	Last price
last_qty	string	Last quantity
open24h	string	Open price during previous 24 hour
high24h	string	Highest price during previous 24 hour
low24h	string	Lowest price during previous 24 hour
volume24h	string	Sum volume during previous 24 hour
open_interest	string	Open interest of current instrument_id
mark_price	string	Mark price
max_buy	string	Max price of buy order
min_sell	string	Min price of sell order
delta	string	Option delta
gamma	string	Option gamma
vega	string	Option vega
theta	string	Option theta

Get funding rate

GET /linear/v1/funding_rate

curl "https://betaapi.bitexch.dev/linear/v1/funding_rate?instrument_id=BTC-USD-PERPETUAL"


{
  "code": 0,
  "message": "",
  "data": {
    "instrument_id": "BTC-USD-PERPETUAL",
    "time": 1635913370000,
    "funding_rate": "0.00000000",
    "funding_rate_8h": "-0.00102858",
    "index_price": "62989.63000000",
    "mark_price": "62969.83608581"
  }
}

Get latest perpetual funding rate. Funding rate will be refreshed in every 10 seconds.

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID (perpetual only)

Response

Name	Type	Description
instrument_id	string	Instrument ID
time	integer	Timestamp
funding_rate	string	Current perpetual funding rate
funding_rate_8h	string	Past 8H avg funding rate, perpetual only
index_price	string	Index price
mark_price	string	Perpetual Mark price

Get funding rate history

GET /linear/v1/funding_rate_history

curl "https://betaapi.bitexch.dev/linear/v1/funding_rate_history?instrument_id=BTC-USD-PERPETUAL&start_time=1603260000000&end_time=1603346400000&history_type=1H"


{
    "code": 0,
    "message": "",
    "data": [
        {
            "instrument_id": "BTC-USD-PERPETUAL",
            "time": 1603263600000,
            "average_funding_rate": "0.00100000",
            "index_price": "8880.17000000",
            "mark_price": "8900.18000000"
        }
    ]
}

Note: Start time must be greater than 2020.10.31 (timestamp: 1604102400000).

Get the funding rate history within a given time period. History type can be 1H/8H/24H.

Returns average funding rate of the past 1 hour at each 3 minutes in the period, or returns average funding rate of the past 8 hours/24 hours at each hour in the period.

For 1H, the query time period cannot exceed 1 days, and for 8H/24H, the query time period cannot exceed 30 days.

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID (perpetual only)
start_time	integer	true		Start timestamp
end_time	integer	true		End timestamp
history_type	string	true		1H/8H/24H

Response

Name	Type	Description
instrument_id	string	Instrument ID
time	integer	Timestamp
average_funding_rate	string	The past 1H/8H/24H average history funding rate for this time
index_price	string	Index price
mark_price	string	Perpetual Mark price

Get all market volume

GET /linear/v1/total_volumes

curl "https://betaapi.bitexch.dev/linear/v1/total_volumes"

{
  "code": 0,
  "message": "",
  "data": {
    "total_usdx_volume_24_hours": "11771592083.60040000",
    "details": [
      {
        "margin_currency": "USD",
        "usdx_option_volume_in_usd": "10000055.21000000",
        "usdx_future_volume_in_usd": "10604770109.18810000"
      },
      {
        "margin_currency": "USDT",
        "usdx_option_volume_in_usd": "0.00000000",
        "usdx_future_volume_in_usd": "1156821919.20230000"
      }
    ]
  }
}

Get all market volumes of previous 24 hours.
This endpoint will be cached with 5 seconds, client request multiple times within sort period of time will get unchanged result.

Query parameters

None

Response

Name	Type	Description
total_usdx_volume_24_hours	string	Total USD-M volume
details	array	Volume details

details

Name	Type	Description
margin_currency	string	Margin Currency
usdx_option_volume_in_usd	string	Option Volume in USD
usdx_future_volume_in_usd	string	Future Volume in USD

Account

Get UM user accounts

GET /um/v1/accounts


curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/um/v1/accounts?timestamp=1589521383462&signature=30f7cf5c8018f5dfee515533e25a1813e9120be7898b62fb85a2f4129f3e9528"


{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 481554,
        "created_at": 1649923879505,
        "total_collateral": "3170125.05978108",
        "total_margin_balance": "3170125.05978108",
        "total_available": "3169721.64891398",
        "total_initial_margin": "403.41086710",
        "total_maintenance_margin": "303.16627631",
        "total_initial_margin_ratio": "0.00012725",
        "total_maintenance_margin_ratio": "0.00009563",
        "total_liability": "0.00000000",
        "total_unsettled_amount": "-0.84400340",
        "total_future_value": "1.26000000",
        "total_option_value": "0.00000000",
        "spot_orders_hc_loss": "0.00000000",
        "total_position_pnl": "1225.53245820",
        "details": [
            {
                "currency": "BTC",
                "equity": "78.13359310",
                "liability": "0.00000000",
                "index_price": "41311.20615385",
                "cash_balance": "78.13360190",
                "margin_balance": "78.13359310",
                "available_balance": "78.12382795",
                "initial_margin": "0.00976516",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00733859",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.02966586",
                "total_delta": "0.48532539",
                "session_rpl": "0.00001552",
                "session_upl": "-0.00003595",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_value": "1.23000000",
                "future_pnl": "0.02966586",
                "future_session_rpl": "0.00001552",
                "future_session_upl": "-0.00003595",
                "future_session_funding": "0.00001552",
                "future_delta": "0.48532539",
                "future_available_balance": "76.72788921",
                "option_available_balance": "76.72788921",
                "unsettled_amount": "-0.00002043",
                "usdt_index_price": "41311.20615385"
            },
            {
                "currency": "ETH",
                "equity": "1.99960000",
                "liability": "0.00000000",
                "index_price": "3119.01923077",
                "cash_balance": "1.99960000",
                "margin_balance": "1.99960000",
                "available_balance": "1.99960000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.00000000",
                "total_delta": "0.00000000",
                "session_rpl": "0.00000000",
                "session_upl": "0.00000000",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_value": "0.03000000",
                "future_pnl": "0.00000000",
                "future_session_rpl": "0.00000000",
                "future_session_upl": "0.00000000",
                "future_session_funding": "0.00000000",
                "future_delta": "0.00000000",
                "future_available_balance": "1.99960000",
                "option_available_balance": "1.99960000",
                "unsettled_amount": "0.00000000",
                "usdt_index_price": "3119.01923077"
            }
        ],
        "usdt_total_collateral": "3170125.05978108",
        "usdt_total_margin_balance": "3170125.05978108",
        "usdt_total_available": "3169721.64891398",
        "usdt_total_initial_margin": "403.41086710",
        "usdt_total_maintenance_margin": "303.16627631",
        "usdt_total_initial_margin_ratio": "0.00012725",
        "usdt_total_maintenance_margin_ratio": "0.00009563",
        "usdt_total_liability": "0.00000000",
        "usdt_total_unsettled_amount": "-0.84400340"
    }
}

USD-M products can only be traded by UM mode users.
um mode,get account information with this endpoint.

total_initial_margin_ratio

PM	total_initial_margin_ratio calculation formula
true	(total_im + spot_haircut_loss) / collateral
false	(total_im + spot_haircut_loss) / margin_balance

In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation

total_maintenance_margin_ratio

PM	total_maintenance_margin_ratio calculation formula
true	total_maintenance_margin / collateral
false	total_maintenance_margin / margin_balance

In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation

Query parameters

Parameter	Type	Required	Default	Description
with_linear_pair_margins	string	false	""	Return margins grouped by linear pairs in field `linear_pair_margins`. only for Portfolio Margin mode.

Response

Name	Type	Desc
user_id	int	User Id
created_at	int	Timestamp (query time)
total_collateral	string	Total Collateral (USD)
total_margin_balance	string	Total Margin Balance (USD)
total_available	string	Total Available (USD)
total_initial_margin	string	Total Initial Margin (USD)
total_maintenance_margin	string	Total Maintenance Margin (USD)
total_initial_margin_ratio	string	Total Initial Margin Ratio, may returns "infinity" (USD)
total_maintenance_margin_ratio	string	Total Maintenance Margin Ratio, may returns "infinity" (USD)
total_liability	string	Total liability (USD)
total_unsettled_amount	string	Total unsettled amount (USD)
total_future_value	string	Total future market value
total_option_value	string	Total option market value
spot_orders_hc_loss	string	Total spot order haircut loss
total_position_pnl	string	Total position PnL in USD [SUM(ccy.pnl * ccy.index-price)]
details	array	Details, array of currency level detail
usdt_total_collateral	string	(For compatibility) equal to total_collateral
usdt_total_margin_balance	string	(For compatibility) equal to total_margin_balance
usdt_total_available	string	(For compatibility) equal to total_available
usdt_total_initial_margin	string	(For compatibility) equal to total_initial_margin
usdt_total_maintenance_margin	string	(For compatibility) equal to total_maintenance_margin
usdt_total_initial_margin_ratio	string	(For compatibility) equal to total_initial_margin_ratio
usdt_total_maintenance_margin_ratio	string	(For compatibility) equal to total_maintenance_margin_ratio
usdt_total_liability	string	(For compatibility) equal to total_liability
usdt_total_unsettled_amount	string	(For compatibility) equal to total_unsettled_amount

Currency level detail

Name	Type	Desc
currency	string	Currency
equity	string	Equity
liability	string	Liability
index_price	string	Index price (USD)
usdt_index_price	string	(For compatibility) equal to index_price
cash_balance	string	Cash Balance
margin_balance	string	Margin Balance
available_balance	string	Account Available Balance
initial_margin	string	Initial Margin
spot_margin	string	Spot Margin
maintenance_margin	string	Maintenance Margin
potential_liability	string	Potential Liability
interest	string	Interest
interest_rate	string	Interest Rate
pnl	string	Currency level position P&L
total_delta	string	Total delta of account
session_rpl	string	Session realized pnl
session_upl	string	Session unrealized pnl
option_value	string	Option market value
option_pnl	string	Option P&L
option_session_rpl	string	Option session realized P&L
option_session_upl	string	Option session unrealized P&L
option_delta	string	Option delta
option_gamma	string	Option gamma
option_vega	string	Option vega
option_theta	string	Option theta
future_value	string	Future market value
future_pnl	string	Future P&L
future_session_rpl	string	Future session realized P&L
future_session_upl	string	Future session unrealized P&L
future_session_funding	string	Future session funding
future_delta	string	Future delta
future_available_balance	string	Available balance for new futures order
option_available_balance	string	Available balance for new option order
unsettled_amount	string	Unsettled amount

Linear pair margins

returns an array in field linear_pair_margins, when add query param with_linear_pair_margins=true. only for Portfolio Margin mode.

Name	Type	Desc
pair	string	linear pair
initial_margin	string	Initial Margin for pair
maintenance_margin	string	Maintenance Margin for pair

Get UM user transactions

GET /um/v1/transactions

curl -H "X-Bit-Access-Key: ak-8e97ac6c-8075-4a94-b2bb-38bd537619fa" "https://betaapi.bitexch.dev/um/v1/transactions?currency=BTC&type=trade-recv&limit=2&timestamp=1620369292928&signature=35d76033f6e251ce85524ec4310417fd555953fff00cd33f3a94e3d27d062965"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "tx_time": 1631240595162,
            "tx_type": "deposit",
            "ccy": "BTC",
            "instrument_id": "",
            "direction": "",
            "qty": "3.20000000",
            "price": "",
            "position": "",
            "fee_paid": "0.00000000",
            "fee_rate": "",
            "funding": "",
            "change": "3.20000000",
            "balance": "107.00000000",
            "order_id": "",
            "trade_id": "",
            "remark": ""
        },
        {
            "tx_time": 1630722195162,
            "tx_type": "spot-trade-recv",
            "ccy": "BTC",
            "instrument_id": "BTC-USD",
            "direction": "buy",
            "qty": "2.00000000",
            "price": "60000.00000000",
            "position": "",
            "fee_paid": "0.00030000",
            "fee_rate": "0.00000000",
            "funding": "",
            "change": "2.00000000",
            "balance": "102.00000000",
            "order_id": "9001",
            "trade_id": "3001",
            "remark": ""
        }
    ],
    "page_info": {
        "has_more": false
    }
}

USD-M products can only be traded by UM mode users.
UM mode,user gets transaction logs with this endpoint.

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	false	""	Currency
instrument_id	string	false	""	Instrument ID
start_time	integer	false	One month ago	Start timestamp millisecond
end_time	integer	false	Now	End timestamp millisecond
type	string	false	""	UM Transaction type
offset	int	false	1	Page index, first page = 1
limit	int	false	100	Page size

Response

Name	Type	Desc
tx_time	integer	Transaction time
tx_type	string	UM Transaction type
ccy	string	Currency
instrument_id	string	Instrument Id
direction	string	buy/sell
qty	string	Qty
price	string	Trade price (for trade transactions)
position	string	Futures/Options position
fee_paid	string	Fee paid
fee_rate	string	Fee rate
funding	string	Perpetual funding
change	string	Change
cash_flow	string	Cashflow(spot cash_flow=change, derivatives cash_flow please refer to derivatives doc for transactions)
balance	string	Balance after change
order_id	string	Order ID
trade_id	string	Trade ID
remark	string	Remark

GET account configs

GET /linear/v1/account_configs

curl -H "X-Bit-Access-Key: ak-7656c65e-6643-4668-807f-32d84a60eda5" "https://betaapi.bitexch.dev/linear/v1/account_configs?timestamp=1677679210295&signature=1273631a3152f5ad6dca3258788b3f7dc39373fcd7c3ab2c22b1080acee56d60"

{
    "code": 0,
    "message": "",
    "data": {
        "ccy_open_params": [
            {
                "ccy": "USD",
                "ccy_display_name": "USD",
                "is_pm": false,
                "is_cust": false,
                "max_open_count": 1000,
                "max_option_open_count_by_ccy": 1000,
                "max_option_open_count_by_instrument": 50,
                "max_future_open_count_by_ccy": 1000,
                "max_future_open_count_by_instrument": 100,
                "max_option_total_usd_pos_by_ccy": "10000000.00000000",
                "max_future_total_usd_pos_by_ccy": "10000000000.00000000",
                "max_total_usd_pos_by_ccy": "10000000.00000000",
                "max_stop_open_count": 50
            },
            {
                "ccy": "USDT",
                "ccy_display_name": "USDT",
                "is_pm": false,
                "is_cust": false,
                "max_open_count": 50,
                "max_option_open_count_by_ccy": 50,
                "max_option_open_count_by_instrument": 20,
                "max_future_open_count_by_ccy": 50,
                "max_future_open_count_by_instrument": 50,
                "max_option_total_usd_pos_by_ccy": "10000000.00000000",
                "max_future_total_usd_pos_by_ccy": "10000000.00000000",
                "max_total_usd_pos_by_ccy": "10000000.00000000",
                "max_stop_open_count": 50
            }
        ],
        "pairs": [
            {
                "base_ccy": "BTC",
                "quote_ccy": "USD",
                "base_display_name": "BTC",
                "quote_display_name": "USD",
                "customize_future_fee_rates": false,
                "perpetual_taker_fee_rate": "0.00080000",
                "perpetual_maker_fee_rate": "-0.00020000",
                "customize_option_fee_rates": true,
                "option_taker_fee_rate": "0.00020000",
                "option_maker_fee_rate": "0.00010000",
                "customize_blocktrades": true,
                "blocktrade_future_min_order_price": "0.00100000",
                "blocktrade_future_max_order_price": "1000000.00000000",
                "blocktrade_future_min_order_qty": "0.00100000",
                "blocktrade_future_max_order_qty": "40000.00000000",
                "blocktrade_future_price_step": "0.00100000",
                "blocktrade_future_size_step": "0.00100000",
                "blocktrade_option_min_order_price": "0.00100000",
                "blocktrade_option_max_put_price": "500.00000000",
                "blocktrade_option_min_order_qty": "0.00100000",
                "blocktrade_option_max_order_qty": "1000000.00000000",
                "blocktrade_option_price_step": "0.00100000",
                "blocktrade_option_size_step": "0.00100000",
                "customize_pos_limit": false,
                "future_pos_limit_by_pair": "500000.00000000",
                "option_pos_limit_by_pair": "1000000.00000000"
            }
        ],
        "feerate_class_list": [
            {
                "base_ccy": "BTC",
                "quote_ccy": "USD",
                "base_display_name": "BTC",
                "quote_display_name": "USD",
                "perpetual_fee_rate_info": {
                    "pair": "BTC-USD",
                    "taker_fee_rate": "0.00300000",
                    "maker_fee_rate": "0.00100000",
                    "source": "vip_manual",
                    "taker_basic": "0.00080000",
                    "maker_basic": "0.00020000",
                    "taker_user_defined": "",
                    "maker_user_defined": "",
                    "taker_vip_level": "0.00300000",
                    "maker_vip_level": "0.00100000",
                    "has_vip_level": true,
                    "vip_level": 2
                },
                "option_fee_rate_info": {
                    "pair": "BTC-USD",
                    "taker_fee_rate": "0.00700000",
                    "maker_fee_rate": "0.00200000",
                    "source": "vip_manual",
                    "taker_basic": "0.00100000",
                    "maker_basic": "0.00050000",
                    "taker_user_defined": "",
                    "maker_user_defined": "",
                    "taker_vip_level": "0.00700000",
                    "maker_vip_level": "0.00200000",
                    "has_vip_level": true,
                    "vip_level": 2
                }
            }
        ]        
    }
}

Query user account USD-M configs.

Query parameters

NONE

Response

Name	Type	Desc
pairs	array	Pair configs
ccy_open_params	array	Margin currency level open order configs

Pair config

Name	Type	Description
base_ccy	string	Base ccy
quote_ccy	string	Quote ccy
base_display_name	string	Base display name
quote_display_name	string	Quote display name
customize_future_fee_rates	bool	Customize future fee rates or not(deprecated, Use feerate class now)
perpetual_taker_fee_rate	string	Perpetual taker fee rate(deprecated, Use feerate class now)
perpetual_maker_fee_rate	string	Perpetual maker fee rate(deprecated, Use feerate class now)
customize_option_fee_rates	bool	Customize option fee rates or not(deprecated, Use feerate class now)
option_taker_fee_rate	string	Option taker fee rate(deprecated, Use feerate class now)
option_maker_fee_rate	string	Option maker fee rate(deprecated, Use feerate class now)
customize_blocktrades	bool	Customize blocktrade params or not
blocktrade_future_min_order_price	string	Blocktrade future min order price
blocktrade_future_max_order_price	string	Blocktrade future max order price
blocktrade_future_min_order_qty	string	Blocktrade future min order qty
blocktrade_future_max_order_qty	string	Blocktrade future max order qty
blocktrade_future_price_step	string	Blocktrade future price step
blocktrade_future_size_step	string	Blocktrade future size step
blocktrade_option_min_order_price	string	Blocktrade option min order price
blocktrade_option_max_put_price	string	Blocktrade option max put price
blocktrade_option_min_order_qty	string	Blocktrade option min order qty
blocktrade_option_max_order_qty	string	Blocktrade option max order qty
blocktrade_option_price_step	string	Blocktrade option price step(quote_ccy)
blocktrade_option_size_step	string	Blocktrade option size step
customize_pos_limit	bool	Customize pos limit or not
future_pos_limit_by_pair	string	Future pos limit by pair
option_pos_limit_by_pair	string	Option pos limit by pair

Feerate class list

Name	Type	Description
base_ccy	string	Base ccy
quote_ccy	string	Quote ccy
base_display_name	string	Base display name
quote_display_name	string	Quote display name
perpetual_fee_rate_info.pair	string	Pair
perpetual_fee_rate_info.has_vip_level	bool	User has vip level or not
perpetual_fee_rate_info.vip_level	integer	User vip level
perpetual_fee_rate_info.taker_basic	string	perpetual taker feerate of instrument config
perpetual_fee_rate_info.maker_basic	string	perpetual maker feerate of instrument config
perpetual_fee_rate_info.taker_user_defined	string	perpetual taker feerate of user defined
perpetual_fee_rate_info.maker_user_defined	string	perpetual maker feerate of user defined
perpetual_fee_rate_info.taker_vip_level	string	perpetual taker feerate of vip level
perpetual_fee_rate_info.maker_vip_level	string	perpetual maker feerate of vip level
perpetual_fee_rate_info.source	string	Feerate source
perpetual_fee_rate_info.taker_fee_rate	string	Final effective perpetual taker feerate
perpetual_fee_rate_info.maker_fee_rate	string	Final effective perpetual maker feerate
option_fee_rate_info.pair	string	Pair
option_fee_rate_info.has_vip_level	bool	User has vip level or not
option_fee_rate_info.vip_level	integer	User vip level
option_fee_rate_info.taker_basic	string	option taker feerate of instrument config
option_fee_rate_info.maker_basic	string	option maker feerate of instrument config
option_fee_rate_info.taker_user_defined	string	option taker feerate of user defined
option_fee_rate_info.maker_user_defined	string	option maker feerate of user defined
option_fee_rate_info.taker_vip_level	string	option taker feerate of vip level
option_fee_rate_info.maker_vip_level	string	option maker feerate of vip level
option_fee_rate_info.source	string	Feerate source
option_fee_rate_info.taker_fee_rate	string	Final effective option taker feerate
option_fee_rate_info.maker_fee_rate	string	Final effective option maker feerate

Currency open order config

Name	Type	Description
ccy	string	Ccy
ccy_display_name	string	Ccy display name
is_pm	bool	Is pm or not
is_cust	bool	Is customization or not
max_open_count	integer	Max open count
max_option_open_count_by_ccy	integer	Max option open count by ccy
max_option_open_count_by_instrument	integer	Max option open count by instrument
max_future_open_count_by_ccy	integer	Max future open count by ccy
max_future_open_count_by_instrument	integer	Max future open count by instrument
max_option_total_usd_pos_by_ccy	string	Max option total usd pos by ccy
max_future_total_usd_pos_by_ccy	string	Max future total usd pos by ccy
max_total_usd_pos_by_ccy	string	Max total usd pos by ccy （future + option)
max_stop_open_count	integer	Max stop open count

Get interest records

GET /um/v1/interest_records


curl -H "X-Bit-Access-Key: ak-8e97ac6c-8075-4a94-b2bb-38bd537619fa" "https://betaapi.bitexch.dev/um/v1/interest_records?currency=BTC&timestamp=1631669478618&signature=3d4685f07751cd51f42ee631938f189cbe6e9712cc6d559881e5b3b6d1ba1224"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "currency": "BTC",
            "time": 1631559600000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.05000000"
        },
        {
            "currency": "BTC",
            "time": 1631556000000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.06000000"
        },
        {
            "currency": "BTC",
            "time": 1631552400000,
            "loan_rate": "0.00300000",
            "liability": "100.00000000",
            "interest": "1.07000000"
        }
    ],
    "page_info": {
        "has_more": true
    }
}

Get UM interest records.

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Currency
start_time	integer	false	One month ago	Start timestamp millisecond
end_time	integer	false	Now	End timestamp millisecond
offset	int	false	1	Page index, first page = 1
limit	int	false	100	Page size

Response

Name	Type	Desc
currency	string	Currency
time	integer	Interest accrual time
loan_rate	string	Annual interest rate
liability	string	liability
interest	string	Accrued interest

Get user positions

GET /linear/v1/positions

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/positions?currency=USD&instrument_id=BTC-USD-PERPETUAL&timestamp=1589521619990&signature=9a7f7704cb4d6ec3cd2dccbd55e09ce8abd1ffb48529a742337706dd1a43eea8"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "instrument_id": "BTC-USD-PERPETUAL",
            "expiration_at": 4102444800000,
            "qty": "-0.20000000",
            "initial_margin": "67.04199679",
            "maintenance_margin": "50.30660069",
            "avg_price": "17047.79250000",
            "session_avg_price": "16785.93357500",
            "mark_price": "16735.39610357",
            "index_price": "16819.49357143",
            "last_price": "16648.00000000",
            "qty_base": "-0.20000000",
            "liq_price": "7651872.25400846",
            "session_funding": "-50.22633841",
            "position_pnl": "62.47927929",
            "position_session_upl": "10.10749429",
            "position_session_rpl": "-50.22633841",
            "category": "future",
            "roi": "0.93194240",
            "leverage": "50.00000000"
        }
    ]
}

Get user positions. qty and qty_base has direction information, positive value means long, negative value means short.

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID

Response

Name	Type	Desc
instrument_id	string	Instrument ID
qty	string	Signed position size in COIN (base currency)
qty_base	string	Signed position size in COIN (base currency)
avg_price	string	Average filled price
index_price	string	Index price
mark_price	string	Mark price
initial_margin	string	Initial margin
maintenance_margin	string	Maintenance margin
session_avg_price	string	Session average price
session_funding	string	Session funding
position_pnl	string	Position P&L
position_session_upl	string	Position session unrealized P&L
position_session_rpl	string	Position session realized P&L
category	string	Category
roi	string	Return on investment
option_delta	string	Option delta(omitted for future)
option_gamma	string	Option gamma(omitted for future)
option_vega	string	Option vega(omitted for future)
option_theta	string	Option theta(omitted for future)
liq_price	string	Estimated liquidation price(Future)
leverage	string	Position leverage(Future)

Get user deliveries

GET /linear/v1/user/deliveries

curl -H "X-Bit-Access-Key: ak-8628663d-678c-49b0-8d4e-a8691152a2d0" "https://betaapi.bitexch.dev/linear/v1/user/deliveries?currency=USD&pair=BTC-USD&timestamp=1659186383799&signature=cc17d4d9f67aabb254ba58085ea6bf498122d88cdf0f991e983674c1bb3a1e2b"

{
    "code": 0,
    "message": "",
    "data": [{
        "type": "delivery",
        "timestamp": 1588492890000,
        "instrument_id": "BTC-30JUL22-23000-C",
        "position": "1.00000000",
        "exercise": true,
        "delivery_price": "23950.37000000",
        "delivery_pnl": "170.60000680"
    }]
}

Get user delivery records

Query Parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
instrument_id	string	false	""	Instrument ID
start_time	integer	false	0	Start timestamp
end_time	integer	false	0	End timestamp
count	int	false	100	Record count (default 100, max 500)

Response

Name	Type	Desc
type	string	Settlement type (delivery)
instrument_id	string	Instrument ID
position	string	Settled position
timestamp	integer	Delivery timestamp
exercise	boolean	Exercised or not
delivery_price	string	Delivery price
delivery_pnl	string	Delivery P&L

Get user settlements

GET /linear/v1/user/settlements


curl -H "X-Bit-Access-Key: ak-c1d4bc58-37f3-49da-93b5-396ab44b1543" "https://betaapi.bitexch.dev/linear/v1/user/settlements?currency=BTC&offset=1&limit=10&timestamp=1590851451072&signature=538b4ed2b917db4c96e12ddb5daafe84b58f566173f4d003533c19ccc32ff177"

{
    "code": 0,
    "message": "",
    "data": [{
        "type": "settlement",
        "timestamp": 1590825600000,
        "instrument_id": "BTC-USD-PERPETUAL",
        "position": "-28.00000000",
        "direction": "short",
        "session_upl": "-1000.02754390",
        "session_rpl": "1343.00125935",
        "session_funding": "-973.00028997",
        "price": "32000"
    }]
}

Get user settlements (only for future currently)

Query Parameters

Parameter	Type	Required	Default	Description
settlement_currency	string	true	""	Settlement Currency
instrument_id	string	false	""	Instrument ID
start_time	integer	false	0	Start timestamp
end_time	integer	false	0	End timestamp
offset	int	false	1	Page index, first page = 1
limit	int	false	100	Page size

Response

Name	Type	Desc
type	string	Settlement type (settlement)
timestamp	integer	Timestamp
instrument_id	string	Instrument
position	string	settled Position
direction	string	Position direction
session_upl	string	Session unrealized pnl
session_rpl	string	Session realized pnl
session_funding	string	Future session funding
price	string	Settlement price

Get Mmp State

GET /linear/v1/mmp_state

curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/linear/v1/mmp_state?timestamp=1600050649936&signature=3a3c511ab776674c4a8db31135f22c8bf2bc5aac4eb0070c8c4d577e89e01643"

{
    "code": 0,
    "message": "",
    "data": {
        "mmp_enabled": true,
        "mmp_user_configurable": true,
        "mmp_data": [
            {
                "pair": "BTC-USD",
                "mmp_config": {
                    "window_ms": 2000,
                    "frozen_period_ms": 10000,
                    "qty_limit": "30.00000000",
                    "delta_limit": "10.00000000"
                },
                "mmp_state": {
                    "mmp_frozen_until_ms": -1,
                    "mmp_frozen": false
                }
            },
            {
                "pair": "ETH-USD",
                "mmp_config": {
                    "window_ms": 5000,
                    "frozen_period_ms": 100,
                    "qty_limit": "100.00000000",
                    "delta_limit": "100.00000000"
                },
                "mmp_state": {
                    "mmp_frozen_until_ms": -1,
                    "mmp_frozen": false
                }
            },
            {
                "pair": "BCH-USD",
                "mmp_config": {
                    "window_ms": 5000,
                    "frozen_period_ms": 100,
                    "qty_limit": "100.00000000",
                    "delta_limit": "100.00000000"
                },
                "mmp_state": {
                    "mmp_frozen_until_ms": -1,
                    "mmp_frozen": false
                }
            },
        ]
    }
}

Get Mmp State.

mmp_enabled
Mmp is enabled or not.

mmp_user_configurable
User can edit mmp config or not. if yes, user can change mmp config through POST /linear/v1/update_mmp_config

mmp_data
Mmp configuration & status detail for each currency pair

mmp_frozen_until_ms
mmp_frozen_until_ms indicate mmp frozen status, it's updated by backend.
mmp_frozen_until_ms > 0: frozen until this timestamp or a manual reset
mmp_frozen_until_ms = 0: frozen until a manual reset
mmp_frozen_until_ms = -1: not frozen (a manual reset sets mmp_frozen_until_ms to -1)

mmp_frozen
Indicate mmp is frozen or not.

Query parameters

None

Response

Name	Type	Desc
mmp_enabled	bool	Mmp is enabled or not
mmp_user_configurable	bool	User can edit mmp config or not
mmp_data	array	Array of mmp data (pair name, config & status detail, see below)

mmp_config

Name	Type	Desc
window_ms	integer	Mmp rolling windows time span (milliseconds)
frozen_period_ms	integer	Mmp frozen time span (milliseconds)
qty_limit	string	Mmp quantity limit (in base currency, e.g. BTC)
delta_limit	string	Mmp delta limit (in base currency, e.g. BTC)

mmp_state

Name	Type	Desc
mmp_frozen_until_ms	integer	Mmp frozen until timestamp (backend update automatically)
mmp_frozen	bool	Mmp is frozen or not

Update Mmp Config

POST /linear/v1/update_mmp_config

curl -X POST "https://betaapi.bitexch.dev/linear/v1/update_mmp_config" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"pair": "BTC-USD", "window_ms": 20000, "frozen_period_ms": 30000, "qty_limit": "1000.00000000", "delta_limit": "1000.00000000", "timestamp": 1600050944127, "signature": "661b535fa878633718922fd90b419de4b5d9ae447833876b91bc8bcc7906e0f3"}'

{
    "code": 0,
    "message": "",
    "data": "ok"
}

Update mmp config, only when mmp.user_configurable = true, otherwise returns error.

Mmp frozen state will be triggered when qty >= qty_limit OR abs(delta) >= delta_limit.

window_ms: Mmp rolling windows time span (milliseconds)
frozen_period_ms: Mmp frozen time span (milliseconds)
qty_limit: Mmp quantity limit (in base currency, e.g. BTC)
delta_limit: Mmp delta limit (in base currency, e.g. BTC)

Post json body

Parameter	Type	Required	Default	Description
pair	string	true	""	Currency pair
window_ms	integer	true	0	Mmp rolling windows time span (milliseconds)
frozen_period_ms	integer	true	0	Mmp frozen time span (milliseconds)
qty_limit	string	true	""	Mmp quantity limit (in base currency, e.g. BTC)
delta_limit	string	true	""	Mmp delta limit (in base currency, e.g. BTC)

Response

Name	Type	Desc
data	string	ok

Reset Mmp State

POST /linear/v1/reset_mmp

curl -X POST "https://betaapi.bitexch.dev/linear/v1/reset_mmp" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"pair": "BTC-USD", "timestamp": 1600050689085, "signature": "992507afc30728c2bc55d7bf7f47e76126ce3f40ddebc205594877381c4374fa"}'

{
    "code": 0,
    "message": "",
    "data": "ok"
}

Reset mmp frozen state, then user is able to place new order.

Post json body

Parameter	Type	Required	Default	Description
pair	string	true	""	Currency pair

Response

Name	Type	Desc
data	string	ok

Query leverage ratio

GET /linear/v1/leverage_ratio

curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/linear/v1/leverage_ratio?pair=BTC-USD&timestamp=1600050649936&signature=a6f2511ab776674c4a9db39835f22c8bf2bc5aac4eb0070c8c4d577e89e016ef"

{
    "code": 0,
    "message": "",
    "data": {
        "pair": "BTC-USD",
        "leverage_ratio": "20.00000000"
    }
}

Query user leverage ratio

Query parameters

Parameter	Type	Required	Default	Description
pair	string	true	""	Pair

Response

Name	Type	Desc
pair	string	Pair
leverage_ratio	string	Leverage ratio

Update leverage ratio

POST /linear/v1/leverage_ratio

curl -X POST "https://betaapi.bitexch.dev/linear/v1/leverage_ratio" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"pair": "BTC-USD", "leverage_ratio": "10.00000000", "timestamp": 1600050944127, "signature": "251b535fa878633718922fd90b419de4b5d9ae447833876b91bc8bcc7906ee72"}'


{
    "code": 0,
    "message": "",
    "data": {
        "pair": "BTC-USD",
        "leverage_ratio": "10.00000000"
    }
}

Update leverage ratio

Post json body

Parameter	Type	Required	Default	Description
pair	string	true	""	Pair
leverage_ratio	string	true	0	New leverage ratio

Response

Name	Type	Desc
pair	string	Pair
leverage_ratio	string	Leverage ratio

Order

Place new order

POST /linear/v1/orders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id": "BTC-USD-PERPETUAL", "price": "5000", "qty": "3", "side": "buy", "time_in_force": "gtc", "auto_price": "", "label":"hedge", "hidden": false, "timestamp": 1589523989378, "signature": "68b658eb68f4ce529623bb4505f5c1c6408b37064a9a5f2102d08088e59d917c"}'

{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "17552314",
        "created_at": 1589523803017,
        "updated_at": 1589523803017,
        "user_id": "51140",
        "instrument_id": "BTC-USD-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "50000.00000000",
        "qty": "3.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "open",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label":"hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp":false,
        "source": "api",
        "hidden": false
    }
}

Place new order.
For market order, price is not required.
Order type default value is 'limit'.
Time in force default value is 'gtc'.
Order qty unit is coin/base-currency (e.g. BTC)

Conditional order:
* Order type should be trigger-market/trigger-limit.
* stop_price is the target trigger price. price is the order price after triggered
* Support triggered by last-price now.

Auto price type:
base: When place order, set [auto price type] = "base", and [auto price] = base ccy price, order price will be automatically calculated as order_price(usd) = auto_price * underlying_price, and order will be automatically re-quoted every 6s to maintain the usd price

iv: When place order, set [auto price type] = "iv", and [auto price] = implied volatility value, order price will be automatically calculated as order_price = convert_iv_to_usd(auto_price), , and order will be automatically re-quoted every 6s to maintain the implied volatility. Example: input 85.56 for 85.56% implied volatility

bbo order:When bbo is true, auto set limit price (ask0 for buy order, bid0 for sell order), if orderbook is not available, set limit price to mark price. (Batch order not supported)

Post json body

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
qty	string	true	""	Order size (positive number)
side	string	true	""	Order side
price	string	false	"0.0"	Order price, not required for market order
order_type	string	false	"limit"	Order type
time_in_force	string	false	"gtc"	Time in force
auto_price_type	string	false	""	Usdx Auto price type
auto_price	string	false	""	Auto price, only if auto price type in ('base','iv') *iv is in percentage, ie. input 85.56 for 85.56%
stop_price	string	false	""	Stop price(or conditional order target price)
trigger_type	string	false	""	conditional order trigger type (mark-price/last-price)
label	string	false	""	User defined label
post_only	bool	false	false	Indicate post only or not. if `reject_post_only` is true, order can not enter book will be cancelled. if `reject_post_only` is false, price will be changed when order can't enter orderbook.
reject_post_only	bool	false	false	Indicate reject post only or not
bbo	bool	false	false	Indicate bbo order or not
mmp	bool	false	false	Indicate mmp order or not
hidden	bool	false	false	Indicate hidden order or not, hidden order won't show in public orderbook

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not

Place batch orders

POST /linear/v1/batchorders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency":"USD", "orders_data": [{"instrument_id": "BTC-USD-", "price": "50000", "qty": "1.5", "side": "buy", "hidden": true}, {"instrument_id": "BTC-USD-PERPETUAL", "price": "50010", "qty": "2", "side": "sell"}], "timestamp": 1596782252388, "signature": "0b8b64d2f35f9742a17af4ee0b993d0248a27a98f320abbfe8e7316f184e30d5"}'

{
    "code": 0,
    "message": "",
    "data": {
        "orders": [
            {
                "order_id": "",
                "created_at": 0,
                "updated_at": 0,
                "user_id": "",
                "instrument_id": "",
                "order_type": "",
                "side": "",
                "price": "",
                "qty": "",
                "time_in_force": "",
                "avg_price": "",
                "filled_qty": "",
                "status": "",
                "is_liquidation": false,
                "auto_price": "",
                "auto_price_type": "",
                "taker_fee_rate": "",
                "maker_fee_rate": "",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": true,
                "error_code": 18100185,
                "error_msg": "Invalid instrument BTC-USD-"
            },
            {
                "order_id": "501758",
                "created_at": 1596782252996,
                "updated_at": 1596782252996,
                "user_id": "51140",
                "instrument_id": "BTC-USD-PERPETUAL",
                "order_type": "limit",
                "side": "sell",
                "price": "50010.00000000",
                "qty": "2.00000000",
                "time_in_force": "gtc",
                "avg_price": "0.00000000",
                "filled_qty": "0.00000000",
                "status": "open",
                "is_liquidation": false,
                "auto_price": "0.00000000",
                "auto_price_type": "",
                "taker_fee_rate": "0.00045000",
                "maker_fee_rate": "0.00025000",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": false,
                "error_code": 0,
                "error_msg": ""
            }
        ]
    }
}

Place batch order.
Provide order array, order parameter details are the same as POST /linear/v1/orders.
conditional order is not supported.
Max order request count is 10.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
orders_data	array	true		Order request list(see below)

order request detail

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
qty	string	true	""	Order size (positive number)
side	string	true	""	Order side
price	string	false	"0.0"	Order price, not required for market order
order_type	string	false	"limit"	Order type
time_in_force	string	false	"gtc"	Time in force
label	string	false	""	User defined label
post_only	bool	false	false	Indicate post only or not
reject_post_only	bool	false	false	Indicate reject post only or not
mmp	bool	false	false	Indicate mmp order or not

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not
error_code	int	New order result code: 0 = no error
error_msg	string	New order error message

Cancel orders

POST /linear/v1/cancel_orders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/cancel_orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"currency": "USD", "order_id": "44092860", "instrument_id":"BTC-USD-PERPETUAL", "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}'

{
    "code": 0,
    "message": "",
    "data": {
        "num_cancelled": 1
    }
}

Cancel order.
Currency is required parameter.
To cancel single order, only need to provide order_id and instrument_id parameters.
Batch cancel filters include: order_id_list, label, instrument_id, pair, category, currency.
Batch cancel filter priorities: order_id_list > label > instrument_id > pair > category > currency

To cancel conditional order, provide cond_order_id + instrument_id. conditional order can not be cancelled in batch.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
order_id	string	false	""	Order ID
pair	string	false	Pair
instrument_id	string	false	""	Instrument ID (if order_id is provided, instrument_id is required)
order_id_list	array	false	""	List of (order_id + instrument_id), e.g [{"instrument_id":"BTC-USD-PERPETUAL","order_id":"1001"}, {"instrument_id":"BTC-USD-29JUL22-24250-C","order_id":"1002"}]
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID (if `order_id` if provided, `instrument_id` is required)
label	string	false	""	Order label

order_id_list details

Parameter	Type	Required	Default	Description
order_id	string	true	""	Order ID
instrument_id	string	true	""	Instrument ID

Response

Name	Type	Desc
num_cancelled	integer	number of order cancelled

Amend orders

POST /linear/v1/amend_orders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/amend_orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"currency": "USD", "order_id": "1206764", "instrument_id":"BTC-USD-PERPETUAL", "price": "49000", "timestamp": 1590760362688, "signature": "a74dda0f2bdaf1e1587a5e7577a281497cb66607166bd3b7e0cc4c805c750bf1"}'

{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "1206764",
        "created_at": 1590760363846,
        "updated_at": 1590760363846,
        "user_id": "51140",
        "instrument_id": "BTC-USD-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "49000.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "49000.00000000",
        "filled_qty": "1.00000000",
        "status": "filled",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "-0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "source": "api",
        "hidden": false,
    }
}

Amend order.
Order id + Instrument id are required.
Need to provide at least one of: price,qty.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
order_id	string	true	""	Order ID
instrument_id	string	true	""	Instrument Id
price	string	false	""	New price of the order
qty	string	false	""	New quantity of the order

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not

Amend batch orders

POST /linear/v1/amend_batchorders


curl -X POST "https://betaapi.bitexch.dev/linear/v1/amend_batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency": "USD", "orders_data": [{"order_id": "572083", "instrument_id":"BTC-USD-PERPETUAL", "price": "50000", "qty": "1.3"}, {"order_id": "invalid-order-id", "instrument_id":"BTC-USD-PERPETUAL", "price": "50000", "qty": "0.2"}], "timestamp": 1597313835731, "signature": "c8b5fddd5f2cfa1517854dc54c51e7c3b79af91f0927ea1389ba43dbeee45652"}'

{
    "code": 0,
    "message": "",
    "data": {
        "orders": [
            {
                "order_id": "572083",
                "created_at": 1597313836214,
                "updated_at": 1597313836214,
                "user_id": "51140",
                "instrument_id": "BTC-USD-PERPETUAL",
                "order_type": "limit",
                "side": "sell",
                "price": "50000.00000000",
                "qty": "1.30000000",
                "time_in_force": "gtc",
                "avg_price": "0.00000000",
                "filled_qty": "0.00000000",
                "status": "open",
                "is_liquidation": false,
                "auto_price": "0.00000000",
                "auto_price_type": "",
                "taker_fee_rate": "0.00045000",
                "maker_fee_rate": "0.00025000",
                "label": "",
                "reduce_only": false,
                "post_only": true,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": true,
                "error_code": 0,
                "error_msg": ""
            },
            {
                "order_id": "",
                "created_at": 0,
                "updated_at": 0,
                "user_id": "",
                "instrument_id": "",
                "order_type": "",
                "side": "",
                "price": "",
                "qty": "",
                "time_in_force": "",
                "avg_price": "",
                "filled_qty": "",
                "status": "",
                "is_liquidation": false,
                "auto_price": "",
                "auto_price_type": "",
                "taker_fee_rate": "",
                "maker_fee_rate": "",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": false,
                "error_code": 18100113,
                "error_msg": "order id is invalid : invalid-order-id"
            }
        ]
    }
}

Amend order in batch.
For each amend request:
Order id + Instrument id are required.
Need to provide at least one of: price,qty.
Max amend request count is 10.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
orders_data	array	true		Amend request list(see below)

order request detail

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin currency
order_id	string	true	""	Order ID
instrument_id	string	true	""	Instrument Id
price	string	false	""	New price of the order
qty	string	false	""	New quantity of the order

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not
error_code	int	Edited order result code: 0 = no error
error_msg	string	Edited order error message

Close positions

POST /linear/v1/close_positions


curl -X POST "https://betaapi.bitexch.dev/linear/v1/close_positions" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id": "BTC-USD-PERPETUAL", "price": "51000", "order_type": "limit", "timestamp": 1589524756236, "signature": "5bf4f9f00722d133336e736196c09a8e02c634dc0deacf2cf12413049d8d8b06"}'



{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "17553311",
        "created_at": 1589524757818,
        "updated_at": 1589524757818,
        "user_id": "51140",
        "instrument_id": "BTC-USD-PERPETUAL",
        "order_type": "limit",
        "side": "sell",
        "price": "51000.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "51000.50000000",
        "filled_qty": "1.00000000",
        "status": "filled",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "source": "api",
        "hidden": false,
    }
}

Close position by instrument_id, send out order with input instrument_id, order_type, price.

order size is abs(open_position), direction is opposite of open_position side.

Limit order is IOC order.

If user don't want to specify price, input order_type = 'market'

Post json body

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID of closing order
order_type	string	false	"limit"	Order type of closing order, default is limit (IOC) Order type
price	string	false	""	Price of closing order

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled quantity
status	string	Order status
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
source	string	Order source
hidden	bool	Indicate hidden order or not

Get open orders

GET /linear/v1/open_orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/open_orders?currency=USD&category=future&timestamp=1589522687689&signature=89d5a1d929e7baa247021e090f9f634f02a7fc6c82a44c8de3bb04fa6b005a7b"

{
    "code": 0,
    "message": "",
    "data": [{
        "order_id": "7610691",
        "created_at": 1589183001000,
        "updated_at": 1589183001000,
        "user_id": "51140",
        "instrument_id": "BTC-USD-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "50010.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "open",
        "fee": "0.00000000",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "pnl": "0.00000000",
        "cash_flow": "0.00000000",
        "initial_margin": "0.24000000",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "reorder_index": 1,
        "source": "api",
        "hidden": false,
        "is_um": true
        }
    ]
}

Get open orders by currency, category, instrument_id

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID
label	string	false	""	Order label

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled qty
status	string	Order status
fee	string	Transaction fees
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
pnl	string	Order P&L
cash_flow	string	Order cash flow
initial_margin	string	Order initial margin (open order only)
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
reorder_index	int64	Sorting index for internal use
source	string	Order source
hidden	bool	Indicate hidden order or not
is_um	bool	Always true for USD-M order

Get orders

GET /linear/v1/orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/orders?currency=USD&instrument_id=BTC-USD-PERPETUAL&order_id=7718222&start_time=1585270800000&end_time=1589522084000&include_open=true&offset=1&limit=10&timestamp=1589523178651&signature=2092cebba4f082f9c8718344cdad9bed83950b5fe90b3a875b708898bfd89b20"



{
    "code": 0,
    "message": "",
    "data": [{
        "order_id": "7718222",
        "created_at": 1589202185000,
        "updated_at": 1589460149000,
        "user_id": "51140",
        "instrument_id": "BTC-USD-PERPETUAL",
        "order_type": "limit",
        "side": "buy",
        "price": "50010.00000000",
        "qty": "1.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "cancelled",
        "fee": "0.00000000",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "pnl": "0.00000000",
        "cash_flow": "0.00000000",
        "initial_margin": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "reorder_index": 1,
        "source": "api",
        "hidden": false,
        "is_um": true
    }]
}

Get order history.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
instrument_id	string	true	""	Instrument ID
order_id	string	false	""	Order ID
label	string	false	""	Order label
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
include_open	boolean	false	true	Include open order or not
limit	int	false	100	Return record count

Response

Name	Type	Desc
order_id	string	Order ID
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	string	User ID
instrument_id	string	Instrument ID
order_type	string	Order type
side	string	Order side
price	string	Order price
qty	string	Order quantity
time_in_force	string	Time in force
avg_price	string	Average filled price
filled_qty	string	Filled quantity
status	string	Order status
fee	string	Transaction fees
is_liquidation	boolean	Liquidation order
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
pnl	string	Order P&L
cash_flow	string	Order cash flow
initial_margin	string	Order initial margin (open order only)
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (conditional order only)
reduce_only	bool	Indicate reduce only or not
post_only	bool	Indicate post only or not
reject_post_only	bool	Indicate reject post only or not
mmp	bool	Indicate mmp order or not
reorder_index	int64	Sorting index for internal use
source	string	Order source
hidden	bool	Indicate hidden order or not
is_um	bool	Always true for USD-M order

Get user trades

GET /linear/v1/user/trades

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/user/trades?currency=USD&category=future&order_id=17551020&start_time=1585270800000&end_time=1589522084000&offset=1&limit=10&timestamp=1589523590679&signature=c4788e3a77b6000424b55067f9ba38009b34d12e482b1c80186756857c869bb5"


{
    "code": 0,
    "message": "",
    "data": [{
        "trade_id": "23210268",
        "order_id": "17551020",
        "instrument_id": "BTC-USD-PERPETUAL",
        "qty": "2.00000000",
        "price": "50010.00000000",
        "sigma": "0.00000000",
        "underlying_price": "",
        "index_price": "50012.81000000",
        "usd_price": "",
        "fee": "0.00100000",
        "fee_rate": "0.00050000",
        "side": "buy",
        "created_at": 1589521371000,
        "is_taker": true,
        "order_type": "limit",
        "label": "hedge"
    }]
}

Get user trades

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Margin Currency
pair	string	false	""	Pair
category	string	false	""	Category
instrument_id	string	false	""	Instrument ID
order_id	string	false	""	Order ID
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
start_id	integer	false		Start Id
end_id	integer	false		End Id
count	int	false	100	Trade count, max 1000

Response

Name	Type	Desc
order_id	string	Order ID
trade_id	string	Trade ID
instrument_id	string	Instrument ID
created_at	integer	Create timestamp
order_type	string	Order type
side	string	Order side
price	string	Trade price
qty	string	Trade quantity
fee	string	Transaction fees
fee_rate	string	Fee rate
sigma	string	Implied volatility , option only
is_taker	boolean	Is taker or not
index_price	string	Index price
underlying_price	string	Underlying price (not for future instrument)
usd_price	string	(Not Applicable)
label	string	Order label of related trade

Get estimated margins

GET /linear/v1/margins

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/linear/v1/margins?instrument_id=BTC-USD-PERPETUAL&price=5000&qty=1&timestamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807"

{
    "code": 0,
    "message": "",
    "data": {
        "buy_margin": "70.93672651",
        "sell_margin": "100.13000000",
        "min_sell": "34890.97000000",
        "max_buy": "35953.65000000",
        "index_price": "35423.91000000"
    }
}

Get margin of orders

Query parameters

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
price	string	true	""	Order price
qty	string	true	""	Order quantity

Response (Margin array)

Name	Type	Desc
buy_margin	string	Estimated buy margin(in margin currency)
sell_margin	string	Estimated sell margin(in margin currency)
min_sell	string	Minimum price for sell order
max_buy	string	Maximum price for buy order
index_price	string	USD index price
usdt_index_price	string	(For compatibility) equal to `index_price`

Get conditional orders

GET /linear/v1/conditional_orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/conditional_orders?currency=USD&instrument_id=BTC-USD-PERPETUAL&status=open&timestamp=1590667739793&signature=14c522605de563064ae36933604225730a8b4e254be8ce58ecc2746f5199d77f"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "cond_order_id": "trigger-c8vbgjdlat8f5clahjpg",
            "created_at": 1648277581254,
            "updated_at": 1648277581254,
            "status": "open",
            "stop_price": "40000.00000000",
            "trigger_type": "last-price",
            "reject_reason": "",
            "instrument_id": "BTC-USD-PERPETUAL",
            "user_id": 8001,
            "qty": "1.00000000",
            "price": "39000.00000000",
            "side": "buy",
            "order_type": "trigger-limit",
            "time_in_force": "gtc",
            "source": "api",
            "hidden": false
        }
    ],
    "page_info": {
        "has_more": false
    }
}

Get conditional order history by currency, instrument_id, or status.

Query parameters

Parameter	Type	Required	Default	Description
currency	string	true	""	Currency
pair	string	false	""	Pair
instrument_id	string	false	""	Instrument ID
status	string	false	""	Conditional Order status
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
limit	int	false	100	Return record count

Response

Name	Type	Desc
cond_order_id	string	Conditional Order ID (with prefix "trigger-")
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
instrument_id	string	Instrument ID
qty	string	Order quantity
price	string	Price of the triggered new order
side	string	Order side
order_type	string	Order type
stop_price	string	Stop price (conditional order only)
time_in_force	string	Time in force
status	string	ConditionalOrder status
trigger_type	string	Triggered by last price
user_id	int	User ID
source	string	Order source
hidden	bool	Indicate hidden order or not

Block Trade

To use block trade API, user need to create API key with linear block trade permission

New block trade request

POST /linear/v1/blocktrades

# <bt_source> should be replaced with real bt_source

curl -X POST "https://betaapi.bitexch.dev/linear/v1/blocktrades" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a"  -d '{"currency":"USD", "label": "e8db3a92b94c482bb0e30f421415982d", "role": "maker", "counterparty": 1026, "bt_source": "<bt_source>", "trades": [{"instrument_id": "BTC-USD-25SEP20-9000-C", "price": "0.18", "qty": "10", "side": "sell"}, {"instrument_id": "BTC-USD-PERPETUAL", "price": "19000", "qty": "5", "side": "buy"}], "timestamp": 1594447520876, "signature": "7e8b0e7987fcb282b691d9e87c5afa9af578ed0c464190ca1fa466d18c17adde"}'

{
    "code": 0,
    "message": "",
    "data": {
        "label": "e8db3a92b94c482bb0e30f421415982d",
        "status": "pending"
    }
}

Make block trade request.
Label: Unique identifier of block trade, both counterpartys use the same label for given block trade request
Both side needs to call /linear/v1/blocktrades with same label, trades(with opposite side).
The block trade request timeout period is 1 minute, if the other side doesn't answer in given time, the request will expired.
Block trade bt_source is bit.com designated block trade source, contact bit.com for detail.

Post json body

Parameter	Type	Required	Default	Description
currency	string	true	""	Currency
bt_source	string	true	""	Block trade source (bit.com designated block trade source)
label	string	true	""	Unique identifier generated for block trade
role	string	true	""	Role: taker/maker
counterparty	integer	true	""	Counterparty user ID
trades	array	true		Trade list of this block trade request(see below)

block trade object

Parameter	Type	Required	Default	Description
instrument_id	string	true	""	Instrument ID
side	string	true	""	Order side: buy/sell
price	string	true	""	Order price
qty	string	true	""	Order quantity

Response

Name	Type	Desc
label	string	Block trade label
status	string	pending/filled/rejected/expired

Query block trades

GET /linear/v1/blocktrades

# <bt_source> should be replaced with real bt_source

curl -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" "https://betaapi.bitexch.dev/linear/v1/blocktrades?currency=USD&bt_source=<bt_source>&timestamp=1594447524043&signature=12b1090ea6432e71f2f6d01c6f08f0ff30e3765791ebff87b4183964643d61d2"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "56",
            "label": "8c5d90b6cbd744ceab49d0e66b8fda68",
            "created_at": 1613637677061,
            "updated_at": 1613637678593,
            "user_id": 51140,
            "counterparty": 481554,
            "instrument_id": "BTC-USD-PERPETUAL",
            "side": "buy",
            "price": "19000.00000000",
            "qty": "10.00000000",
            "fee": "0.00000392",
            "status": "filled",
            "role": "maker",
            "bt_source": "<bt_source>",
            "order_id": "6325142",
            "trade_id": "1299120841",
            "index_price": "51723.49000000",
            "sigma": "0.00000000"
        }
    ]
}

Query block trades.

Query parameters

Parameter	Type	Required	Default	Description
bt_source	string	true	""	Block trade source
currency	string	true	""	Currency
instrument_id	string	false	""	Instrument ID
label	string	false	""	Label of the block trade request
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
limit	int	false	100	Return record count

Response

Name	Type	Desc
block_order_id	string	Block order id
label	string	Label of the block trade request
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	integer	User ID
counterparty	integer	Counterparty User ID
instrument_id	string	Instrument ID
side	string	Order side
price	string	Order price
qty	string	Order quantity
fee	string	Transaction fees
status	string	Status
role	string	Order role(taker/maker)
bt_source	string	Block trade source
order_id	string	Exchange order id
trade_id	string	Exchange trade id
index_price	string	Index price
sigma	string	Implied volatility , option only

Query block trades by platform

GET /linear/v1/platform_blocktrades

# <bt_source> should be replaced with real bt_source

curl -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" "https://betaapi.bitexch.dev/linear/v1/platform_blocktrades?currency=USD&bt_source=<bt_source>&timestamp=1594448745124&signature=39078700dbe556df7f34dd6e0fb444b4ead9ef6ddc8e5b24c76555b6758c68d2"

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "56",
            "label": "8c5d90b6cbd744ceab49d0e66b8fda68",
            "created_at": 1613637677061,
            "updated_at": 1613637678593,
            "user_id": 51140,
            "counterparty": 481554,
            "instrument_id": "BTC-USD-PERPETUAL",
            "side": "buy",
            "price": "19000.00000000",
            "qty": "10.00000000",
            "fee": "0.00000392",
            "status": "filled",
            "role": "maker",
            "bt_source": "<bt_source>",
            "order_id": "6325142",
            "trade_id": "1299120841",
            "index_price": "51723.49000000",
            "sigma": "0.00000000"
        }   
    ]
}

Query block trades of specific platform.

Query parameters

Parameter	Type	Required	Default	Description
bt_source	string	true	""	Block trade source
currency	string	true	""	Currency
instrument_id	string	false	""	Instrument ID
label	string	false	""	Label of the block trade request
taker	string	false	""	Filtered by taker
maker	string	false	""	Filtered by maker
start_time	integer	false		Start timestamp
end_time	integer	false		End timestamp
limit	int	false	100	Return record count

Response

Name	Type	Desc
block_order_id	string	Block order id
label	string	Label of the block trade request
created_at	integer	Create timestamp
updated_at	integer	Update timestamp
user_id	integer	User ID
counterparty	integer	Counterparty User ID
instrument_id	string	Instrument ID
side	string	Order side
price	string	Order price
qty	string	Order quantity
fee	string	Transaction fees
status	string	Status
role	string	Order role(taker/maker)
bt_source	string	Block trade source
order_id	string	Exchange order id
trade_id	string	Exchange trade id
index_price	string	Index price
sigma	string	Implied volatility , option only

Get blocktrade user info

GET /linear/v1/user/info

curl -H "X-Bit-Access-Key: ak-77fd5728-e7d4-4174-991a-6e9b8f5887e6" "https://betaapi.bitexch.dev/linear/v1/user/info?timestamp=1613713263340&signature=038be893be10e51b7545abacbf669e7569b7de2dcb2693c33f4aa29c956a611a"

{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 10031
    }
}

Get user information with only blocktrade permission.
API key with "read" permission should use GET /linear/v1/accounts instead.

Query Parameters

None

Response

Name	Type	Description
user_id	integer	User ID of bit.com

Websocket subscription

Data subscription is based on Websocket protocol. Users can send subscription requests after established Websocket connections.

Connection will be auto disconnected if no subscription is initiated within 30s.

The data of the USD-M contract and the COIN-M contract are subscribed through the same websocket service address, and the channels can be subscribed together. The websocket service will return the corresponding data according to instruments or pairs/currencies in subscription parameters.

All the responses are based on the following structure.

Name	Type	Description
channel	string	Channel name
timestamp	integer	The timestamp (milliseconds since the Unix epoch)
data	object	Content
module	string	[`linear`, `um`] The module which the subscription data came from

Subscription management

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL",
        "ETH-USD-PERPETUAL"
    ],
    "channels":[
        "depth",
        "ticker",
        "kline.5",
        "order"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"be4ffcc9-2b2b-4c3e-9d47-68bf062cf651"
}

{
    "channel":"subscription",
    "timestamp":1587921122970,
    "data":{
        "code":0,
        "subscription":[
            "depth",
            "ticker",
            "kline.5"
        ]
    }
}

{
    "channel":"subscription",
    "timestamp":1587921122970,
    "data":{
        "code":13200302,
        "message":"auth failed: invalid token"
    }
}

Users can subscribe to different channels, public and private. Private channel requires token and authentication.

Channels have different specifications, see details in the documentations below.

Users can set the push frequency with the parameter interval. * interval=raw, the channel will push the updates immediately. * interval=100ms, the updates within 100ms period will be aggregated and pushed out, note: if no updates within 100ms, no data will be pushed. * interval=fixed100ms, data will be pushed every 100ms no matter has update or not (Only apply to order_book channel currently).

If the subscription request contains more than one channel and one of them failed, you will receive two separate responses.

Users can stop the feed by submitting an unsubscribe request.

Parameters

Name	Type	Description
type	string	[`subscribe`, `unsubscribe`]
channels	string[]	List of channels
pairs	string[]	List of pairs
categories	string[]	List of instrument categories
instruments	string[]	List of instrument IDs
interval	string	[`raw`, `100ms`, `fixed100ms`] default value is `raw`
token	string	Authentication Token for private channel

interval parameter:

All channels support setting interval to raw or 100ms
Only some channels support setting interval to fixed100ms, currently supported channels include：order_book

Response

Name	Type	Description
code	integer	0 means success, !=0 means failure
message	string	Error message, return when failed
subscription	string[]	Subscription list, return when successful

Authentication Token

GET /v1/ws/auth

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/ws/auth?timestamp=1588996062516&signature=9ed1dd821cc6464d2cfc5bf9614df1f22611c977b513e1ffde864a673b6915f0"

{
    "code":0,
    "message":"",
    "data":{
        "token":"be4ffcc9-2b2b-4c3e-9d47-68bf062cf651"
    }
}

To connect private websocket channels, user needs to first call GET /v1/ws/auth to acquire a token, which will be used to fill in private websocket channel subscription for websocket authentication.

Each token is used for single websocket connection, it's not cached in server, can not be reused, user needs to acquire new token if reconnect. (Thus token of user A can not be reused by user B even when the token is compromised)

For websocket connection, user only need to do authentication in first private channel subscription, subsequent private subscription do not need authenticate(and subsequent token will be discarded, so different users can not share private websocket connections)

Parameters

None

Response

Name	Type	Description
token	string	private channel authentication token

Heartbeat

Standard protocol

According to RFC 6455, Websocket protocol uses PING/PONG to indicate that the connection is kept alive.

Server sends PING to client every minute through Websocket, client responds with PONG. Connection will be closed if PONG is not received after one minute.

Client can also send PING to check if the server is still responsive.

PING/PONG are both control frames. PING's opcode is 0x9，PONG's opcode is 0xA. One can refer to this link。

Custom PING/PONG

Since some clients cannot support sending control frames, payload-based PING/PONG is provided in addition to the standard protocol. Refer to "Websocket RPC - PING" for details.

Channel Summary

Channel	Scope	Arguments	Description
depth	public	instruments	Changes to the order book
order_book.{group}.{depth}	public	instruments	Order book based on specified group and depth
depth1	public	instruments	Top of order book bid/ask
ticker	public	instruments	The most recent traded price and trading summary
kline.{timeframe}	public	instruments	Kline data
trade	public	instruments	Trades for an instrument
market_trade	public	categories + pairs	All the trades of available options or futures
index_price	public	pairs	Index price of the specific currency pair
mark_price	public	instruments	Mark price for an instrument
um_account	private		UM user's account information
position	private	categories + pairs	User's position information
order	private	categories + pairs	User's order information
user_trade	private	categories + pairs	User's trade information
mmp_frozen	private	pairs.	MMP frozen event

Depth Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL"
    ],
    "channels":[
        "depth"
    ],
    "interval": "100ms"
}

{
    "channel":"depth",
    "timestamp":1643094930373,
    "module":"linear",
    "data":{
        "type":"snapshot",
        "instrument_id":"BTC-USD-PERPETUAL",
        "sequence":9,
        "bids":[
            [
                "35731.05000000",
                "6.82000000"
            ]
        ],
        "asks":[
            [
                "35875.00000000",
                "1.00000000""
            ]
        ]
    }
}

{
    "channel":"depth",
    "timestamp":1643094930373,
    "module":"linear",
    "data":{
        "type":"update",
        "instrument_id":"BTC-USD-PERPETUAL",
        "sequence":10,
        "prev_sequence":9,
        "changes":[
            [
                "sell",
                "35733.00000000",
                "2.10000000"
            ]
        ]
    }
}

Depth channel can have two message types: snapshot and update. Snapshot sends snapshots of the current order book. Updates sends changes of the order book.

The first message will always be a snapshot followed by updates, if there is any sort of disruption, a new snapshot will be sent follow by updates.

A snapshot includes bids and asks depths, each depth layer consists of two elements: price and quantity.

A normal update message contains sequence and prev_sequence, with the prev_sequence matching the previous update.

Changes in update is a result in a change in depth, every changes consists of three elements: side, price and quantity. Quantity=0 means a layer is been removed from the depth.

Channel Information

Channel	Scope	Arguments	Interval
depth	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
type	string	[`snapshot`, `update`]
instrument_id	string	Instrument ID
sequence	integer	Order book update sequence
asks	array of [price, quantity]	Asks, price and quantity are string, return when type=snapshot
bids	array of [price, quantity]	Bids, price and quantity are string, return when type=snapshot
prev_sequence	integer	Previous update sequence number, return when type=update
changes	array of [side, price, quantity]	Depth changes, side、price、quantity are string, quantity=0 means deletion, return when type = update

Order Book Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL"
    ],
    "channels":[
        "order_book.1.20"
    ],
    "interval": "100ms"
}

{
    "channel":"order_book.1.20",
    "timestamp":1643095202401,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USD-PERPETUAL",
        "sequence":1643010119674372,
        "timestamp":1643095202400,
        "asks":[
            [
                "35725.80000000",
                "2.29000000"
            ],
            [
                "35747.00000000",
                "1.00000000"
            ]
        ],
        "bids":[
            [
                "35724.80000000",
                "5.25000000"
            ],
            [
                "35724.75000000",
                "1.38000000"
            ]
        ]
    }
}

Order Book pushes certain layers of an order book data based on group and depth.

An order book message includes bids and asks depths, each depth layer consists of two elements: price and quantity.

Channel Information

Channel	Scope	Arguments	Interval
order_book.{group}.{depth}	public	instruments	[`raw`, `100ms`,`fixed100ms`]

When subscribing to orderbook channel, user will need to specify group and depth in channel

group value: represents the multiple of the order book price steps, aggregation level = group * price_step.
Valid group value of the instrument can be retrieved via the rest api /linear/v1/instruments.
depth value: 1, 10, 20, 100, represents order book layers

Default is group=1, depth=10

Order book price aggregation example

Assume price_step = 0.01

raw depth:
bids: [[0.13, 3], [0.19, 7], [0.26, 5], [0.77, 12.3]]

for orderbook.10.5, aggregation price level = 0.01 * 10 = 0.1
output bids: [[0.1, 10], [0.2, 5], [0.7, 12.3]]

Response

Name	Type	Description
instrument_id	string	Instrument ID
sequence	integer	Order book update sequence
timestamp	integer	Timestamp at order book update
asks	array of [price, quantity]	Asks, price and quantity are string
bids	array of [price, quantity]	Bids, price and quantity are string

Depth1 Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL"
    ],
    "channels":[
        "depth1"
    ],
    "interval": "100ms"
}

{
    "channel":"depth1",
    "timestamp":1643095202400,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USD-PERPETUAL",
        "asks":[
            [
                "35725.80000000",
                "2.29000000"
            ]
        ],
        "bids":[
            [
                "35724.80000000",
                "5.25000000"
            ]
        ]
    }
}

Depth1 pushes top of book bid/ask information

Channel Information

Channel	Scope	Arguments	Interval
depth1	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
asks	array of [price, quantity]	Asks, price and quantity are string, return 0 or 1 layer
bids	array of [price, quantity]	Bids, price and quantity are string, return 0 or 1 layer

Ticker Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL"
    ],
    "channels":[
        "ticker"
    ],
    "interval": "100ms"
}

{
    "channel":"ticker",
    "timestamp":1643099422727,
    "module":"linear",
    "data":{
        "ask_sigma":"",
        "best_ask":"36295.00000000",
        "best_ask_qty":"1.00000000",
        "best_bid":"36242.30000000",
        "best_bid_qty":"7.01000000",
        "bid_sigma":"",
        "funding_rate":"0.00203429",
        "funding_rate8h":"0.00009707",
        "high24h":"37377.00000000",
        "instrument_id":"BTC-USD-PERPETUAL",
        "last_price":"36242.30000000",
        "last_qty":"0.42000000",
        "low24h":"33117.95000000",
        "mark_price":"36261.48392714",
        "max_buy":"36805.41000000",
        "min_sell":"35717.56000000",
        "open24h":"34998.65000000",
        "open_interest":"87.69310000",
        "price_change24h":"0.03553423",
        "time":1643099422727,
        "volume24h":"4422.94140000"
    }
}

Ticker pushes the most recent traded price and the last 24 hrs trading summary.

Channel Information

Channel	Scope	Arguments	Interval
ticker	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
last_price	string	Most recent traded price
last_qty	string	Most recent traded volume
open24h	string	Open price during previous 24 hour
high24h	string	Highest price during previous 24 hour
low24h	string	Lowest price during previous 24 hour
volume24h	string	Sum volume during previous 24 hour
price_change24h	string	Price change% during previous 24 hour
open_interest	string	Open interest
best_bid	string	Best bid price
best_ask	string	Best ask price
best_bid_qty	string	Best bid quantity
best_ask_qty	string	Best ask quantity
bid_sigma	string	Top of book bid implied vol, option only
ask_sigma	string	Top of book ask implied vol, option only
underlying_name	string	Underlying index name, option only
underlying_price	string	Underlying price, option only
funding_rate	string	Funding rate, perpetual only
funding_rate8h	string	Past 8H avg funding rate, perpetual only
mark_price	string	Mark price
sigma	string	Mark price implied vol, option only
delta	string	Mark price delta, option only
vega	string	Mark price vega, option only
theta	string	Mark price theta, option only
gamma	string	Mark price gamma, option only
max_buy	string	Maximum price of buy order
min_sell	string	Minimum price of sell order

Kline Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL"
    ],
    "channels":[
        "kline.5"
    ],
    "interval": "100ms"
}

{
    "channel":"kline.5",
    "timestamp":1643099753388,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USD-PERPETUAL",
        "close":"36088.00000000",
        "high":"36088.00000000",
        "low":"36081.45000000",
        "open":"36176.90000000",
        "tick":1643099700000,
        "volume":"3.29000000"
    }
}

Kline pushed kline data. If there is no trade during the current period, the previous close will be used for open, high and low.

Channel Information

Channel	Scope	Arguments	Interval
kline.{timeframe}	public	instruments	[`raw`, `100ms`]

When subscribing to kline channel, user will need to specify timeframe.

Support timeframes:

Timeframe	Name Desc
1	1 minute
3	3 minute
5	5 minute
15	15 minute
30	30 minute
60	60 minute
240	240 minute
360	360 minute
720	720 minute
1d	daily
1w	weekly
1m	monthly

Response

Name	Type	Description
instrument_id	string	Instrument ID
tick	integer	Tick starting time
open	string	Open price
close	string	Close price
high	string	High price
low	string	Low price
volume	string	Volume

Trade Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL"
    ],
    "channels":[
        "trade"
    ],
    "interval": "100ms"
}

{
    "channel":"trade",
    "timestamp":1643099734031,
    "module":"linear",
    "data":[
        {
            "instrument_id":"BTC-USD-PERPETUAL",
            "created_at":1643099733988,
            "is_block_trade":false,
            "price":"36081.45000000",
            "qty":"2.29000000",
            "side":"buy",
            "sigma":"0.00000000",
            "trade_id":"1005590555"
        }
    ]
}

Trade pushes instrument's trading information

Channel Information

Channel	Scope	Arguments	Interval
trade	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
trade_id	string	Trade ID
price	string	Price
qty	string	Quantity
side	string	Taker trade side
sigma	string	Trade implied vol, option only
option_type	string	Option type, option only
is_block_trade	boolean	Is block trade or not
created_at	integer	Trade timestamp (milliseconds since the Unix epoch)

Market Trade Channel

{
    "type":"subscribe",
    "channels":[
        "market_trade"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms"
}

{
    "channel":"market_trade",
    "timestamp":1643099734031,
    "module":"linear",
    "data":[
        {
            "instrument_id":"BTC-USD-PERPETUAL",
            "created_at":1643099733988,
            "is_block_trade":false,
            "price":"36081.45000000",
            "qty":"2.29000000",
            "side":"buy",
            "sigma":"0.00000000",
            "trade_id":"1005590555"
        }
    ]
}

Market Trade pushes all the trading information of available options or futures.

Channel Information

Channel	Scope	Arguments	Interval
market_trade	public	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
trade_id	string	Trade ID
price	string	Price
qty	string	Quantity
side	string	Taker trade side
sigma	string	Trade implied vol, option only
option_type	string	Option type, option only
is_block_trade	boolean	Is block trade or not
created_at	integer	Trade timestamp (milliseconds since the Unix epoch)

Index Price Channel

{
    "type":"subscribe",
    "channels":[
        "index_price"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "interval": "100ms"
}

{
    "channel":"index_price",
    "timestamp":1643099733988,
    "module":"linear",
    "data":{
        "index_name":"BTC-USD",
        "index_price":"35866.66000000"
    }
}

index_price pushes index price of the specific currency pair.

Channel Information

Channel	Scope	Arguments	Interval
index_price	public	pairs	[`raw`, `100ms`]

Response

Name	Type	Description
index_name	string	Index name
index_price	string	Index price

Mark Price Channel

{
    "type":"subscribe",
    "instruments":[
        "BTC-USD-PERPETUAL"
    ],
    "channels":[
        "mark_price"
    ],
    "interval": "100ms"
}

{
    "channel":"mark_price",
    "timestamp":1643100336677,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USD-PERPETUAL",
        "mark_price":"36079.52938997"
    }
}

Mark Price pushes mark price of a specific instrument

Channel Information

Channel	Scope	Arguments	Interval
mark_price	public	instruments	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
mark_price	string	Mark price
sigma	string	Mark price implied vol, option only
delta	string	Mark price delta, option only
vega	string	Mark price vega, option only
theta	string	Mark price theta, option only
gamma	string	Mark price gamma, option only

UM Account Channel

{
    "type":"subscribe",
    "channels":[
        "um_account"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"um_account",
    "timestamp":1632439007081,
    "module":"um",
    "data": {
        "user_id": 481554,
        "created_at": 1649923879505,
        "total_collateral": "3170125.05978108",
        "total_margin_balance": "3170125.05978108",
        "total_available": "3169721.64891398",
        "total_initial_margin": "403.41086710",
        "total_maintenance_margin": "303.16627631",
        "total_initial_margin_ratio": "0.00012725",
        "total_maintenance_margin_ratio": "0.00009563",
        "total_liability": "0.00000000",
        "total_unsettled_amount": "-0.84400340",
        "spot_orders_hc_loss": "0.00000000",
        "total_position_pnl": "1225.53245820",
        "details": [
            {
                "currency": "BTC",
                "equity": "78.13359310",
                "liability": "0.00000000",
                "index_price": "41311.20615385",
                "cash_balance": "78.13360190",
                "margin_balance": "78.13359310",
                "available_balance": "78.12382795",
                "initial_margin": "0.00976516",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00733859",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.02966586",
                "total_delta": "0.48532539",
                "session_rpl": "0.00001552",
                "session_upl": "-0.00003595",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.02966586",
                "future_session_rpl": "0.00001552",
                "future_session_upl": "-0.00003595",
                "future_session_funding": "0.00001552",
                "future_delta": "0.48532539",
                "future_available_balance": "76.72788921",
                "option_available_balance": "76.72788921",
                "unsettled_amount": "-0.00002043",
                "usdt_index_price": "41311.20615385"
            },
            {
                "currency": "ETH",
                "equity": "1.99960000",
                "liability": "0.00000000",
                "index_price": "3119.01923077",
                "cash_balance": "1.99960000",
                "margin_balance": "1.99960000",
                "available_balance": "1.99960000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "0.00000000",
                "interest": "0.00000000",
                "interest_rate": "0.07000000",
                "pnl": "0.00000000",
                "total_delta": "0.00000000",
                "session_rpl": "0.00000000",
                "session_upl": "0.00000000",
                "option_value": "0.00000000",
                "option_pnl": "0.00000000",
                "option_session_rpl": "0.00000000",
                "option_session_upl": "0.00000000",
                "option_delta": "0.00000000",
                "option_gamma": "0.00000000",
                "option_vega": "0.00000000",
                "option_theta": "0.00000000",
                "future_pnl": "0.00000000",
                "future_session_rpl": "0.00000000",
                "future_session_upl": "0.00000000",
                "future_session_funding": "0.00000000",
                "future_delta": "0.00000000",
                "future_available_balance": "1.99960000",
                "option_available_balance": "1.99960000",
                "unsettled_amount": "0.00000000",
                "usdt_index_price": "3119.01923077"
            }
        ],
        "usdt_total_collateral": "3170125.05978108",
        "usdt_total_margin_balance": "3170125.05978108",
        "usdt_total_available": "3169721.64891398",
        "usdt_total_initial_margin": "403.41086710",
        "usdt_total_maintenance_margin": "303.16627631",
        "usdt_total_initial_margin_ratio": "0.00012725",
        "usdt_total_maintenance_margin_ratio": "0.00009563",
        "usdt_total_liability": "0.00000000",
        "usdt_total_unsettled_amount": "-0.84400340"
    }
}

UM mode: subscribe um_accountchannnel to get UM account information.

Channel Information

Channel	Scope	Arguments	Interval
um_account	private		[`raw`, `100ms`]

Response

Name	Type	Desc
user_id	int	User Id
created_at	int	Timestamp (query time)
total_collateral	string	Total Collateral (USD)
total_margin_balance	string	Total Margin Balance (USD)
total_available	string	Total Available (USD)
total_initial_margin	string	Total Initial Margin (USD)
total_maintenance_margin	string	Total Maintenance Margin (USD)
total_initial_margin_ratio	string	Total Initial Margin Ratio, may returns "infinity" (USD)
total_maintenance_margin_ratio	string	Total Maintenance Margin Ratio, may returns "infinity" (USD)
total_liability	string	Total liability (USD)
total_unsettled_amount	string	Total unsettled amount (USD)
spot_orders_hc_loss	string	Total spot order haircut loss
total_position_pnl	string	Total position PnL in USD [SUM(ccy.pnl * ccy.index-price)]
details	array	Details, array of currency level detail
usdt_total_collateral	string	(For compatibility) equal to total_collateral
usdt_total_margin_balance	string	(For compatibility) equal to total_margin_balance
usdt_total_available	string	(For compatibility) equal to total_available
usdt_total_initial_margin	string	(For compatibility) equal to total_initial_margin
usdt_total_maintenance_margin	string	(For compatibility) equal to total_maintenance_margin
usdt_total_initial_margin_ratio	string	(For compatibility) equal to total_initial_margin_ratio
usdt_total_maintenance_margin_ratio	string	(For compatibility) equal to total_maintenance_margin_ratio
usdt_total_liability	string	(For compatibility) equal to total_liability
usdt_total_unsettled_amount	string	(For compatibility) equal to total_unsettled_amount

Detail object

Name	Type	Desc
currency	string	Currency
equity	string	Equity
liability	string	Liability
index_price	string	Index price (USD)
usdt_index_price	string	(For compatibility) equal to index_price
cash_balance	string	Cash Balance
margin_balance	string	Margin Balance
available_balance	string	Account Available Balance
initial_margin	string	Initial Margin
spot_margin	string	Spot Margin
maintenance_margin	string	Maintenance Margin
potential_liability	string	Potential Liability
interest	string	Interest
interest_rate	string	Interest Rate
pnl	string	Currency level position P&L
total_delta	string	Total delta of account
session_rpl	string	Session realized pnl
session_upl	string	Session unrealized pnl
option_value	string	Option market value
option_pnl	string	Option P&L
option_session_rpl	string	Option session realized P&L
option_session_upl	string	Option session unrealized P&L
option_delta	string	Option delta
option_gamma	string	Option gamma
option_vega	string	Option vega
option_theta	string	Option theta
future_pnl	string	Future P&L
future_session_rpl	string	Future session realized P&L
future_session_upl	string	Future session unrealized P&L
future_session_funding	string	Future session funding
future_delta	string	Future delta
future_available_balance	string	Available balance for new futures order
option_available_balance	string	Available balance for new option order
unsettled_amount	string	Unsettled amount

Position Channel

{
    "type":"subscribe",
    "channels":[
        "position"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"position",
    "timestamp":1643101230232,
    "module":"linear",
    "data":[
        {
            "avg_price":"42474.49668874",
            "category":"future",
            "expiration_at":4102444800000,
            "index_price":"36076.66600000",
            "initial_margin":"21.81149685",
            "instrument_id":"BTC-USD-PERPETUAL",
            "leverage":"50.00000000",
            "maintenance_margin":"16.36076260",
            "mark_price":"36097.57784846",
            "position_pnl":"192.58294898",
            "position_session_rpl":"-0.16699671",
            "position_session_upl":"-1.28505101",
            "qty":"-0.03020000",
            "qty_base":"-0.03020000",
            "roi":"8.82942378",
            "session_avg_price":"36055.02649047",
            "session_funding":"-0.16699671",
            "liq_price": "3587263.29572346",
        }
    ]
}

Position pushes user's position information

Channel Information

Channel	Scope	Arguments	Interval
position	private	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
qty	string	Position size (for option, qty in base currency, for future, qty in USD)
qty_base	string	Position size in base currency, future only
avg_price	string	Average filled price
position_pnl	string	Position P&L
position_session_upl	string	Position session unrealized P&L
position_session_rpl	string	Position session realized P&L
index_price	string	Index price
mark_price	string	Mark price
initial_margin	string	Initial margin
maintenance_margin	string	Maintenance margin
session_avg_price	string	Session average price
session_funding	string	Session funding, future only
category	string	Instrument category
roi	string	Return on investment
option_delta	string	Option position delta, option only
option_gamma	string	Option position gamma, option only
option_vega	string	Option position vega, option only
option_theta	string	Option position theta, option only
liq_price	string	Estimated liquidation price, future only
leverage	string	Position leverage, future only

Order Channel

{
    "type":"subscribe",
    "channels":[
        "order"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"order",
    "timestamp":1643101425658,
    "module":"linear",
    "data":[
        {
            "auto_price":"0.00000000",
            "auto_price_type":"",
            "avg_price":"0.00000000",
            "cash_flow":"0.00000000",
            "created_at":1643101425539,
            "fee":"0.00000000",
            "filled_qty":"0.00000000",
            "hidden":false,
            "initial_margin":"",
            "instrument_id":"BTC-USD-PERPETUAL",
            "is_liquidation":false,
            "is_um":true,
            "label":"",
            "maker_fee_rate":"0.00010000",
            "mmp":false,
            "order_id":"1034087",
            "order_type":"limit",
            "pnl":"0.00000000",
            "post_only":false,
            "price":"36088.95000000",
            "qty":"0.02000000",
            "reduce_only":false,
            "reject_post_only":false,
            "reorder_index":0,
            "side":"buy",
            "source":"web",
            "status":"pending",
            "stop_order_id":"",
            "stop_price":"0.00000000",
            "taker_fee_rate":"0.00010000",
            "time_in_force":"gtc",
            "updated_at":1643101425539,
            "user_id":"606122"
        }
    ]
}

Order pushes user's order information

Channel Information

Channel	Scope	Arguments	Interval
order	private	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
instrument_id	string	Instrument ID
order_id	string	Order ID
qty	string	Quantity
filled_qty	string	Filled quantity
remain_qty	string	Remaining quantity
price	string	Order price
avg_price	string	Average filled price
side	string	Order side
order_type	string	Order type
time_in_force	string	Order time in force
status	string	Order status
fee	string	Fee
cash_flow	string	Cash flow
pnl	string	P&L
auto_price	string	Auto price
auto_price_type	string	Usdx Auto price type
is_liquidation	boolean	Is liquidation order or not
taker_fee_rate	string	Taker fee rate
maker_fee_rate	string	Maker fee rate
label	string	User defined label
stop_price	string	Stop price (stop order only)
reduce_only	boolean	Indicate reduce only or not
post_only	boolean	Indicate post only or not
reject_post_only	boolean	Indicate reject post only or not
mmp	boolean	Indicate mmp order or not
reorder_index	integer	Sorting index for internal use
created_at	integer	Timestamp at order creation (milliseconds since the Unix epoch)
updated_at	integer	Timestamp at order update (milliseconds since the Unix epoch)

User Trade Channel

{
    "type":"subscribe",
    "channels":[
        "user_trade"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "categories":[
        "future"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"user_trade",
    "timestamp":1643101722258,
    "module":"linear",
    "data":[
        {
            "created_at":1643101722020,
            "fee":"0.00000000",
            "fee_rate":"0.00010000",
            "index_price":"36214.05400000",
            "instrument_id":"BTC-USD-PERPETUAL",
            "is_block_trade":false,
            "is_taker":true,
            "label":"",
            "order_id":"1034149",
            "order_type":"limit",
            "price":"36219.85000000",
            "qty":"0.00100000",
            "side":"buy",
            "sigma":"0.00000000",
            "trade_id":"1005590992",
            "underlying_price":"",
            "usd_price":""
        }
    ]
}

User Trade pushes user trade information

Channel Information

Channel	Scope	Arguments	Interval
user_trade	private	categories + pairs	[`raw`, `100ms`]

Response

Name	Type	Description
order_id	string	Order ID
trade_id	string	Trade ID
instrument_id	string	Instrument ID
order_type	string	User Order type
side	string	User Order side
price	string	Trade price
qty	string	Trade quantity
fee	string	Transaction fees
fee_rate	string	Fee rate
sigma	string	Imply volatility
is_taker	boolean	Is taker or not
is_block_trade	boolean	Is block trade or not
index_price	string	Index price
underlying_price	string	Underlying price, option only
usd_price	string	USD price of auto price order
label	string	Order label of related trade
created_at	integer	Timestamp at trade creation (milliseconds since the Unix epoch)

MMP Frozen Event Channel

{
    "type":"subscribe",
    "channels":[
        "mmp_frozen"
    ],
    "pairs":[
        "BTC-USD"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

{
    "channel":"mmp_frozen",
    "timestamp":1643101722258,
    "module":"linear",
    "data":{
        "pair":"BTC-USD",
        "frozen_until_ms":1643101725000
    }
}

MMP Frozen pushes MMP frozen event

frozen_until_ms indicate MMP frozen status.
frozen_until_ms > 0: frozen until this timestamp or a manual reset
frozen_until_ms = 0: frozen until a manual reset

Channel Information

Channel	Scope	Arguments	Interval
mmp_frozen	private	pairs	[`raw`, `100ms`]

for USD-M system, MMP Frozen Event argument is paris

Response

Name	Type	Description
pair	string	Currency pair
frozen_until_ms	integer	MMP frozen until timestamp

Constant definitions

Account Mode

Account mode	Description
classic	Classic mode
um	Unified margin mode
migrating-to-um	Migrating from classic to um (transient state)
migrating-to-classic	Migrating from um to classic (transient state)

Risk mode

Mode	Description
regular	Regular account
portfolio_margin	Determines margin requirements base on future & option portfolio

Instrument Category

Category	Description
option	Options
future	Future (include perpetual)

Option type

Option type	Description
call	Call option
put	Put option

Order side

Order side	Description
buy	Buy
sell	Sell

Order type

To place market order, client input order_type = market
Since market order is translated into special limit order in system, client will see limit(m) for market order in API order query response

OrderType	Description
limit	Limit order
market	Market order
trigger-limit	Trigger limit order
trigger-market	Trigger market order

Order status

Status	Description
pending	Order initial state
open	Order active state
filled	Order fully filled
cancelled	Order is cancelled

ConditionalOrder status

Status	Description
open	Conditional Order is active
triggered	Conditional order is triggered
cancelled	Conditional order is cancelled without being triggered
failed	Conditional order failed to be triggered

Order time in force

Status	Description
gtc	Good till cancel
fok	Fill or kill
ioc	Immediate or cancel

Usdx Order auto price type

Option only

Type	Description
base	Place order with base currency price
iv	Place order with imply volatility

Order source

Order source	Description
api	From API
web	From Web GUI
app	From mobile app

UM transaction log type

Um Tx log type	Description
spot-trade-pay	Paying out cash for spot trade
spot-trade-recv	Receiving cash of spot trade
deri-trade	COIN-M trade
deri-delivery	COIN-M delivery
deri-settlement	COIN-M settlement
deri-socialized-fund	COIN-M socialized fund
usdx-trade	USD-M trade
usdx-delivery	USD-M delivery
usdx-settlement	USD-M settlement
usdx-socialized-fund	USD-M socialized fund
pay-accrued-interest	Paying interest
um-pex-trade-pay	Auto sell
um-pex-trade-recv	Auto buy
deposit	Deposit
bad-deposit	Deposit rollback
withdraw	Withdraw
withdraw-revert	Withdraw refund
transfer-in	Fund transfer in
transfer-out	Fund transfer out

Feerate source

Source	Description
user_defined	User defined feerate on the pair (top priority)
vip	Feerate of vip level updated volume
vip_manual	Feerate of vip level updated manually

Errors

Error Handling

A clarification of bit.com trading APIs:

When calling the trading APIs of bit.com to, e.g. placing, editing, cancelling orders, the caller will get one of the following four types of results:

A response indicating the request was successful
A response indicating the request had been rejected
A response indicating failed to get the processing result of the request
Failed to receive a response (should be handled similarly to type 3, see below)

A result of type 3. happens when the frontend web servers of bit.com failed to receive a response from the matching engine in time (due to a network issue or a timeout). The response can be in the form of

A HTTP response with status "504 - Gateway Timeout", when the failure was at the gateway layer.
A HTTP response with status "200 - OK", but the JSON error code = 18500000 (Rpc timeout)
Other forms of network errors if the failure was even before the gateway of bit.com.

When a result of type 3 happens, it is unknown to the caller whether the sent request has been received/processed/rejected by the matching engine. Therefore, the caller has to make another call checking the state of the order or the account to find out.

Error code list

Bit.com API error codes:

Error Code	Description
0	Success (no error)
18100100	General Error
18100101	Invalid Order Request
18100102	Invalid Order Side
18100103	Invalid Order Price
18100104	Invalid Order Quantity
18100105	Invalid Order Type
18100106	Invalid Time In Force
18100107	Get Position Error
18100109	Get Underlying Price Fail
18100110	Place Order Error
18100111	Marshal Order Error
18100112	Submit Order Request Error
18100113	Invalid Order ID
18100114	Get Order Error
18100115	Order Not Found
18100116	Submit Order Cancel Error
18100117	Invalid Order Status Parameter
18100119	Get Trade Error
18100120	Bad Create Option Request
18100121	Calc Strike Price Error
18100122	Create Option Error
18100123	Bad Update Option Request
18100124	Invalid Expiration
18100125	Get Option Error
18100126	Invalid Option Status
18100127	Update Option Error
18100128	Get Expiration Error
18100129	Invalid Delivery Price
18100130	Option Has Incomplete Orders
18100131	Bad Transfer Request
18100132	Invalid Transfer Quantity
18100133	Create Transfer Error
18100134	Get User Trade Error
18100135	Get Transfer Error
18100137	Get Account Error
18100138	Get Trades Error
18100139	Invalid Option Type
18100141	Invalid Currency
18100142	Get Underlying Error
18100143	Get Ticks Error
18100144	Get Mark Price Error
18100145	Get Portfolio Margin Error
18100146	Update Account Error
18100147	Get Transaction Log Error
18100148	Audit Account Error
18100149	Delivery Information Error
18100150	Exceed Max Open Order By Account
18100151	Exceed Max Open Order By Instrument
18100152	Get Open Order Count Error
18100153	Create Expiration Error
18100154	Update Access Token Error
18100155	Bad Delete Option Request
18100156	Delete Option Error
18100157	Bad Config Error
18100158	Update Config Error
18100159	Get Fee Rate Error
18100160	Invalidate Parameters Error
18100161	Get Orderbook Error
18100162	Get Index Error
18100163	Big Account Information Error
18100164	Get Uc Transfer Record Error
18100165	Invalid User Error
18100166	Insurance Account Error
18100167	Insurance Log Error
18100168	Fee Account Error
18100169	Fee Log Error
18100170	Get Delivery Error
18100171	Get Insurance Data Error
18100172	Invalid Depth Error
18100173	Invalid Expired Error
18100174	Get Orderbook Summary Error
18100175	Get Settlement Error
18100176	Get Trading View Data Error
18100177	Get User Error
18100178	Save User Error
18100179	Get Funding Chart Data Error
18100180	Invalid Order Cancel Request
18100181	Get Instrument Error
18100183	Get Future Error
18100185	Invalid Instrument
18100186	Close Position Request Error
18100187	Get Order Margin Error
18100188	Get Limit Price Error
18100189	Invalid Stop Price
18100190	Get Open Stop Order Count Error
18100191	Exceed Max Open Stop Order
18100192	Invalid Order Stop Price
18100193	Invalid Order Trigger Type
18100194	Save Stop Order Failed
18100195	Delete Expiration Error
18100196	Get Funding Rate Error
18100197	Bad Update Expiration Request
18100198	Update Expiration Error
18100199	Insufficient Balance Error
18100200	Invalid Transaction Type Error
18100201	Get Index Data Error
18100202	Invalid Argument Error
18100204	Invalid Page Parameter Error
18100205	Get Market Summary Error
18100206	System Account Error
18100210	Invalid Operator Id Error
18100211	Get Takeover Records Error
18100212	Invalid Operator User Ids
18100213	Start Takeover
18100214	Invalid Account Id
18100215	Exit Admin Takeover
18100216	Link Admin To Account
18100217	Unlink Admin From Account
18100218	Calc Portfolio Margin
18100223	Get Takeover Orders Error
18100224	Invalid Amend Order Request Error
18100225	Auto Price Error
18100226	Takeover Switch User Id Error
18100227	Account Is Locked Error
18100228	Get Bankruptcy Error
18100229	Filled Bankruptcy Request Error
18100230	Exceed Max Stop Order Error
18100231	Invalid Stop Order Status Error
18100232	Verification Code Mail Error
18100233	Verification Code Phone Error
18100234	Rpc Error: Order not active
18100235	Fill Bankruptcy Error
18100236	Invalid Order Role
18100237	No Block Order Permission
18100238	Self Trading Error
18100239	Illegal Valid Time Error
18100240	Invalid Block Order Request
18100241	Accept Block Order Error
18100242	Reject Block Order Error
18100243	Calculate Option Mm Error
18100244	Reduce Only Error
18100245	Block Trade Service Stop Error
18100246	Get Stop Trigger Price Error
18100247	Get Open Order Size Error
18100248	Get Position Size Error
18100249	Exceed Max Open Order By Option
18100250	Exceed Max Open Order By Future
18100251	Marketing Bonus Request Error
18100252	Bonus Error
18100253	Get Bonus Error
18100254	Marketing Refund Request Error
18100255	Refund Error
18100256	Get Active Error
18100257	Get Account Configuration Error
18100258	Invalid User Kyc Level Error
18100259	Duplicate Bonus Error
18100260	Calc Position Summary Error
18100261	Exceed Account Delta Error
18100262	Withdraw Request Error
18100263	Withdraw Error
18100264	Invalid User Defined String
18100265	Invalid Blocktrade Source
18100266	Send Captcha Error
18100267	Invalid Captcha Error
18100268	Invalid Number String
18100269	Exceed Max Position Error
18100270	Exceed Max Open Quantity Error
18100271	Get Block Order Error
18100272	Duplicated Blocktrade Key
18100273	Creat Bonus Active Error
18100274	Bonus Total Limit Error
18100275	Invalid Batch Order Request
18100276	Invalid Batch Order Count Request
18100277	Rpc New Batch Order Error
18100278	Fetch Db Timeout
18100279	Takeover Not Allowed
18100280	Invalid Batch Order Amend Request
18100281	Not Found In Open Orders
18100282	Rpc Batch Amend Error
18100285	Mmp error
18100304	Invalid Channel Error
18100305	Invalid Category Error
18100306	Invalid Interval Error
18100311	CashBalance Smaller Than AccruedInterest
18100312	Pair Not Allowed For Pm
18100313	Not Enough Margin
18100637	Get TpslConfig Error
18100638	Invalid TpslMode Error
18100639	TpslMode MisMatchCfg ModeError
18100640	Invalid TpslTriggerType Error
18100641	Invalid TpslQty Error
18100642	TpslQty Negtive Error
18100401	Invalid Address
18100402	Address Not Whitelisted
18100403	Invalid Fund Password
18100404	Withdrawal Order Not Exist
18100405	KYT Rejected
18100406	Withdraw Too Frequently
18100407	Withdraw Limit Exceeded
18100408	Withdraw Amount Less Than Minimum Amount
18100500	Trading permission error
18100501	Internal Db error
18100502	Internal cache error
18100503	Internal network error
18200300	Rate Limit Exceed
18200301	Login Error
18200302	Authentication Error, auth code: 17002012: no permission to access this endpoint 17002011: invalid IP address 17002010: signature error 17002014: timestamp expired 17002006: internal error 17002013: Invalid access key
18200303	Exceed Max Connection Error
18300300	Not Part In Competition
18300301	Register Competition Failed
18300302	Registered Competition
18400300	Cancel Only Period
18500000	Rpc timeout error (API result in uncertain state, see above info)

Changelogs

Introduction

API hosts (production)

API hosts (testnet)

API rate limits

Authentication

Private API mandatory fields

Signature algorithm

Example for GET request

Example for POST request

POST request json body with boolean field

request

string to sign

POST request json body with array field

request

string to sign

Sharding

Id uniqueness

Query pagination

API summary

System

Get server timestamp

GET /linear/v1/system/time

Query Parameters

Response

Get system version

GET /linear/v1/system/version

Query Parameters

Response

Get cancel only status

GET /linear/v1/system/cancel_only_status

Query parameters

Response

Market

Get index

GET /um/v1/index_price

Query parameters

Response

Get configs

GET /linear/v1/configs

Query parameters

Response

Get instruments

GET /linear/v1/instruments

Query parameters

Response

Get active option pairs

GET /linear/v1/option_pairs

Query parameters

Response

Get tickers

GET /linear/v1/tickers

Query parameters

Response

Get orderbooks

GET /linear/v1/orderbooks

Query parameters

Response

Get market trades

GET /linear/v1/market/trades

Query parameters

Response

Get klines

GET /linear/v1/klines

Query parameters

Response

Get market deliveries

GET /linear/v1/market/deliveries

Query parameters

Response

Get market settlement price info

GET /linear/v1/settlement_prices

Query parameters

Response

Get market summary

GET /linear/v1/market/summary

Query parameters

Response

Get funding rate

GET /linear/v1/funding_rate

Example for `GET` request

Example for `POST` request