NAV Navbar
json

Changelogs

Changelogs

Version: V0.1.7.3 (Date: 2024 Sep 26)

Add FD (funding) account balances query endpoint: GET /um/v1/fd/balances
Cancel-only status GET /linear/v1/system/cancel_only_status add upgrading info

Version: V0.1.7.2 (Date: 2024 Aug 27)

Add system quote ccy endpoint: GET /linear/v1/anon/system_quote_currencies
Add pos margin mode query endpoint: GET /linear/v1/pos_margin_mode
Add pos margin mode update endpoint: POST /linear/v1/pos_margin_mode
Add isolated margin query endpoint: GET /linear/v1/isolated_margins
Add isolated margin update endpoint: POST /linear/v1/isolated_margins
Add isolated margin max-addable endpoint: GET /linear/v1/isolated_margins/max_addable
Add isolated margin max-removable endpoint: GET /linear/v1/isolated_margins/max_removable
Add new field in GET /linear/v1/positions, GET /linear/v1/aggregated/positions, Websocket position channel

Add new field in GET /linear/v1/orders, Websocket order channel

Add new error codes:

Old change logs

version time content
V0.1.7.1
2024 JUL 5
Add error codes: 18100298, 18100299
V0.1.7.0
2023 SEP 30
GET /um/v1/transactions Add transaction type usdx-funding-settlement
Add closed_pnl in trade query /linear/v1/user/trades and websocket channel user_trade
V0.1.6.2
2023 JUL 1
* APIs and websocket channels of orders and trades, add fields related to fee deduction
V0.1.6.1
2023 JUN 2
* POST /linear/v1/orders support twap_market
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/USDT-M blocktrade:
POST /linear/v1/blocktrades
GET /linear/v1/blocktrades
GET /linear/v1/platform_blocktrades
GET /linear/v1/user/info

* Support USD-M/USDT-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/USDT-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)

API hosts (testnet)

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.

Authentication

Private API mandatory fields

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

  1. Request parameters: JSON Body for POST, query string for the rest
  2. 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'
  3. 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.
  4. Signature = hex(hmac_sha256(str_to_sign, secret_key))
  5. 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,

Example

request

string to sign

POST request json body with array field

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,

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

Example

request

string to sign

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

Path Method Description Scope Rate Limit Type Permission
/linear/v1/orders POST Place new order private trade USD-M/USDT-M trade
/linear/v1/cancel_orders POST Cancel order private trade USD-M/USDT-M trade
/linear/v1/close_positions POST Close positions private trade USD-M/USDT-M trade
/linear/v1/amend_orders POST Amend order private trade USD-M/USDT-M trade
/linear/v1/batchorders POST Place multiple orders private trade USD-M/USDT-M trade
/linear/v1/amend_batchorders POST Amend multiple orders private trade USD-M/USDT-M trade
/linear/v1/update_mmp_config POST Update MMP config private trade USD-M/USDT-M trade
/linear/v1/reset_mmp POST Reset MMP state private trade USD-M/USDT-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/USDT-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"

Response

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

Response

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

Response


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

Get cancel-only status after system maintenance.

status
status=1: means cancel-only or system upgrading is in effective.
status=0: means cancel-only period is finished and system is not upgrading, 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.

is_upgrading
The system is upgrading or not.

Query parameters

None

Response

Name Type Description
status integer Cancel-only or upgrading status.
remain_ms integer Remain time (in milliseconds) for the cancel-only period to finish.
is_upgrading boolean The system is upgrading or not.

Market

Get System quote currencies

GET /linear/v1/anon/system_quote_currencies

curl "https://betaapi.bitexch.dev/linear/v1/anon/system_quote_currencies"

Response

{
    "code": 0,
    "message": "",
    "data": ["USDT"]
}

Get system supported quote currencies.

Query parameters

NONE

Response

Name Type Description
data array quote currency list

Get index

GET /um/v1/index_price

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

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "index_name": "BTC-USDT",
            "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"

Response

{
    "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/USDT-M system configs in Quote currency and pair level.

Query parameters

NONE

Response

Name Type Description
pairs array Pair configs
ccy_open_order_params array Quote currency level open order configs
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
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=USDT"

Response

{
  "code": 0,
  "message": "",
  "data": [
    {
      "instrument_id": "BTC-USDT-PERPETUAL",
      "created_at": 1640944328750,
      "updated_at": 1640944328750,
      "base_currency": "BTC",
      "quote_currency": "USDT",
      "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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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=USDT"

Response


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

Get pairs with active option instruments.

Query parameters

Parameter Type Required Default Description
currency string true "" Quote 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-USDT-28APR23-25000-C"

Response


{
    "code": 0,
    "message": "",
    "data": {
        "time": 1680751572771,
        "instrument_id": "BTC-USDT-28APR23-25000-C",
        "best_bid": "3155.00000000",
        "best_ask": "",
        "best_bid_qty": "0.10000000",
        "best_ask_qty": "",
        "ask_sigma": "",
        "bid_sigma": "0.14172180",
        "last_price": "0.00000000",
        "last_qty": "0.00000000",
        "open24h": "2618.00000000",
        "high24h": "2618.00000000",
        "low24h": "2618.00000000",
        "price_change24h": "0.00000000",
        "volume24h": "0.00000000",
        "volume_usd24h": "0.00000000",
        "open_interest": "0.00000000",
        "underlying_name": "BTC-USDT",
        "underlying_price": "28154.92000000",
        "mark_price": "3235.76757442",
        "index_price": "28085.79850000",
        "sigma": "0.34255983",
        "delta": "0.92637271",
        "vega": "9.68923779",
        "theta": "-7.47882399",
        "gamma": "0.00005869",
        "min_sell": "2672.00000000",
        "max_buy": "3799.00000000",
        "display_name": "BTC-USDT-28APR23-25000-C"
    }
}


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-USDT-PERPETUAL"

Response

{
  "code": 0,
  "message": "",
  "data": {
    "instrument_id": "BTC-USDT-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=USDT"

Response

{
  "code": 0,
  "message": "",
  "data": [
    {
      "created_at": 1642994704633,
      "trade_id": 1005483402,
      "instrument_id": "ETH-USDT-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-USDT-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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
pair string true "" Pair
category string false "" Category
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-USDT-PERPETUAL&timeframe_min=1d"

Response

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

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USDT-26JUL22-110-C",
            "position": "1.00000000",
            "exercise": true,
            "delivery_price": "115.63000000",
            "delivery_pnl": "5.63000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USDT-26JUL22-110-P",
            "position": "1.00000000",
            "exercise": false,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.00000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USDT-26JUL22-115-C",
            "position": "1.00000000",
            "exercise": true,
            "delivery_price": "115.63000000",
            "delivery_pnl": "0.63000000"
        },
        {
            "type": "delivery",
            "timestamp": 1658822400000,
            "instrument_id": "BCH-USDT-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 "" Quote 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=USDT&start_time=1600421456435&end_time=1603013456435"

Response


{
  "code": 0,
  "message": "",
  "data": {
    "data": {
      "1642204800000": [
        {
          "date": 1642204800000,
          "currency": "USDT",
          "instrument_id": "BCH-USDT-PERPETUAL",
          "settlement_type": "settlement",
          "price": "389.66802679"
        },
        {
          "date": 1642204800000,
          "currency": "USDT",
          "instrument_id": "BTC-USDT-PERPETUAL",
          "settlement_type": "settlement",
          "price": "43076.50631543"
        },
        {
          "date": 1642204800000,
          "currency": "USDT",
          "instrument_id": "ETH-USDT-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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
instrument_id string false "" Instrument ID
start_time integer true Start timestamp
end_time integer true End timestamp

Response

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=USDT&category=future"

Response


{
  "code": 0,
  "message": "",
  "data": [
    {
      "instrument_id": "BTC-USDT-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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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-USDT-PERPETUAL"

Response


{
  "code": 0,
  "message": "",
  "data": {
    "instrument_id": "BTC-USDT-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-USDT-PERPETUAL&start_time=1603260000000&end_time=1603346400000&history_type=1H"

Response


{
    "code": 0,
    "message": "",
    "data": [
        {
            "instrument_id": "BTC-USDT-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"

Response

{
  "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/USDT-M volume
details array Volume details

details

Name Type Description
margin_currency string Quote currency(GET /linear/v1/anon/system_quote_currencies)
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"

Response


{
    "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/USDT-M products can only be traded by UM mode users.
um mode,get account information with this endpoint.

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

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

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 FD account balances

GET /um/v1/fd/balances


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

Response

{
  "code": 0,
  "message": "",
  "data": [
    {
      "ccy": "ETH",
      "cash_balance": "0.100000000000",
      "frozen": "0.000000000000",
      "available_balance": "0.100000000000",
      "index_price": "2333.895000000000",
      "ccy_display_name": "ETH",
      "is_square_option": false
    }
  ]
}

Get FD (Funding) Account balances information. No currency with a balance of 0 is returned.

Query parameters

No any parameters.

Response

Name Type Desc
ccy string currency
ccy_display_name string Display name of the currency
cash_balance string Cash Balance of funding account
frozen string Frozen of funding account
available_balance string Available balance of funding account = cash_balance - frozen
index_price string Currency index price
is_square_option bool Whether the currency is square option

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" 


Response

{
    "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/USDT-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 "" Transaction currency
instrument_id string false "" Instrument ID
start_time integer false Three 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
merge_twap_market bool false Aggregate twap order info

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" 

Response

{
    "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/USDT-M configs.

Query parameters

NONE

Response

Name Type Desc
pairs array Pair configs
ccy_open_params array Quote currency level open order configs
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
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
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" 

Response

{
    "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-8628663d-678c-49b0-8d4e-a8691152a2d0" "https://betaapi.bitexch.dev/linear/v1/positions?timestamp=1721901222939&signature=860e9e1248c8d2de78fde8b3fccd443d89ca31a9db53642b52e6a659bf434df7" 

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "user_id": 51140,
            "instrument_id": "LTC-USDT-PERPETUAL",
            "expiration_at": 4102444800000,
            "qty": "5.000000000000",
            "initial_margin": "61.495027970000",
            "maintenance_margin": "3.843439248125",
            "avg_price": "62.000000000000",
            "session_avg_price": "62.000000000000",
            "mark_price": "61.495027970000",
            "index_price": "68.865000000000",
            "last_price": "62.000000000000",
            "qty_base": "5.000000000000",
            "liq_price": "0.000000000000",
            "session_funding": "0.364122397724",
            "position_pnl": "-2.524860150000",
            "position_session_upl": "-2.524860150000",
            "position_session_rpl": "0.364122397724",
            "category": "future",
            "roi": "-0.041057955958",
            "option_position_value": "",
            "future_value": "307.475139850000",
            "future_position_value": "307.475139850000",
            "leverage": "5.000000000000",
            "display_name": "LTC-USDT-PERPETUAL",
            "adl_level": "4",
            "pos_type": 20,
            "isolated_pos_hold": "61.000688700000",
            "isolated_mb": "58.457237750000",
            "isolated_mm": "3.843206863125",
            "isolated_im": "61.491309810000",
            "isolated_margin_ratio": "0.065722999715"
        }
    ]
}

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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
pair string false "" Pair
category string false "" Category
instrument_id string false "" Instrument ID

Response

Name Type Desc
user_id integer User ID
instrument_id string Instrument ID
qty string Signed position size in COIN (base currency)
qty_base string Signed position size in COIN (base currency), Same as qty
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
position_pnl string Position P&L
session_funding string Session funding (in every 8 hours)
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)
adl_level string ADL level(value in 1,2,3,4), higher level means higher chance to be liquidated
session_avg_price string Session average price
position_session_upl string Position session unrealized P&L
position_session_rpl string Position session realized P&L
pos_type integer Pos type
isolated_pos_hold string Isolated position hold
isolated_mb string Isolated Margin Balance
isolated_mm string Isolated Maintenance Balance
isolated_im string Isolated Initial Margin
isolated_margin_ratio string Isolated Margin Ratio

Get aggregated user positions

GET /linear/v1/aggregated/positions

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

Response


{
    "code": 0,
    "message": "",
    "data": [
        {
            "user_id": 51140,
            "instrument_id": "LTC-USDT-PERPETUAL",
            "expiration_at": 4102444800000,
            "qty": "5.000000000000",
            "initial_margin": "61.495027970000",
            "maintenance_margin": "3.843439248125",
            "avg_price": "62.000000000000",
            "session_avg_price": "62.000000000000",
            "mark_price": "61.495027970000",
            "index_price": "68.865000000000",
            "last_price": "62.000000000000",
            "qty_base": "5.000000000000",
            "liq_price": "0.000000000000",
            "session_funding": "0.364122397724",
            "position_pnl": "-2.524860150000",
            "position_session_upl": "-2.524860150000",
            "position_session_rpl": "0.364122397724",
            "category": "future",
            "roi": "-0.041057955958",
            "option_position_value": "",
            "future_value": "307.475139850000",
            "future_position_value": "307.475139850000",
            "leverage": "5.000000000000",
            "display_name": "LTC-USDT-PERPETUAL",
            "adl_level": "4",
            "pos_type": 20,
            "isolated_pos_hold": "61.000688700000",
            "isolated_mb": "58.457237750000",
            "isolated_mm": "3.843206863125",
            "isolated_im": "61.491309810000",
            "isolated_margin_ratio": "0.065722999715"
        }
    ]
}

Get positions of current user and all sub-account users.

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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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), Same as qty
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
position_pnl string Position P&L
session_funding string Session funding (in every 8 hours)
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)
adl_level string ADL level(value in 1,2,3,4), higher level means higher chance to be liquidated
session_avg_price string Session average price
position_session_upl string Position session unrealized P&L
position_session_rpl string Position session realized P&L
pos_type integer Pos type
isolated_pos_hold string Isolated position hold
isolated_mb string Isolated Margin Balance
isolated_mm string Isolated Maintenance Balance
isolated_im string Isolated Initial Margin
isolated_margin_ratio string Isolated Margin Ratio

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=USDT&pair=BTC-USDT&timestamp=1659186383799&signature=cc17d4d9f67aabb254ba58085ea6bf498122d88cdf0f991e983674c1bb3a1e2b" 

Response

{
    "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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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" 


Response

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

Deprecated.

please use GET /um/v1/transactions type = 'usdx-funding-settlement'

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" 

Response

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

Response

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

Response

{
    "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-USDT&timestamp=1600050649936&signature=a6f2511ab776674c4a9db39835f22c8bf2bc5aac4eb0070c8c4d577e89e016ef" 

Response

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

Response


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

Enable or disable Cancel On Disconnect

POST /v1/account_configs/cod

curl -X POST "https://betaapi.bitexch.dev/v1/account_configs/cod" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"cod":true, "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}'

Response

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

Enable or disable Cancel On Disconnect. If Cancel On Disconnect is enabled, all orders of the account(web AND API) will be cancelled when all ‘private' websocket connections are disconnected.

Post json body

Parameter Type Required Default Description
cod bool true "" Whether to enable Cancel On Disconnect

Response

None


Get Cancel On Disconnect configuration

GET /v1/account_configs/cod

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/account_configs/cod?timestamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807"

Response

{
    "code": 0,
    "message": "",
    "data": {
        "cod": true
    }
}

Get Cancel On Disconnect configuration of the account

Query parameters

None

Response

Name Type Desc
cod bool Whether to enable Cancel On Disconnect

Query user pos margin mode

GET /linear/v1/pos_margin_mode

curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/linear/v1/pos_margin_mode?instrument_id=ETH-USDT-PERPETUAL&timestamp=1721098235948&signature=70c2511ab776674c4a9ab39835f22c8bf2bc5aac4eb0070c8c4d577e89e016ab" 

Response

{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 8001,
        "instrument_id": "ETH-USDT-PERPETUAL",
        "pos_margin_mode": 2
    }
}    

Query user position margin mode

Query parameters

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

Response

Name Type Desc
user_id int User Id
instrument_id string Instrument Id
pos_margin_mode integer Pos margin mode

Update user pos margin mode

POST /linear/v1/pos_margin_mode

curl -X POST "https://betaapi.bitexch.dev/linear/v1/pos_margin_mode" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id":"ETH-USDT-PERPETUAL", "pos_margin_mode": 2, "timestamp": 1590572422557, "signature": "9y8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d21"}'

Response

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

Update user position margin mode

Post json body

Parameter Type Required Default Description
instrument_id string true "" Instrument id
pos_margin_mode integer true 0 Pos margin mode

Response

Name Type Desc
data string ok

Query isolated margins

GET /linear/v1/isolated_margins

curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/linear/v1/isolated_margins?instrument_id=ETH-USDT-PERPETUAL&timestamp=1721098235948&signature=15cj511ab776674c4a9ab39835f22c8bf2bc5aac4eb0070c8c4d577e89e016xu" 

Response

{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 8001,
        "instrument_id": "ETH-USDT-PERPETUAL",
        "pos_type": 20,
        "mb": "20000.00000000",
        "mm": "10000.00000000",
        "im": "10000.00000000",
    }
}    

Query user isolated account margins

Query parameters

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

Response

Name Type Desc
user_id int User Id
instrument_id string Instrument Id
pos_type integer Pos type
mb string Margin balance
mm string Maintenance Margin
im string Initial Margin

Update isolated margins

POST /linear/v1/isolated_margins

curl -X POST "https://betaapi.bitexch.dev/linear/v1/isolated_margins" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id":"ETH-USDT-PERPETUAL", "change": "10", "timestamp": 1590572422725, "signature": "j38c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66dn1"}'

Response

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

Update isolated margin

Post json body

Parameter Type Required Default Description
instrument_id string true "" Instrument id
change string true "" margin change, positive value = addition, negative value = subtraction.

Response

Name Type Desc
data string ok

Query isolated margins max addable

GET /linear/v1/isolated_margins/max_addable

curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/linear/v1/isolated_margins/max_addable?instrument_id=ETH-USDT-PERPETUAL&timestamp=1721098235948&signature=15cj511ab776674c4a9ab39835f22c8bf2bc5aac4eb0070c8c4d577e89e016xu" 

Response

{
    "code": 0,
    "message": "",
    "data": {
        "max_addable": "3000.00000000",
        "initial_margin": "10000.00000000",
        "curr_pos_margin": "10000.00000000",
        "liq_price": "80000.0000000",
        "adjusted_liq_price": "90000.0000000",
    }
}    

Query user isolated account max-addable: min(0, cross_ab)

Query parameters

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

Response

Name Type Desc
max_addable string Max addable
initial_margin string Initial Margin
curr_pos_margin string Current position margin
liq_price string Liq price
adjusted_liq_price string Liq price after margin adjusted

Query isolated margins max removable

GET /linear/v1/isolated_margins/max_removable

curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/linear/v1/isolated_margins/max_removable?instrument_id=ETH-USDT-PERPETUAL&timestamp=1721098235948&signature=15cj511ab776674c4a9ab39835f22c8bf2bc5aac4eb0070c8c4d577e89e016xu" 

Response

{
    "code": 0,
    "message": "",
    "data": {
        "max_removable": "800.00000000",
        "initial_margin": "10000.00000000",
        "curr_pos_margin": "10000.00000000",
        "liq_price": "80000.0000000",
        "adjusted_liq_price": "90000.0000000",
    }
}    

Query user isolated account max-removable: max (0, min(isolated_mb, isolated_pos_margin) - isolated_im)

Query parameters

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

Response

Name Type Desc
max_removable string Max removable
initial_margin string Initial Margin
curr_pos_margin string Current position margin
liq_price string Liq price
adjusted_liq_price string Liq price after margin adjusted

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-USDT-PERPETUAL", "price": "5000", "qty": "3", "side": "buy", "time_in_force": "gtc", "auto_price": "", "label":"hedge", "hidden": false, "timestamp": 1589523989378, "signature": "68b658eb68f4ce529623bb4505f5c1c6408b37064a9a5f2102d08088e59d917c"}' 


Response

{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "17552314",
        "created_at": 1589523803017,
        "updated_at": 1589523803017,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-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,
        "fee": "0.000000000000",
        "fee_ccy": "USDT",
        "fee_deduction_enabled": true,
        "fee_in_deduction_ccy": "0.088423738581",
        "fee_deduction_ccy": "TONCOIN",
        "fee_deduction_rate": "0.202100000000"
    }
}

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)




Example:
Twap order: p1
Child orders(like other exchange orders): o1, o2, o3
Trades of child order: t1-1, t1-2 (trades of o1), t2-6(trade of o2), t3-7(trade of o3)

Query orders: GET /linear/v1/orders

Query trade: GET /linear/v1/user/trades

Query transactions(GET /um/v1/transactions)


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
reduce_only bool Indicate reduce only or not (for PERPETUAL)
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)
post_only bool Indicate post only or not
reject_post_only bool Indicate reject post only or not
reduce_only bool Indicate reduce only or not
mmp bool Indicate mmp order or not
source string Order source
hidden bool Indicate hidden order or not
fee string Transaction fees
fee_ccy string Fee currency
fee_deduction_enabled bool Fee deduction enabled
fee_in_deduction_ccy string Transaction fees in deduction currency
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio

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":"USDT", "orders_data": [{"instrument_id": "BTC-USDT-", "price": "50000", "qty": "1.5", "side": "buy", "hidden": true}, {"instrument_id": "BTC-USDT-PERPETUAL", "price": "50010", "qty": "2", "side": "sell"}], "timestamp": 1596782252388, "signature": "0b8b64d2f35f9742a17af4ee0b993d0248a27a98f320abbfe8e7316f184e30d5"}' 


Response

{
    "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,
                "fee": "0.000000000000",
                "fee_ccy": "USDT",
                "fee_deduction_enabled": true,
                "fee_in_deduction_ccy": "0.088423738581",
                "fee_deduction_ccy": "TONCOIN",
                "fee_deduction_rate": "0.202100000000",
                "error_code": 18100185,
                "error_msg": "Invalid instrument BTC-USDT-"
            },
            {
                "order_id": "501758",
                "created_at": 1596782252996,
                "updated_at": 1596782252996,
                "user_id": "51140",
                "instrument_id": "BTC-USDT-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,
                "fee": "0.000000000000",
                "fee_ccy": "USDT",
                "fee_deduction_enabled": true,
                "fee_in_deduction_ccy": "0.088423738581",
                "fee_deduction_ccy": "TONCOIN",
                "fee_deduction_rate": "0.202100000000",
                "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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
orders_data array true Order request list(see below)
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
reduce_only bool Indicate reduce only or not (for PERPETUAL)
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
fee string Transaction fees
fee_ccy string Fee currency
fee_deduction_enabled bool Fee deduction enabled
fee_in_deduction_ccy string Transaction fees in deduction currency
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
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": "USDT", "order_id": "44092860", "instrument_id":"BTC-USDT-PERPETUAL", "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}' 



Response

{
    "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: all_global, all_cond_orders, order_id_list, label, instrument_id, pair, category, currency.
Batch cancel filter priorities: all_global > all_cond_orders > 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.

Batch cancel behaviors (notes: narrow the cancel scope will get faster response time):

Post json body

Parameter Type Required Default Description
currency string false "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
order_id string false "" Order ID (need to use with instrument_id)
pair string false "" Pair
instrument_id string false "" Instrument ID (if order_id if provided, instrument_id is required)
order_id_list array false "" List of (order_id + instrument_id), e.g [{"instrument_id":"BTC-USDT-PERPETUAL","order_id":"1001"}, {"instrument_id":"BTC-USDT-29JUL22-24250-C","order_id":"1002"}]
category string false "" Category
label string false "" Order label
all_cond_orders bool false false Cancel all conditional orders only (Limit orders remain unchanged)
all_global bool false false Cancel all limit orders and all conditional orders
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": "USDT", "order_id": "1206764", "instrument_id":"BTC-USDT-PERPETUAL", "price": "49000", "timestamp": 1590760362688, "signature": "a74dda0f2bdaf1e1587a5e7577a281497cb66607166bd3b7e0cc4c805c750bf1"}' 



Response

{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "1206764",
        "created_at": 1590760363846,
        "updated_at": 1590760363846,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-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,
        "fee": "0.000000000000",
        "fee_ccy": "USDT",
        "fee_deduction_enabled": true,
        "fee_in_deduction_ccy": "0.088423738581",
        "fee_deduction_ccy": "TONCOIN",
        "fee_deduction_rate": "0.202100000000",
    }
}

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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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
auto_price string false "" New auto price 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
fee string Transaction fees
fee_ccy string Fee currency
fee_deduction_enabled bool Fee deduction enabled
fee_in_deduction_ccy string Transaction fees in deduction currency
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio

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": "USDT", "orders_data": [{"order_id": "572083", "instrument_id":"BTC-USDT-PERPETUAL", "price": "50000", "qty": "1.3"}, {"order_id": "invalid-order-id", "instrument_id":"BTC-USDT-PERPETUAL", "price": "50000", "qty": "0.2"}], "timestamp": 1597313835731, "signature": "c8b5fddd5f2cfa1517854dc54c51e7c3b79af91f0927ea1389ba43dbeee45652"}' 


Response

{
    "code": 0,
    "message": "",
    "data": {
        "orders": [
            {
                "order_id": "572083",
                "created_at": 1597313836214,
                "updated_at": 1597313836214,
                "user_id": "51140",
                "instrument_id": "BTC-USDT-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,
                "fee": "0.000000000000",
                "fee_ccy": "USDT",
                "fee_deduction_enabled": true,
                "fee_in_deduction_ccy": "0.088423738581",
                "fee_deduction_ccy": "TONCOIN",
                "fee_deduction_rate": "0.202100000000",
                "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,
                "fee": "0.000000000000",
                "fee_ccy": "USDT",
                "fee_deduction_enabled": true,
                "fee_in_deduction_ccy": "0.088423738581",
                "fee_deduction_ccy": "TONCOIN",
                "fee_deduction_rate": "0.202100000000",
                "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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
orders_data array true Amend request list(see below)
Parameter Type Required Default Description
currency string true "" Quote 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
fee string Transaction fees
fee_ccy string Fee currency
fee_deduction_enabled bool Fee deduction enabled
fee_in_deduction_ccy string Transaction fees in deduction currency
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
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-USDT-PERPETUAL", "price": "51000", "order_type": "limit", "timestamp": 1589524756236, "signature": "5bf4f9f00722d133336e736196c09a8e02c634dc0deacf2cf12413049d8d8b06"}' 




Response



{
    "code": 0,
    "message": "",
    "data": {
        "order_id": "17553311",
        "created_at": 1589524757818,
        "updated_at": 1589524757818,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-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=USDT&category=future&timestamp=1589522687689&signature=89d5a1d929e7baa247021e090f9f634f02a7fc6c82a44c8de3bb04fa6b005a7b" 

Response

{
    "code": 0,
    "message": "",
    "data": [{
        "order_id": "7610691",
        "created_at": 1589183001000,
        "updated_at": 1589183001000,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-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",
        "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,
        "fee": "0.00000000",
        "fee_ccy": "USDT",
        "is_fee_deducted": true,
        "fee_in_deduction_ccy": "3.000000000000",
        "fee_deduction_ccy": "TONCOIN",
        "fee_deduction_rate": "0.202100000000",
        "ext": "",
        "pos_type": 0
    }]
}

Get open orders by currency, category, instrument_id

Query parameters

Parameter Type Required Default Description
currency string true "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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
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/USDT-M order
fee string Transaction fees
fee_ccy string Fee currency
fee_deduction_enabled bool Fee deduction enabled
fee_in_deduction_ccy string Transaction fees in deduction currency
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
ext string internal field
pos_type integer Pos type

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=USDT&instrument_id=BTC-USDT-PERPETUAL&order_id=7718222&start_time=1585270800000&end_time=1589522084000&include_open=true&offset=1&limit=10&timestamp=1589523178651&signature=2092cebba4f082f9c8718344cdad9bed83950b5fe90b3a875b708898bfd89b20" 


Response



{
    "code": 0,
    "message": "",
    "data": [{
        "order_id": "7718222",
        "created_at": 1589202185000,
        "updated_at": 1589460149000,
        "user_id": "51140",
        "instrument_id": "BTC-USDT-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",
        "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,
        "fee": "0.00000000",
        "fee_ccy": "USDT",
        "is_fee_deducted": true,
        "fee_in_deduction_ccy": "3.000000000000",
        "fee_deduction_ccy": "TONCOIN",
        "fee_deduction_rate": "0.202100000000",
        "ext": "",
        "pos_type": 0
    }]
}


Get order history.

Query parameters

Parameter Type Required Default Description
currency string true "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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
merge_twap_market bool false false Aggregate twap order info

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
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/USDT-M order
fee string Transaction fees
fee_ccy string Fee currency
fee_deduction_enabled bool Fee deduction enabled
fee_in_deduction_ccy string Transaction fees in deduction currency
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
ext string internal field
pos_type integer Pos type

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=USDT&category=future&order_id=17551020&start_time=1585270800000&end_time=1589522084000&offset=1&limit=10&timestamp=1589523590679&signature=c4788e3a77b6000424b55067f9ba38009b34d12e482b1c80186756857c869bb5" 


Response


{
    "code": 0,
    "message": "",
    "data": [{
        "user_id": 51130,
        "trade_id": "23210268",
        "order_id": "17551020",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "qty": "2.00000000",
        "price": "50010.00000000",
        "sigma": "0.00000000",
        "underlying_price": "",
        "index_price": "50012.81000000",
        "usd_price": "",
        "fee_rate": "0.00050000",
        "side": "buy",
        "created_at": 1589521371000,
        "is_taker": true,
        "order_type": "limit",
        "label": "hedge",
        "fee": "0.00000000",
        "fee_ccy": "USDT",
        "is_fee_deducted": true,
        "fee_in_deduction_ccy": "3.000000000000",
        "fee_deduction_ccy": "TONCOIN",
        "fee_deduction_rate": "0.202100000000",
        "fee_deduction_ccy_index": "1.372980000000",
        "closed_pnl": "0.03600000"
    }]
}

Get user trades

Query parameters

Parameter Type Required Default Description
currency string true "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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 500
merge_twap_market bool false false Aggregate twap order info

Response

Name Type Desc
user_id integer User ID
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_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
fee string Transaction fees
fee_ccy string Fee currency
is_fee_deducted bool Fee deduction enabled
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
fee_deduction_ccy_index string Fee deduction currency index price
closed_pnl string Trade closed pnl

Get aggregated user trades

GET /linear/v1/aggregated/trades

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


Response


{
    "code": 0,
    "message": "",
    "data": [{
        "user_id": 51130,
        "trade_id": "23210268",
        "order_id": "17551020",
        "instrument_id": "BTC-USDT-PERPETUAL",
        "qty": "2.00000000",
        "price": "50010.00000000",
        "sigma": "0.00000000",
        "underlying_price": "",
        "index_price": "50012.81000000",
        "usd_price": "",
        "fee_rate": "0.00050000",
        "side": "buy",
        "created_at": 1589521371000,
        "is_taker": true,
        "order_type": "limit",
        "label": "hedge",
        "fee": "0.00100000",
        "fee_ccy": "TONCOIN",
        "is_fee_deducted": true,
        "fee_deduction_ccy": "TONCOIN",
        "fee_deduction_rate": "0.101100000000",
        "fee_deduction_ccy_index": "1.372980000000",
        "closed_pnl": "0.03600000"
    }]
}

Get aggregated user trades of current user and all sub-account users.

Query parameters

Parameter Type Required Default Description
currency string true "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
pair string false "" Pair
category string false "" Category
instrument_id string false "" Instrument 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 500
merge_twap_market bool false false Aggregate twap order info

Response

Name Type Desc
user_id integer User ID
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_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
fee string Transaction fees
fee_ccy string Fee currency
is_fee_deducted bool Fee deduction enabled
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
fee_deduction_ccy_index string Fee deduction currency index price
closed_pnl string Trade closed pnl

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-USDT-PERPETUAL&price=5000&qty=1&timestamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807" 

Response

{
    "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 Quote currency)
sell_margin string Estimated sell margin(in Quote 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=USDT&instrument_id=BTC-USDT-PERPETUAL&status=open&timestamp=1590667739793&signature=14c522605de563064ae36933604225730a8b4e254be8ce58ecc2746f5199d77f" 


Response

{
    "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-USDT-PERPETUAL",
            "user_id": 8001,
            "qty": "1.00000000",
            "price": "39000.00000000",
            "side": "buy",
            "order_type": "trigger-limit",
            "time_in_force": "gtc",
            "source": "api",
            "hidden": false
        }
    ]
}

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

Query parameters

Parameter Type Required Default Description
currency string true "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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


Get active conditional orders

GET /linear/v1/active_conditional_orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/active_conditional_orders?currency=USDT&instrument_id=BTC-USDT-PERPETUAL&timestamp=1590667739793&signature=29a17f1f44ed2258e1422504c3e9a1b6c20e587566ca90f32c3bdf7efe662208" 


Response

{
    "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-USDT-PERPETUAL",
            "user_id": 8001,
            "qty": "1.00000000",
            "price": "39000.00000000",
            "side": "buy",
            "order_type": "trigger-limit",
            "time_in_force": "gtc",
            "source": "api",
            "hidden": false
        }
    ]
}

Get active conditional orders by currency, instrument_id.

Query parameters

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

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

TPSL - New (position level)

POST /linear/v1/tpsl/new

curl -X "POST" "https://betaapi.bitexch.dev/linear/v1/tpsl/new" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-8628663d-678c-49b0-8d4e-a8691152a2d0"  -d '{"trigger_type": "mark-price", "take_profit_price": "40000", "qty": "0.5", "tpsl_mode": 1, "instrument_id": "BTC-USDT-PERPETUAL", "stoploss_price": "44000", "timestamp": 1703139275532, "signature": "bd2bf2123d2bf53ab776b1c77cf56c5dc42efaade77aecf46c41ac8f796619e8"}' 

Response


{
    "code": 0,
    "message": "",
    "data": {
        "tpsl_id": "tpsl-cm1tfipm2rc7n9vrv4b0",
        "created_at": 1703139275902,
        "update_at": 1703139275902,
        "instrument_id": "BTC-USDT-PERPETUAL",
        "qty": "0.500000000000",
        "trigger_type": "mark-price",
        "tpsl_mode": 1,
        "tp_price": "40000.000000000000",
        "tp_status": "open",
        "sl_price": "44000.000000000000",
        "sl_status": "open",
        "display_name": "BTC-USDT-PERPETUAL",
        "is_user_twap": false,
        "user_stgy_id": 0
    }
}

tpsl: take-profit/stoploss order

Create tpsl order for position. (this is different from new-order tpsl)

Parameters

Parameter Type Required Default Description
instrument_id string false "" instrument
trigger_type string true "" mark-price/index-price
qty string false "" qty (for partial mode only)
tpsl_mode int true "" tpsl_mode, 1:partial, 2:all(exit all position when triggered)
take_profit_price string true "" take profit price
stoploss_price string true "" stoploss price

Response

Name Type Desc
tpsl_id string tpsl ID
created_at integer create timestamp
updated_at integer update timestamp
instrument_id string instrument
qty string qty (for partial mode only)
trigger_type string trigger type: mark-price/index-price
tpsl_mode int tpsl_mode, 1:partial, 2:all(exit all position when triggered)
tp_price string take profit price
tp_status string take profit order status
sl_price string stoploss price
sl_status string stoploss order status
is_user_twap bool execute as TWAP after triggered
user_stgy_id int twap id (when is_user_twap=true)
display_name string display name

TPSL - Query

GET /linear/v1/tpsl/list

curl -H "X-Bit-Access-Key: ak-8628663d-678c-49b0-8d4e-a8691152a2d0" "https://betaapi.bitexch.dev/linear/v1/tpsl/list?currency=USDT&active_only=false&timestamp=1703139930897&signature=1053585256ce9a3cdd92d3750fe8e363a09b69fc26d8301d4f0e7989bbf99508" 

Response


{
    "code": 0,
    "message": "",
    "data": [
        {
            "tpsl_id": "tpsl-cm1tfipm2rc7n9vrv4b0",
            "created_at": 1703139275902,
            "update_at": 1703139275902,
            "instrument_id": "BTC-USDT-PERPETUAL",
            "qty": "0.500000000000",
            "trigger_type": "mark-price",
            "tpsl_mode": 1,
            "tp_price": "40000.000000000000",
            "tp_status": "open",
            "sl_price": "44000.000000000000",
            "sl_status": "open",
            "display_name": "BTC-USDT-PERPETUAL",
            "is_user_twap": false,
            "user_stgy_id": 0
        }
    ]
}

Query tpsl list.

Parameters

Parameter Type Required Default Description
currency string true "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
instrument_id string false "" instrument
active_only bool false false get active only
start_time integer false start timestamp
end_time integer false end timestamp
count int false 100 record count

Response

Name Type Desc
tpsl_id string tpsl ID
created_at integer create timestamp
updated_at integer update timestamp
instrument_id string instrument
qty string qty (for partial mode only)
trigger_type string trigger type: mark-price/index-price
tpsl_mode int tpsl_mode, 1:partial, 2:all(exit all position when triggered)
tp_price string take profit price
tp_status string take profit order status
sl_price string stoploss price
sl_status string stoploss order status
is_user_twap bool execute as TWAP after triggered
user_stgy_id int twap id (when is_user_twap=true)
display_name string display name

TPSL - Cancel

POST /linear/v1/tpsl/cancel

curl -X "POST" "https://betaapi.bitexch.dev/linear/v1/tpsl/cancel" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-8628663d-678c-49b0-8d4e-a8691152a2d0"  -d '{"instrument_id": "BTC-USDT-PERPETUAL", "tpsl_id": "tpsl-cm1tfipm2rc7n9vrv4b0", "cancel_mode": 1, "timestamp": 1703140404331, "signature": "295892b8a1b2a6364d5c3ea4c4c4b377f846bab428d4eff23f085aab0de75f4d"}' 

Response


{
    "code": 0,
    "message": "",
    "data": {
        "tpsl_id": "tpsl-cm1tfipm2rc7n9vrv4b0",
        "created_at": 1703139275902,
        "update_at": 1703139275902,
        "instrument_id": "BTC-USDT-PERPETUAL",
        "qty": "0.500000000000",
        "trigger_type": "mark-price",
        "tpsl_mode": 1,
        "tp_price": "40000.000000000000",
        "tp_status": "cancelled",
        "sl_price": "44000.000000000000",
        "sl_status": "open",
        "display_name": "BTC-USDT-PERPETUAL",
        "is_user_twap": false,
        "user_stgy_id": 0
    }
}

Cancel tpsl order.

Parameters

Parameter Type Required Default Description
tpsl_id string true "" tpsl ID
instrument_id string true "" instrument
cancel_mode int true 0 1=cancel all, 2=cancel take-profit, 3=cancel stoploss

Response

Name Type Desc
tpsl_id string tpsl ID
created_at integer create timestamp
updated_at integer update timestamp
instrument_id string instrument
qty string qty (for partial mode only)
trigger_type string trigger type: mark-price/index-price
tpsl_mode int tpsl_mode, 1:partial, 2:all(exit all position when triggered)
tp_price string take profit price
tp_status string take profit order status
sl_price string stoploss price
sl_status string stoploss order status
is_user_twap bool execute as TWAP after triggered
user_stgy_id int twap id (when is_user_twap=true)
display_name string display name

TPSL - Edit

POST /linear/v1/tpsl/edit

curl -X "POST" "https://alphaapi.bitexch.dev/linear/v1/tpsl/edit" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-8628663d-678c-49b0-8d4e-a8691152a2d0"  -d '{"instrument_id": "BTC-USDT-PERPETUAL", "tpsl_id": "tpsl-cm1tfipm2rc7n9vrv4b0", "take_profit_price": "41000", "timestamp": 1703142258792, "signature": "351125be64a2d5f9fafb5c5c7c29764480f05e37aa6a891ed5687a978c4cc8e9"}' 

Response


{
    "code": 0,
    "message": "",
    "data": {
        "tpsl_id": "tpsl-cm1tfipm2rc7n9vrv4b0",
        "created_at": 1703139275902,
        "update_at": 1703139275902,
        "instrument_id": "BTC-USDT-PERPETUAL",
        "qty": "0.500000000000",
        "trigger_type": "mark-price",
        "tpsl_mode": 1,
        "tp_price": "40000.000000000000",
        "tp_status": "cancelled",
        "sl_price": "44000.000000000000",
        "sl_status": "open",
        "display_name": "BTC-USDT-PERPETUAL",
        "is_user_twap": false,
        "user_stgy_id": 0
    }
}

Edit tpsl order.

Parameters

Parameter Type Required Default Description
tpsl_id string true "" tpsl ID
instrument_id string true "" instrument
take_profit_price string false "" new take-profit price
stoploss_price string false "" new stoploss price
trigger_type string false "" new trigger type
cancel_tp bool false false cancel take-profit leg
cancel_sl bool false false cancel stoploss leg
is_user_twap bool false false execute as TWAP after triggered

Response

Name Type Desc
tpsl_id string tpsl ID
created_at integer create timestamp
updated_at integer update timestamp
instrument_id string instrument
qty string qty (for partial mode only)
trigger_type string trigger type: mark-price/index-price
tpsl_mode int tpsl_mode, 1:partial, 2:all(exit all position when triggered)
tp_price string take profit price
tp_status string take profit order status
sl_price string stoploss price
sl_status string stoploss order status
is_user_twap bool execute as TWAP after triggered
user_stgy_id int twap id (when is_user_twap=true)
display_name string display name

Block Trade



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":"USDT", "label": "e8db3a92b94c482bb0e30f421415982d", "role": "maker", "counterparty": 1026, "bt_source": "<bt_source>", "trades": [{"instrument_id": "BTC-USDT-25SEP20-9000-C", "price": "0.18", "qty": "10", "side": "sell"}, {"instrument_id": "BTC-USDT-PERPETUAL", "price": "19000", "qty": "5", "side": "buy"}], "timestamp": 1594447520876, "signature": "7e8b0e7987fcb282b691d9e87c5afa9af578ed0c464190ca1fa466d18c17adde"}' 


Response

{
    "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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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)
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=USDT&bt_source=<bt_source>&timestamp=1594447524043&signature=12b1090ea6432e71f2f6d01c6f08f0ff30e3765791ebff87b4183964643d61d2" 

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "56",
            "label": "8c5d90b6cbd744ceab49d0e66b8fda68",
            "created_at": 1613637677061,
            "updated_at": 1613637678593,
            "user_id": 51140,
            "counterparty": 481554,
            "instrument_id": "BTC-USDT-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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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=USDT&bt_source=<bt_source>&timestamp=1594448745124&signature=39078700dbe556df7f34dd6e0fb444b4ead9ef6ddc8e5b24c76555b6758c68d2" 

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "56",
            "label": "8c5d90b6cbd744ceab49d0e66b8fda68",
            "created_at": 1613637677061,
            "updated_at": 1613637678593,
            "user_id": 51140,
            "counterparty": 481554,
            "instrument_id": "BTC-USDT-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 "" Quote currency(GET /linear/v1/anon/system_quote_currencies)
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" 

Response

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

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

Request

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

Response (success)

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

Response (failure)

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

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

Request

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

Response

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

Request

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

Response (snapshot)

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

Response (update)

{
    "channel":"depth",
    "timestamp":1643094930373,
    "module":"linear",
    "data":{
        "type":"update",
        "instrument_id":"BTC-USDT-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

Request

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

Response

{
    "channel":"order_book.1.20",
    "timestamp":1643095202401,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-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

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

Request

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

Response

{
    "channel":"depth1",
    "timestamp":1643095202400,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-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

Request

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

Response

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

Request

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

Response

{
    "channel":"kline.5",
    "timestamp":1643099753388,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-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

Request

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

Response

{
    "channel":"trade",
    "timestamp":1643099734031,
    "module":"linear",
    "data":[
        {
            "instrument_id":"BTC-USDT-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

Request

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

Response

{
    "channel":"market_trade",
    "timestamp":1643099734031,
    "module":"linear",
    "data":[
        {
            "instrument_id":"BTC-USDT-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

Request

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

Response

{
    "channel":"index_price",
    "timestamp":1643099733988,
    "module":"linear",
    "data":{
        "index_name":"BTC-USDT",
        "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

Request

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

Response

{
    "channel":"mark_price",
    "timestamp":1643100336677,
    "module":"linear",
    "data":{
        "instrument_id":"BTC-USDT-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

Request

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

Response

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

Request

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

Response

{
    "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-USDT-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",
            "adl_level": "4",
            "pos_type": 20,
            "isolated_pos_hold": "61.000688700000",
            "isolated_mb": "58.457237750000",
            "isolated_mm": "3.843206863125",
            "isolated_im": "61.491309810000",
            "isolated_margin_ratio": "0.065722999715"            
        }
    ]
}

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
adl_level string ADL level(value in 1,2,3,4), higher level means higher chance to be liquidated
pos_type integer Pos type
isolated_pos_hold string Isolated position hold
isolated_mb string Isolated Margin Balance
isolated_mm string Isolated Maintenance Balance
isolated_im string Isolated Initial Margin
isolated_margin_ratio string Isolated Margin Ratio

Order Channel

Request

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

Response

{
    "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,
            "filled_qty":"0.00000000",
            "hidden":false,
            "initial_margin":"",
            "instrument_id":"BTC-USDT-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",
            "fee": "0.00000000",
            "fee_ccy": "USDT",
            "is_fee_deducted": true,
            "fee_in_deduction_ccy": "3.000000000000",
            "fee_deduction_ccy": "TONCOIN",
            "fee_deduction_rate": "0.202100000000",
            "ext": "",
            "pos_type": 0
        }
    ]
}

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
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
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)
fee string Transaction fees
fee_ccy string Fee currency
fee_deduction_enabled bool Fee deduction enabled
fee_in_deduction_ccy string Transaction fees in deduction currency
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
ext string internal field
pos_type integer Pos Type

User Trade Channel

Request

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

Response

{
    "channel":"user_trade",
    "timestamp":1643101722258,
    "module":"linear",
    "data":[
        {
            "created_at":1643101722020,
            "fee_rate":"0.00010000",
            "index_price":"36214.05400000",
            "instrument_id":"BTC-USDT-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":"",
            "fee": "0.00000000",
            "fee_ccy": "USDT",
            "is_fee_deducted": true,
            "fee_in_deduction_ccy": "3.000000000000",
            "fee_deduction_ccy": "TONCOIN",
            "fee_deduction_rate": "0.202100000000",
            "fee_deduction_ccy_index": "1.372980000000",
            "closed_pnl": "0.03600000"
        }
    ]
}

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_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)
fee string Transaction fees
fee_ccy string Fee currency
is_fee_deducted bool Fee deduction enabled
fee_deduction_ccy string Fee deduction currency
fee_deduction_rate string Fee deduction remission ratio
fee_deduction_ccy_index string Fee deduction currency index price
closed_pnl string Trade closed pnl

MMP Frozen Event Channel

Request

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

Response

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

Response

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

Websocket RPC

Overview

Request

{
    "type":"RPC_name",
    "token":"If3Fy-o5TiOOTfvlmtryR0MTiziutYaYFkH3aRovJWWEXqCAD7CIdnbhGG5bwRqLRrGkOFEOjh0L",
    "params":{
        "param1":"hello"
    }
}

Response

{
    "type":"RPC_name",
    "result":{
        "code":0,
        "message":"",
        "data":{
            "field1":"world"
        }
    }
}

After the websocket connection is established, in addition to data subscription, it also supports RPC in JSON.

Private requests need token get from rest API and authentication at the first time. For details please link to Authentication Token.

Parameters

Name Type Description
type string Request type
token string Private request authentication token
params object Parameters

Response

Name Type Description
type string Request type
result object Result

result object

Name Type Description
code integer Error code
message string Error message
data object Response data

PING

Request

{
    "type":"ping",
    "params":{
        "id":123
    }
}

Response

{
    "type":"pong",
    "result":{
        "code":0,
        "message":"",
        "data":{
            "id":123,
            "timestamp":1632295288253
        }
    }
}

It is used to detect weather the connection is alive.The client timer send 'PING' regularly,expect a 'PONG' and the timestamp as response. If 'PONG' is not received within the set time, it may be a network error.

Request Information

Request Type Scope
ping public

Parameters

Name Type Required Description
id integer optional Client defined request id

Response

Name Type Description
id integer Client defined request id
timestamp integer Timestamp received

Enable or disable Cancel On Disconnect (WS)

Request

{
    "type":"cancel_on_disconnect",
    "token":"If3Fy-o5TiOOTfvlmtryR0MTiziutYaYFkH3aRovJWWEXqCAD7CIdnbhGG5bwRqLRrGkOFEOjh0L",
    "params":{
        "scope":"connection",
        "enable":true
    }
}

Response

{
    "type":"cancel_on_disconnect",
    "result":{
        "code":0,
        "message":"",
        "data":""
    }
}

When a COD-Enabled websocket connection is dropped, all open orders of the user will be canceled. Differences between rest API account_configs/cod and this interface:

Request Information

Request Type Scope
cancel_on_disconnect private

Parameters

Name Type Required Description
scope string optional COD scope, currently only support connection
enable bool required true=enable COD ,false=disable COD

Response

None

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

OrderType Description
limit Limit order
market Market order
trigger-limit Trigger limit order
trigger-market Trigger market order
twap_market Twap style 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

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/USDT-M trade
usdx-delivery USD-M/USDT-M delivery
usdx-settlement USD-M/USDT-M settlement
usdx-socialized-fund USD-M/USDT-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
usdx-funding-settlement Realtime funding

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

Position margin mode

Position margin mode Description
0 Cross margin
2 Isolated margin

Position type

Position type Description
0 Cross margin, Uni-direction
20 Isolated margin, Uni-direction

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:

  1. A response indicating the request was successful
  2. A response indicating the request had been rejected
  3. A response indicating failed to get the processing result of the request
  4. 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

  1. A HTTP response with status "504 - Gateway Timeout", when the failure was at the gateway layer.
  2. A HTTP response with status "200 - OK", but the JSON error code = 18500000 (Rpc timeout)
  3. 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: Edit order failed
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
18100298 Order qty less than MinOrderQty
18100299 Order qty greater than MaxOrderQty
18100300 Failed To Update PosMode
18100301 Failed To Update Leverage
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
18100314 Account mode migrating to UM
18100315 Account mode migrating to Classic
18100316 Isolated margin change exceed max-addable
18100317 Isolated margin change exceed max-removable
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
18400301 Settlement ongoing
18500000 Rpc timeout error (API result in uncertain state, see above info)