Spot COIN-M Futures&Options USD-M/USDT-M Futures Wallet
Chinese
NAV Navbar
json

COIN-M Futures&Options Changelogs

version time content
V1.10.3
2022 JUN 2
 * Add kline resolution: 1w, 1m
V1.10.2
2021 NOV 11
 * GET /v1/margins add UM mode margin info.
V1.10.1
2021 AUG 10
 * GET /v1/user_trades add parameters: start_id/end_id
* Add a new interval fixed100ms for websocket order_book channel
* Add websocket RPC cancel_on_disconnect
V1.10.0
2021 MAY 26
 * Query paging: max offset is 100, query exceed this offset should narrow the range filter (time etc)
V1.9.0
2021 MAR 30
 * Update prefix of stop order: for normal stop order, prefix is stop-, for trigger order, prefix is trigger-
V1.8.0
2021 MAR 12
 * Update paging information of following REST endpoints:
GET v1/market/trades
GET v1/orders
GET v1/transactions
GET v1/user/settlements
Original: "paging": {"limit": 2, "offset": 3, "total": 59}
New: "page_info": { "has_more": true }
* Support hidden order:
POST /v1/orders
POST /v1/batchorders
* Add source, hidden to the response of following REST endpoints:
POST /v1/orders
POST /v1/batchorders
POST /v1/amend_orders
POST /v1/amend_batchorders
GET /v1/orders
GET /v1/open_orders
GET /v1/stop_orders
* Add hidden to the response of websocket order channel.
* Enhanced stop order, add trigger-limit, trigger-market order type
V1.7.2
2021 FEB 19
 * Add GET /v1/user/info
* For GET /v1/platform_blocktrades and GET /v1/blocktrades, add fields trade_id, index_price, sigma
V1.7.1
2021 FEB 4
 * Add GET /v1/currencies
V1.7.0
2021 JAN 14
 * GET /v1/tickers and websocket ticker add funding_rate and funding_rate8h
* Add response field reorder_index(internal use) for REST endpoints GET /v1/orders, GET /v1/open_orders and websocket channel order
V1.6.1
2020 DEC 29
 * For /v1/accounts, the response add projected_info object
* For /v1/market/trades add start_time and end_time filter
* Add v1/total_volumes
* For GET /v1/wallet/withdraw, /v1/wallet/withdrawals and /v1/wallet/deposits, the response add is_onchain
V1.6.0
2020 DEC 8
 * Currency parameter is required
* Following endpoints will add currency parameter
POST /v1/batchorders
POST /v1 amend_orders
POST /v1/amend_batchorders
POST /v1/blocktrades
* Endpoint POST /v1/account_configs/cod is no longer currency-level, so the currency parameter is removed and will be ignored if user provide it
* For GET /v1/tickers REST endpoint and ticker websocket stream, if no tick in previous 24 hours, fetch last tick close as open,high,low,close
V1.4.0 2020 OCT 22 * Add /v1/settlement_prices
* Add GET /v1/funding_rate_history
V1.3.1 2020 SEP 22 * Add future_delta to websocket account stream
* Add liq_price, leverage to websocket position stream
V1.3.0 2020 SEP 18 * Add mmp rest api:
GET /v1/mmp_state,
POST /v1/update_mmp_config,
POST /v1/reset_mmp, and
websocket mmp_frozen channel
V1.0.2.6 2020 SEP 8 * Add label in private trade response: GET /v1/user/trades and WS user_trade channel
* Add /v1/system/cancel_only_status to query cancel-only period status.
* Fix the return type of websocket trade and market_trade channel.
* Support BBO order.
* Fix usd_price in trades (rest & ws) for options
V1.0.2 2020 AUG 25 * Add batch amend orders: POST /v1/amend_batchorders
* /v1/market/trades add block trade tag
* Fix transaction log trade id issues.
* Add /v1/funding_rate
V1.0.1 2020 AUG 10 * Add batch new orders: POST /v1/batchorders
V1.0 2020 JUL 30 *add POST /v1/account_configs/cod
* Add is_liquidation, taker_fee_rate, maker_fee_rate, label, stop_price, reduce_only, post_only, reject_post_only to websocket order stream
* Add is_block_trade to websocket trade, market_trade, user_trade stream
V0.4 2020 JUL 15 *Remove fee,pnl,cashflow order action fields information regarding these fields are not available when Api call returns. Affected endpoints:POST /v1/orders,POST /v1/amend_orders,POST /v1/close_positions
*Endpoint POST /v1/amend_orders add qty
* Add block trade source for:POST /v1/blocktrades,GET /v1/blocktrades,GET /v1/platform_blocktrades
*Add future_delta to GET /v1/accounts
*Add contract_size,contract_size_currency to GET /v1/instruments
V0.3 2020 Jun 30 * Transaction log query add position
* Add block trade
* Batch cancel: support more parameters
* Update block trade query filter: taker/maker
V0.2 2020 Jun 15 * Order vo add: post_only, reject_post_only
*Order query add label filter
V0.1 2020 Jun 1 first version

Introduction

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

The document consists of three parts: table of contents for easy browsing (left), longer explanation of each API interface although they are quite self-explanatory already(middle), and example code (right)

How to contact us:

WEB: www.bit.com
support team: [email protected]
VIP server: [email protected]
Telegram:https://t.me/bitcom_exchange

Market maker projects


Market makers are welcome to participate in bit long-term market making projects.
Send the following information to: [email protected]
1. Bit account information;
2. Effective contact information except email;


The type of market maker to be applied for should be indicated in the email (multiple choices are allowed)
Application of market maker for bit spot
Application of market maker for bit delivery contract
Application of market maker for bit perpetual contract
Application of market maker for bit option contract


To encourage market makers to provide better liquidity for the platform, they can enjoy preferential transaction fees. Specific market making responsibilities and handling charges shall be provided after application.
* Bit owns the final interpretation right of the market maker project.

User Manual

We currently offer spot,future and option on bit.com.

Two methods to call API are currently offered at bit.com: Rest and Websocket.

REST endpoint consists of public and private APIs, where public API can be called directly without authentication.

Private API, on the other hand, requires API key signature authentication, Please register, set up API key and related access set ups on API page before kicking off API development.

Private API access: read,future&option trade,spot trade,wallet,block trade

API types and access details can be viewed API summary.

Websocket API is based on websocket protocol. Users need to first establish websocket connection, then send request for channel subscriptions, bit.com start pushing data (ever after) afterwards. You can always unsubscribe or disconnect if you change mind (no longer wish to be subscribed)

Subscription consists of public and private channels, where public channel can be subscribed directly without authentication. Private channel, on the other hand, requires token and authentication.

Channel types and access details can be viewed channel summary.

API hosts (production)

API hosts (testnet)

API rate limits

In order to ensure the system efficiency, bit.com implements the API rate limits . 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”. The individual API limits can be found on the webpage of the trading center. Users who need to increase the speed limit please contact the support team via [email protected]

Public API: 10 requests per second per IP.
Private API(future&option trade): 5 requests per second per user.
Private API(option trade): 10 requests per second per user.
Private API(Wallet): 1 request per second per user.
Private API(Block Trade):2 requests per second per user.
Private API(Others): 5 requests second per user.

About the type of API rate limits, please refer to API summary.

Unlogged users:100 connections per IP
Unlogged users:10 connection requests per second per IP.
Login users: 5 private connections per user.
Connected IP:disconnection triggers when subscription is not established more than 30s.

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, param_map):
        sorted_keys = sorted(param_map.keys())
        ret_list = []
        for key in sorted_keys:
            val = param_map[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

Multi-currency support

Supported currencies: BTC,ETHand BCH

To support multi currency in future versions, we revised the backend architecture. account/order/trade/position/tx_log etc for each currency has its own separate storage space and independent, so the account_id/order_id/trade_id etc for BTC and ETH may have the same values. For example, a user may have an order 123 for BTC, and has an order 123 for ETH as well, i.e. order_id is NOT unique across currencies, but currency + order_id is unique.

API summary

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

System

Get server timestamp

GET /v1/system/time

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

Response

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

Get server timestamp

Query Parameters

None

Response

Name Type Description
data string Server timestamp

Get system version

GET /v1/system/version

curl "https://betaapi.bitexch.dev/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 /v1/system/cancel_only_status

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

Response


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

Get cancel-only status after system maintenance.

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

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

Query parameters

None

Response

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

Market

Get index

GET /v1/index

curl "https://betaapi.bitexch.dev/v1/index?currency=BTC"

Response

{
    "code": 0,
    "message": "",
    "data": {
        "name": "BTC",
        "index_price": "9444.49000000"
    }
}

Deprecated, please use /um/index_price

Get index price

Query parameters

Parameter Type Required Default Description
currency string true "" Currency

Response

Name Type Description
name string Index name
index_price string Index price

Get instruments

GET /v1/instruments

curl "https://betaapi.bitexch.dev/v1/instruments?currency=BTC&category=option&active=true"

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "instrument_id": "BTC-29MAY20-9500-P",
            "created_at": 1589425192000,
            "updated_at": 1589425192000,
            "base_currency": "BTC",
            "quote_currency": "USD",
            "strike_price": "9500.00000000",
            "expiration_at": 1590739200000,
            "option_type": "put",
            "category": "option",
            "min_price": "0.00050000",
            "max_price": "10.00000000",
            "price_step": "0.00050000",
            "min_size": "0.10000000",
            "size_step": "0.10000000",
            "delivery_fee_rate": "0.00020000",
            "contract_size": "1.00000000",
            "contract_size_currency": "BTC",  
            "display_at": 1589425292000,
            "active": true
        }
    ]
}

Get instrument list by currency or category

Query parameters

Parameter Type Required Default Description
currency string true "" Currency
category string false "" Category
active boolean false true Set true to query active instruments

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
display_at integer Displayed time at management console (For internal use)

Get tickers

GET /v1/tickers

curl "https://betaapi.bitexch.dev/v1/tickers?instrument_id=BTC-26JUN20-5000-C"

Response

{
    "code": 0,
    "message": "",
    "data":{
        "time":1589126498813,
        "instrument_id":"BTC-26JUN20-5000-C",
        "best_bid":"0.50200000",
        "best_ask":"0.50500000",
        "best_bid_qty":"2.30000000",
        "best_ask_qty":"0.80000000",
        "ask_sigma":"2.22748567",
        "bid_sigma":"2.18964114",
        "last_price":"0.50500000",
        "last_qty":"0.10000000",
        "open24h":"0.50500000",
        "high24h":"0.50500000",
        "low24h":"0.50500000",
        "price_change24h":"",
        "volume24h":"0.10000000",
        "open_interest":"289.50000000",
        "underlying_name":"BTC-26JUN20",
        "underlying_price":"8616.02000000",
        "mark_price":"0.43989364",
        "sigma":"1.29049244",
        "delta":"0.92073799",
        "vega":"4.54807454",
        "theta":"-6.28858194",
        "gamma":"0.00003713",
        "min_sell":"0.38950000",
        "max_buy":"0.49000000"
    }

}

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

Get orderbooks

GET /v1/orderbooks

curl "https://betaapi.bitexch.dev/v1/orderbooks?instrument_id=BTC-27MAR20-9000-C&level=3"

Response

{
    "code": 0,
    "message": "",
    "data": {
        "instrument_id": "BTC-27MAR20-9000-C",
        "timestamp": 1585299600000,
        "asks": [
            ["0.02300000", "3.00000000"],
            ["0.02400000", "0.70000000"],
            ["0.02500000", "18.00000000"]
        ],
        "bids": [
            ["0.02100000", "0.30000000"],
            ["0.02000000", "2.00000000"],
            ["0.01900000", "5.60000000"]
        ]
    }
}

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 /v1/market/trades

curl "https://betaapi.bitexch.dev/v1/market/trades?currency=BTC&category=option&option_type=call&instrument_id=BTC-27MAR20-9000-C&offset=1&limit=1"

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "created_at": 1585299600000,
            "index_price": "8000.00000000",
            "underlying_price": "8000.00000000",
            "instrument_id": "BTC-27MAR20-9000-C",
            "price": "0.03400000",
            "qty": "1.00000000",
            "side": "buy",
            "sigma": "0.00200000",
            "trade_id": 3743,
            "is_block_trade": false
        }
    ]
}

Get market trades by currency, category, option_type, instrument_id

Query parameters

Parameter Type Required Default Description
currency string true "" Currency
category string false "" Category
option_type string false "" Option type
instrument_id string false "" Instrument ID
start_time integer false Start timestamp
end_time integer false End timestamp
offset int false 1 Page index, first page = 1
limit int false 100 Page size

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

curl "https://betaapi.bitexch.dev/v1/klines?instrument_id=BTC-27MAR20-9000-C&start_time=1585296000000&end_time=1585596000000&timeframe_min=1440"

Response

{
    "code": 0,
    "message": "",
    "data": {
        "close": [
            0.023
        ],
        "high": [
            0.031
        ],
        "low": [
            0.022
        ],
        "open": [
            0.028
        ],
        "timestamps": [
            1585296000000
        ],
        "volume": [
            31.2
        ]
    }
}

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

/v1/klines return max 1000 records in given search conditions.

Query parameters

Parameter Type Required Default Description
instrument_id string true "" Instrument ID
start_time integer true Start timestamp
end_time integer true End timestamp
timeframe_min string true "" Timeframe in minutes (1, 3, 5, 15, 30, 60, 120, 240, 360, 720, 1440)

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 daily delivery price info

GET /v1/delivery_info

curl "https://betaapi.bitexch.dev/v1/delivery_info?currency=BTC&offset=1&limit=10"

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "currency": "BTC",
            "delivery_time": 1585296000000,
            "price": "7982.00000000"
        }
    ]
}

Get daily delivery price info history.

Query parameters

Parameter Type Required Default Description
currency string true "" Currency
offset int false 1 Page index, first page = 1
limit int false 100 Page size

Response

Name Type Description
currency string Currency
delivery_time integer Timestamp
price string Delivery price

Get market settlement price info

GET /v1/settlement_prices

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

Response


{
  "code": 0,
  "message": "",
  "data": {
    "data": {
      "1600473600000": [
        {
          "date": 1600473600000,
          "currency": "BTC",
          "instrument_id": "BTC-OPTIONS",
          "settlement_type": "delivery",
          "price": "10920.02000000"
        },
        {
          "date": 1600473600000,
          "currency": "BTC",
          "instrument_id": "BTC-PERPETUAL",
          "settlement_type": "settlement",
          "price": "10907.68451016"
        },
        {
          "date": 1600473600000,
          "currency": "BTC",
          "instrument_id": "BTC-19SEP20-F",
          "settlement_type": "delivery",
          "price": "10920.02000000"
        }
      ],
      "1600560000000": [
        {
          "date": 1600560000000,
          "currency": "BTC",
          "instrument_id": "BTC-OPTIONS",
          "settlement_type": "delivery",
          "price": "10981.62000000"
        },
        {
          "date": 1600560000000,
          "currency": "BTC",
          "instrument_id": "BTC-PERPETUAL",
          "settlement_type": "settlement",
          "price": "10961.44289452"
        },
        {
          "date": 1600560000000,
          "currency": "BTC",
          "instrument_id": "BTC-20SEP20-F",
          "settlement_type": "delivery",
          "price": "10981.62000000"
        }
      ]
    }
  }
}

Get settlement/delivery price history.
Time range filter is within 30 days.
BTC-OPTIONS means all options share same delivery price.

Query parameters

Parameter Type Required Default Description
currency string true "" Currency
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 (BTC-OPTIONS means all options)
settlement_type string delivery or settlement
price string Delivery/settlement price

Get market summary

GET /v1/market/summary

curl "https://betaapi.bitexch.dev/v1/market/summary?currency=BTC&category=future&instrument_id=BTC-PERPETUAL"

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "instrument_id": "BTC-PERPETUAL",
            "timestamp": 1589029194249,
            "best_bid": "9594.00000000",
            "best_ask": "9623.50000000",
            "best_bid_qty": "16860.00000000",
            "best_ask_qty": "5770.00000000",
            "last_price": "9617.00000000",
            "last_qty": "5530.00000000",
            "open24h": "9858.00000000",
            "high24h": "9989.50000000",
            "low24h": "9498.50000000",
            "volume24h": "1325995140.00000000",
            "open_interest": "460634610.00000000",
            "mark_price": "9556.24890315",
            "max_buy": "9700.50000000",
            "min_sell": "9413.00000000",
            "delta": "",
            "gamma": "",
            "vega": "",
            "theta": ""
        }
    ]
}

Get market summary by instrument

Query parameters

Parameter Type Required Default Description
currency string true "" Currency
category string false "option" 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 /v1/funding_rate

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

Response


{
  "code": 0,
  "message": "",
  "data": {
    "instrument_id": "BTC-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 /v1/funding_rate_history

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

Response


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

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

Response

{
  "code": 0,
  "message": "",
  "data": {
    "total_volume_24_hours": "140512988.61600000",
    "details": [
      {
        "currency": "BTC",
        "category": "option",
        "volume_base_ccy": "5254.40000000",
        "volume_usd": "124599899.13600000",
        "index_price": "23713.44000000"
      },
      {
        "currency": "BTC",
        "category": "future",
        "volume_base_ccy": "404.96317700",
        "volume_usd": "9603070.00000000",
        "index_price": "23713.44000000"
      },
      {
        "currency": "ETH",
        "category": "option",
        "volume_base_ccy": "6233.00000000",
        "volume_usd": "3855484.48000000",
        "index_price": "618.56000000"
      },
      {
        "currency": "ETH",
        "category": "future",
        "volume_base_ccy": "3968.14375323",
        "volume_usd": "2454535.00000000",
        "index_price": "618.56000000"
      }
    ]
  }
}

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_volume_24_hours string Total volume
details array Volume details

details

Name Type Description
currency string Currency
category string Category
volume_base_ccy string Volume in base ccy
volume_usd string Volume in USD
index_price string Index price

Get coin-margined currencies

GET v1/currencies

curl "https://betaapi.bitexch.dev/v1/currencies"

Response

{
    "code": 0,
    "message": "",
    "data": {
        "currencies": [
            "BTC",
            "ETH",
            "BCH"
        ]
    }
}

Get all margin currencies for coin-margined contracts.

Query parameters

None

Response

Name Type Description
currencies array Currencies array

Account

Get account mode

GET /um/v1/account_mode


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

Response


// account_mode = Um
{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 1,
        "account_mode": "um",
        "auto_borrow": true,
        "um_risk_mode": "regular",
        "classic_accounts": []
    }
}

// account_mode = classic
{
    "code": 0,
    "message": "",
    "data": {
        "user_id": 1,
        "account_mode": "classic",
        "auto_borrow": false,
        "um_risk_mode": "",
        "classic_accounts": [
            {
                "currency": "BCH",
                "classic_risk_mode": "portfolio_margin"
            },
            {
                "currency": "BTC",
                "classic_risk_mode": "portfolio_margin"
            },
            {
                "currency": "ETH",
                "classic_risk_mode": "portfolio_margin"
            }
        ]
    }
}

Get account mode.

Query parameters

None

Response

Name Type Desc
user_id int User ID
account_mode string Account mode
auto_borrow bool Auto borrow or not
um_risk_mode string Um risk mode, regular/pm (only valid when account_mode = um)
classic_accounts array classic account info (only valid when account_mode = classic)
Name Type Desc
currency string Currency
classic_risk_mode string regular/pm

Get user accounts

GET /v1/accounts


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

Response

{
    "code": 0,
    "message": "",
    "data": {
        "user_id": "51140",
        "currency": "BTC",
        "cash_balance": "99.59591877",
        "available_balance": "97.47174526",
        "margin_balance": "99.59589266",
        "initial_margin": "2.12414740",
        "maintenance_margin": "0.00002866",
        "equity": "100.02737507",
        "pnl": "0.08047907",
        "total_delta": "1.40711353",
        "account_id": "3033",
        "mode": "regular",
        "session_upl": "0.08047907",
        "session_rpl": "-0.00002286",
        "option_value": "0.43148240",
        "option_pnl": "0.08048240",
        "option_session_rpl": "0.00000000",
        "option_session_upl": "0.08048240",
        "option_delta": "1.83338535",
        "option_gamma": "0.00017907",
        "option_vega": "4.04908990",
        "option_theta": "-36.98180587",
        "future_pnl": "-0.00000333",
        "future_session_rpl": "-0.00002286",
        "future_session_upl": "-0.00000333",
        "future_session_funding": "-0.00002286",
        "future_delta":"0.00521057",
        "created_at": 1588218506000,
        "projected_info": {
            "projected_initial_margin": "0.97919888",
            "projected_maintenance_margin": "0.78335911",
            "projected_total_delta": "3.89635553"
        }
    }
}

Query parameters

Parameter Type Required Default Description
currency string true "" Currency

Response

Name Type Desc
account_id string Account ID
mode string Risk mode
available_balance string Available balance
cash_balance string Cash balance
currency string Currency
equity string Account equity
initial_margin string Account initial margin
maintenance_margin string Account maintenance margin
margin_balance string Account margin balance
pnl string Account 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
user_id string User ID
created_at integer Account create timestamp
projected_info object Projected Info


ProjectedInfo Projected information(IM/MM/Delta) is the predicted value after the settlement of current trading session.

Name Type Desc
projected_initial_margin string Projected IM
projected_maintenance_margin string Projected MM
projected_total_delta string Projected Delta

Get user transaction logs

GET /v1/transactions

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/transactions?currency=BTC&start_time=1585270800000&end_time=1589522084000&type=trade&offset=1&limit=10&timestamp=1589522094430&signature=50b8d98d358253a1f12bc4d75c1ff77f4c0fe6cde8d00251a144c2f699d26b8a"

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "transaction_time": 1589521370683,
            "instrument_id": "BTC-22MAY20-7500-C",
            "transaction_type": "trade",
            "direction": "open-buy",
            "qty": "2.00000000",
            "price": "0.17550000",
            "cash_flow": "-0.35100000",
            "funding": "--",
            "fee_paid": "0.00100000",
            "fee_rate": "0.00050000",
            "change": "-0.35200000",
            "balance": "99.59591877",
            "position": "3.00000000",
            "trade_id": "23210268",
            "order_id": "17551020",
            "remark": ""
        }
    ]
}

Query Parameters

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

Response

Name Type Desc
transaction_time integer Transaction timestamp
instrument_id string Instrument ID
transaction_type string Transaction type
direction string Trade：open buy/open sell/close buy/close sell/liquidation buy/liquidation sell
delivery：close buy/close sell
settlement：long/short
qty string Quantity
price string Type=trade:
filled price (BTC for option, USD for future)
Type=delivery:
Price is delivery unit pnl
Type=settlement:
Price is mark price of 8:00 UTC
cash_flow string Cashflow
funding string type = trade/settlement
fee_paid string Fee paid
fee_rate string Fee rate
change string Change of account
balance string Balance after change
position string Position after transaction
order_id string Corresponding order ID
trade_id string Corresponding trade ID
remark string

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",
        "spot_orders_hc_loss": "0.00000000",
        "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"
    }
}

USD-M/USDT-M Futures 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

None

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

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

Get UM user transaction logs.

Query Parameters

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

Response

Name Type Desc
tx_time integer Transaction time
tx_type string 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 user positions

GET /v1/positions

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/positions?currency=BTC&category=option&instrument_id=BTC-22MAY20-7500-C&offset=1&limit=10&timestamp=1589521619990&signature=9a7f7704cb4d6ec3cd2dccbd55e09ce8abd1ffb48529a742337706dd1a43eea8"

Response

{
    "code": 0,
    "message": "",
    "data": [{
        "instrument_id": "BTC-22MAY20-7500-C",
        "qty": "-2.00000000",
        "initial_margin": "0.00000000",
        "maintenance_margin": "0.00000000",
        "avg_price": "0.17550000",
        "session_avg_price": "0.17550000",
        "mark_price": "0.21738391",
        "index_price": "9496.73000000",
        "session_funding": "0.00000000",
        "position_pnl": "0.08376782",
        "position_session_upl": "0.08376782",
        "position_session_rpl": "0.00000000",
        "category": "option",
        "roi": "0.00000000",
        "option_delta": "1.84693852",
        "option_gamma": "0.00017124",
        "option_vega": "3.80882409",
        "option_theta": "-34.02850739",
        "liq_price": "0.00000000",
        "leverage:": "50.00000000",
    }]
}

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

Query Parameters

Parameter Type Required Default Description
currency string true "" Currency
category string false "" Category
instrument_id string false "" Instrument ID
offset int false 1 Page index, first page = 1
limit int false 100 Page size

Response

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

Get user deliveries

GET /v1/user/deliveries

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/user/deliveries?currency=BTC&category=option&instrument_id=BTC-3MAY20-8625-C&start_time=1585270800000&end_time=1589522084000&offset=1&limit=10&timestamp=1589531240715&signature=1f060cafdcab4466ef3c79363ecea6710ec1966419a35b78f20d75329fed4a7b"

Response

{
    "code": 0,
    "message": "",
    "data": [{
        "type": "delivery",
        "timestamp": 1588492890000,
        "instrument_id": "BTC-3MAY20-8625-C",
        "position": "1.00000000",
        "exercise": true,
        "delivery_price": "8994.37000000",
        "delivery_pnl": "0.04106680"
    }]
}

Get user delivery records

Query Parameters

Parameter Type Required Default Description
currency string true "" Currency
category string false "" Category
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 (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 /v1/user/settlements


curl -H "X-Bit-Access-Key: ak-c1d4bc58-37f3-49da-93b5-396ab44b1543" "https://betaapi.bitexch.dev/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-PERPETUAL",
        "position": "-280750.00000000",
        "direction": "short",
        "session_upl": "-0.02754390",
        "session_rpl": "0.00125935",
        "session_funding": "-0.00028997",
        "price": "32000"
    }]
}

Get user settlements (only for future currently)

Query Parameters

Parameter Type Required Default Description
currency string true "" Currency
category string false "" Category
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

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

Get Mmp State

GET /v1/mmp_state

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

Response

{
    "code": 0,
    "message": "",
    "data": {
        "currency": "BTC",
        "mmp_enabled": true,
        "mmp_user_configurable": false,
        "mmp_config": {
            "window_ms": 20000,
            "frozen_period_ms": 30000,
            "qty_limit": "1000.00000000",
            "delta_limit": "1000.00000000"
        },
        "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 /v1/update_mmp_config

mmp_config
Mmp configuration detail.

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

Parameter Type Required Default Description
currency string true "" Currency

Response

Name Type Desc
currency string Currency
mmp_enabled bool Mmp is enabled or not
mmp_user_configurable bool User can edit mmp config or not
mmp_config object Mmp config detail (see below)
mmp_frozen_until_ms integer Mmp frozen until timestamp (backend update automatically)
mmp_frozen bool Mmp is frozen or not
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)

Update Mmp Config

POST /v1/update_mmp_config

curl -X POST "https://betaapi.bitexch.dev/v1/update_mmp_config" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency": "BTC", "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
currency string true "" Currency
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 /v1/reset_mmp

curl -X POST "https://betaapi.bitexch.dev/v1/reset_mmp" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency": "BTC", "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
currency string true "" Currency

Response

Name Type Desc
data string ok

Order

Place new order

POST /v1/orders


curl -X POST "https://betaapi.bitexch.dev/v1/orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id": "BTC-29MAY20-8000-C", "price": "0.08", "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-29MAY20-8000-C",
        "order_type": "limit",
        "side": "buy",
        "price": "0.08000000",
        "qty": "3.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "open",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label":"hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp":false,
        "source": "api",
        "hidden": false
    }
}

Place new order.
For market order, price is not required.
Order type default value is 'limit'.
Time in force default value is 'gtc'.
Order size unit: USD for Futures, COIN(e.g. BTC) for options


Enhanced Stop order:
* Order type should be stop-market/stop-limit/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:
usd: When place order, set [auto price type] = "usd", and [auto price] = usd value, order price will be automatically calculated as order_price = auto_price / underlying_price, and order will be automatically requoted every 6s to maintain the usd price

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


mmp order:Indicate that this order is mmp-enabled (Market Maker Protection).


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



Post json body

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

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 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 (stop order only)
reduce_only bool Indicate reduce only or not
post_only bool Indicate post only or not
reject_post_only bool Indicate reject post only or not
mmp bool Indicate mmp order or not
source string Order source
hidden bool Indicate hidden order or not

Place batch orders

POST /v1/batchorders


curl -X POST "https://betaapi.bitexch.dev/v1/batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency": "BTC", "orders_data": [{"instrument_id": "BTC-25SEP20-8000-C-XX", "price": "0.15", "qty": "51", "side": "buy", "hidden": true}, {"instrument_id": "BTC-PERPETUAL", "price": "12000", "qty": "100", "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,
                "error_code": 18100185,
                "error_msg": "Invalid instrument BTC-25SEP20-8000-C-XX"
            },
            {
                "order_id": "501758",
                "created_at": 1596782252996,
                "updated_at": 1596782252996,
                "user_id": "51140",
                "instrument_id": "BTC-PERPETUAL",
                "order_type": "limit",
                "side": "sell",
                "price": "12000.00000000",
                "qty": "100.00000000",
                "time_in_force": "gtc",
                "avg_price": "0.00000000",
                "filled_qty": "0.00000000",
                "status": "open",
                "is_liquidation": false,
                "auto_price": "0.00000000",
                "auto_price_type": "",
                "taker_fee_rate": "0.00045000",
                "maker_fee_rate": "0.00025000",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": false,
                "error_code": 0,
                "error_msg": ""
            }
        ]
    }
}

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


Post json body

Parameter Type Required Default Description
currency string true "" Currency
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 Notes: stop order not supported
time_in_force string false "gtc" Time in force
auto_price_type string false "" Auto price type
auto_price string false "" Auto price, only if auto price type in ('usd','implv') *implv is in percentage, ie. input 85.56 for 85.56%
label string false "" User defined label
post_only bool false false Indicate post only or not
reject_post_only bool false false Indicate reject post only or not
mmp bool false false Indicate mmp order or not
hidden bool false false Indicate hidden 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 Auto price type
taker_fee_rate string Taker fee rate
maker_fee_rate string Maker fee rate
label string User defined label
reduce_only bool Indicate reduce only or not
post_only bool Indicate post only or not
reject_post_only bool Indicate reject post only or not
mmp bool Indicate mmp order or not
source string Order source
hidden bool Indicate hidden order or not
error_code int New order result code: 0 = no error
error_msg string New order error message

Cancel orders

POST /v1/cancel_orders


curl -X POST "https://betaapi.bitexch.dev/v1/cancel_orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"currency": "BTC", "order_id": "44092860", "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 parameter.
Batch cancel filters include: order_id_list, label, instrument_id, category, currency.
Batch cancel filter priorities: order_id_list > label > instrument_id > category > currency

To cancel stop order, provide stop order id only. stop order can not be cancelled in batch.

Post json body

Parameter Type Required Default Description
currency string true "" Currency
order_id string false "" Order ID
order_id_list string false "" Order id list in csv format, e.g: 1,2,3
category string false "" Category
instrument_id string false "" Instrument ID
label string false "" Order label

Response

Name Type Desc
num_cancelled integer number of order cancelled

Amend orders

POST /v1/amend_orders


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

Response

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

Amend order.
Order id is required.
Need to provide at least one of: price,qty,auto_price.

Post json body

Parameter Type Required Default Description
currency string true "" Currency
order_id string true "" Order ID
price string false "" New price of the order
auto_price string false "" New auto price of the order (for usd/implv 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 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 (stop order only)
reduce_only bool Indicate reduce only or not
post_only bool Indicate post only or not
reject_post_only bool Indicate reject post only or not
mmp bool Indicate mmp order or not
source string Order source
hidden bool Indicate hidden order or not

Amend batch orders

POST /v1/amend_batchorders


curl -X POST "https://betaapi.bitexch.dev/v1/amend_batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f"  -d '{"currency": "BTC", "orders_data": [{"order_id": "572083", "price": "14000", "qty": "3000"}, {"order_id": "invalid-order-id", "price": "15000", "qty": "1000"}, {"order_id": "615775", "price": "0.12", "qty": "3.7"}], "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-PERPETUAL",
                "order_type": "limit",
                "side": "sell",
                "price": "14000.00000000",
                "qty": "3000.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": true,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": true,
                "error_code": 0,
                "error_msg": ""
            },
            {
                "order_id": "",
                "created_at": 0,
                "updated_at": 0,
                "user_id": "",
                "instrument_id": "",
                "order_type": "",
                "side": "",
                "price": "",
                "qty": "",
                "time_in_force": "",
                "avg_price": "",
                "filled_qty": "",
                "status": "",
                "is_liquidation": false,
                "auto_price": "",
                "auto_price_type": "",
                "taker_fee_rate": "",
                "maker_fee_rate": "",
                "label": "",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": false,
                "error_code": 18100113,
                "error_msg": "order id is invalid : invalid-order-id"
            },
            {
                "order_id": "615775",
                "created_at": 1597313836214,
                "updated_at": 1597313836214,
                "user_id": "51140",
                "instrument_id": "BTC-25SEP20-9000-C",
                "order_type": "limit",
                "side": "buy",
                "price": "0.12000000",
                "qty": "3.70000000",
                "time_in_force": "gtc",
                "avg_price": "0.00000000",
                "filled_qty": "0.00000000",
                "status": "open",
                "is_liquidation": false,
                "auto_price": "90.00000000",
                "auto_price_type": "usd",
                "taker_fee_rate": "0.00040000",
                "maker_fee_rate": "0.00030000",
                "label": "aaaa",
                "reduce_only": false,
                "post_only": false,
                "reject_post_only": false,
                "mmp": false,
                "source": "api",
                "hidden": false,
                "error_code": 0,
                "error_msg": ""
            }
        ]
    }
}

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


Post json body

Parameter Type Required Default Description
currency string true "" Currency
orders_data array true Amend request list(see below)
Parameter Type Required Default Description
order_id string true "" Order ID
price string false "" New price of the order
auto_price string false "" New auto price of the order (for usd/implv 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 Auto price type
taker_fee_rate string Taker fee rate
maker_fee_rate string Maker fee rate
label string User defined label
reduce_only bool Indicate reduce only or not
post_only bool Indicate post only or not
reject_post_only bool Indicate reject post only or not
mmp bool Indicate mmp order or not
source string Order source
hidden bool Indicate hidden order or not
error_code int Edited order result code: 0 = no error
error_msg string Edited order error message

Close positions

POST /v1/close_positions


curl -X POST "https://betaapi.bitexch.dev/v1/close_positions" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113"  -d '{"instrument_id": "BTC-PERPETUAL", "price": "9500", "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-PERPETUAL",
        "order_type": "limit",
        "side": "sell",
        "price": "9500.00000000",
        "qty": "50.00000000",
        "time_in_force": "gtc",
        "avg_price": "9522.50000000",
        "filled_qty": "50.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

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 (GTC) 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 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 (stop 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 /v1/open_orders

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

Response

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

Get open orders by currency, category, instrument_id

Query parameters

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

Response

Name Type Desc
order_id string Order ID
created_at integer Create timestamp
updated_at integer Update timestamp
user_id string User ID
instrument_id string Instrument ID
order_type string Order type
side string Order side
price string Order price
qty string Order quantity
time_in_force string Time in force
avg_price string Average filled price
filled_qty string Filled qty
status string Order status
fee string Transaction fees
is_liquidation boolean Liquidation order
auto_price string Auto price
auto_price_type string 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 (stop 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 Indicate is UM order or not

Get orders

GET /v1/orders

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/orders?currency=BTC&category=option&instrument_id=BTC-29MAY20-7500-C&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-29MAY20-7500-C",
        "order_type": "limit",
        "side": "buy",
        "price": "0.08000000",
        "qty": "3.00000000",
        "time_in_force": "gtc",
        "avg_price": "0.00000000",
        "filled_qty": "0.00000000",
        "status": "cancelled",
        "fee": "0.00000000",
        "is_liquidation": false,
        "auto_price": "0.00000000",
        "auto_price_type": "",
        "pnl": "0.00000000",
        "cash_flow": "0.00000000",
        "initial_margin": "",
        "taker_fee_rate": "0.00050000",
        "maker_fee_rate": "0.00020000",
        "label": "hedge",
        "stop_price": "0.00000000",
        "reduce_only": false,
        "post_only": false,
        "reject_post_only": false,
        "mmp": false,
        "reorder_index": 1,
        "source": "api",
        "hidden": false,
        "is_um": true
    }]
}

Get order history by currency, category, instrument_id, or order_id

Query parameters

Parameter Type Required Default Description
currency string true "" Currency
category string false "" category
instrument_id string false "" 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
offset int false 1 Page index, first page = 1
limit int false 100 Page size

Response

Name Type Desc
order_id string Order ID
created_at integer Create timestamp
updated_at integer Update timestamp
user_id string User ID
instrument_id string Instrument ID
order_type string Order type
side string Order side
price string Order price
qty string Order quantity
time_in_force string Time in force
avg_price string Average filled price
filled_qty string Filled quantity
status string Order status
fee string Transaction fees
is_liquidation boolean Liquidation order
auto_price string Auto price
auto_price_type string 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 (stop 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 Indicate is UM order or not

Get enhanced stop orders

GET /v1/stop_orders

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

Response

{
    "code": 0,
    "message": "",
    "data": [{
        "stop_order_id": "stop-br7lik3752cq6kouf9ng",
        "created_at": 1590647120000,
        "updated_at": 1590647120000,
        "status": "open",
        "stop_price": "9300.00000000",
        "trigger_type": "last-price",
        "instrument_id": "BTC-PERPETUAL",
        "user_id": "51140",
        "qty": "60.00000000",
        "price": "9200.00000000",
        "side": "buy",
        "type": "stop-limit",
        "time_in_force": "gtc",
        "source": "api",
        "hidden": false
    }]
}

Get enhanced stop order history by currency, instrument_id, or status.

Query parameters

Parameter Type Required Default Description
currency string true "" Currency
instrument_id string false "" Instrument ID
status string false "" Enhanced stop order status
start_time integer false Start timestamp
end_time integer false End timestamp
offset int false 1 Page index, first page = 1
limit int false 100 Page size

Response

Name Type Desc
stop_order_id string Stop Order ID (with prefix "stop-")
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
time_in_force string Time in force
status string Enhanced stop order status
trigger_type string Triggered by last price
user_id string User ID
source string Order source
hidden bool Indicate hidden order or not

Get user trades

GET /v1/user/trades

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

Response

{
    "code": 0,
    "message": "",
    "data": [{
        "trade_id": "23210268",
        "order_id": "17551020",
        "instrument_id": "BTC-22MAY20-7500-C",
        "qty": "2.00000000",
        "price": "0.17550000",
        "sigma": "0.00000000",
        "underlying_price": "9471.25000000",
        "index_price": "9469.81000000",
        "usd_price": "1661.95165500",
        "fee": "0.00100000",
        "fee_rate": "0.00050000",
        "side": "buy",
        "created_at": 1589521371000,
        "is_taker": true,
        "order_type": "limit",
        "label": "hedge"
    }]
}

Get user trades

Query parameters

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

Response

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

Get estimated margins

GET /v1/margins

curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/margins?instrument_id=BTC-29MAY20-7500-C&price=0.08&qty=3&timestamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807"

Response

{
    "code": 0,
    "message": "",
    "data": {
        "buy_margin": "0.00018326",
        "buy_margin_ccy": "0.00048299",
        "buy_margin_usdt": "19.98670096",
        "sell_margin": "0.0.00087369",
        "sell_margin_ccy": "0.00040010",
        "sell_margin_usdt": "16.55661412",
        "min_sell": "40799.50000000",
        "max_buy": "42042.50000000",
        "usdt_index_price": "41381.19000000"
    }
}

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 Original estimated buy margin
buy_margin_ccy string UM mode estimated buy margin
buy_margin_usdt string UM mode estimated buy margin in USDT ( = buy_margin_ccy * usdt_index_price)
sell_margin string Original estimated sell margin
sell_margin_ccy string UM mode estimated sell margin
sell_margin_usdt string UM mode estimated sell margin in USDT ( = sell_margin_ccy * usdt_index_price)
min_sell string Minimum price for sell order
max_buy string Maximum price for buy order
usdt_index_price string USDT index price

Block Trade


New block trade request

POST /v1/blocktrades

# <bt_source> should be replaced with real bt_source

curl -X POST "https://betaapi.bitexch.dev/v1/blocktrades" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a"  -d '{"currency":"BTC", "label": "e8db3a92b94c482bb0e30f421415982d", "role": "maker", "counterparty": "1026", "bt_source": "<bt_source>", "trades": [{"instrument_id": "BTC-25SEP20-9000-C", "price": "0.18", "qty": "10", "side": "sell"}, {"instrument_id": "BTC-PERPETUAL", "price": "9300", "qty": "5000", "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 /v1/blocktrades with same label, trades(with opposite side).
The block trade request timeout period is 1 minute, if the other side doesn't answer in given time, the request will expired.
Block trade bt_source is bit.com designated block trade source, contact bit.com for detail.

Post json body

Parameter Type Required Default Description
currency string true "" Currency
bt_source string true "" Block trade source (bit.com designated block trade source)
label string true "" Unique identifier generated for block trade
role string true "" Role: taker/maker
counterparty string 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 /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/v1/blocktrades?currency=BTC&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-PERPETUAL",
            "side": "buy",
            "price": "51000.00000000",
            "qty": "1000.00000000",
            "fee": "0.00000392",
            "status": "filled",
            "role": "maker",
            "bt_source": "<bt_source>",
            "order_id": "6325142",
            "trade_id": "1299120841",
            "index_price": "51723.49000000",
            "sigma": "0.00000000"
        }
    ]
}

Query block trades.

Query parameters

Parameter Type Required Default Description
bt_source string true "" Block trade source
currency string true "" Currency
instrument_id string false "" Instrument ID
label string false "" Label of the block trade request
start_time integer false Start timestamp
end_time integer false End timestamp
offset int false 1 Page index, first page = 1
limit int false 100 Page size

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 string User ID
counterparty string 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 /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/v1/platform_blocktrades?currency=BTC&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-PERPETUAL",
            "side": "buy",
            "price": "51000.00000000",
            "qty": "1000.00000000",
            "fee": "0.00000392",
            "status": "filled",
            "role": "maker",
            "bt_source": "<bt_source>",
            "order_id": "6325142",
            "trade_id": "1299120841",
            "index_price": "51723.49000000",
            "sigma": "0.00000000"
        }   
    ]
}

Query block trades of specific platform.

Query parameters

Parameter Type Required Default Description
bt_source string true "" Block trade source
currency string true "" Currency
instrument_id string false "" Instrument ID
label string false "" Label of the block trade request
taker string false "" Filtered by taker
maker string false "" Filtered by maker
start_time integer false Start timestamp
end_time integer false End timestamp
offset int false 1 Page index, first page = 1
limit int false 100 Page size

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 string User ID
counterparty string 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 /v1/user/info

curl -H "X-Bit-Access-Key: ak-77fd5728-e7d4-4174-991a-6e9b8f5887e6" "https://betaapi.bitexch.dev/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 /v1/accounts instead.

Query Parameters

None

Response

Name Type Description
user_id string 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 [inverse, um] The module which the subscription data came from

Subscription management

Request

{
    "type":"subscribe",
    "instruments":[
        "BTC-26JUN20-6000-P",
        "BTC-26JUN20-6000-C",
        "BTC-26JUN20-7000-P",
        "BTC-26JUN20-7000-C",
        "BTC-26JUN20-8000-C"
    ],
    "channels":[
        "depth",
        "ticker",
        "kline.5",
        "order",
        "account"
    ],
    "currencies":[
        "BTC"
    ],
    "categories":[
        "option"
    ],
    "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
currencies string[] List of currencies
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.{resolution} public instruments Kline data
trade public instruments Trades for an instrument
market_trade public categories + currencies All the trades of available options or futures
index_price public currencies Index price of a specific USD pair
mark_price public instruments Mark price for an instrument
account private currencies User's account information
um_account private UM user's account information
position private categories + currencies User's position information
order private categories + currencies User's order information
user_trade private categories + currencies User's trade information
mmp_frozen private currencies MMP frozen event

Depth Channel

Request

{
    "type":"subscribe",
    "instruments":[
        "BTC-26JUN20-7000-P"
    ],
    "channels":[
        "depth"
    ],
    "interval": "100ms"
}

Response (snapshot)

{
    "channel":"depth",
    "timestamp":1587929552250,
    "module":"inverse",
    "data":{
        "type":"snapshot",
        "instrument_id":"BTC-26JUN20-7000-P",
        "sequence":9,
        "bids":[
            [
                "0.08000000",
                "0.10000000"
            ]
        ],
        "asks":[
            [
                "0.09000000",
                "0.20000000"
            ]
        ]
    }
}

Response (update)

{
    "channel":"depth",
    "timestamp":1587930311331,
    "module":"inverse",
    "data":{
        "type":"update",
        "instrument_id":"BTC-26JUN20-7000-P",
        "sequence":10,
        "prev_sequence":9,
        "changes":[
            [
                "sell",
                "0.08500000",
                "0.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-26JUN20-7000-C"
    ],
    "channels":[
        "order_book.10.10"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"order_book.10.10",
    "timestamp":1587930311331,
    "module":"inverse",
    "data":{
        "instrument_id":"BTC-26JUN20-7000-C",
        "sequence":3,
        "timestamp":1587930311330,
        "asks":[
            [
                "0.00300000",
                "0.20000000"
            ]
        ],
        "bids":[
            [
                "0.00200000",
                "0.50000000"
            ],
            [
                "0.00100000",
                "0.30000000"
            ]
        ]
    }
}

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

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

Channel Information

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

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

group value: 1, 5, 10, 100,1000 represents the order book price increments. 1 represents the smallest increment, increments in 0.0001; 10 represents increments in 0.001

depth value: 1, 10, 20, 100, represents order book layers

Default is group=1, depth=10

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-26JUN20-7000-P"
    ],
    "channels":[
        "depth1"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"depth1",
    "timestamp":1587932635873,
    "module":"inverse",
    "data":{
        "instrument_id":"BTC-26JUN20-7000-P",
        "asks":[
            [
                "0.08500000",
                "0.10000000"
            ]
        ],
        "bids":[
            [
                "0.08000000",
                "0.10000000"
            ]
        ]
    }
}

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-26JUN20-5000-C"
    ],
    "channels":[
        "ticker"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"ticker",
    "timestamp":1589126498813,
    "module":"inverse",
    "data":{
        "time":1589126498813,
        "instrument_id":"BTC-26JUN20-5000-C",
        "best_bid":"0.50200000",
        "best_ask":"0.50500000",
        "best_bid_qty":"2.30000000",
        "best_ask_qty":"0.80000000",
        "ask_sigma":"2.22748567",
        "bid_sigma":"2.18964114",
        "last_price":"0.50500000",
        "last_qty":"0.10000000",
        "open24h":"0.50500000",
        "high24h":"0.50500000",
        "low24h":"0.50500000",
        "price_change24h":"",
        "volume24h":"0.10000000",
        "open_interest":"289.50000000",
        "underlying_name":"BTC-26JUN20",
        "underlying_price":"8616.02000000",
        "mark_price":"0.43989364",
        "sigma":"1.29049244",
        "delta":"0.92073799",
        "vega":"4.54807454",
        "theta":"-6.28858194",
        "gamma":"0.00003713",
        "min_sell":"0.38950000",
        "max_buy":"0.49000000"
    }
}

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-PERPETUAL"
    ],
    "channels":[
        "kline.5"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"kline.5",
    "timestamp":1587979850118,
    "module":"inverse",
    "data":{
        "instrument_id":"BTC-PERPETUAL",
        "tick":1587979800000,
        "open":"7737.50000000",
        "low":"7737.50000000",
        "high":"7737.50000000",
        "close":"7737.50000000",
        "volume":"0.00000000"
    }
}

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: 1, 3, 5, 15, 30, 60, 120, 240, 360, 720, 1440, 1w, 1m

The timeframe is in minutes. 1 represents 1 minute kline, 1440 represents 1 day kline.

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-26JUN20-6000-P"
    ],
    "channels":[
        "trade"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"trade",
    "timestamp":1588997059735,
    "module":"inverse",
    "data":[
        {
            "trade_id":"2388418",
            "instrument_id":"BTC-26JUN20-6000-P",
            "price":"0.01800000",
            "qty":"0.10000000",
            "side":"buy",
            "sigma":"1.15054346",
            "option_type":"put",
            "is_block_trade":false,
            "created_at":1588997060000
        }
    ]
}

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"
    ],
    "currencies":[
        "BTC"
    ],
    "categories":[
        "option"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"market_trade",
    "timestamp":1588997059735,
    "module":"inverse",
    "data":[
        {
            "trade_id":"2388418",
            "instrument_id":"BTC-26JUN20-6000-P",
            "price":"0.01800000",
            "qty":"0.10000000",
            "side":"buy",
            "sigma":"1.15054346",
            "option_type":"put",
            "is_block_trade":false,
            "created_at":1588997060000
        }
    ]
}

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

Channel Information

Channel Scope Arguments Interval
market_trade public categories + currencies [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"
    ],
    "currencies":[
        "BTC"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"index_price",
    "timestamp":1588997560081,
    "module":"inverse",
    "data":{
        "index_name":"BTC_USD",
        "index_price":"9866.66000000"
    }
}

Index Price pushes index price of a specific USD pair.

Channel Information

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

Response

Name Type Description
index_name string USD pair
index_price string Index price

Mark Price Channel

Request

{
    "type":"subscribe",
    "instruments":[
        "BTC-26JUN20-10000-C"
    ],
    "channels":[
        "mark_price"
    ],
    "interval": "100ms"
}

Response

{
    "channel":"mark_price",
    "timestamp":1588997840512,
    "module":"inverse",
    "data":{
        "instrument_id":"BTC-26JUN20-10000-C",
        "mark_price":"0.11006342",
        "sigma":"0.79384700",
        "delta":"0.54298511",
        "vega":"14.25666243",
        "theta":"-11.75126302",
        "gamma":"0.00013900"
    }
}

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

Account Channel

Request

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

Response

{
    "channel":"account",
    "timestamp":1589031930115,
    "module":"inverse",
    "data":{
        "user_id":"53345",
        "currency":"BTC",
        "cash_balance":"9999.94981346",
        "available_balance":"9999.90496213",
        "margin_balance":"9999.94981421",
        "initial_margin":"0.04485208",
        "maintenance_margin":"0.00000114",
        "equity":"10000.00074364",
        "pnl":"0.00746583",
        "total_delta":"0.06207078",
        "account_id":"8",
        "mode":"regular",
        "session_upl":"0.00081244",
        "session_rpl":"0.00000021",
        "option_value":"0.05092943",
        "option_pnl":"0.00737943",
        "option_session_rpl":"0.00000000",
        "option_session_upl":"0.00081190",
        "option_delta":"0.11279249",
        "option_gamma":"0.00002905",
        "option_vega":"4.30272923",
        "option_theta":"-3.08908220",
        "future_pnl":"0.00008640",
        "future_session_rpl":"0.00000021",
        "future_session_upl":"0.00000054",
        "future_session_funding":"0.00000021",
        "future_delta":"0.00955630",
        "created_at":1588997840512,
        "projected_info": {
            "projected_initial_margin": "0.97919888",
            "projected_maintenance_margin": "0.78335911",
            "projected_total_delta": "3.89635553"
        }
    }
}

Account pushes user's account information

Channel Information

Channel Scope Arguments Interval
account private currencies [raw, 100ms]

Response

Name Type Description
account_id string Account ID
mode string Risk mode
available_balance string Available balance
cash_balance string Cash balance
currency string Currency
equity string Account equity
initial_margin string Account initial margin
maintenance_margin string Account maintenance margin
margin_balance string Account margin balance
pnl string Profit & loss (P&L)
total_delta string Total delta
session_rpl string Session realized P&L
session_upl string Session unrealized P&L
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
user_id string User ID
projected_info object Projected information

Projected information(IM/MM/Delta) is the predicted value after the settlement of current trading session.

Name Type Description
projected_initial_margin string Projected IM
projected_maintenance_margin string Projected MM
projected_total_delta string Projected Delta

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": 1,
        "created_at": 1632642549581,
        "usdt_total_collateral": "200.00000000",
        "usdt_total_margin_balance": "190.00000000",
        "usdt_total_available": "80.00000000",
        "usdt_total_initial_margin": "90.00000000",
        "usdt_total_maintenance_margin": "120.00000000",
        "usdt_total_initial_margin_ratio": "0.60000000",
        "usdt_total_maintenance_margin_ratio": "0.60000000",
        "usdt_total_liability": "8060000.00000000",
        "usdt_total_unsettled_amount": "322143.95604395",
        "spot_orders_hc_loss": "30.00000000",
        "details": [
            {
                "currency": "BTC",
                "equity": "100.00000000",
                "liability": "0.00000000",
                "usdt_index_price": "40000.00000000",
                "cash_balance": "100.00000000",
                "margin_balance": "100.00000000",
                "available_balance": "50.00000000",
                "initial_margin": "20.00000000",
                "spot_margin": "30.00000000",
                "maintenance_margin": "80.00000000",
                "potential_liability": "0.00000000",
                "interest": "1.00000000",
                "interest_rate": "0.01000000",
                "pnl": "0.11538462",
                "total_delta": "0.38461538",
                "session_rpl": "10.00000000",
                "session_upl": "0.11538462",
                "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.11538462",
                "future_session_rpl": "10.00000000",
                "future_session_upl": "0.11538462",
                "future_session_funding": "10.00000000",
                "future_delta": "0.38461538",
                "future_available_balance": "0.00200000",
                "option_available_balance": "0.00200000",
                "unsettled_amount": "9.11538462"
            },
            {
                "currency": "USDT",
                "equity": "-8000000.00000000",
                "liability": "8000000.00000000",
                "usdt_index_price": "1.00000000",
                "cash_balance": "-8000000.00000000",
                "margin_balance": "-8000000.00000000",
                "available_balance": "0.00000000",
                "initial_margin": "0.00000000",
                "spot_margin": "0.00000000",
                "maintenance_margin": "0.00000000",
                "potential_liability": "8000000.00000000",
                "interest": "300.00000000",
                "interest_rate": "0.00500000",
                "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": "0.00000000",
                "option_available_balance": "0.00000000",
                "unsettled_amount": "-300.00000000"
            }
        ]
    }
}

UM mode: subscribe um_accountchannnel to get UM account information.

Channel Information

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

Response

Name Type Description
user_id int User Id
created_at int Timestamp (query time)
usdt_total_collateral string USDT Total Collateral
usdt_total_margin_balance string USDT Total Margin Balance
usdt_total_available string USDT Total Available
usdt_total_initial_margin string USDT Total Initial Margin
usdt_total_maintenance_margin string USDT Total Maintenance Margin
usdt_total_initial_margin_ratio string USDT Total Initial Margin Ratio, may returns "infinity"
usdt_total_maintenance_margin_ratio string USDT Total Maintenance Margin Ratio, may returns "infinity"
usdt_total_liability string USDT total liability
usdt_total_unsettled_amount string USDT total unsettled amount
spot_orders_hc_loss string Total spot order haircut loss
details array of Detail Details, array of currency level detail
Name Type Description
currency string Currency
equity string Equity
liability string Liability
usdt_index_price string USDT 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 Account 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"
    ],
    "currencies":[
        "BTC"
    ],
    "categories":[
        "option"
    ],
    "interval": "100ms",
    "token":"6d501ded-3c40-4697-b390-218a54b9de19"
}

Response (option)

{
    "channel":"position",
    "timestamp":1600743533528,
    "module":"inverse",
    "data":[
        {
            "instrument_id":"BTC-30OCT20-14000-P",
            "qty":"-0.20000000",
            "initial_margin":"0.09735673",
            "maintenance_margin":"0.08235673",
            "avg_price":"0.43800000",
            "session_avg_price":"0.43800000",
            "mark_price":"0.33678364",
            "index_price":"10452.57000000",
            "position_pnl":"0.02024327",
            "position_session_upl":"0.02024327",
            "position_session_rpl":"0.00000000",
            "category":"option",
            "roi":"0.23108759",
            "option_delta":"0.18646500",
            "option_gamma":"-0.00001376",
            "option_vega":"-0.88990013",
            "option_theta":"0.65103919",
        },
        {
            "instrument_id":"BTC-30OCT20-14500-P",
            "qty":"-0.10000000",
            "initial_margin":"0.05522940",
            "maintenance_margin":"0.04772940",
            "avg_price":"0.49700000",
            "session_avg_price":"0.49700000",
            "mark_price":"0.40229400",
            "index_price":"10452.57000000",
            "position_pnl":"0.00947060",
            "position_session_upl":"0.00947060",
            "position_session_rpl":"0.00000000",
            "category":"option",
            "roi":"0.19055534",
            "option_delta":"0.08317211",
            "option_gamma":"-0.00000823",
            "option_vega":"-0.85511325",
            "option_theta":"1.00527001",
        }
    ]
}

Response (future)

{
    "channel":"position",
    "timestamp":1600681824660,
    "module":"inverse",
    "data":[
        {
            "instrument_id":"BTC-PERPETUAL",
            "qty":"100.00000000",
            "initial_margin":"0.00018592",
            "maintenance_margin":"0.00013945",
            "avg_price":"10852.50000000",
            "session_avg_price":"10852.50000000",
            "mark_price":"10758.39435000",
            "index_price":"10704.87000000",
            "qty_base":"0.00929507",
            "liq_price":"0.12199202",
            "session_funding":"-0.00000002",
            "position_pnl":"-0.00008060",
            "position_session_upl":"-0.00008060",
            "position_session_rpl":"-0.00000002",
            "category":"future",
            "roi":"-0.43351632",
            "leverage":"50.00000000"
        }
    ]
}

Position pushes user's position information

Channel Information

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

Response

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

Order Channel

Request

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

Response

{
    "channel":"order",
    "timestamp":1587994934089,
    "module":"inverse",
    "data":[
        {
            "order_id":"1590",
            "instrument_id":"BTC-1MAY20-8750-P",
            "qty":"0.50000000",
            "filled_qty":"0.10000000",
            "remain_qty":"0.40000000",
            "price":"0.16000000",
            "avg_price":"0.16000000",
            "side":"buy",
            "order_type":"limit",
            "time_in_force":"gtc",
            "created_at":1587870609000,
            "updated_at":1587870609000,
            "status":"open",
            "fee":"0.00002000",
            "cash_flow":"-0.01600000",
            "pnl":"0.00000000",
            "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": true,
            "reorder_index": 1
        }
    ]
}

Order pushes user's order information

Channel Information

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

Response

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

User Trade Channel

Request

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

Response

{
    "channel":"user_trade",
    "timestamp":1588997059737,
    "module":"inverse",
    "data":[
        {
            "trade_id":2388418,
            "order_id":1384232,
            "instrument_id":"BTC-26JUN20-6000-P",
            "qty":"0.10000000",
            "price":"0.01800000",
            "sigma":"1.15054346",
            "underlying_price":"9905.54000000",
            "index_price":"9850.47000000",
            "usd_price":"177.30846000",
            "fee":"0.00005000",
            "fee_rate":"0.00050000",
            "side":"buy",
            "created_at":1588997060000,
            "is_taker":true,
            "order_type":"limit",
            "is_block_trade":false,
            "label": "hedge"
        }
    ]
}

User Trade pushes user trade information

Channel Information

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

Response

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

MMP Frozen Event Channel

Request

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

Response

{
    "channel":"mmp_frozen",
    "timestamp":1599277666000,
    "module":"inverse",
    "data":{
        "currency":"BTC",
        "frozen_until_ms":1599277929000
    }
}

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 currencies [raw, 100ms]

Response

Name Type Description
currency string Currency
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
stop-limit Stop limit order
stop-market Stop market order
trigger-limit Trigger limit order
trigger-market Trigger market order

Order status

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

StopOrder status

Status Description
open Enhanced stop Order is active
triggered Enhanced stop order is triggered
cancelled Enhanced stop order is cancelled without being triggered

Order time in force

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

Order auto price type

Type Description
usd Place order with usd price
implv Place order with imply volatility

Transaction log type

Tx log type Description
deposit Make deposit
bad-deposit Deposit failed
withdraw Make withdrawal
withdraw-revert Withdraw revert
trade Trading(buy/sell)
delivery Delivery
settlement Settlement
bankruptcy Account bankruptcy
socialized-fund Socialized-fund

Withdrawal state

State Description
original Request accepted, original state
pending Pending
rejected Withdraw rejected
confirmed Once over 1 confirmation on chain

Deposit state

State Description
mempool Transaction in the mempool
pending KYT Pending
rejected Deposit rejected
confirmed Once over 1 confirmation on chain
unconfirmed Transaction was packed
rollback Transaction was rolled back

Order source

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

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: Order not active
18100235 Fill Bankruptcy Error
18100236 Invalid Order Role
18100237 No Block Order Permission
18100238 Self Trading Error
18100239 Illegal Valid Time Error
18100240 Invalid Block Order Request
18100241 Accept Block Order Error
18100242 Reject Block Order Error
18100243 Calculate Option Mm Error
18100244 Reduce Only Error
18100245 Block Trade Service Stop Error
18100246 Get Stop Trigger Price Error
18100247 Get Open Order Size Error
18100248 Get Position Size Error
18100249 Exceed Max Open Order By Option
18100250 Exceed Max Open Order By Future
18100251 Marketing Bonus Request Error
18100252 Bonus Error
18100253 Get Bonus Error
18100254 Marketing Refund Request Error
18100255 Refund Error
18100256 Get Active Error
18100257 Get Account Configuration Error
18100258 Invalid User Kyc Level Error
18100259 Duplicate Bonus Error
18100260 Calc Position Summary Error
18100261 Exceed Account Delta Error
18100262 Withdraw Request Error
18100263 Withdraw Error
18100264 Invalid User Defined String
18100265 Invalid Blocktrade Source
18100266 Send Captcha Error
18100267 Invalid Captcha Error
18100268 Invalid Number String
18100269 Exceed Max Position Error
18100270 Exceed Max Open Quantity Error
18100271 Get Block Order Error
18100272 Duplicated Blocktrade Key
18100273 Creat Bonus Active Error
18100274 Bonus Total Limit Error
18100275 Invalid Batch Order Request
18100276 Invalid Batch Order Count Request
18100277 Rpc New Batch Order Error
18100278 Fetch Db Timeout
18100279 Takeover Not Allowed
18100280 Invalid Batch Order Amend Request
18100281 Not Found In Open Orders
18100282 Rpc Batch Amend Error
18100285 Mmp error
18100304 Invalid Channel Error
18100305 Invalid Category Error
18100306 Invalid Interval Error
18100401 Invalid Address
18100402 Address Not Whitelisted
18100403 Invalid Fund Password
18100404 Withdrawal Order Not Exist
18100405 KYT Rejected
18100406 Withdraw Too Frequently
18100407 Withdraw Limit Exceeded
18100408 Withdraw Amount Less Than Minimum Amount
18100500 Trading permission error
18100501 Internal Db error
18100502 Internal cache error
18100503 Internal network error
18200300 Rate Limit Exceed
18200301 Login Error
18200302 Authentication Error, auth code:
17002012: no permission to access this endpoint
17002011: invalid IP address
17002010: signature error
17002014: timestamp expired
17002006: internal error
17002013: Invalid access key
18200303 Exceed Max Connection Error
18300300 Not Part In Competition
18300301 Register Competition Failed
18300302 Registered Competition
18400300 Cancel Only Period
18500000 Rpc timeout error (API result in uncertain state, see above info)
json