NAV Navbar
json

Changelogs

version time content
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: support@bit.com
VIP server:vip@bit.com

User Manual

We currently offer perpetual 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,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 https://www.bit.com/propertyCenter/tradingCenter Users who need to increase the speed limit please contact the support team via bd@bit.com.

Public API: 5 requests per second per IP.
Private API(Matching engine): 2 requests per second per user.
Private API(Wallet): 1 request per second per user.
Private API(Others): 5 requests second per user.

About the type of API rate limits, please refer to https://www.bit.com/docs/#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

API summary

Path Method Description Scope Matching engine Permission
/v1/orders POST Place new order private yes read,trade
/v1/cancel_orders POST Cancel order private yes read,trade
/v1/close_positions POST Close positions private yes read,trade
/v1/amend_orders POST Amend order private yes read,trade
/v1/blocktrades POST New block trade private yes read,trade
/v1/batchorders POST Place multiple orders private yes read,trade
/v1/amend_batchorders POST Amend multiple orders private yes read,trade
/v1/account_configs/cod POST Update COD config private yes read,trade
/v1/update_mmp_config POST Update MMP config private yes read,trade
/v1/reset_mmp POST Reset MMP state private yes read,trade
/v1/open_orders GET Query open orders private no read
/v1/orders GET Query order history private no read
/v1/stop_orders GET Query stop order history private no read
/v1/margins GET Query estimated margins private no read
/v1/user/trades GET Query user trades private no read
/v1/positions GET Query positions private no read
/v1/user/deliveries GET Query user deliveries private no read
/v1/user/settlements GET Query user settlements private no read
/v1/transactions GET Query transaction logs private no read
/v1/accounts GET Query user account private no read
/v1/ws/auth GET Get websocket access token private no read
/v1/blocktrades GET Get block trades of current user private no read
/v1/platform_blocktrades GET Get block trades of paltform private no read
/v1/account_configs/cod GET Query COD config private no read
/v1/mmp_state GET Query Mmp State private no read
/v1/wallet/withdraw POST New withdrawal request private no wallet
/v1/wallet/withdraw GET GET withdrawal status private no wallet
/v1/wallet/withdrawals GET GET withdrawal history private no wallet
/v1/wallet/deposits GET GET deposit records private no wallet
/v1/system/time GET Get server time public no
/v1/system/version GET Get system version public no
/v1/system/cancel_only_status GET Get cancel only status public no
/v1/instruments GET Query instruments public no
/v1/market/summary GET Query instrument summary public no
/v1/tickers GET Query instrument ticker public no
/v1/orderbooks GET Query orderbook public no
/v1/market/trades GET Query market trades public no
/v1/klines GET Query kline data public no
/v1/index GET Query index price public no
/v1/delivery_info GET Query daily delivery price info public no
/v1/fundding_rate GET Get latest perpetual funding rate public no

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

Get index price

Query parameters

Parameter Type Required Default Description
currency string false "BTC" Currency (BTC)

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",            
            "active": true
        }
    ]
}

Get instrument list by currency or category

Query parameters

Parameter Type Required Default Description
currency string false "BTC" Currency (BTC)
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

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
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
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 false "" Currency (BTC)
category string false "" Category
option_type string false "" Option type
instrument_id string false "" Instrument ID
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(BTC)
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 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 false "BTC" Currency (BTC)
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": 1598361330000,
        "funding_rate": "0.00000000",
        "index_price": "11498.25000000",
        "mark_price": "11497.96381883"
    }
}

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
index_price string Index price
mark_price string Perpetual Mark price

Account

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

Get user account information

Query parameters

Parameter Type Required Default Description
currency string true "" Currency (BTC)

Response

Name Type Desc
account_id string Account ID
mode string Account 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

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 false "BTC" Currency (BTC)
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, BTC (Perpetual 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 (Perpetual only)
leverage string Position leverage (Perpetual only)

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?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": ""
        }
    ]
}

Get user transactions

Query Parameters

Parameter Type Required Default Description
currency string false "BTC" Currency (BTC)
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 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 false "BTC" Currency (BTC)
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?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",
    }]
}

Get user settlements (only for perpetual currently)

Query Parameters

Parameter Type Required Default Description
currency string false "BTC" Currency (BTC)
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 Perpetual session funding

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 '{"currency": "BTC", "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
currency string true "" Currency (BTC)
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?currency=BTC&timestamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807"

Response

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

Get Cancel On Disconnect configuration of the account

Query parameters

Parameter Type Required Default Description
currency string true "" Currency (BTC)

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 (BTC)

Response

Name Type Desc
currency string Currency (BTC)
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 (BTC)
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 (BTC)

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

    }
}

Place new order.
For market order, price is not required.
Order type default value is 'limit'.
Time in force default value is 'gtc'.


Stop order:
* Order type should be stop-limit or stop-market.
* 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
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

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

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 '{"orders_data": [{"instrument_id": "BTC-25SEP20-8000-C-XX", "price": "0.15", "qty": "51", "side": "buy"}, {"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,
                "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,
                "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
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

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
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 '{"order_id": "44092860", "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}' 



Response

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

Cancel order.
Empty filter means to cancel all orders.
To cancel single order, only need to provide order_id parameter.
Batch cancel filters include: label, instrument_id, category, currency.
Batch cancel filter priorities: 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
order_id string false "" Order ID
currency string false "" Currency (BTC)
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 '{"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
    }
}

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

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


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

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

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

Get open orders by currency, category, instrument_id

Query parameters

Parameter Type Required Default Description
currency string false "" Currency (BTC)
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

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,
    }]
}

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

Query parameters

Parameter Type Required Default Description
currency string false "" Currency (BTC)
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

Get 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?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"
    }]
}

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

Query parameters

Parameter Type Required Default Description
currency string false "" Currency (BTC)
instrument_id string false "" Instrument ID
status string false "" 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 Stop order status
trigger_type string Triggered by last price
user_id string User ID

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 false "" Currency (BTC)
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
count int false 1 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 Use price of auto price order
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.00023000",
        "sell_margin": "0.00190000",
        "min_sell":"7400.00000000",
        "max_buy":"7500.00000000"
    }
}

Get margin of orders

Query parameters

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

Response (Margin array)

Name Type Desc
buy_margin string Estimated buy margin
sell_margin string Estimated sell margin
min_sell string Minimum price for sell order
max_buy string Maximum price for buy order

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 '{"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
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?bt_source=<bt_source>&timestamp=1594447524043&signature=12b1090ea6432e71f2f6d01c6f08f0ff30e3765791ebff87b4183964643d61d2" 

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "1078",
            "label": "test12",
            "created_at": 1593421014546,
            "updated_at": 1593421014565,
            "user_id": "1078",
            "counterparty": "1026",
            "instrument_id": "BTC-PERPETUAL",
            "side": "buy",
            "price": "9000.00000000",
            "qty": "500000.00000000",
            "fee": "27.78333333",
            "status": "filled",
            "role": "taker",
            "bt_source":"<bt_source>",
            "order_id": "3482361"
        }
    ]
}

Query block trades.

Query parameters

Parameter Type Required Default Description
bt_source string true "" Block trade source
currency string false "" Currency (BTC)
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

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?bt_source=<bt_source>&timestamp=1594448745124&signature=39078700dbe556df7f34dd6e0fb444b4ead9ef6ddc8e5b24c76555b6758c68d2" 

Response

{
    "code": 0,
    "message": "",
    "data": [
        {
            "block_order_id": "1088",
            "label": "test13",
            "created_at": 1593437040172,
            "updated_at": 1593437110042,
            "user_id": "1026",
            "counterparty": "1078",
            "instrument_id": "BTC-PERPETUAL",
            "side": "sell",
            "price": "9000.00000000",
            "qty": "500000.00000000",
            "fee": "27.78333333",
            "status": "filled",
            "role": "taker",
            "bt_source":"<bt_source>",
            "order_id": "3482361"
        },        
    ]
}

Query block trades of specific platform.

Query parameters

Parameter Type Required Default Description
bt_source string true "" Block trade source
currency string false "" Currency (BTC)
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

Wallet

Withdraw

POST /v1/wallet/withdraw

curl -X POST "https://betaapi.bitexch.dev/v1/wallet/withdraw" -H "Content-Type: application/json" -H "X-Bit-Access-Key: Your Access Key" -d '{"currency": "BTC", "address": "Your address", "amount": "1.2", "pwd": "Your password", "timestamp": 1589523989378, "signature": "signature"}'

Response


{
    "code": 0,
    "message": "",
    "data": {
        "withdraw_id": "b61c2b93-8a25-44d4-9715-023cce61dc50"
    }
}

Withdraw address need to be whitelisted first here: https://www.bit.com/propertyCenter/withdraw Password need to be encoded to base64(sha256(pwd)). For example, if password is 123456, the encoded password will be:jZae727K08KaOmKSgOaGzww/XVqGr/PKEgIMkjrcbJI=

Post json body

Parameter Type Required Default Description
currency string true "" Currency, BTC
address string true "" Withdrawal address
amount string true "" Withdrawal amount
pwd string true "" Fund password

Response

Name Type Description
withdraw_id string Withdraw ID, can be used in later inquries

Inquire withdraw update

GET /v1/wallet/withdraw

curl -H "X-Bit-Access-Key: Your Access Key" "https://betaapi.bitexch.dev/v1/wallet/withdraw?withdraw_id=b61c2b93-8a25-44d4-9715-023cce61dc50&timestamp=1589522687689&signature=signature"

Response


{
    "code": 0,
    "data": {
        "address": "mfaFpdVCb6UFS5AXUhC8VGXgj9dnJ37nLP",
        "amount": "0.001",
        "code": 0,
        "confirmations": 0,
        "currency": "BTC",
        "fee": "0.00001",
        "state": "unconfirmed",
        "transaction_id": "52e1537002f51acbf5f52b9dfeab6a9e7cc185a669cda2573e768420b0839523"
    },
    "message": ""
}

Inquire withdraw state based on withdraw ID

Query parameters

Parameter Type Required Default Description
withdraw_id String true "" Withdraw ID

Response

Name Type Description
code int Withdraw ID error code, 0 means normal, rest means failed
state string withdrawal state
address string Withdraw address
amount string Withdraw amount
confirmations int Confirmation counts, 0 for internal transafers since they are offchain
currency string Currency
fee string Withdraw fee
transaction_id string Transaction hash

Withdrawal history

GET /v1/wallet/withdrawals

curl -H "X-Bit-Access-Key: Your Access Key" "https://betaapi.bitexch.dev/v1/wallet/withdrawals?currency=BTC&count=10&offset=0&timestamp=1589522687689&signature=signature"

Response


{
    "code": 0,
    "data": {
        "count": 2,
        "items": [{
            "address": "mfaFpdVCb6UFS5AXUhC8VGXgj9dnJ37nLP",
            "amount": "0.001",
            "code": 0,
            "confirmations": 0,
            "currency": "BTC",
            "fee": "0.00001",
            "state": "confirmed",
            "transaction_id": "52e1537002f51acbf5f52b9dfeab6a9e7cc185a669cda2573e768420b0839523"
        }, {
            "address": "mfaFpdVCb6UFS5AXUhC8VGXgj9dnJ37nLP",
            "amount": "0.11",
            "code": 13100100,
            "confirmations": 0,
            "currency": "BTC",
            "fee": "0.00001",
            "state": "rejected",
            "transaction_id": ""
        }]
    }
}

Retrieves the withdrawal records of a specific currency

Query parameters

Parameter Type Required Default Description
currency String true "" Currency
count int false 10 Number of requested items, Max - 50
offset int false 0 the offset for pagination

Response

Name Type Description
code int Withdraw ID error code, 0 means normal, rest means failed
state string withdrawal state
address string Withdraw address
amount string Withdraw amount
confirmations int Confirmation counts, 0 for internal transafers since they are offchain
currency string Currency
fee string Withdraw fee
transaction_id string Transaction hash

Deposits history

GET /v1/wallet/deposits

curl -H "X-Bit-Access-Key: Your Access Key" "https://betaapi.bitexch.dev/v1/wallet/deposits?currency=BTC&count=10&offset=0&timestamp=1589522687689&signature=signature"

Response


{
    "code": 0,
    "data": {
        "count": 1,
        "items": [{
            "address": "mfaFpdVCb6UFS5AXUhC8VGXgj9dnJ37nLP",
            "amount": "0.001",
            "code": 0,
            "confirmations": 0,
            "currency": "BTC",
            "state": "confirmed",
            "transaction_id": "52e1537002f51acbf5f52b9dfeab6a9e7cc185a669cda2573e768420b0839523"
        }]
    }
}

Retrieves the deposit records of a specific currency

Query parameters

Parameter Type Required Default Description
currency String true "" Currency
count int false 10 Number of requested items, Max - 50
offset int false 0 the offset for pagination

Response

Name Type Description
code int Deposit error code, 0 means normal, rest means failed
state string deposit state
address string Deposit address
amount string Deposit amount
confirmations int Confirmation counts, 0 for internal transafers since they are offchain
currency string Currency
transaction_id string Transaction hash

Websocket API

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 will be based on the below return format.

Name Type Description
channel string Channel name
timestamp integer The timestamp (milliseconds since the Unix epoch)
data object Content

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 push frequency via 'interval'. raw = push when there is a change, 100ms = push if any change in the last 100ms

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] default value is raw
token string Authentication Token for private channel

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

Users need to first establish websocket connection, then send request for channel subscriptions. bit.com will then start pushing data (ever after) afterwards.

Each token can only be used once, reconnection requires a new token.

Users can stop the feed by submit an unsubscribe request.

Parameters

None

Response

Name Type Description
token string private channel authentication token

Heartbeat

According to RFC 6455, Websocket protocol uses PING/PONG to indicate connection is 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

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
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,
    "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,
    "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
depth public instruments

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,
    "data":{
        "instrument_id":"BTC-26JUN20-7000-C",
        "sequence":3,
        "bids":[
            [
                "0.00200000",
                "0.50000000"
            ],
            [
                "0.00100000",
                "0.30000000"
            ]
        ],
        "asks":[
            [
                "0.00300000",
                "0.20000000"
            ]
        ]
    }
}

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
order_book.{group}.{depth} public instruments

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
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,
    "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
depth1 public instruments

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,
    "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
ticker public instruments

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
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,
    "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
kline.{resolution} public instruments

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

Kline value: 1, 3, 5, 15, 30, 60, 120, 240, 360, 720, 1440

represents kline resolution, 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,
    "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
trade public instruments

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,
    "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
market_trade public categories + currencies

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,
    "data":{
        "index_name":"BTC_USD",
        "index_price":"9866.66000000"
    }
}

Index Price pushes index price of a specific USD pair.

Channel Information

Channel Scope Arguments
index_price public currencies

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,
    "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
mark_price public instruments

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

Account pushes user's account information

Channel Information

Channel Scope Arguments
account private currencies

Response

Name Type Description
account_id string Account ID
mode string Account 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

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,
    "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,
    "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
position private categories + currencies

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, perpetual only
leverage string Position leverage, perpetual 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,
    "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": false
        }
    ]
}

Order pushes user's order information

Channel Information

Channel Scope Arguments
order private categories + currencies

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
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,
    "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
user_trade private categories + currencies

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,
    "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
mmp_frozen private currencies

Response

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

Constant definitions

Account 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

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 Stop Order is active
triggered Stop order is triggered
cancelled 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

Errors

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 Perpetual
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
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
18200303 Exceed Max Connection Error
18300300 Not Part In Competition
18300301 Register Competition Failed
18300302 Registered Competition
18400300 Cancel Only Period

bit.com SDK

python-api

go-api