COIN-M Futures&Options Changelogs
version | time | content |
---|---|---|
V1.10.3 | 2022 JUN 2 |
* Add kline resolution: 1w , 1m |
V1.10.2 | 2021 NOV 11 |
* GET /v1/margins add UM mode margin info. |
V1.10.1 | 2021 AUG 10 |
* GET /v1/user_trades add parameters: start_id /end_id * Add a new interval fixed100ms for websocket order_book channel * Add websocket RPC cancel_on_disconnect |
V1.10.0 | 2021 MAY 26 |
* Query paging: max offset is 100, query exceed this offset should narrow the range filter (time etc) |
V1.9.0 | 2021 MAR 30 |
* Update prefix of stop order: for normal stop order, prefix is stop- , for trigger order, prefix is trigger- |
V1.8.0 | 2021 MAR 12 |
* Update paging information of following REST endpoints: GET v1/market/trades GET v1/orders GET v1/transactions GET v1/user/settlements Original: "paging": {"limit": 2, "offset": 3, "total": 59} New: "page_info": { "has_more": true } * Support hidden order: POST /v1/orders POST /v1/batchorders * Add source , hidden to the response of following REST endpoints: POST /v1/orders POST /v1/batchorders POST /v1/amend_orders POST /v1/amend_batchorders GET /v1/orders GET /v1/open_orders GET /v1/stop_orders * Add hidden to the response of websocket order channel. * Enhanced stop order, add trigger-limit , trigger-market order type |
V1.7.2 | 2021 FEB 19 |
* Add GET /v1/user/info * For GET /v1/platform_blocktrades and GET /v1/blocktrades , add fields trade_id , index_price , sigma |
V1.7.1 | 2021 FEB 4 |
* Add GET /v1/currencies |
V1.7.0 | 2021 JAN 14 |
* GET /v1/tickers and websocket ticker add funding_rate and funding_rate8h * Add response field reorder_index (internal use) for REST endpoints GET /v1/orders , GET /v1/open_orders and websocket channel order |
V1.6.1 | 2020 DEC 29 |
* For /v1/accounts, the response add projected_info object* For /v1/market/trades add start_time and end_time filter * Add v1/total_volumes * For GET /v1/wallet/withdraw , /v1/wallet/withdrawals and /v1/wallet/deposits , the response add is_onchain |
V1.6.0 | 2020 DEC 8 |
* Currency parameter is required * Following endpoints will add currency parameter POST /v1/batchorders POST /v1 amend_orders POST /v1/amend_batchorders POST /v1/blocktrades * Endpoint POST /v1/account_configs/cod is no longer currency-level, so the currency parameter is removed and will be ignored if user provide it * For GET /v1/tickers REST endpoint and ticker websocket stream, if no tick in previous 24 hours, fetch last tick close as open,high,low,close |
V1.4.0 | 2020 OCT 22 | * Add /v1/settlement_prices * Add GET /v1/funding_rate_history |
V1.3.1 | 2020 SEP 22 | * Add future_delta to websocket account stream * Add liq_price , leverage to websocket position stream |
V1.3.0 | 2020 SEP 18 | * Add mmp rest api: GET /v1/mmp_state , POST /v1/update_mmp_config , POST /v1/reset_mmp , and websocket mmp_frozen channel |
V1.0.2.6 | 2020 SEP 8 | * Add label in private trade response: GET /v1/user/trades and WS user_trade channel* Add /v1/system/cancel_only_status to query cancel-only period status. * Fix the return type of websocket trade and market_trade channel. * Support BBO order. * Fix usd_price in trades (rest & ws) for options |
V1.0.2 | 2020 AUG 25 | * Add batch amend orders: POST /v1/amend_batchorders * /v1/market/trades add block trade tag * Fix transaction log trade id issues. * Add /v1/funding_rate |
V1.0.1 | 2020 AUG 10 | * Add batch new orders: POST /v1/batchorders |
V1.0 | 2020 JUL 30 | *add POST /v1/account_configs/cod * Add is_liquidation , taker_fee_rate , maker_fee_rate , label , stop_price , reduce_only , post_only , reject_post_only to websocket order stream * Add is_block_trade to websocket trade, market_trade, user_trade stream |
V0.4 | 2020 JUL 15 | *Remove fee ,pnl ,cashflow order action fields information regarding these fields are not available when Api call returns. Affected endpoints:POST /v1/orders,POST /v1/amend_orders,POST /v1/close_positions *Endpoint POST /v1/amend_orders add qty* Add block trade source for:POST /v1/blocktrades,GET /v1/blocktrades,GET /v1/platform_blocktrades *Add future_delta to GET /v1/accounts *Add contract_size ,contract_size_currency to GET /v1/instruments |
V0.3 | 2020 Jun 30 | * Transaction log query add position * Add block trade * Batch cancel: support more parameters * Update block trade query filter: taker/maker |
V0.2 | 2020 Jun 15 | * Order vo add: post_only, reject_post_only *Order query add label filter |
V0.1 | 2020 Jun 1 | first version |
Introduction
Welcome to bit.com API. You can retrieve market data, execute trades and manage your bit.com account through bit.com API.
The document consists of three parts: table of contents for easy browsing (left), longer explanation of each API interface although they are quite self-explanatory already(middle), and example code (right)
How to contact us:
WEB: www.bit.com
support team: [email protected]
VIP server: [email protected]
Telegram:https://t.me/bitcom_exchange
Market maker projects
Market makers are welcome to participate in bit long-term market making projects.
Send the following information to: [email protected]
1. Bit account information;
2. Effective contact information except email;
The type of market maker to be applied for should be indicated in the email (multiple choices are allowed)
Application of market maker for bit spot
Application of market maker for bit delivery contract
Application of market maker for bit perpetual contract
Application of market maker for bit option contract
To encourage market makers to provide better liquidity for the platform, they can enjoy preferential transaction fees. Specific market making responsibilities and handling charges shall be provided after application.
* Bit owns the final interpretation right of the market maker project.
User Manual
We currently offer spot
,future
and option
on bit.com.
Two methods to call API are currently offered at bit.com: Rest and Websocket.
- Rest endpoint
REST endpoint consists of public and private APIs, where public API can be called directly without authentication.
Private API, on the other hand, requires API key signature authentication, Please register, set up API key and related access set ups on API page before kicking off API development.
Private API access: read,future&option trade,spot trade,wallet,block trade
API types and access details can be viewed API summary.
- Websocket API
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)
- REST API base url: https://api.bit.com
- WS API base url: wss://ws.bit.com
API hosts (testnet)
- REST API base url: https://betaapi.bitexch.dev
- WS API base url: wss://betaws.bitexch.dev
API rate limits
In order to ensure the system efficiency, bit.com implements the API rate limits . The public interface implements IP-specified frequency limitation , and the private interface implements user-specified frequency limitation. When a breach happens, a prompt will be returned: “429 too many requests”. The individual API limits can be found on the webpage of the trading center. Users who need to increase the speed limit please contact the support team via [email protected]
- Rest API rate limits:
Public API: 10 requests per second per IP.
Private API(future&option trade): 5 requests per second per user.
Private API(option trade): 10 requests per second per user.
Private API(Wallet): 1 request per second per user.
Private API(Block Trade):2 requests per second per user.
Private API(Others): 5 requests second per user.
About the type of API rate limits, please refer to API summary.
- WebSockets API Rate Limits:
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
- User must put
Access Key
in http request headerX-Bit-Access-Key
. - User must add
timestamp
(epoch in millisecond) field in request parameter (query string for GET, json body for POST),API server will check this timestamp, ifabs(server_timestamp - request_timestamp) > 5000
, the request will be rejected. timestamp
must be integer, not quoted string.- User must add
signature
field in request parameter (query string for GET, json body for POST). - For POST request, Header
Content-Type
should be set asapplication/json
.
If authentication fails, a prompt will be returned: “AkId is invalid” and http status code is 412
Signature algorithm
#########
# Python code to calc BIT.COM API signature
#########
import hashlib
import hmac
def encode_list(self, item_list):
list_val = []
for item in item_list:
obj_val = self.encode_object(item)
list_val.append(obj_val)
output = '&'.join(list_val)
output = '[' + output + ']'
return output
def encode_object(self, 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
#########
- Request parameters: JSON Body for POST, query string for the rest
- Encode string to sign, for simple json object, sort your parameter keys alphabetically, and join them with '&' like 'param1=value1¶m2=value2', then get str_to_sign = api_path + '&' + 'param1=value1¶m2=value2'
- For nested array objects, encode each object and sort them alphabetically, join them with '&' and embraced with '[', ']', e.g. str_to_sign = api_path + '&' + 'param1=value1&array_key1=[array_item1&array_item2]', see example below.
- Signature = hex(hmac_sha256(str_to_sign, secret_key))
- Add
signature
field to request parameter:
for query string, add '&signature=YOUR_SIGNATURE' for JSON body, add {'signature':YOUR_SIGNATURE}
Example for GET
request
Secret Key: eabc3108-dd2b-43df-a98d-3e2054049b73
HTTP method: GET
API Path: /v1/margins
Query string: price=8000&qty=30&instrument_id=BTC-PERPETUAL×tamp=1588242614000
Then str_to_sign = /v1/margins&instrument_id=BTC-PERPETUAL&price=8000&qty=30×tamp=1588242614000
> echo -n "/v1/margins&instrument_id=BTC-PERPETUAL&price=8000&qty=30×tamp=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×tamp=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×tamp=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×tamp=1588242614000" | openssl dgst -sha256 -hmac "eabc3108-dd2b-43df-a98d-3e2054049b73"
> 34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817
sig = hex(hmac_sha256(str_to_sign, secret_key)) = 34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817
Final JSON body:
{
"instrument_id": "BTC-27MAR20-9000-C",
"order_type": "limit",
"price": "0.021",
"qty": "3.14",
"side": "buy",
"time_in_force": "gtc",
"stop_price": "",
"stop_price_trigger": "",
"auto_price": "",
"auto_price_type": "",
"timestamp": 1588242614000,
"signature": "34d9afa68830a4b09c275f405d8833cd1c3af3e94a9572da75f7a563af1ca817"
}
POST request json body with boolean field
For example, When calling POST /v1/orders with boolean fields:
Take post_only as example,
In json body, use following format, a real json boolean field, no quoted string: {"post_only": true}
In string payload before making signature: post_only=true
Example
request
curl -X POST "https://betaapi.bitexch.dev/v1/orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" -d '{"instrument_id": "BTC-26JUN20-3500-P", "price": "15", "qty": "1", "side": "sell", "time_in_force": "gtc", "order_type": "limit", "post_only": true, "timestamp": 1592587664652, "signature": "cf2d8fe95b71764056a4f707e2388ce84a82ed2915cbe92b58f37c26ea0eda97"}'
string to sign
- str_to_sign = /v1/orders&instrument_id=BTC-26JUN20-3500-P&order_type=limit&post_only=true&price=15&qty=1&side=sell&time_in_force=gtc×tamp=1592587664652
POST request json body with array field
- Algo
for item in object_array:
str_list.add(encode(item))
str_to_sign = '&'.join(str_list)
For example, When calling POST /v1/blocktrades with array fields:
Take trades as example,
- In json body, use following format {"trades": [{"instrument_id": "BTC-25SEP20-9000-C", "price": "0.21", "qty": "50", "side": "sell"}, {"instrument_id": "BTC-PERPETUAL", "price": "9000", "qty": "500000", "side": "buy"}]}
And secret key is eabc3108-dd2b-43df-a98d-3e2054049b73
Example
request
curl -X POST "https://betaapi.bitexch.dev/v1/trades" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" -d '{"label": "A0627-1", "role": "taker", "trades": [{"instrument_id": "BTC-25SEP20-9000-C", "price": "0.21", "qty": "50", "side": "sell"}, {"instrument_id": "BTC-PERPETUAL", "price": "9000", "qty": "500000", "side": "buy"}], "timestamp": 1593239722621, "signature": "9636f1850e33557c03a499bb5c1aed9a36be340f3dbfd22a3f066438b3987d6b"}'
string to sign
- str_to_sign = /v1/trades&label=A0627-1&role=taker×tamp=1593239722621&trades=[instrument_id=BTC-25SEP20-9000-C&price=0.21&qty=50&side=sell&instrument_id=BTC-PERPETUAL&price=9000&qty=500000&side=buy]
Multi-currency support
Supported currencies: BTC
,ETH
and BCH
To support multi currency in future versions, we revised the backend architecture. account/order/trade/position/tx_log etc for each currency has its own separate storage space and independent, so the account_id/order_id/trade_id etc for BTC and ETH may have the same values. For example, a user may have an order 123 for BTC, and has an order 123 for ETH as well, i.e. order_id is NOT unique across currencies, but currency + order_id is unique.
Every trading endpoint needs to have a parameter for determining which currency it refers to. It can be either
acurrency
parameter, e.g. GET /v1/accounts, or an
instrument_id
parameter, e.g. GET /v1/funding_rate.
If an API endpoint has bothcurrency
andinstrument_id
,currency
will be used. e.g. GET /v1/market/summary.currency
/instrument_id
parameter is required
Historically some endpoints have an optional parameter with default value "BTC", e.g. GET /v1/orders. For compatibility we will continue to have this default value for a period of time. But in the future, we will drop the default value, and thecurrency
parameter MUST be set explicitly.The following endpoints will add currency parameter
currency
since v1.6.0
POST /v1/batchorders
POST /v1/amend_orders
POST /v1/amend_batchorders
POST /v1/blocktradesThe following endpoints'
currency
parameter will become REQUIRED since v1.6.0 (after the grace period stated above)
GET /v1/positions
GET /v1/transactions
GET /v1/user/deliveries
GET /v1/user/settlements
GET /v1/blocktrades
GET /v1/platform_blocktrades
GET /v1/index
GET /v1/instruments
GET /v1/market/trades
GET /v1/market/summary
GET /v1/open_orders
GET /v1/orders
GET /v1/stop_orders
GET /v1/user/trades
POST /v1/cancel_ordersEndpoint
POST /v1/account_configs/cod
is no longer currency-level, so thecurrency
parameter is removed and will be ignored if user provide it
API summary
- User defined string fields(label etc): valid characters are [A-Z], [a-z], [0-9], "-", "_"
Path | Method | Description | Scope | Rate Limit Type | Permission |
---|---|---|---|---|---|
/v1/orders | POST | Place new order | private | futures&options trade | future&option trade |
/v1/cancel_orders | POST | Cancel order | private | futures&options trade | future&option trade |
/v1/close_positions | POST | Close positions | private | futures&options trade | future&option trade |
/v1/amend_orders | POST | Amend order | private | futures&options trade | future&option trade |
/v1/batchorders | POST | Place multiple orders | private | futures&options trade | future&option trade |
/v1/amend_batchorders | POST | Amend multiple orders | private | futures&options trade | future&option trade |
/v1/account_configs/cod | POST | Update COD config | private | futures&options trade | future&option trade |
/v1/update_mmp_config | POST | Update MMP config | private | futures&options trade | future&option trade |
/v1/reset_mmp | POST | Reset MMP state | private | futures&options trade | future&option trade |
/v1/open_orders | GET | Query open orders | private | futures&options others | read |
/v1/orders | GET | Query order history | private | futures&options others | read |
/v1/stop_orders | GET | Query stop order history | private | futures&options others | read |
/v1/margins | GET | Query estimated margins | private | futures&options others | read |
/v1/user/trades | GET | Query user trades | private | futures&options others | read |
/v1/positions | GET | Query positions | private | futures&options others | read |
/v1/user/deliveries | GET | Query user deliveries | private | futures&options others | read |
/v1/user/settlements | GET | Query user settlements | private | futures&options others | read |
/um/v1/account_mode | GET | Query Account mode | private | UM others | read |
/v1/accounts | GET | Query user account | private | futures&options others | read |
/v1/transactions | GET | Query transaction logs | private | futures&options others | read |
/um/v1/account | GET | Query um account information | private | UM-others | read |
/um/v1/transactions | GET | Query um transaction logs | private | UM-others | read |
/um/v1/interest_records | GET | Query um interest records | private | UM-others | read |
/v1/ws/auth | GET | Get websocket access token | private | futures&options others | read |
/v1/account_configs/cod | GET | Query COD config | private | futures&options others | read |
/v1/mmp_state | GET | Query Mmp State | private | futures&options others | read |
/v1/blocktrades | POST | New block trade | private | futures&options block_trade | block_trade |
/v1/blocktrades | GET | Get block trades of current user | private | futures&options block_trade | block_trade |
/v1/platform_blocktrades | GET | Get block trades of paltform | private | futures&options block_trade | block_trade |
/v1/user/info | GET | Get user info with blocktrade permission | private | futures&options block_trade | block_trade |
/v1/system/time | GET | Get server time | public | futures&options public | / |
/v1/system/version | GET | Get system version | public | futures&options public | / |
/v1/system/cancel_only_status | GET | Get cancel only status | public | futures&options public | / |
/v1/instruments | GET | Query instruments | public | futures&options public | / |
/v1/market/summary | GET | Query instrument summary | public | futures&options public | / |
/v1/tickers | GET | Query instrument ticker | public | futures&options public | / |
/v1/orderbooks | GET | Query orderbook | public | futures&options public | / |
/v1/market/trades | GET | Query market trades | public | futures&options public | / |
/v1/klines | GET | Query kline data | public | futures&options public | / |
/v1/index | GET | Query index price | public | futures&options public | / |
/v1/delivery_info | GET | Query daily delivery price info | public | futures&options public | / |
/v1/funding_rate | GET | Get latest perpetual funding rate | public | futures&options public | / |
/v1/funding_rate_history | GET | Get perpetual funding rate history | public | futures&options public | / |
/v1/settlement_prices | GET | Get settlement/delivery prices | public | futures&options public | / |
v1/total_volumes | GET | Get total volumes for all currencies | public | futures&options public | / |
/um/v1/loan_rates | GET | Query loan rate | public | public | / |
System
Get server timestamp
GET /v1/system/time
curl "https://betaapi.bitexch.dev/v1/system/time"
Response
{
"code": 0,
"message": "",
"data": 1587884283175
}
Get server timestamp
Query Parameters
None
Response
Name | Type | Description |
---|---|---|
data | string | Server timestamp |
Get system version
GET /v1/system/version
curl "https://betaapi.bitexch.dev/v1/system/version"
Response
{
"code": 0,
"message": "",
"data": "v1.0"
}
Get API version
Query Parameters
None
Response
Name | Type | Description |
---|---|---|
data | string | Api server version |
Get cancel only status
GET /v1/system/cancel_only_status
curl "https://betaapi.bitexch.dev/v1/system/cancel_only_status"
Response
{
"code": 0,
"message": "",
"data": {
"status": 0,
"remain_ms": 0
}
}
Get cancel-only status after system maintenance.
status
status=1: means cancel-only is in effective.
status=0: means cancel-only period is finished, the system is ready to accept orders.
remain_ms
Remain time (in milliseconds) for the cancel-only period to finish. when status=0, remain_ms is 0.
Query parameters
None
Response
Name | Type | Description |
---|---|---|
status | integer | Cancel-only status. |
remain_ms | integer | Remain time (in milliseconds) for the cancel-only period to finish. |
Market
Get index
GET /v1/index
curl "https://betaapi.bitexch.dev/v1/index?currency=BTC"
Response
{
"code": 0,
"message": "",
"data": {
"name": "BTC",
"index_price": "9444.49000000"
}
}
Deprecated
, please use /um/index_price
Get index price
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
Response
Name | Type | Description |
---|---|---|
name | string | Index name |
index_price | string | Index price |
Get instruments
GET /v1/instruments
curl "https://betaapi.bitexch.dev/v1/instruments?currency=BTC&category=option&active=true"
Response
{
"code": 0,
"message": "",
"data": [
{
"instrument_id": "BTC-29MAY20-9500-P",
"created_at": 1589425192000,
"updated_at": 1589425192000,
"base_currency": "BTC",
"quote_currency": "USD",
"strike_price": "9500.00000000",
"expiration_at": 1590739200000,
"option_type": "put",
"category": "option",
"min_price": "0.00050000",
"max_price": "10.00000000",
"price_step": "0.00050000",
"min_size": "0.10000000",
"size_step": "0.10000000",
"delivery_fee_rate": "0.00020000",
"contract_size": "1.00000000",
"contract_size_currency": "BTC",
"display_at": 1589425292000,
"active": true
}
]
}
Get instrument list by currency or category
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
active | boolean | false | true | Set true to query active instruments |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
category | string | Category |
created_at | integer | Created timestamp |
updated_at | integer | Updated timestamp |
expiration_at | integer | Expiration timestamp (for perpetual, is timestamp of 2100-01-01) |
base_currency | string | Base currency |
quote_currency | string | Quote currency |
option_type | string | Call/put, option only |
strike_price | string | Strike price, option only |
min_price | string | System-wise minimum order price, (order price also restricted to min sell/max buy) |
max_price | string | System-wise maximum order price, (order price also restricted to min sell/max buy) |
price_step | string | Order price should be multiple of price_step |
min_size | string | System-wise minimum order size |
size_step | string | Order size should be multiple of size_step |
delivery_fee_rate | string | Instrument delivery fee rate,option only |
contract_size | string | Contract size of the instrument |
contract_size_currency | string | Contract size currency |
active | bool | Instrument is allowed to trade or not |
display_at | integer | Displayed time at management console (For internal use) |
Get tickers
GET /v1/tickers
curl "https://betaapi.bitexch.dev/v1/tickers?instrument_id=BTC-26JUN20-5000-C"
Response
{
"code": 0,
"message": "",
"data":{
"time":1589126498813,
"instrument_id":"BTC-26JUN20-5000-C",
"best_bid":"0.50200000",
"best_ask":"0.50500000",
"best_bid_qty":"2.30000000",
"best_ask_qty":"0.80000000",
"ask_sigma":"2.22748567",
"bid_sigma":"2.18964114",
"last_price":"0.50500000",
"last_qty":"0.10000000",
"open24h":"0.50500000",
"high24h":"0.50500000",
"low24h":"0.50500000",
"price_change24h":"",
"volume24h":"0.10000000",
"open_interest":"289.50000000",
"underlying_name":"BTC-26JUN20",
"underlying_price":"8616.02000000",
"mark_price":"0.43989364",
"sigma":"1.29049244",
"delta":"0.92073799",
"vega":"4.54807454",
"theta":"-6.28858194",
"gamma":"0.00003713",
"min_sell":"0.38950000",
"max_buy":"0.49000000"
}
}
Get ticker information by instrument
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
last_price | string | Most recent traded price |
last_qty | string | Most recent traded volume |
open24h | string | Open price during previous 24 hour |
high24h | string | Highest price during previous 24 hour |
low24h | string | Lowest price during previous 24 hour |
volume24h | string | Sum volume during previous 24 hour |
price_change24h | string | Price change% during previous 24 hour |
open_interest | string | Open interest |
best_bid | string | Best bid price |
best_ask | string | Best ask price |
best_bid_qty | string | Best bid quantity |
best_ask_qty | string | Best ask quantity |
bid_sigma | string | Top of book bid implied vol, option only |
ask_sigma | string | Top of book ask implied vol, option only |
underlying_name | string | Underlying index name, option only |
underlying_price | string | Underlying price, option only |
funding_rate | string | Funding rate, perpetual only |
funding_rate8h | string | Past 8H avg funding rate, perpetual only |
mark_price | string | Mark price |
sigma | string | Mark price implied vol, option only |
delta | string | Mark price delta, option only |
vega | string | Mark price vega, option only |
theta | string | Mark price theta, option only |
gamma | string | Mark price gamma, option only |
max_buy | string | Maximum price of buy order |
min_sell | string | Minimum price of sell order |
Get orderbooks
GET /v1/orderbooks
curl "https://betaapi.bitexch.dev/v1/orderbooks?instrument_id=BTC-27MAR20-9000-C&level=3"
Response
{
"code": 0,
"message": "",
"data": {
"instrument_id": "BTC-27MAR20-9000-C",
"timestamp": 1585299600000,
"asks": [
["0.02300000", "3.00000000"],
["0.02400000", "0.70000000"],
["0.02500000", "18.00000000"]
],
"bids": [
["0.02100000", "0.30000000"],
["0.02000000", "2.00000000"],
["0.01900000", "5.60000000"]
]
}
}
Get orderbook by instrument
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID |
level | int | false | 5 | No. of depth, value range [1,50] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
timestamp | integer | Timestamp (data time) |
asks | string | Asks array [price, qty] |
bids | string | Bids array [price, qty] |
Get market trades
GET /v1/market/trades
curl "https://betaapi.bitexch.dev/v1/market/trades?currency=BTC&category=option&option_type=call&instrument_id=BTC-27MAR20-9000-C&offset=1&limit=1"
Response
{
"code": 0,
"message": "",
"data": [
{
"created_at": 1585299600000,
"index_price": "8000.00000000",
"underlying_price": "8000.00000000",
"instrument_id": "BTC-27MAR20-9000-C",
"price": "0.03400000",
"qty": "1.00000000",
"side": "buy",
"sigma": "0.00200000",
"trade_id": 3743,
"is_block_trade": false
}
]
}
Get market trades by currency, category, option_type, instrument_id
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
option_type | string | false | "" | Option type |
instrument_id | string | false | "" | Instrument ID |
start_time | integer | false | Start timestamp | |
end_time | integer | false | End timestamp | |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Description |
---|---|---|
trade_id | integer | Trade ID |
instrument_id | string | Instrument ID |
created_at | integer | Creation timestamp of the trade |
price | string | Price |
qty | string | Quantity |
side | string | Order side |
index_price | string | Index price |
sigma | string | Implied volatility (option only) |
underlying_price | string | Underlying price (option only) |
is_block_trade | bool | Is block trade or not |
Get klines
GET /v1/klines
curl "https://betaapi.bitexch.dev/v1/klines?instrument_id=BTC-27MAR20-9000-C&start_time=1585296000000&end_time=1585596000000&timeframe_min=1440"
Response
{
"code": 0,
"message": "",
"data": {
"close": [
0.023
],
"high": [
0.031
],
"low": [
0.022
],
"open": [
0.028
],
"timestamps": [
1585296000000
],
"volume": [
31.2
]
}
}
Get klines by instrument.
klines endpoint returns 6 time series of data: open price array, hight price array, low price array, close price array,
timestamp array of each kline, and volume array.
/v1/klines return max 1000 records in given search conditions.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID |
start_time | integer | true | Start timestamp | |
end_time | integer | true | End timestamp | |
timeframe_min | string | true | "" | Timeframe in minutes (1, 3, 5, 15, 30, 60, 120, 240, 360, 720, 1440) |
Response
Name | Type | Description |
---|---|---|
open | float array | Open price series |
high | float array | High price series |
low | float array | Low price series |
close | float array | Close price series |
timestamps | float array | Timestamp series |
volume | float array | Volume series |
Get daily delivery price info
GET /v1/delivery_info
curl "https://betaapi.bitexch.dev/v1/delivery_info?currency=BTC&offset=1&limit=10"
Response
{
"code": 0,
"message": "",
"data": [
{
"currency": "BTC",
"delivery_time": 1585296000000,
"price": "7982.00000000"
}
]
}
Get daily delivery price info history.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Description |
---|---|---|
currency | string | Currency |
delivery_time | integer | Timestamp |
price | string | Delivery price |
Get market settlement price info
GET /v1/settlement_prices
curl "https://betaapi.bitexch.dev/v1/settlement_prices?currency=BTC&start_time=1600421456435&end_time=1603013456435"
Response
{
"code": 0,
"message": "",
"data": {
"data": {
"1600473600000": [
{
"date": 1600473600000,
"currency": "BTC",
"instrument_id": "BTC-OPTIONS",
"settlement_type": "delivery",
"price": "10920.02000000"
},
{
"date": 1600473600000,
"currency": "BTC",
"instrument_id": "BTC-PERPETUAL",
"settlement_type": "settlement",
"price": "10907.68451016"
},
{
"date": 1600473600000,
"currency": "BTC",
"instrument_id": "BTC-19SEP20-F",
"settlement_type": "delivery",
"price": "10920.02000000"
}
],
"1600560000000": [
{
"date": 1600560000000,
"currency": "BTC",
"instrument_id": "BTC-OPTIONS",
"settlement_type": "delivery",
"price": "10981.62000000"
},
{
"date": 1600560000000,
"currency": "BTC",
"instrument_id": "BTC-PERPETUAL",
"settlement_type": "settlement",
"price": "10961.44289452"
},
{
"date": 1600560000000,
"currency": "BTC",
"instrument_id": "BTC-20SEP20-F",
"settlement_type": "delivery",
"price": "10981.62000000"
}
]
}
}
}
Get settlement/delivery price history.
Time range filter is within 30 days.
BTC-OPTIONS
means all options share same delivery price.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
start_time | integer | true | Start timestamp | |
end_time | integer | true | End timestamp |
Response
Dictionary key is date in milliseconds, value is delivery/settlement record list
Name | Type | Description |
---|---|---|
date | integer | Delivery/settlement date in ms |
currency | string | Currency |
instrument_id | string | Instrument Id (BTC-OPTIONS means all options) |
settlement_type | string | delivery or settlement |
price | string | Delivery/settlement price |
Get market summary
GET /v1/market/summary
curl "https://betaapi.bitexch.dev/v1/market/summary?currency=BTC&category=future&instrument_id=BTC-PERPETUAL"
Response
{
"code": 0,
"message": "",
"data": [
{
"instrument_id": "BTC-PERPETUAL",
"timestamp": 1589029194249,
"best_bid": "9594.00000000",
"best_ask": "9623.50000000",
"best_bid_qty": "16860.00000000",
"best_ask_qty": "5770.00000000",
"last_price": "9617.00000000",
"last_qty": "5530.00000000",
"open24h": "9858.00000000",
"high24h": "9989.50000000",
"low24h": "9498.50000000",
"volume24h": "1325995140.00000000",
"open_interest": "460634610.00000000",
"mark_price": "9556.24890315",
"max_buy": "9700.50000000",
"min_sell": "9413.00000000",
"delta": "",
"gamma": "",
"vega": "",
"theta": ""
}
]
}
Get market summary by instrument
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "option" | Category |
instrument_id | string | false | "" | Instrument ID |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
timestamp | integer | Timestamp |
best_bid | string | Best bid price |
best_ask | string | Best ask price |
best_bid_qty | string | Best bid quantity |
best_ask_qty | string | Best ask quantity |
last_price | string | Last price |
last_qty | string | Last quantity |
open24h | string | Open price during previous 24 hour |
high24h | string | Highest price during previous 24 hour |
low24h | string | Lowest price during previous 24 hour |
volume24h | string | Sum volume during previous 24 hour |
open_interest | string | Open interest of current instrument_id |
mark_price | string | Mark price |
max_buy | string | Max price of buy order |
min_sell | string | Min price of sell order |
delta | string | Option delta |
gamma | string | Option gamma |
vega | string | Option vega |
theta | string | Option theta |
Get funding rate
GET /v1/funding_rate
curl "https://betaapi.bitexch.dev/v1/funding_rate?instrument_id=BTC-PERPETUAL"
Response
{
"code": 0,
"message": "",
"data": {
"instrument_id": "BTC-PERPETUAL",
"time": 1635913370000,
"funding_rate": "0.00000000",
"funding_rate_8h": "-0.00102858",
"index_price": "62989.63000000",
"mark_price": "62969.83608581"
}
}
Get latest perpetual funding rate. Funding rate will be refreshed in every 10 seconds.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID (perpetual only) |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
time | integer | Timestamp |
funding_rate | string | Current perpetual funding rate |
funding_rate_8h | string | Past 8H avg funding rate, perpetual only |
index_price | string | Index price |
mark_price | string | Perpetual Mark price |
Get funding rate history
GET /v1/funding_rate_history
curl "https://betaapi.bitexch.dev/v1/funding_rate_history?instrument_id=BTC-PERPETUAL&start_time=1603260000000&end_time=1603346400000&history_type=1H"
Response
{
"code": 0,
"message": "",
"data": [
{
"instrument_id": "BTC-PERPETUAL",
"time": 1603263600000,
"average_funding_rate": "0.00100000",
"index_price": "8880.17000000",
"mark_price": "8900.18000000"
}
]
}
Note: Start time must be greater than 2020.10.31 (timestamp: 1604102400000).
Get the funding rate history within a given time period. History type can be 1H/8H/24H.
Returns average funding rate of the past 1 hour at each 3 minutes in the period, or returns average funding rate of the past 8 hours/24 hours at each hour in the period.
For 1H, the query time period cannot exceed 1 days, and for 8H/24H, the query time period cannot exceed 30 days.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID (perpetual only) |
start_time | integer | true | Start timestamp | |
end_time | integer | true | End timestamp | |
history_type | string | true | 1H/8H/24H |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
time | integer | Timestamp |
average_funding_rate | string | The past 1H/8H/24H average history funding rate for this time |
index_price | string | Index price |
mark_price | string | Perpetual Mark price |
Get all market volume
GET v1/total_volumes
curl "https://betaapi.bitexch.dev/v1/total_volumes"
Response
{
"code": 0,
"message": "",
"data": {
"total_volume_24_hours": "140512988.61600000",
"details": [
{
"currency": "BTC",
"category": "option",
"volume_base_ccy": "5254.40000000",
"volume_usd": "124599899.13600000",
"index_price": "23713.44000000"
},
{
"currency": "BTC",
"category": "future",
"volume_base_ccy": "404.96317700",
"volume_usd": "9603070.00000000",
"index_price": "23713.44000000"
},
{
"currency": "ETH",
"category": "option",
"volume_base_ccy": "6233.00000000",
"volume_usd": "3855484.48000000",
"index_price": "618.56000000"
},
{
"currency": "ETH",
"category": "future",
"volume_base_ccy": "3968.14375323",
"volume_usd": "2454535.00000000",
"index_price": "618.56000000"
}
]
}
}
Get all market volumes of previous 24 hours.
This endpoint will be cached with 5 seconds, client request multiple times within sort period of time will get unchanged result.
Query parameters
None
Response
Name | Type | Description |
---|---|---|
total_volume_24_hours | string | Total volume |
details | array | Volume details |
details
Name | Type | Description |
---|---|---|
currency | string | Currency |
category | string | Category |
volume_base_ccy | string | Volume in base ccy |
volume_usd | string | Volume in USD |
index_price | string | Index price |
Get coin-margined currencies
GET v1/currencies
curl "https://betaapi.bitexch.dev/v1/currencies"
Response
{
"code": 0,
"message": "",
"data": {
"currencies": [
"BTC",
"ETH",
"BCH"
]
}
}
Get all margin currencies for coin-margined contracts.
Query parameters
None
Response
Name | Type | Description |
---|---|---|
currencies | array | Currencies array |
Account
Get account mode
GET /um/v1/account_mode
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/um/v1/account_mode?timestamp=1589521383462&signature=30f7cf5c8018f5dfee515533e25a1813e9120be7898b62fb85a2f4129f3e9528"
Response
// account_mode = Um
{
"code": 0,
"message": "",
"data": {
"user_id": 1,
"account_mode": "um",
"auto_borrow": true,
"um_risk_mode": "regular",
"classic_accounts": []
}
}
// account_mode = classic
{
"code": 0,
"message": "",
"data": {
"user_id": 1,
"account_mode": "classic",
"auto_borrow": false,
"um_risk_mode": "",
"classic_accounts": [
{
"currency": "BCH",
"classic_risk_mode": "portfolio_margin"
},
{
"currency": "BTC",
"classic_risk_mode": "portfolio_margin"
},
{
"currency": "ETH",
"classic_risk_mode": "portfolio_margin"
}
]
}
}
Get account mode.
Query parameters
None
Response
Name | Type | Desc |
---|---|---|
user_id | int | User ID |
account_mode | string | Account mode |
auto_borrow | bool | Auto borrow or not |
um_risk_mode | string | Um risk mode, regular/pm (only valid when account_mode = um ) |
classic_accounts | array | classic account info (only valid when account_mode = classic ) |
- classic account info (only valid when
account_mode
=classic
)
Name | Type | Desc |
---|---|---|
currency | string | Currency |
classic_risk_mode | string | regular/pm |
Get user accounts
GET /v1/accounts
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/accounts?currency=BTC×tamp=1589521383462&signature=30f7cf5c8018f5dfee515533e25a1813e9120be7898b62fb85a2f4129f3e9528"
Response
{
"code": 0,
"message": "",
"data": {
"user_id": "51140",
"currency": "BTC",
"cash_balance": "99.59591877",
"available_balance": "97.47174526",
"margin_balance": "99.59589266",
"initial_margin": "2.12414740",
"maintenance_margin": "0.00002866",
"equity": "100.02737507",
"pnl": "0.08047907",
"total_delta": "1.40711353",
"account_id": "3033",
"mode": "regular",
"session_upl": "0.08047907",
"session_rpl": "-0.00002286",
"option_value": "0.43148240",
"option_pnl": "0.08048240",
"option_session_rpl": "0.00000000",
"option_session_upl": "0.08048240",
"option_delta": "1.83338535",
"option_gamma": "0.00017907",
"option_vega": "4.04908990",
"option_theta": "-36.98180587",
"future_pnl": "-0.00000333",
"future_session_rpl": "-0.00002286",
"future_session_upl": "-0.00000333",
"future_session_funding": "-0.00002286",
"future_delta":"0.00521057",
"created_at": 1588218506000,
"projected_info": {
"projected_initial_margin": "0.97919888",
"projected_maintenance_margin": "0.78335911",
"projected_total_delta": "3.89635553"
}
}
}
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
Response
Name | Type | Desc |
---|---|---|
account_id | string | Account ID |
mode | string | Risk mode |
available_balance | string | Available balance |
cash_balance | string | Cash balance |
currency | string | Currency |
equity | string | Account equity |
initial_margin | string | Account initial margin |
maintenance_margin | string | Account maintenance margin |
margin_balance | string | Account margin balance |
pnl | string | Account P&L |
total_delta | string | Total delta of account |
session_rpl | string | Session realized pnl |
session_upl | string | Session unrealized pnl |
option_value | string | Option market value |
option_pnl | string | Option P&L |
option_session_rpl | string | Option session realized P&L |
option_session_upl | string | Option session unrealized P&L |
option_delta | string | Option delta |
option_gamma | string | Option gamma |
option_vega | string | Option vega |
option_theta | string | Option theta |
future_pnl | string | Future P&L |
future_session_rpl | string | Future session realized P&L |
future_session_upl | string | Future session unrealized P&L |
future_session_funding | string | Future session funding |
future_delta | string | Future delta |
user_id | string | User ID |
created_at | integer | Account create timestamp |
projected_info | object | Projected Info |
ProjectedInfo
Projected information(IM/MM/Delta) is the predicted value after the settlement of current trading session.
Name | Type | Desc |
---|---|---|
projected_initial_margin | string | Projected IM |
projected_maintenance_margin | string | Projected MM |
projected_total_delta | string | Projected Delta |
Get user transaction logs
GET /v1/transactions
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/transactions?currency=BTC&start_time=1585270800000&end_time=1589522084000&type=trade&offset=1&limit=10×tamp=1589522094430&signature=50b8d98d358253a1f12bc4d75c1ff77f4c0fe6cde8d00251a144c2f699d26b8a"
Response
{
"code": 0,
"message": "",
"data": [
{
"transaction_time": 1589521370683,
"instrument_id": "BTC-22MAY20-7500-C",
"transaction_type": "trade",
"direction": "open-buy",
"qty": "2.00000000",
"price": "0.17550000",
"cash_flow": "-0.35100000",
"funding": "--",
"fee_paid": "0.00100000",
"fee_rate": "0.00050000",
"change": "-0.35200000",
"balance": "99.59591877",
"position": "3.00000000",
"trade_id": "23210268",
"order_id": "17551020",
"remark": ""
}
]
}
Query Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
instrument_id | string | false | "" | Instrument ID |
start_time | integer | false | 0 | Start timestamp |
end_time | integer | false | 0 | End timestamp |
type | string | false | "" | Transaction type |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
transaction_time | integer | Transaction timestamp |
instrument_id | string | Instrument ID |
transaction_type | string | Transaction type |
direction | string | Trade:open buy/open sell/close buy/close sell/liquidation buy/liquidation sell delivery:close buy/close sell settlement:long/short |
qty | string | Quantity |
price | string | Type=trade: filled price (BTC for option, USD for future) Type=delivery: Price is delivery unit pnl Type=settlement: Price is mark price of 8:00 UTC |
cash_flow | string | Cashflow |
funding | string | type = trade/settlement |
fee_paid | string | Fee paid |
fee_rate | string | Fee rate |
change | string | Change of account |
balance | string | Balance after change |
position | string | Position after transaction |
order_id | string | Corresponding order ID |
trade_id | string | Corresponding trade ID |
remark | string |
Get UM user accounts
GET /um/v1/accounts
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/um/v1/accounts?timestamp=1589521383462&signature=30f7cf5c8018f5dfee515533e25a1813e9120be7898b62fb85a2f4129f3e9528"
Response
{
"code": 0,
"message": "",
"data": {
"user_id": 481554,
"created_at": 1649923879505,
"total_collateral": "3170125.05978108",
"total_margin_balance": "3170125.05978108",
"total_available": "3169721.64891398",
"total_initial_margin": "403.41086710",
"total_maintenance_margin": "303.16627631",
"total_initial_margin_ratio": "0.00012725",
"total_maintenance_margin_ratio": "0.00009563",
"total_liability": "0.00000000",
"total_unsettled_amount": "-0.84400340",
"spot_orders_hc_loss": "0.00000000",
"details": [
{
"currency": "BTC",
"equity": "78.13359310",
"liability": "0.00000000",
"index_price": "41311.20615385",
"cash_balance": "78.13360190",
"margin_balance": "78.13359310",
"available_balance": "78.12382795",
"initial_margin": "0.00976516",
"spot_margin": "0.00000000",
"maintenance_margin": "0.00733859",
"potential_liability": "0.00000000",
"interest": "0.00000000",
"interest_rate": "0.07000000",
"pnl": "0.02966586",
"total_delta": "0.48532539",
"session_rpl": "0.00001552",
"session_upl": "-0.00003595",
"option_value": "0.00000000",
"option_pnl": "0.00000000",
"option_session_rpl": "0.00000000",
"option_session_upl": "0.00000000",
"option_delta": "0.00000000",
"option_gamma": "0.00000000",
"option_vega": "0.00000000",
"option_theta": "0.00000000",
"future_pnl": "0.02966586",
"future_session_rpl": "0.00001552",
"future_session_upl": "-0.00003595",
"future_session_funding": "0.00001552",
"future_delta": "0.48532539",
"future_available_balance": "76.72788921",
"option_available_balance": "76.72788921",
"unsettled_amount": "-0.00002043",
"usdt_index_price": "41311.20615385"
},
{
"currency": "ETH",
"equity": "1.99960000",
"liability": "0.00000000",
"index_price": "3119.01923077",
"cash_balance": "1.99960000",
"margin_balance": "1.99960000",
"available_balance": "1.99960000",
"initial_margin": "0.00000000",
"spot_margin": "0.00000000",
"maintenance_margin": "0.00000000",
"potential_liability": "0.00000000",
"interest": "0.00000000",
"interest_rate": "0.07000000",
"pnl": "0.00000000",
"total_delta": "0.00000000",
"session_rpl": "0.00000000",
"session_upl": "0.00000000",
"option_value": "0.00000000",
"option_pnl": "0.00000000",
"option_session_rpl": "0.00000000",
"option_session_upl": "0.00000000",
"option_delta": "0.00000000",
"option_gamma": "0.00000000",
"option_vega": "0.00000000",
"option_theta": "0.00000000",
"future_pnl": "0.00000000",
"future_session_rpl": "0.00000000",
"future_session_upl": "0.00000000",
"future_session_funding": "0.00000000",
"future_delta": "0.00000000",
"future_available_balance": "1.99960000",
"option_available_balance": "1.99960000",
"unsettled_amount": "0.00000000",
"usdt_index_price": "3119.01923077"
}
],
"usdt_total_collateral": "3170125.05978108",
"usdt_total_margin_balance": "3170125.05978108",
"usdt_total_available": "3169721.64891398",
"usdt_total_initial_margin": "403.41086710",
"usdt_total_maintenance_margin": "303.16627631",
"usdt_total_initial_margin_ratio": "0.00012725",
"usdt_total_maintenance_margin_ratio": "0.00009563",
"usdt_total_liability": "0.00000000",
"usdt_total_unsettled_amount": "-0.84400340"
}
}
USD-M/USDT-M Futures can only be traded by UM mode users.
um mode,get account information with this endpoint.
total_initial_margin_ratio
PM | total_initial_margin_ratio calculation formula |
---|---|
true | (total_im + spot_haircut_loss) / collateral |
false | (total_im + spot_haircut_loss) / margin_balance |
In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation
total_maintenance_margin_ratio
PM | total_maintenance_margin_ratio calculation formula |
---|---|
true | total_maintenance_margin / collateral |
false | total_maintenance_margin / margin_balance |
In above formula,
1) if numerator and denominator are zero, output is zero.
2) otherwise if denominator <= 0, output is "infinity".
3) return normal calculation
Query parameters
None
Response
Name | Type | Desc |
---|---|---|
user_id | int | User Id |
created_at | int | Timestamp (query time) |
total_collateral | string | Total Collateral (USD) |
total_margin_balance | string | Total Margin Balance (USD) |
total_available | string | Total Available (USD) |
total_initial_margin | string | Total Initial Margin (USD) |
total_maintenance_margin | string | Total Maintenance Margin (USD) |
total_initial_margin_ratio | string | Total Initial Margin Ratio, may returns "infinity" (USD) |
total_maintenance_margin_ratio | string | Total Maintenance Margin Ratio, may returns "infinity" (USD) |
total_liability | string | Total liability (USD) |
total_unsettled_amount | string | Total unsettled amount (USD) |
spot_orders_hc_loss | string | Total spot order haircut loss |
details | array | Details, array of currency level detail |
usdt_total_collateral | string | (For compatibility) equal to total_collateral |
usdt_total_margin_balance | string | (For compatibility) equal to total_margin_balance |
usdt_total_available | string | (For compatibility) equal to total_available |
usdt_total_initial_margin | string | (For compatibility) equal to total_initial_margin |
usdt_total_maintenance_margin | string | (For compatibility) equal to total_maintenance_margin |
usdt_total_initial_margin_ratio | string | (For compatibility) equal to total_initial_margin_ratio |
usdt_total_maintenance_margin_ratio | string | (For compatibility) equal to total_maintenance_margin_ratio |
usdt_total_liability | string | (For compatibility) equal to total_liability |
usdt_total_unsettled_amount | string | (For compatibility) equal to total_unsettled_amount |
- Currency level detail
Name | Type | Desc |
---|---|---|
currency | string | Currency |
equity | string | Equity |
liability | string | Liability |
index_price | string | Index price (USD) |
usdt_index_price | string | (For compatibility) equal to index_price |
cash_balance | string | Cash Balance |
margin_balance | string | Margin Balance |
available_balance | string | Account Available Balance |
initial_margin | string | Initial Margin |
spot_margin | string | Spot Margin |
maintenance_margin | string | Maintenance Margin |
potential_liability | string | Potential Liability |
interest | string | Interest |
interest_rate | string | Interest Rate |
pnl | string | Account P&L |
total_delta | string | Total delta of account |
session_rpl | string | Session realized pnl |
session_upl | string | Session unrealized pnl |
option_value | string | Option market value |
option_pnl | string | Option P&L |
option_session_rpl | string | Option session realized P&L |
option_session_upl | string | Option session unrealized P&L |
option_delta | string | Option delta |
option_gamma | string | Option gamma |
option_vega | string | Option vega |
option_theta | string | Option theta |
future_pnl | string | Future P&L |
future_session_rpl | string | Future session realized P&L |
future_session_upl | string | Future session unrealized P&L |
future_session_funding | string | Future session funding |
future_delta | string | Future delta |
future_available_balance | string | Available balance for new futures order |
option_available_balance | string | Available balance for new option order |
unsettled_amount | string | Unsettled amount |
Get UM user transactions
GET /um/v1/transactions
curl -H "X-Bit-Access-Key: ak-8e97ac6c-8075-4a94-b2bb-38bd537619fa" "https://betaapi.bitexch.dev/um/v1/transactions?currency=BTC&type=trade-recv&limit=2×tamp=1620369292928&signature=35d76033f6e251ce85524ec4310417fd555953fff00cd33f3a94e3d27d062965"
Response
{
"code": 0,
"message": "",
"data": [
{
"tx_time": 1631240595162,
"tx_type": "deposit",
"ccy": "BTC",
"instrument_id": "",
"direction": "",
"qty": "3.20000000",
"price": "",
"position": "",
"fee_paid": "0.00000000",
"fee_rate": "",
"funding": "",
"change": "3.20000000",
"balance": "107.00000000",
"order_id": "",
"trade_id": "",
"remark": ""
},
{
"tx_time": 1630722195162,
"tx_type": "spot-trade-recv",
"ccy": "BTC",
"instrument_id": "BTC-USDT",
"direction": "buy",
"qty": "2.00000000",
"price": "60000.00000000",
"position": "",
"fee_paid": "0.00030000",
"fee_rate": "0.00000000",
"funding": "",
"change": "2.00000000",
"balance": "102.00000000",
"order_id": "9001",
"trade_id": "3001",
"remark": ""
}
],
"page_info": {
"has_more": false
}
}
Get UM user transaction logs.
Query Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | false | "" | Currency |
instrument_id | string | false | "" | Instrument ID |
start_time | integer | false | One month ago | Start timestamp millisecond |
end_time | integer | false | Now | End timestamp millisecond |
type | string | false | "" | Transaction type |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
tx_time | integer | Transaction time |
tx_type | string | Transaction type |
ccy | string | Currency |
instrument_id | string | Instrument Id |
direction | string | buy/sell |
qty | string | Qty |
price | string | Trade price (for trade transactions) |
position | string | Futures/Options position |
fee_paid | string | Fee paid |
fee_rate | string | Fee rate |
funding | string | Perpetual funding |
change | string | Change |
cash_flow | string | Cashflow(spot cash_flow=change, derivatives cash_flow please refer to derivatives doc for transactions) |
balance | string | Balance after change |
order_id | string | Order ID |
trade_id | string | Trade ID |
remark | string | Remark |
Get user positions
GET /v1/positions
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/positions?currency=BTC&category=option&instrument_id=BTC-22MAY20-7500-C&offset=1&limit=10×tamp=1589521619990&signature=9a7f7704cb4d6ec3cd2dccbd55e09ce8abd1ffb48529a742337706dd1a43eea8"
Response
{
"code": 0,
"message": "",
"data": [{
"instrument_id": "BTC-22MAY20-7500-C",
"qty": "-2.00000000",
"initial_margin": "0.00000000",
"maintenance_margin": "0.00000000",
"avg_price": "0.17550000",
"session_avg_price": "0.17550000",
"mark_price": "0.21738391",
"index_price": "9496.73000000",
"session_funding": "0.00000000",
"position_pnl": "0.08376782",
"position_session_upl": "0.08376782",
"position_session_rpl": "0.00000000",
"category": "option",
"roi": "0.00000000",
"option_delta": "1.84693852",
"option_gamma": "0.00017124",
"option_vega": "3.80882409",
"option_theta": "-34.02850739",
"liq_price": "0.00000000",
"leverage:": "50.00000000",
}]
}
Get user positions.
qty
and qty_base
has direction information, positive value means long, negative value means short.
Query Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
instrument_id | string | false | "" | Instrument ID |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
instrument_id | string | Instrument ID |
qty | string | Signed position size (for option, qty in BTC, for future, qty in USD) |
qty_base | string | Signed position size in base currency (Future only) |
avg_price | string | Average filled price |
index_price | string | Index price |
mark_price | string | Mark price |
initial_margin | string | Initial margin |
maintenance_margin | string | Maintenance margin |
session_avg_price | string | Session average price |
session_funding | string | Session funding |
position_pnl | string | Position P&L |
position_session_upl | string | Position session unrealized P&L |
position_session_rpl | string | Position session realized P&L |
category | string | Category |
roi | string | Return on investment |
option_delta | string | Option delta |
option_gamma | string | Option gamma |
option_vega | string | Option vega |
option_theta | string | Option theta |
liq_price | string | Estimated liquidation price (Future only) |
leverage | string | Position leverage (Future only) |
Get user deliveries
GET /v1/user/deliveries
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/user/deliveries?currency=BTC&category=option&instrument_id=BTC-3MAY20-8625-C&start_time=1585270800000&end_time=1589522084000&offset=1&limit=10×tamp=1589531240715&signature=1f060cafdcab4466ef3c79363ecea6710ec1966419a35b78f20d75329fed4a7b"
Response
{
"code": 0,
"message": "",
"data": [{
"type": "delivery",
"timestamp": 1588492890000,
"instrument_id": "BTC-3MAY20-8625-C",
"position": "1.00000000",
"exercise": true,
"delivery_price": "8994.37000000",
"delivery_pnl": "0.04106680"
}]
}
Get user delivery records
Query Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
instrument_id | string | false | "" | Instrument ID |
start_time | integer | false | 0 | Start timestamp |
end_time | integer | false | 0 | End timestamp |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
type | string | Settlement type (delivery) |
instrument_id | string | Instrument ID |
position | string | Settled position |
timestamp | integer | Delivery timestamp |
exercise | boolean | Exercised or not |
delivery_price | string | Delivery price |
delivery_pnl | string | Delivery P&L |
Get user settlements
GET /v1/user/settlements
curl -H "X-Bit-Access-Key: ak-c1d4bc58-37f3-49da-93b5-396ab44b1543" "https://betaapi.bitexch.dev/v1/user/settlements?currency=BTC&offset=1&limit=10×tamp=1590851451072&signature=538b4ed2b917db4c96e12ddb5daafe84b58f566173f4d003533c19ccc32ff177"
Response
{
"code": 0,
"message": "",
"data": [{
"type": "settlement",
"timestamp": 1590825600000,
"instrument_id": "BTC-PERPETUAL",
"position": "-280750.00000000",
"direction": "short",
"session_upl": "-0.02754390",
"session_rpl": "0.00125935",
"session_funding": "-0.00028997",
"price": "32000"
}]
}
Get user settlements (only for future currently)
Query Parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
instrument_id | string | false | "" | Instrument ID |
start_time | integer | false | 0 | Start timestamp |
end_time | integer | false | 0 | End timestamp |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
type | string | Settlement type (settlement) |
timestamp | integer | Timestamp |
instrument_id | string | Instrument |
position | string | settled Position |
direction | string | Position direction |
session_upl | string | Session unrealized pnl |
session_rpl | string | Session realized pnl |
session_funding | string | Future session funding |
price | string | Settlement price |
Enable or disable Cancel On Disconnect
POST /v1/account_configs/cod
curl -X POST "https://betaapi.bitexch.dev/v1/account_configs/cod" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" -d '{"cod":true, "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}'
Response
{
"code": 0,
"message": "",
"data": {
}
}
Enable or disable Cancel On Disconnect. If Cancel On Disconnect is enabled, all orders of the account(web AND API) will be cancelled when all ‘private' websocket connections are disconnected.
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
cod | bool | true | "" | Whether to enable Cancel On Disconnect |
Response
None
Get Cancel On Disconnect configuration
GET /v1/account_configs/cod
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/account_configs/cod?timestamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807"
Response
{
"code": 0,
"message": "",
"data": {
"cod": true
}
}
Get Cancel On Disconnect configuration of the account
Query parameters
None
Response
Name | Type | Desc |
---|---|---|
cod | bool | Whether to enable Cancel On Disconnect |
Get Mmp State
GET /v1/mmp_state
curl -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" "https://betaapi.bitexch.dev/v1/mmp_state?currency=BTC×tamp=1600050649936&signature=3a3c511ab776674c4a8db31135f22c8bf2bc5aac4eb0070c8c4d577e89e01643"
Response
{
"code": 0,
"message": "",
"data": {
"currency": "BTC",
"mmp_enabled": true,
"mmp_user_configurable": false,
"mmp_config": {
"window_ms": 20000,
"frozen_period_ms": 30000,
"qty_limit": "1000.00000000",
"delta_limit": "1000.00000000"
},
"mmp_frozen_until_ms": -1,
"mmp_frozen":false
}
}
Get Mmp State.
mmp_enabled
Mmp is enabled or not.
mmp_user_configurable
User can edit mmp config or not. if yes, user can change mmp config through POST /v1/update_mmp_config
mmp_config
Mmp configuration detail.
mmp_frozen_until_ms
mmp_frozen_until_ms indicate mmp frozen status, it's updated by backend.
mmp_frozen_until_ms > 0: frozen until this timestamp or a manual reset
mmp_frozen_until_ms = 0: frozen until a manual reset
mmp_frozen_until_ms = -1: not frozen (a manual reset sets mmp_frozen_until_ms to -1)
mmp_frozen
Indicate mmp is frozen or not.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
Response
Name | Type | Desc |
---|---|---|
currency | string | Currency |
mmp_enabled | bool | Mmp is enabled or not |
mmp_user_configurable | bool | User can edit mmp config or not |
mmp_config | object | Mmp config detail (see below) |
mmp_frozen_until_ms | integer | Mmp frozen until timestamp (backend update automatically) |
mmp_frozen | bool | Mmp is frozen or not |
- Mmp Config
Name | Type | Desc |
---|---|---|
window_ms | integer | Mmp rolling windows time span (milliseconds) |
frozen_period_ms | integer | Mmp frozen time span (milliseconds) |
qty_limit | string | Mmp quantity limit (in base currency, e.g. BTC) |
delta_limit | string | Mmp delta limit (in base currency, e.g. BTC) |
Update Mmp Config
POST /v1/update_mmp_config
curl -X POST "https://betaapi.bitexch.dev/v1/update_mmp_config" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" -d '{"currency": "BTC", "window_ms": 20000, "frozen_period_ms": 30000, "qty_limit": "1000.00000000", "delta_limit": "1000.00000000", "timestamp": 1600050944127, "signature": "661b535fa878633718922fd90b419de4b5d9ae447833876b91bc8bcc7906e0f3"}'
Response
{
"code": 0,
"message": "",
"data": "ok"
}
Update mmp config, only when mmp.user_configurable = true, otherwise returns error.
Mmp frozen state will be triggered when qty >= qty_limit
OR abs(delta) >= delta_limit
.
window_ms
: Mmp rolling windows time span (milliseconds)
frozen_period_ms
: Mmp frozen time span (milliseconds)
qty_limit
: Mmp quantity limit (in base currency, e.g. BTC)
delta_limit
: Mmp delta limit (in base currency, e.g. BTC)
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
window_ms | integer | true | 0 | Mmp rolling windows time span (milliseconds) |
frozen_period_ms | integer | true | 0 | Mmp frozen time span (milliseconds) |
qty_limit | string | true | "" | Mmp quantity limit (in base currency, e.g. BTC) |
delta_limit | string | true | "" | Mmp delta limit (in base currency, e.g. BTC) |
Response
Name | Type | Desc |
---|---|---|
data | string | ok |
Reset Mmp State
POST /v1/reset_mmp
curl -X POST "https://betaapi.bitexch.dev/v1/reset_mmp" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" -d '{"currency": "BTC", "timestamp": 1600050689085, "signature": "992507afc30728c2bc55d7bf7f47e76126ce3f40ddebc205594877381c4374fa"}'
Response
{
"code": 0,
"message": "",
"data": "ok"
}
Reset mmp frozen state, then user is able to place new order.
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
Response
Name | Type | Desc |
---|---|---|
data | string | ok |
Order
Place new order
POST /v1/orders
curl -X POST "https://betaapi.bitexch.dev/v1/orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" -d '{"instrument_id": "BTC-29MAY20-8000-C", "price": "0.08", "qty": "3", "side": "buy", "time_in_force": "gtc", "auto_price": "", "label":"hedge", "hidden": false, "timestamp": 1589523989378, "signature": "68b658eb68f4ce529623bb4505f5c1c6408b37064a9a5f2102d08088e59d917c"}'
Response
{
"code": 0,
"message": "",
"data": {
"order_id": "17552314",
"created_at": 1589523803017,
"updated_at": 1589523803017,
"user_id": "51140",
"instrument_id": "BTC-29MAY20-8000-C",
"order_type": "limit",
"side": "buy",
"price": "0.08000000",
"qty": "3.00000000",
"time_in_force": "gtc",
"avg_price": "0.00000000",
"filled_qty": "0.00000000",
"status": "open",
"is_liquidation": false,
"auto_price": "0.00000000",
"auto_price_type": "",
"taker_fee_rate": "0.00050000",
"maker_fee_rate": "0.00020000",
"label":"hedge",
"stop_price": "0.00000000",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp":false,
"source": "api",
"hidden": false
}
}
Place new order.
For market order, price is not required.
Order type default value is 'limit'.
Time in force default value is 'gtc'.
Order size unit: USD for Futures, COIN(e.g. BTC) for options
Enhanced Stop order:
* Order type should be stop-market
/stop-limit
/trigger-market
/trigger-limit
.
* stop_price
is the target trigger price. price
is the order price after triggered
* Support triggered by last-price
now.
Auto price type:
usd: When place order, set [auto price type] = "usd", and [auto price] = usd value, order price will be automatically calculated as order_price = auto_price / underlying_price, and order will be automatically requoted every 6s to maintain the usd price
implv: When place order, set [auto price type] = "implv", and [auto price] = implied volatility value, order price will be automatically calculated as order_price = convert_iv_to_usd(auto_price) / underlying_price, , and order will be automatically requoted every 6s to maintain the implied volatility. Example: input 85.56 for 85.56% implied volatility
mmp order:Indicate that this order is mmp-enabled (Market Maker Protection).
bbo order:When bbo
is true, auto set limit price (ask0 for buy order, bid0 for sell order), if orderbook is not available, set limit price to mark price. (Batch order not supported)
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID |
qty | string | true | "" | Order size (positive number) |
side | string | true | "" | Order side |
price | string | false | "0.0" | Order price, not required for market order |
order_type | string | false | "limit" | Order type |
time_in_force | string | false | "gtc" | Time in force |
auto_price_type | string | false | "" | Auto price type |
auto_price | string | false | "" | Auto price, only if auto price type in ('usd','implv') *implv is in percentage, ie. input 85.56 for 85.56% |
stop_price | string | false | "" | Stop price |
label | string | false | "" | User defined label |
post_only | bool | false | false | Indicate post only or not. if reject_post_only is true, order can not enter book will be cancelled. if reject_post_only is false, price will be changed when order can't enter orderbook. |
reject_post_only | bool | false | false | Indicate reject post only or not |
bbo | bool | false | false | Indicate bbo order or not |
mmp | bool | false | false | Indicate mmp order or not |
hidden | bool | false | false | Indicate hidden order or not |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
instrument_id | string | Instrument ID |
order_type | string | Order type |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
time_in_force | string | Time in force |
avg_price | string | Average filled price |
filled_qty | string | Filled qty |
status | string | Order status |
is_liquidation | boolean | Liquidation order |
auto_price | string | Auto price |
auto_price_type | string | Auto price type |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
stop_price | string | Stop price (stop order only) |
reduce_only | bool | Indicate reduce only or not |
post_only | bool | Indicate post only or not |
reject_post_only | bool | Indicate reject post only or not |
mmp | bool | Indicate mmp order or not |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
Place batch orders
POST /v1/batchorders
curl -X POST "https://betaapi.bitexch.dev/v1/batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" -d '{"currency": "BTC", "orders_data": [{"instrument_id": "BTC-25SEP20-8000-C-XX", "price": "0.15", "qty": "51", "side": "buy", "hidden": true}, {"instrument_id": "BTC-PERPETUAL", "price": "12000", "qty": "100", "side": "sell"}], "timestamp": 1596782252388, "signature": "0b8b64d2f35f9742a17af4ee0b993d0248a27a98f320abbfe8e7316f184e30d5"}'
Response
{
"code": 0,
"message": "",
"data": {
"Orders": [
{
"order_id": "",
"created_at": 0,
"updated_at": 0,
"user_id": "",
"instrument_id": "",
"order_type": "",
"side": "",
"price": "",
"qty": "",
"time_in_force": "",
"avg_price": "",
"filled_qty": "",
"status": "",
"is_liquidation": false,
"auto_price": "",
"auto_price_type": "",
"taker_fee_rate": "",
"maker_fee_rate": "",
"label": "",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"source": "api",
"hidden": true,
"error_code": 18100185,
"error_msg": "Invalid instrument BTC-25SEP20-8000-C-XX"
},
{
"order_id": "501758",
"created_at": 1596782252996,
"updated_at": 1596782252996,
"user_id": "51140",
"instrument_id": "BTC-PERPETUAL",
"order_type": "limit",
"side": "sell",
"price": "12000.00000000",
"qty": "100.00000000",
"time_in_force": "gtc",
"avg_price": "0.00000000",
"filled_qty": "0.00000000",
"status": "open",
"is_liquidation": false,
"auto_price": "0.00000000",
"auto_price_type": "",
"taker_fee_rate": "0.00045000",
"maker_fee_rate": "0.00025000",
"label": "",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"source": "api",
"hidden": false,
"error_code": 0,
"error_msg": ""
}
]
}
}
Place batch order.
Provide order array, order parameter details are the same as POST /v1/orders.
stop order
is not supported.
Max order request count is 10
.
User input orders_data
array
If resp['code'] != 0, means all request items are failed
If resp['code'] == 0, user will get result array resp['data']['Orders']
, which
* size(resp['data']['Orders']
) == size(orders_data
)
* resp['data']['Orders']
[i] is corresponding to orders_data[i]
* To get request result of orders_data[i], check resp['data']['Orders']
[i].error_code (0 = success otherwise failure)
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
orders_data | array | true | Order request list(see below) |
- order request detail
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID |
qty | string | true | "" | Order size (positive number) |
side | string | true | "" | Order side |
price | string | false | "0.0" | Order price, not required for market order |
order_type | string | false | "limit" | Order type Notes: stop order not supported |
time_in_force | string | false | "gtc" | Time in force |
auto_price_type | string | false | "" | Auto price type |
auto_price | string | false | "" | Auto price, only if auto price type in ('usd','implv') *implv is in percentage, ie. input 85.56 for 85.56% |
label | string | false | "" | User defined label |
post_only | bool | false | false | Indicate post only or not |
reject_post_only | bool | false | false | Indicate reject post only or not |
mmp | bool | false | false | Indicate mmp order or not |
hidden | bool | false | false | Indicate hidden order or not |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
instrument_id | string | Instrument ID |
order_type | string | Order type |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
time_in_force | string | Time in force |
avg_price | string | Average filled price |
filled_qty | string | Filled qty |
status | string | Order status |
is_liquidation | boolean | Liquidation order |
auto_price | string | Auto price |
auto_price_type | string | Auto price type |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
reduce_only | bool | Indicate reduce only or not |
post_only | bool | Indicate post only or not |
reject_post_only | bool | Indicate reject post only or not |
mmp | bool | Indicate mmp order or not |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
error_code | int | New order result code: 0 = no error |
error_msg | string | New order error message |
Cancel orders
POST /v1/cancel_orders
curl -X POST "https://betaapi.bitexch.dev/v1/cancel_orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" -d '{"currency": "BTC", "order_id": "44092860", "timestamp": 1590572422557, "signature": "3c8c2271a58e3d11dfbd262a6be40ebdd07e8f394a002db0065068b36bc66d5a"}'
Response
{
"code": 0,
"message": "",
"data": {
"num_cancelled": 1
}
}
Cancel order.
Currency is required parameter.
To cancel single order, only need to provide order_id parameter.
Batch cancel filters include: order_id_list, label, instrument_id, category, currency.
Batch cancel filter priorities: order_id_list > label > instrument_id > category > currency
To cancel stop order
, provide stop order id only. stop order
can not be cancelled in batch.
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
order_id | string | false | "" | Order ID |
order_id_list | string | false | "" | Order id list in csv format, e.g: 1,2,3 |
category | string | false | "" | Category |
instrument_id | string | false | "" | Instrument ID |
label | string | false | "" | Order label |
Response
Name | Type | Desc |
---|---|---|
num_cancelled | integer | number of order cancelled |
Amend orders
POST /v1/amend_orders
curl -X POST "https://betaapi.bitexch.dev/v1/amend_orders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" -d '{"currency": "BTC", "order_id": "1206764", "price": "9450", "timestamp": 1590760362688, "signature": "a74dda0f2bdaf1e1587a5e7577a281497cb66607166bd3b7e0cc4c805c750bf1"}'
Response
{
"code": 0,
"message": "",
"data": {
"order_id": "1206764",
"created_at": 1590760363846,
"updated_at": 1590760363846,
"user_id": "51140",
"instrument_id": "BTC-PERPETUAL",
"order_type": "limit",
"side": "buy",
"price": "9450.00000000",
"qty": "260.00000000",
"time_in_force": "gtc",
"avg_price": "9435.67307692",
"filled_qty": "260.00000000",
"status": "filled",
"is_liquidation": false,
"auto_price": "0.00000000",
"auto_price_type": "",
"taker_fee_rate": "0.00050000",
"maker_fee_rate": "-0.00020000",
"label": "hedge",
"stop_price": "0.00000000",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"source": "api",
"hidden": false,
}
}
Amend order.
Order id is required.
Need to provide at least one of: price,qty,auto_price.
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
order_id | string | true | "" | Order ID |
price | string | false | "" | New price of the order |
auto_price | string | false | "" | New auto price of the order (for usd/implv order) |
qty | string | false | "" | New quantity of the order |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
instrument_id | string | Instrument ID |
order_type | string | Order type |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
time_in_force | string | Time in force |
avg_price | string | Average filled price |
filled_qty | string | Filled qty |
status | string | Order status |
is_liquidation | boolean | Liquidation order |
auto_price | string | Auto price |
auto_price_type | string | Auto price type |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
stop_price | string | Stop price (stop order only) |
reduce_only | bool | Indicate reduce only or not |
post_only | bool | Indicate post only or not |
reject_post_only | bool | Indicate reject post only or not |
mmp | bool | Indicate mmp order or not |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
Amend batch orders
POST /v1/amend_batchorders
curl -X POST "https://betaapi.bitexch.dev/v1/amend_batchorders" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-96cc0cbd-c501-448f-a32d-21228bc9648f" -d '{"currency": "BTC", "orders_data": [{"order_id": "572083", "price": "14000", "qty": "3000"}, {"order_id": "invalid-order-id", "price": "15000", "qty": "1000"}, {"order_id": "615775", "price": "0.12", "qty": "3.7"}], "timestamp": 1597313835731, "signature": "c8b5fddd5f2cfa1517854dc54c51e7c3b79af91f0927ea1389ba43dbeee45652"}'
Response
{
"code": 0,
"message": "",
"data": {
"Orders": [
{
"order_id": "572083",
"created_at": 1597313836214,
"updated_at": 1597313836214,
"user_id": "51140",
"instrument_id": "BTC-PERPETUAL",
"order_type": "limit",
"side": "sell",
"price": "14000.00000000",
"qty": "3000.00000000",
"time_in_force": "gtc",
"avg_price": "0.00000000",
"filled_qty": "0.00000000",
"status": "open",
"is_liquidation": false,
"auto_price": "0.00000000",
"auto_price_type": "",
"taker_fee_rate": "0.00045000",
"maker_fee_rate": "0.00025000",
"label": "",
"reduce_only": false,
"post_only": true,
"reject_post_only": false,
"mmp": false,
"source": "api",
"hidden": true,
"error_code": 0,
"error_msg": ""
},
{
"order_id": "",
"created_at": 0,
"updated_at": 0,
"user_id": "",
"instrument_id": "",
"order_type": "",
"side": "",
"price": "",
"qty": "",
"time_in_force": "",
"avg_price": "",
"filled_qty": "",
"status": "",
"is_liquidation": false,
"auto_price": "",
"auto_price_type": "",
"taker_fee_rate": "",
"maker_fee_rate": "",
"label": "",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"source": "api",
"hidden": false,
"error_code": 18100113,
"error_msg": "order id is invalid : invalid-order-id"
},
{
"order_id": "615775",
"created_at": 1597313836214,
"updated_at": 1597313836214,
"user_id": "51140",
"instrument_id": "BTC-25SEP20-9000-C",
"order_type": "limit",
"side": "buy",
"price": "0.12000000",
"qty": "3.70000000",
"time_in_force": "gtc",
"avg_price": "0.00000000",
"filled_qty": "0.00000000",
"status": "open",
"is_liquidation": false,
"auto_price": "90.00000000",
"auto_price_type": "usd",
"taker_fee_rate": "0.00040000",
"maker_fee_rate": "0.00030000",
"label": "aaaa",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"source": "api",
"hidden": false,
"error_code": 0,
"error_msg": ""
}
]
}
}
Amend order in batch.
For each amend request:
Order id is required.
Need to provide at least one of: price,qty,auto_price.
Max amend request count is 10
.
User input orders_data
array
If resp['code'] != 0, means all request items are failed
If resp['code'] == 0, user will get result array resp['data']['Orders']
, which
* size(resp['data']['Orders']
) == size(orders_data
)
* resp['data']['Orders']
[i] is corresponding to orders_data[i]
* To get request result of orders_data[i], check resp['data']['Orders']
[i].error_code (0 = success otherwise failure)
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
orders_data | array | true | Amend request list(see below) |
- order request detail
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
order_id | string | true | "" | Order ID |
price | string | false | "" | New price of the order |
auto_price | string | false | "" | New auto price of the order (for usd/implv order) |
qty | string | false | "" | New quantity of the order |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
instrument_id | string | Instrument ID |
order_type | string | Order type |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
time_in_force | string | Time in force |
avg_price | string | Average filled price |
filled_qty | string | Filled qty |
status | string | Order status |
is_liquidation | boolean | Liquidation order |
auto_price | string | Auto price |
auto_price_type | string | Auto price type |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
reduce_only | bool | Indicate reduce only or not |
post_only | bool | Indicate post only or not |
reject_post_only | bool | Indicate reject post only or not |
mmp | bool | Indicate mmp order or not |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
error_code | int | Edited order result code: 0 = no error |
error_msg | string | Edited order error message |
Close positions
POST /v1/close_positions
curl -X POST "https://betaapi.bitexch.dev/v1/close_positions" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" -d '{"instrument_id": "BTC-PERPETUAL", "price": "9500", "order_type": "limit", "timestamp": 1589524756236, "signature": "5bf4f9f00722d133336e736196c09a8e02c634dc0deacf2cf12413049d8d8b06"}'
Response
{
"code": 0,
"message": "",
"data": {
"order_id": "17553311",
"created_at": 1589524757818,
"updated_at": 1589524757818,
"user_id": "51140",
"instrument_id": "BTC-PERPETUAL",
"order_type": "limit",
"side": "sell",
"price": "9500.00000000",
"qty": "50.00000000",
"time_in_force": "gtc",
"avg_price": "9522.50000000",
"filled_qty": "50.00000000",
"status": "filled",
"is_liquidation": false,
"auto_price": "0.00000000",
"auto_price_type": "",
"taker_fee_rate": "0.00050000",
"maker_fee_rate": "0.00020000",
"label": "hedge",
"stop_price": "0.00000000",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"source": "api",
"hidden": false,
}
}
Close position by instrument_id, send out order with input instrument_id, order_type, price,
order size is abs(open_position), direction is opposite of open_position side
If user don't want to specify price
, input order_type
= 'market'
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID of closing order |
order_type | string | false | "limit" | Order type of closing order, default is limit (GTC) Order type |
price | string | false | "" | Price of closing order |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
instrument_id | string | Instrument ID |
order_type | string | Order type |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
time_in_force | string | Time in force |
avg_price | string | Average filled price |
filled_qty | string | Filled quantity |
status | string | Order status |
is_liquidation | boolean | Liquidation order |
auto_price | string | Auto price |
auto_price_type | string | Auto price type |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
stop_price | string | Stop price (stop order only) |
reduce_only | bool | Indicate reduce only or not |
post_only | bool | Indicate post only or not |
reject_post_only | bool | Indicate reject post only or not |
mmp | bool | Indicate mmp order or not |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
Get open orders
GET /v1/open_orders
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/open_orders?currency=BTC&category=option&instrument_id=BTC-29MAY20-7500-C×tamp=1589522687689&signature=89d5a1d929e7baa247021e090f9f634f02a7fc6c82a44c8de3bb04fa6b005a7b"
Response
{
"code": 0,
"message": "",
"data": [{
"order_id": "7610691",
"created_at": 1589183001000,
"updated_at": 1589183001000,
"user_id": "51140",
"instrument_id": "BTC-29MAY20-7500-C",
"order_type": "limit",
"side": "buy",
"price": "0.08000000",
"qty": "3.00000000",
"time_in_force": "gtc",
"avg_price": "0.00000000",
"filled_qty": "0.00000000",
"status": "open",
"fee": "0.00000000",
"is_liquidation": false,
"auto_price": "0.00000000",
"auto_price_type": "",
"pnl": "0.00000000",
"cash_flow": "0.00000000",
"initial_margin": "0.24000000",
"taker_fee_rate": "0.00050000",
"maker_fee_rate": "0.00020000",
"label": "hedge",
"stop_price": "0.00000000",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"reorder_index": 1,
"source": "api",
"hidden": false,
"is_um": true
}
]
}
Get open orders by currency, category, instrument_id
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
instrument_id | string | false | "" | Instrument ID |
label | string | false | "" | Order label |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
instrument_id | string | Instrument ID |
order_type | string | Order type |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
time_in_force | string | Time in force |
avg_price | string | Average filled price |
filled_qty | string | Filled qty |
status | string | Order status |
fee | string | Transaction fees |
is_liquidation | boolean | Liquidation order |
auto_price | string | Auto price |
auto_price_type | string | Auto price type |
pnl | string | Order P&L |
cash_flow | string | Order cash flow |
initial_margin | string | Order initial margin (open order only) |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
stop_price | string | Stop price (stop order only) |
reduce_only | bool | Indicate reduce only or not |
post_only | bool | Indicate post only or not |
reject_post_only | bool | Indicate reject post only or not |
mmp | bool | Indicate mmp order or not |
reorder_index | int64 | Sorting index for internal use |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
is_um | bool | Indicate is UM order or not |
Get orders
GET /v1/orders
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/orders?currency=BTC&category=option&instrument_id=BTC-29MAY20-7500-C&order_id=7718222&start_time=1585270800000&end_time=1589522084000&include_open=true&offset=1&limit=10×tamp=1589523178651&signature=2092cebba4f082f9c8718344cdad9bed83950b5fe90b3a875b708898bfd89b20"
Response
{
"code": 0,
"message": "",
"data": [{
"order_id": "7718222",
"created_at": 1589202185000,
"updated_at": 1589460149000,
"user_id": "51140",
"instrument_id": "BTC-29MAY20-7500-C",
"order_type": "limit",
"side": "buy",
"price": "0.08000000",
"qty": "3.00000000",
"time_in_force": "gtc",
"avg_price": "0.00000000",
"filled_qty": "0.00000000",
"status": "cancelled",
"fee": "0.00000000",
"is_liquidation": false,
"auto_price": "0.00000000",
"auto_price_type": "",
"pnl": "0.00000000",
"cash_flow": "0.00000000",
"initial_margin": "",
"taker_fee_rate": "0.00050000",
"maker_fee_rate": "0.00020000",
"label": "hedge",
"stop_price": "0.00000000",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": false,
"reorder_index": 1,
"source": "api",
"hidden": false,
"is_um": true
}]
}
Get order history by currency, category, instrument_id, or order_id
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | category |
instrument_id | string | false | "" | Instrument ID |
order_id | string | false | "" | Order ID |
label | string | false | "" | Order label |
start_time | integer | false | Start timestamp | |
end_time | integer | false | End timestamp | |
include_open | boolean | false | true | Include open order or not |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
instrument_id | string | Instrument ID |
order_type | string | Order type |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
time_in_force | string | Time in force |
avg_price | string | Average filled price |
filled_qty | string | Filled quantity |
status | string | Order status |
fee | string | Transaction fees |
is_liquidation | boolean | Liquidation order |
auto_price | string | Auto price |
auto_price_type | string | Auto price type |
pnl | string | Order P&L |
cash_flow | string | Order cash flow |
initial_margin | string | Order initial margin (open order only) |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
stop_price | string | Stop price (stop order only) |
reduce_only | bool | Indicate reduce only or not |
post_only | bool | Indicate post only or not |
reject_post_only | bool | Indicate reject post only or not |
mmp | bool | Indicate mmp order or not |
reorder_index | int64 | Sorting index for internal use |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
is_um | bool | Indicate is UM order or not |
Get enhanced stop orders
GET /v1/stop_orders
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/stop_orders?currency=BTC&instrument_id=BTC-PERPETUAL&status=open×tamp=1590667739793&signature=14c522605de563064ae36933604225730a8b4e254be8ce58ecc2746f5199d77f"
Response
{
"code": 0,
"message": "",
"data": [{
"stop_order_id": "stop-br7lik3752cq6kouf9ng",
"created_at": 1590647120000,
"updated_at": 1590647120000,
"status": "open",
"stop_price": "9300.00000000",
"trigger_type": "last-price",
"instrument_id": "BTC-PERPETUAL",
"user_id": "51140",
"qty": "60.00000000",
"price": "9200.00000000",
"side": "buy",
"type": "stop-limit",
"time_in_force": "gtc",
"source": "api",
"hidden": false
}]
}
Get enhanced stop order history by currency, instrument_id, or status.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
instrument_id | string | false | "" | Instrument ID |
status | string | false | "" | Enhanced stop order status |
start_time | integer | false | Start timestamp | |
end_time | integer | false | End timestamp | |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
stop_order_id | string | Stop Order ID (with prefix "stop-") |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
instrument_id | string | Instrument ID |
qty | string | Order quantity |
price | string | Price of the triggered new order |
side | string | Order side |
order_type | string | Order type |
stop_price | string | Stop price |
time_in_force | string | Time in force |
status | string | Enhanced stop order status |
trigger_type | string | Triggered by last price |
user_id | string | User ID |
source | string | Order source |
hidden | bool | Indicate hidden order or not |
Get user trades
GET /v1/user/trades
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/user/trades?currency=BTC&category=option&instrument_id=BTC-22MAY20-7500-C&order_id=17551020&start_time=1585270800000&end_time=1589522084000&offset=1&limit=10×tamp=1589523590679&signature=c4788e3a77b6000424b55067f9ba38009b34d12e482b1c80186756857c869bb5"
Response
{
"code": 0,
"message": "",
"data": [{
"trade_id": "23210268",
"order_id": "17551020",
"instrument_id": "BTC-22MAY20-7500-C",
"qty": "2.00000000",
"price": "0.17550000",
"sigma": "0.00000000",
"underlying_price": "9471.25000000",
"index_price": "9469.81000000",
"usd_price": "1661.95165500",
"fee": "0.00100000",
"fee_rate": "0.00050000",
"side": "buy",
"created_at": 1589521371000,
"is_taker": true,
"order_type": "limit",
"label": "hedge"
}]
}
Get user trades
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
category | string | false | "" | Category |
instrument_id | string | false | "" | Instrument ID |
order_id | string | false | "" | Order ID |
start_time | integer | false | Start timestamp | |
end_time | integer | false | End timestamp | |
start_id | integer | false | Start Id | |
end_id | integer | false | End Id | |
count | int | false | 100 | Trade count, max 1000 |
Response
Name | Type | Desc |
---|---|---|
order_id | string | Order ID |
trade_id | string | Trade ID |
instrument_id | string | Instrument ID |
created_at | integer | Create timestamp |
order_type | string | Order type |
side | string | Order side |
price | string | Trade price |
qty | string | Trade quantity |
fee | string | Transaction fees |
fee_rate | string | Fee rate |
sigma | string | Implied volatility , option only |
is_taker | boolean | Is taker or not |
index_price | string | Index price |
underlying_price | string | Underlying price (not for future instrument) |
usd_price | string | USD price |
label | string | Order label of related trade |
Get estimated margins
GET /v1/margins
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/margins?instrument_id=BTC-29MAY20-7500-C&price=0.08&qty=3×tamp=1588932548594&signature=d642b046b247bf00ba285bb260582aadf33e98d2b47d26479b99cc1a7941f807"
Response
{
"code": 0,
"message": "",
"data": {
"buy_margin": "0.00018326",
"buy_margin_ccy": "0.00048299",
"buy_margin_usdt": "19.98670096",
"sell_margin": "0.0.00087369",
"sell_margin_ccy": "0.00040010",
"sell_margin_usdt": "16.55661412",
"min_sell": "40799.50000000",
"max_buy": "42042.50000000",
"usdt_index_price": "41381.19000000"
}
}
Get margin of orders
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID |
price | string | true | "" | Order price |
qty | string | true | "" | Order quantity |
Response (Margin array)
Name | Type | Desc |
---|---|---|
buy_margin | string | Original estimated buy margin |
buy_margin_ccy | string | UM mode estimated buy margin |
buy_margin_usdt | string | UM mode estimated buy margin in USDT ( = buy_margin_ccy * usdt_index_price) |
sell_margin | string | Original estimated sell margin |
sell_margin_ccy | string | UM mode estimated sell margin |
sell_margin_usdt | string | UM mode estimated sell margin in USDT ( = sell_margin_ccy * usdt_index_price) |
min_sell | string | Minimum price for sell order |
max_buy | string | Maximum price for buy order |
usdt_index_price | string | USDT index price |
Block Trade
New block trade request
POST /v1/blocktrades
# <bt_source> should be replaced with real bt_source
curl -X POST "https://betaapi.bitexch.dev/v1/blocktrades" -H "Content-Type: application/json" -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" -d '{"currency":"BTC", "label": "e8db3a92b94c482bb0e30f421415982d", "role": "maker", "counterparty": "1026", "bt_source": "<bt_source>", "trades": [{"instrument_id": "BTC-25SEP20-9000-C", "price": "0.18", "qty": "10", "side": "sell"}, {"instrument_id": "BTC-PERPETUAL", "price": "9300", "qty": "5000", "side": "buy"}], "timestamp": 1594447520876, "signature": "7e8b0e7987fcb282b691d9e87c5afa9af578ed0c464190ca1fa466d18c17adde"}'
Response
{
"code": 0,
"message": "",
"data": {
"label": "e8db3a92b94c482bb0e30f421415982d",
"status": "pending"
}
}
Make block trade request.
Label: Unique identifier of block trade, both counterpartys use the same label for given block trade request
Both side needs to call /v1/blocktrades
with same label
, trades
(with opposite side).
The block trade request timeout period is 1 minute
, if the other side doesn't answer in given time, the request will expired.
Block trade bt_source
is bit.com designated block trade source, contact bit.com for detail.
Post json body
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
currency | string | true | "" | Currency |
bt_source | string | true | "" | Block trade source (bit.com designated block trade source) |
label | string | true | "" | Unique identifier generated for block trade |
role | string | true | "" | Role: taker/maker |
counterparty | string | true | "" | Counterparty user ID |
trades | array | true | Trade list of this block trade request(see below) |
- block trade object
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
instrument_id | string | true | "" | Instrument ID |
side | string | true | "" | Order side: buy/sell |
price | string | true | "" | Order price |
qty | string | true | "" | Order quantity |
Response
Name | Type | Desc |
---|---|---|
label | string | Block trade label |
status | string | pending/filled/rejected/expired |
Query block trades
GET /v1/blocktrades
# <bt_source> should be replaced with real bt_source
curl -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" "https://betaapi.bitexch.dev/v1/blocktrades?currency=BTC&bt_source=<bt_source>×tamp=1594447524043&signature=12b1090ea6432e71f2f6d01c6f08f0ff30e3765791ebff87b4183964643d61d2"
Response
{
"code": 0,
"message": "",
"data": [
{
"block_order_id": "56",
"label": "8c5d90b6cbd744ceab49d0e66b8fda68",
"created_at": 1613637677061,
"updated_at": 1613637678593,
"user_id": "51140",
"counterparty": "481554",
"instrument_id": "BTC-PERPETUAL",
"side": "buy",
"price": "51000.00000000",
"qty": "1000.00000000",
"fee": "0.00000392",
"status": "filled",
"role": "maker",
"bt_source": "<bt_source>",
"order_id": "6325142",
"trade_id": "1299120841",
"index_price": "51723.49000000",
"sigma": "0.00000000"
}
]
}
Query block trades.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
bt_source | string | true | "" | Block trade source |
currency | string | true | "" | Currency |
instrument_id | string | false | "" | Instrument ID |
label | string | false | "" | Label of the block trade request |
start_time | integer | false | Start timestamp | |
end_time | integer | false | End timestamp | |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
block_order_id | string | Block order id |
label | string | Label of the block trade request |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
counterparty | string | Counterparty User ID |
instrument_id | string | Instrument ID |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
fee | string | Transaction fees |
status | string | Status |
role | string | Order role(taker/maker) |
bt_source | string | Block trade source |
order_id | string | Exchange order id |
trade_id | string | Exchange trade id |
index_price | string | Index price |
sigma | string | Implied volatility , option only |
Query block trades by platform
GET /v1/platform_blocktrades
# <bt_source> should be replaced with real bt_source
curl -H "X-Bit-Access-Key: ak-df074cbc-dbf7-46f9-b07c-f4f51763ac7a" "https://betaapi.bitexch.dev/v1/platform_blocktrades?currency=BTC&bt_source=<bt_source>×tamp=1594448745124&signature=39078700dbe556df7f34dd6e0fb444b4ead9ef6ddc8e5b24c76555b6758c68d2"
Response
{
"code": 0,
"message": "",
"data": [
{
"block_order_id": "56",
"label": "8c5d90b6cbd744ceab49d0e66b8fda68",
"created_at": 1613637677061,
"updated_at": 1613637678593,
"user_id": "51140",
"counterparty": "481554",
"instrument_id": "BTC-PERPETUAL",
"side": "buy",
"price": "51000.00000000",
"qty": "1000.00000000",
"fee": "0.00000392",
"status": "filled",
"role": "maker",
"bt_source": "<bt_source>",
"order_id": "6325142",
"trade_id": "1299120841",
"index_price": "51723.49000000",
"sigma": "0.00000000"
}
]
}
Query block trades of specific platform.
Query parameters
Parameter | Type | Required | Default | Description |
---|---|---|---|---|
bt_source | string | true | "" | Block trade source |
currency | string | true | "" | Currency |
instrument_id | string | false | "" | Instrument ID |
label | string | false | "" | Label of the block trade request |
taker | string | false | "" | Filtered by taker |
maker | string | false | "" | Filtered by maker |
start_time | integer | false | Start timestamp | |
end_time | integer | false | End timestamp | |
offset | int | false | 1 | Page index, first page = 1 |
limit | int | false | 100 | Page size |
Response
Name | Type | Desc |
---|---|---|
block_order_id | string | Block order id |
label | string | Label of the block trade request |
created_at | integer | Create timestamp |
updated_at | integer | Update timestamp |
user_id | string | User ID |
counterparty | string | Counterparty User ID |
instrument_id | string | Instrument ID |
side | string | Order side |
price | string | Order price |
qty | string | Order quantity |
fee | string | Transaction fees |
status | string | Status |
role | string | Order role(taker/maker) |
bt_source | string | Block trade source |
order_id | string | Exchange order id |
trade_id | string | Exchange trade id |
index_price | string | Index price |
sigma | string | Implied volatility , option only |
Get blocktrade user info
GET /v1/user/info
curl -H "X-Bit-Access-Key: ak-77fd5728-e7d4-4174-991a-6e9b8f5887e6" "https://betaapi.bitexch.dev/v1/user/info?timestamp=1613713263340&signature=038be893be10e51b7545abacbf669e7569b7de2dcb2693c33f4aa29c956a611a"
Response
{
"code": 0,
"message": "",
"data": {
"user_id": "10031"
}
}
Get user information with only blocktrade permission.
API key with "read" permission should use GET /v1/accounts
instead.
Query Parameters
None
Response
Name | Type | Description |
---|---|---|
user_id | string | User ID of bit.com |
Websocket subscription
Data subscription is based on Websocket protocol. Users can send subscription requests after established Websocket connections.
Connection will be auto disconnected if no subscription is initiated within 30s.
All the responses are based on the following structure.
Name | Type | Description |
---|---|---|
channel | string | Channel name |
timestamp | integer | The timestamp (milliseconds since the Unix epoch) |
data | object | Content |
module | string | [inverse , um ] The module which the subscription data came from |
Subscription management
Request
{
"type":"subscribe",
"instruments":[
"BTC-26JUN20-6000-P",
"BTC-26JUN20-6000-C",
"BTC-26JUN20-7000-P",
"BTC-26JUN20-7000-C",
"BTC-26JUN20-8000-C"
],
"channels":[
"depth",
"ticker",
"kline.5",
"order",
"account"
],
"currencies":[
"BTC"
],
"categories":[
"option"
],
"interval": "100ms",
"token":"be4ffcc9-2b2b-4c3e-9d47-68bf062cf651"
}
Response (success)
{
"channel":"subscription",
"timestamp":1587921122970,
"data":{
"code":0,
"subscription":[
"depth",
"ticker",
"kline.5"
]
}
}
Response (failure)
{
"channel":"subscription",
"timestamp":1587921122970,
"data":{
"code":13200302,
"message":"auth failed: invalid token"
}
}
Users can subscribe to different channels, public and private. Private channel requires token and authentication.
Channels have different specifications, see details in the documentations below.
Users can set the push frequency with the parameter interval
.
* interval=raw, the channel will push the updates immediately.
* interval=100ms, the updates within 100ms period will be aggregated and pushed out, note: if no updates within 100ms, no data will be pushed.
* interval=fixed100ms, data will be pushed every 100ms no matter has update or not (Only apply to order_book
channel currently).
If the subscription request contains more than one channel and one of them failed, you will receive two separate responses.
Users can stop the feed by submitting an unsubscribe request.
Parameters
Name | Type | Description |
---|---|---|
type | string | [subscribe , unsubscribe ] |
channels | string[] | List of channels |
currencies | string[] | List of currencies |
categories | string[] | List of instrument categories |
instruments | string[] | List of instrument IDs |
interval | string | [raw , 100ms , fixed100ms ] default value is raw |
token | string | Authentication Token for private channel |
interval
parameter:
- All channels support setting
interval
toraw
or100ms
- Only some channels support setting
interval
tofixed100ms
, currently supported channels include:order_book
Response
Name | Type | Description |
---|---|---|
code | integer | 0 means success, !=0 means failure |
message | string | Error message, return when failed |
subscription | string[] | Subscription list, return when successful |
Authentication Token
GET /v1/ws/auth
Request
curl -H "X-Bit-Access-Key: ak-ba3bd026-29e6-443b-8eb6-d2ea3b607113" "https://betaapi.bitexch.dev/v1/ws/auth?timestamp=1588996062516&signature=9ed1dd821cc6464d2cfc5bf9614df1f22611c977b513e1ffde864a673b6915f0"
Response
{
"code":0,
"message":"",
"data":{
"token":"be4ffcc9-2b2b-4c3e-9d47-68bf062cf651"
}
}
To connect private websocket channels, user needs to first call GET /v1/ws/auth
to acquire a token,
which will be used to fill in private websocket channel subscription for websocket authentication.
Each token is used for single websocket connection, it's not cached in server, can not be reused, user needs to acquire new token if reconnect. (Thus token of user A
can not be reused by user B
even when the token is compromised)
For websocket connection, user only need to do authentication in first private channel subscription, subsequent private subscription do not need authenticate(and subsequent token will be discarded, so different users can not share private websocket connections)
Parameters
None
Response
Name | Type | Description |
---|---|---|
token | string | private channel authentication token |
Heartbeat
Standard protocol
According to RFC 6455, Websocket protocol uses PING/PONG to indicate that the connection is kept alive.
Server sends PING to client every minute through Websocket, client responds with PONG. Connection will be closed if PONG is not received after one minute.
Client can also send PING to check if the server is still responsive.
PING/PONG are both control frames. PING's opcode is 0x9,PONG's opcode is 0xA. One can refer to this link。
Custom PING/PONG
Since some clients cannot support sending control frames, payload-based PING/PONG is provided in addition to the standard protocol. Refer to "Websocket RPC - PING" for details.
Channel Summary
Channel | Scope | Arguments | Description |
---|---|---|---|
depth | public | instruments | Changes to the order book |
order_book.{group}.{depth} | public | instruments | Order book based on specified group and depth |
depth1 | public | instruments | Top of order book bid/ask |
ticker | public | instruments | The most recent traded price and trading summary |
kline.{resolution} | public | instruments | Kline data |
trade | public | instruments | Trades for an instrument |
market_trade | public | categories + currencies | All the trades of available options or futures |
index_price | public | currencies | Index price of a specific USD pair |
mark_price | public | instruments | Mark price for an instrument |
account | private | currencies | User's account information |
um_account | private | UM user's account information | |
position | private | categories + currencies | User's position information |
order | private | categories + currencies | User's order information |
user_trade | private | categories + currencies | User's trade information |
mmp_frozen | private | currencies | MMP frozen event |
Depth Channel
Request
{
"type":"subscribe",
"instruments":[
"BTC-26JUN20-7000-P"
],
"channels":[
"depth"
],
"interval": "100ms"
}
Response (snapshot)
{
"channel":"depth",
"timestamp":1587929552250,
"module":"inverse",
"data":{
"type":"snapshot",
"instrument_id":"BTC-26JUN20-7000-P",
"sequence":9,
"bids":[
[
"0.08000000",
"0.10000000"
]
],
"asks":[
[
"0.09000000",
"0.20000000"
]
]
}
}
Response (update)
{
"channel":"depth",
"timestamp":1587930311331,
"module":"inverse",
"data":{
"type":"update",
"instrument_id":"BTC-26JUN20-7000-P",
"sequence":10,
"prev_sequence":9,
"changes":[
[
"sell",
"0.08500000",
"0.10000000"
]
]
}
}
Depth channel can have two message types: snapshot
and update
. Snapshot sends snapshots of the current order book. Updates sends changes of the order book.
The first message will always be a snapshot followed by updates, if there is any sort of disruption, a new snapshot will be sent follow by updates.
A snapshot includes bids and asks depths, each depth layer consists of two elements: price and quantity.
A normal update message contains sequence and prev_sequence, with the prev_sequence matching the previous update.
Changes in update is a result in a change in depth, every changes consists of three elements: side, price and quantity. Quantity=0 means a layer is been removed from the depth.
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
depth | public | instruments | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
type | string | [snapshot , update ] |
instrument_id | string | Instrument ID |
sequence | integer | Order book update sequence |
asks | array of [price, quantity] | Asks, price and quantity are string, return when type=snapshot |
bids | array of [price, quantity] | Bids, price and quantity are string, return when type=snapshot |
prev_sequence | integer | Previous update sequence number, return when type=update |
changes | array of [side, price, quantity] | Depth changes, side、price、quantity are string, quantity=0 means deletion, return when type = update |
Order Book Channel
Request
{
"type":"subscribe",
"instruments":[
"BTC-26JUN20-7000-C"
],
"channels":[
"order_book.10.10"
],
"interval": "100ms"
}
Response
{
"channel":"order_book.10.10",
"timestamp":1587930311331,
"module":"inverse",
"data":{
"instrument_id":"BTC-26JUN20-7000-C",
"sequence":3,
"timestamp":1587930311330,
"asks":[
[
"0.00300000",
"0.20000000"
]
],
"bids":[
[
"0.00200000",
"0.50000000"
],
[
"0.00100000",
"0.30000000"
]
]
}
}
Order Book pushes certain layers of an order book data based on group and depth.
An order book message includes bids and asks depths, each depth layer consists of two elements: price and quantity.
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
order_book.{group}.{depth} | public | instruments | [raw , 100ms ,fixed100ms ] |
When subscribing to orderbook channel, user will need to specify group and depth in channel
group value: 1
, 5
, 10
, 100
,1000
represents the order book price increments. 1 represents the smallest increment, increments in 0.0001; 10 represents increments in 0.001
depth value: 1
, 10
, 20
, 100
, represents order book layers
Default is group=1, depth=10
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
sequence | integer | Order book update sequence |
timestamp | integer | Timestamp at order book update |
asks | array of [price, quantity] | Asks, price and quantity are string |
bids | array of [price, quantity] | Bids, price and quantity are string |
Depth1 Channel
Request
{
"type":"subscribe",
"instruments":[
"BTC-26JUN20-7000-P"
],
"channels":[
"depth1"
],
"interval": "100ms"
}
Response
{
"channel":"depth1",
"timestamp":1587932635873,
"module":"inverse",
"data":{
"instrument_id":"BTC-26JUN20-7000-P",
"asks":[
[
"0.08500000",
"0.10000000"
]
],
"bids":[
[
"0.08000000",
"0.10000000"
]
]
}
}
Depth1 pushes top of book bid/ask information
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
depth1 | public | instruments | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
asks | array of [price, quantity] | Asks, price and quantity are string, return 0 or 1 layer |
bids | array of [price, quantity] | Bids, price and quantity are string, return 0 or 1 layer |
Ticker Channel
Request
{
"type":"subscribe",
"instruments":[
"BTC-26JUN20-5000-C"
],
"channels":[
"ticker"
],
"interval": "100ms"
}
Response
{
"channel":"ticker",
"timestamp":1589126498813,
"module":"inverse",
"data":{
"time":1589126498813,
"instrument_id":"BTC-26JUN20-5000-C",
"best_bid":"0.50200000",
"best_ask":"0.50500000",
"best_bid_qty":"2.30000000",
"best_ask_qty":"0.80000000",
"ask_sigma":"2.22748567",
"bid_sigma":"2.18964114",
"last_price":"0.50500000",
"last_qty":"0.10000000",
"open24h":"0.50500000",
"high24h":"0.50500000",
"low24h":"0.50500000",
"price_change24h":"",
"volume24h":"0.10000000",
"open_interest":"289.50000000",
"underlying_name":"BTC-26JUN20",
"underlying_price":"8616.02000000",
"mark_price":"0.43989364",
"sigma":"1.29049244",
"delta":"0.92073799",
"vega":"4.54807454",
"theta":"-6.28858194",
"gamma":"0.00003713",
"min_sell":"0.38950000",
"max_buy":"0.49000000"
}
}
Ticker pushes the most recent traded price and the last 24 hrs trading summary.
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
ticker | public | instruments | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
last_price | string | Most recent traded price |
last_qty | string | Most recent traded volume |
open24h | string | Open price during previous 24 hour |
high24h | string | Highest price during previous 24 hour |
low24h | string | Lowest price during previous 24 hour |
volume24h | string | Sum volume during previous 24 hour |
price_change24h | string | Price change% during previous 24 hour |
open_interest | string | Open interest |
best_bid | string | Best bid price |
best_ask | string | Best ask price |
best_bid_qty | string | Best bid quantity |
best_ask_qty | string | Best ask quantity |
bid_sigma | string | Top of book bid implied vol, option only |
ask_sigma | string | Top of book ask implied vol, option only |
underlying_name | string | Underlying index name, option only |
underlying_price | string | Underlying price, option only |
funding_rate | string | Funding rate, perpetual only |
funding_rate8h | string | Past 8H avg funding rate, perpetual only |
mark_price | string | Mark price |
sigma | string | Mark price implied vol, option only |
delta | string | Mark price delta, option only |
vega | string | Mark price vega, option only |
theta | string | Mark price theta, option only |
gamma | string | Mark price gamma, option only |
max_buy | string | Maximum price of buy order |
min_sell | string | Minimum price of sell order |
Kline Channel
Request
{
"type":"subscribe",
"instruments":[
"BTC-PERPETUAL"
],
"channels":[
"kline.5"
],
"interval": "100ms"
}
Response
{
"channel":"kline.5",
"timestamp":1587979850118,
"module":"inverse",
"data":{
"instrument_id":"BTC-PERPETUAL",
"tick":1587979800000,
"open":"7737.50000000",
"low":"7737.50000000",
"high":"7737.50000000",
"close":"7737.50000000",
"volume":"0.00000000"
}
}
Kline pushed kline data. If there is no trade during the current period, the previous close will be used for open, high and low.
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
kline.{timeframe} | public | instruments | [raw , 100ms ] |
When subscribing to kline channel, user will need to specify timeframe.
Support timeframes: 1
, 3
, 5
, 15
, 30
, 60
, 120
, 240
, 360
, 720
, 1440
, 1w
, 1m
The timeframe is in minutes. 1 represents 1 minute kline, 1440 represents 1 day kline.
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
tick | integer | Tick starting time |
open | string | Open price |
close | string | Close price |
high | string | High price |
low | string | Low price |
volume | string | Volume |
Trade Channel
Request
{
"type":"subscribe",
"instruments":[
"BTC-26JUN20-6000-P"
],
"channels":[
"trade"
],
"interval": "100ms"
}
Response
{
"channel":"trade",
"timestamp":1588997059735,
"module":"inverse",
"data":[
{
"trade_id":"2388418",
"instrument_id":"BTC-26JUN20-6000-P",
"price":"0.01800000",
"qty":"0.10000000",
"side":"buy",
"sigma":"1.15054346",
"option_type":"put",
"is_block_trade":false,
"created_at":1588997060000
}
]
}
Trade pushes instrument's trading information
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
trade | public | instruments | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
trade_id | string | Trade ID |
price | string | Price |
qty | string | Quantity |
side | string | Taker trade side |
sigma | string | Trade implied vol, option only |
option_type | string | Option type, option only |
is_block_trade | boolean | Is block trade or not |
created_at | integer | Trade timestamp (milliseconds since the Unix epoch) |
Market Trade Channel
Request
{
"type":"subscribe",
"channels":[
"market_trade"
],
"currencies":[
"BTC"
],
"categories":[
"option"
],
"interval": "100ms"
}
Response
{
"channel":"market_trade",
"timestamp":1588997059735,
"module":"inverse",
"data":[
{
"trade_id":"2388418",
"instrument_id":"BTC-26JUN20-6000-P",
"price":"0.01800000",
"qty":"0.10000000",
"side":"buy",
"sigma":"1.15054346",
"option_type":"put",
"is_block_trade":false,
"created_at":1588997060000
}
]
}
Market Trade pushes all the trading information of available options or futures.
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
market_trade | public | categories + currencies | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
trade_id | string | Trade ID |
price | string | Price |
qty | string | Quantity |
side | string | Taker trade side |
sigma | string | Trade implied vol, option only |
option_type | string | Option type, option only |
is_block_trade | boolean | Is block trade or not |
created_at | integer | Trade timestamp (milliseconds since the Unix epoch) |
Index Price Channel
Request
{
"type":"subscribe",
"channels":[
"index_price"
],
"currencies":[
"BTC"
],
"interval": "100ms"
}
Response
{
"channel":"index_price",
"timestamp":1588997560081,
"module":"inverse",
"data":{
"index_name":"BTC_USD",
"index_price":"9866.66000000"
}
}
Index Price pushes index price of a specific USD pair.
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
index_price | public | currencies | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
index_name | string | USD pair |
index_price | string | Index price |
Mark Price Channel
Request
{
"type":"subscribe",
"instruments":[
"BTC-26JUN20-10000-C"
],
"channels":[
"mark_price"
],
"interval": "100ms"
}
Response
{
"channel":"mark_price",
"timestamp":1588997840512,
"module":"inverse",
"data":{
"instrument_id":"BTC-26JUN20-10000-C",
"mark_price":"0.11006342",
"sigma":"0.79384700",
"delta":"0.54298511",
"vega":"14.25666243",
"theta":"-11.75126302",
"gamma":"0.00013900"
}
}
Mark Price pushes mark price of a specific instrument
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
mark_price | public | instruments | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
mark_price | string | Mark price |
sigma | string | Mark price implied vol, option only |
delta | string | Mark price delta, option only |
vega | string | Mark price vega, option only |
theta | string | Mark price theta, option only |
gamma | string | Mark price gamma, option only |
Account Channel
Request
{
"type":"subscribe",
"channels":[
"account"
],
"currencies":[
"BTC"
],
"interval": "100ms",
"token":"6d501ded-3c40-4697-b390-218a54b9de19"
}
Response
{
"channel":"account",
"timestamp":1589031930115,
"module":"inverse",
"data":{
"user_id":"53345",
"currency":"BTC",
"cash_balance":"9999.94981346",
"available_balance":"9999.90496213",
"margin_balance":"9999.94981421",
"initial_margin":"0.04485208",
"maintenance_margin":"0.00000114",
"equity":"10000.00074364",
"pnl":"0.00746583",
"total_delta":"0.06207078",
"account_id":"8",
"mode":"regular",
"session_upl":"0.00081244",
"session_rpl":"0.00000021",
"option_value":"0.05092943",
"option_pnl":"0.00737943",
"option_session_rpl":"0.00000000",
"option_session_upl":"0.00081190",
"option_delta":"0.11279249",
"option_gamma":"0.00002905",
"option_vega":"4.30272923",
"option_theta":"-3.08908220",
"future_pnl":"0.00008640",
"future_session_rpl":"0.00000021",
"future_session_upl":"0.00000054",
"future_session_funding":"0.00000021",
"future_delta":"0.00955630",
"created_at":1588997840512,
"projected_info": {
"projected_initial_margin": "0.97919888",
"projected_maintenance_margin": "0.78335911",
"projected_total_delta": "3.89635553"
}
}
}
Account pushes user's account information
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
account | private | currencies | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
account_id | string | Account ID |
mode | string | Risk mode |
available_balance | string | Available balance |
cash_balance | string | Cash balance |
currency | string | Currency |
equity | string | Account equity |
initial_margin | string | Account initial margin |
maintenance_margin | string | Account maintenance margin |
margin_balance | string | Account margin balance |
pnl | string | Profit & loss (P&L) |
total_delta | string | Total delta |
session_rpl | string | Session realized P&L |
session_upl | string | Session unrealized P&L |
option_value | string | Option market value |
option_pnl | string | Option P&L |
option_session_rpl | string | Option session realized P&L |
option_session_upl | string | Option session unrealized P&L |
option_delta | string | Option delta |
option_gamma | string | Option gamma |
option_vega | string | Option vega |
option_theta | string | Option theta |
future_pnl | string | Future P&L |
future_session_rpl | string | Future session realized P&L |
future_session_upl | string | Future session unrealized P&L |
future_session_funding | string | Future session funding |
future_delta | string | Future delta |
user_id | string | User ID |
projected_info | object | Projected information |
- Projected Information
Projected information(IM/MM/Delta) is the predicted value after the settlement of current trading session.
Name | Type | Description |
---|---|---|
projected_initial_margin | string | Projected IM |
projected_maintenance_margin | string | Projected MM |
projected_total_delta | string | Projected Delta |
UM Account Channel
Request
{
"type":"subscribe",
"channels":[
"um_account"
],
"interval": "100ms",
"token":"6d501ded-3c40-4697-b390-218a54b9de19"
}
Response
{
"channel":"um_account",
"timestamp":1632439007081,
"module":"um",
"data": {
"user_id": 1,
"created_at": 1632642549581,
"usdt_total_collateral": "200.00000000",
"usdt_total_margin_balance": "190.00000000",
"usdt_total_available": "80.00000000",
"usdt_total_initial_margin": "90.00000000",
"usdt_total_maintenance_margin": "120.00000000",
"usdt_total_initial_margin_ratio": "0.60000000",
"usdt_total_maintenance_margin_ratio": "0.60000000",
"usdt_total_liability": "8060000.00000000",
"usdt_total_unsettled_amount": "322143.95604395",
"spot_orders_hc_loss": "30.00000000",
"details": [
{
"currency": "BTC",
"equity": "100.00000000",
"liability": "0.00000000",
"usdt_index_price": "40000.00000000",
"cash_balance": "100.00000000",
"margin_balance": "100.00000000",
"available_balance": "50.00000000",
"initial_margin": "20.00000000",
"spot_margin": "30.00000000",
"maintenance_margin": "80.00000000",
"potential_liability": "0.00000000",
"interest": "1.00000000",
"interest_rate": "0.01000000",
"pnl": "0.11538462",
"total_delta": "0.38461538",
"session_rpl": "10.00000000",
"session_upl": "0.11538462",
"option_value": "0.00000000",
"option_pnl": "0.00000000",
"option_session_rpl": "0.00000000",
"option_session_upl": "0.00000000",
"option_delta": "0.00000000",
"option_gamma": "0.00000000",
"option_vega": "0.00000000",
"option_theta": "0.00000000",
"future_pnl": "0.11538462",
"future_session_rpl": "10.00000000",
"future_session_upl": "0.11538462",
"future_session_funding": "10.00000000",
"future_delta": "0.38461538",
"future_available_balance": "0.00200000",
"option_available_balance": "0.00200000",
"unsettled_amount": "9.11538462"
},
{
"currency": "USDT",
"equity": "-8000000.00000000",
"liability": "8000000.00000000",
"usdt_index_price": "1.00000000",
"cash_balance": "-8000000.00000000",
"margin_balance": "-8000000.00000000",
"available_balance": "0.00000000",
"initial_margin": "0.00000000",
"spot_margin": "0.00000000",
"maintenance_margin": "0.00000000",
"potential_liability": "8000000.00000000",
"interest": "300.00000000",
"interest_rate": "0.00500000",
"pnl": "0.00000000",
"total_delta": "0.00000000",
"session_rpl": "0.00000000",
"session_upl": "0.00000000",
"option_value": "0.00000000",
"option_pnl": "0.00000000",
"option_session_rpl": "0.00000000",
"option_session_upl": "0.00000000",
"option_delta": "0.00000000",
"option_gamma": "0.00000000",
"option_vega": "0.00000000",
"option_theta": "0.00000000",
"future_pnl": "0.00000000",
"future_session_rpl": "0.00000000",
"future_session_upl": "0.00000000",
"future_session_funding": "0.00000000",
"future_delta": "0.00000000",
"future_available_balance": "0.00000000",
"option_available_balance": "0.00000000",
"unsettled_amount": "-300.00000000"
}
]
}
}
UM mode: subscribe um_account
channnel to get UM account information.
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
um_account | private | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
user_id | int | User Id |
created_at | int | Timestamp (query time) |
usdt_total_collateral | string | USDT Total Collateral |
usdt_total_margin_balance | string | USDT Total Margin Balance |
usdt_total_available | string | USDT Total Available |
usdt_total_initial_margin | string | USDT Total Initial Margin |
usdt_total_maintenance_margin | string | USDT Total Maintenance Margin |
usdt_total_initial_margin_ratio | string | USDT Total Initial Margin Ratio, may returns "infinity" |
usdt_total_maintenance_margin_ratio | string | USDT Total Maintenance Margin Ratio, may returns "infinity" |
usdt_total_liability | string | USDT total liability |
usdt_total_unsettled_amount | string | USDT total unsettled amount |
spot_orders_hc_loss | string | Total spot order haircut loss |
details | array of Detail |
Details, array of currency level detail |
Detail
object
Name | Type | Description |
---|---|---|
currency | string | Currency |
equity | string | Equity |
liability | string | Liability |
usdt_index_price | string | USDT index price |
cash_balance | string | Cash Balance |
margin_balance | string | Margin Balance |
available_balance | string | Account Available Balance |
initial_margin | string | Initial Margin |
spot_margin | string | Spot Margin |
maintenance_margin | string | Maintenance Margin |
potential_liability | string | Potential Liability |
interest | string | Interest |
interest_rate | string | Interest Rate |
pnl | string | Account P&L |
total_delta | string | Total delta of account |
session_rpl | string | Session realized pnl |
session_upl | string | Session unrealized pnl |
option_value | string | Option market value |
option_pnl | string | Option P&L |
option_session_rpl | string | Option session realized P&L |
option_session_upl | string | Option session unrealized P&L |
option_delta | string | Option delta |
option_gamma | string | Option gamma |
option_vega | string | Option vega |
option_theta | string | Option theta |
future_pnl | string | Future P&L |
future_session_rpl | string | Future session realized P&L |
future_session_upl | string | Future session unrealized P&L |
future_session_funding | string | Future session funding |
future_delta | string | Future delta |
future_available_balance | string | Available balance for new futures order |
option_available_balance | string | Available balance for new option order |
unsettled_amount | string | Unsettled amount |
Position Channel
Request
{
"type":"subscribe",
"channels":[
"position"
],
"currencies":[
"BTC"
],
"categories":[
"option"
],
"interval": "100ms",
"token":"6d501ded-3c40-4697-b390-218a54b9de19"
}
Response (option)
{
"channel":"position",
"timestamp":1600743533528,
"module":"inverse",
"data":[
{
"instrument_id":"BTC-30OCT20-14000-P",
"qty":"-0.20000000",
"initial_margin":"0.09735673",
"maintenance_margin":"0.08235673",
"avg_price":"0.43800000",
"session_avg_price":"0.43800000",
"mark_price":"0.33678364",
"index_price":"10452.57000000",
"position_pnl":"0.02024327",
"position_session_upl":"0.02024327",
"position_session_rpl":"0.00000000",
"category":"option",
"roi":"0.23108759",
"option_delta":"0.18646500",
"option_gamma":"-0.00001376",
"option_vega":"-0.88990013",
"option_theta":"0.65103919",
},
{
"instrument_id":"BTC-30OCT20-14500-P",
"qty":"-0.10000000",
"initial_margin":"0.05522940",
"maintenance_margin":"0.04772940",
"avg_price":"0.49700000",
"session_avg_price":"0.49700000",
"mark_price":"0.40229400",
"index_price":"10452.57000000",
"position_pnl":"0.00947060",
"position_session_upl":"0.00947060",
"position_session_rpl":"0.00000000",
"category":"option",
"roi":"0.19055534",
"option_delta":"0.08317211",
"option_gamma":"-0.00000823",
"option_vega":"-0.85511325",
"option_theta":"1.00527001",
}
]
}
Response (future)
{
"channel":"position",
"timestamp":1600681824660,
"module":"inverse",
"data":[
{
"instrument_id":"BTC-PERPETUAL",
"qty":"100.00000000",
"initial_margin":"0.00018592",
"maintenance_margin":"0.00013945",
"avg_price":"10852.50000000",
"session_avg_price":"10852.50000000",
"mark_price":"10758.39435000",
"index_price":"10704.87000000",
"qty_base":"0.00929507",
"liq_price":"0.12199202",
"session_funding":"-0.00000002",
"position_pnl":"-0.00008060",
"position_session_upl":"-0.00008060",
"position_session_rpl":"-0.00000002",
"category":"future",
"roi":"-0.43351632",
"leverage":"50.00000000"
}
]
}
Position pushes user's position information
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
position | private | categories + currencies | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
qty | string | Position size (for option, qty in base currency, for future, qty in USD) |
qty_base | string | Position size in base currency, future only |
avg_price | string | Average filled price |
position_pnl | string | Position P&L |
position_session_upl | string | Position session unrealized P&L |
position_session_rpl | string | Position session realized P&L |
index_price | string | Index price |
mark_price | string | Mark price |
initial_margin | string | Initial margin |
maintenance_margin | string | Maintenance margin |
session_avg_price | string | Session average price |
session_funding | string | Session funding, future only |
category | string | Instrument category |
roi | string | Return on investment |
option_delta | string | Option position delta, option only |
option_gamma | string | Option position gamma, option only |
option_vega | string | Option position vega, option only |
option_theta | string | Option position theta, option only |
liq_price | string | Estimated liquidation price, future only |
leverage | string | Position leverage, future only |
Order Channel
Request
{
"type":"subscribe",
"channels":[
"order"
],
"currencies":[
"BTC"
],
"categories":[
"option"
],
"interval": "100ms",
"token":"6d501ded-3c40-4697-b390-218a54b9de19"
}
Response
{
"channel":"order",
"timestamp":1587994934089,
"module":"inverse",
"data":[
{
"order_id":"1590",
"instrument_id":"BTC-1MAY20-8750-P",
"qty":"0.50000000",
"filled_qty":"0.10000000",
"remain_qty":"0.40000000",
"price":"0.16000000",
"avg_price":"0.16000000",
"side":"buy",
"order_type":"limit",
"time_in_force":"gtc",
"created_at":1587870609000,
"updated_at":1587870609000,
"status":"open",
"fee":"0.00002000",
"cash_flow":"-0.01600000",
"pnl":"0.00000000",
"is_liquidation": false,
"auto_price":"0.00000000",
"auto_price_type":"",
"taker_fee_rate": "0.00050000",
"maker_fee_rate": "0.00020000",
"label": "hedge",
"stop_price": "0.00000000",
"reduce_only": false,
"post_only": false,
"reject_post_only": false,
"mmp": true,
"reorder_index": 1
}
]
}
Order pushes user's order information
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
order | private | categories + currencies | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
instrument_id | string | Instrument ID |
order_id | string | Order ID |
qty | string | Quantity |
filled_qty | string | Filled quantity |
remain_qty | string | Remaining quantity |
price | string | Order price |
avg_price | string | Average filled price |
side | string | Order side |
order_type | string | Order type |
time_in_force | string | Order time in force |
status | string | Order status |
fee | string | Fee |
cash_flow | string | Cash flow |
pnl | string | P&L |
auto_price | string | Auto price |
auto_price_type | string | Auto price type, option only |
is_liquidation | boolean | Is liquidation order or not |
taker_fee_rate | string | Taker fee rate |
maker_fee_rate | string | Maker fee rate |
label | string | User defined label |
stop_price | string | Stop price (stop order only) |
reduce_only | boolean | Indicate reduce only or not |
post_only | boolean | Indicate post only or not |
reject_post_only | boolean | Indicate reject post only or not |
mmp | boolean | Indicate mmp order or not |
reorder_index | integer | Sorting index for internal use |
created_at | integer | Timestamp at order creation (milliseconds since the Unix epoch) |
updated_at | integer | Timestamp at order update (milliseconds since the Unix epoch) |
User Trade Channel
Request
{
"type":"subscribe",
"channels":[
"user_trade"
],
"currencies":[
"BTC"
],
"categories":[
"option"
],
"interval": "100ms",
"token":"6d501ded-3c40-4697-b390-218a54b9de19"
}
Response
{
"channel":"user_trade",
"timestamp":1588997059737,
"module":"inverse",
"data":[
{
"trade_id":2388418,
"order_id":1384232,
"instrument_id":"BTC-26JUN20-6000-P",
"qty":"0.10000000",
"price":"0.01800000",
"sigma":"1.15054346",
"underlying_price":"9905.54000000",
"index_price":"9850.47000000",
"usd_price":"177.30846000",
"fee":"0.00005000",
"fee_rate":"0.00050000",
"side":"buy",
"created_at":1588997060000,
"is_taker":true,
"order_type":"limit",
"is_block_trade":false,
"label": "hedge"
}
]
}
User Trade pushes user trade information
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
user_trade | private | categories + currencies | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
order_id | string | Order ID |
trade_id | string | Trade ID |
instrument_id | string | Instrument ID |
order_type | string | User Order type |
side | string | User Order side |
price | string | Trade price |
qty | string | Trade quantity |
fee | string | Transaction fees |
fee_rate | string | Fee rate |
sigma | string | Imply volatility |
is_taker | boolean | Is taker or not |
is_block_trade | boolean | Is block trade or not |
index_price | string | Index price |
underlying_price | string | Underlying price, option only |
usd_price | string | USD price of auto price order |
label | string | Order label of related trade |
created_at | integer | Timestamp at trade creation (milliseconds since the Unix epoch) |
MMP Frozen Event Channel
Request
{
"type":"subscribe",
"channels":[
"mmp_frozen"
],
"currencies":[
"BTC"
],
"interval": "100ms",
"token":"6d501ded-3c40-4697-b390-218a54b9de19"
}
Response
{
"channel":"mmp_frozen",
"timestamp":1599277666000,
"module":"inverse",
"data":{
"currency":"BTC",
"frozen_until_ms":1599277929000
}
}
MMP Frozen pushes MMP frozen event
frozen_until_ms
indicate MMP frozen status.
frozen_until_ms > 0: frozen until this timestamp or a manual reset
frozen_until_ms = 0: frozen until a manual reset
Channel Information
Channel | Scope | Arguments | Interval |
---|---|---|---|
mmp_frozen | private | currencies | [raw , 100ms ] |
Response
Name | Type | Description |
---|---|---|
currency | string | Currency |
frozen_until_ms | integer | MMP frozen until timestamp |
Websocket RPC
Overview
Request
{
"type":"RPC_name",
"token":"If3Fy-o5TiOOTfvlmtryR0MTiziutYaYFkH3aRovJWWEXqCAD7CIdnbhGG5bwRqLRrGkOFEOjh0L",
"params":{
"param1":"hello"
}
}
Response
{
"type":"RPC_name",
"result":{
"code":0,
"message":"",
"data":{
"field1":"world"
}
}
}
After the websocket connection is established, in addition to data subscription, it also supports RPC in JSON.
Private requests need token get from rest API and authentication at the first time. For details please link to Authentication Token.
Parameters
Name | Type | Description |
---|---|---|
type | string | Request type |
token | string | Private request authentication token |
params | object | Parameters |
Response
Name | Type | Description |
---|---|---|
type | string | Request type |
result | object | Result |
result object
Name | Type | Description |
---|---|---|
code | integer | Error code |
message | string | Error message |
data | object | Response data |
PING
Request
{
"type":"ping",
"params":{
"id":123
}
}
Response
{
"type":"pong",
"result":{
"code":0,
"message":"",
"data":{
"id":123,
"timestamp":1632295288253
}
}
}
It is used to detect weather the connection is alive.The client timer send 'PING' regularly,expect a 'PONG' and the timestamp as response. If 'PONG' is not received within the set time, it may be a network error.
Request Information
Request Type | Scope |
---|---|
ping | public |
Parameters
Name | Type | Required | Description |
---|---|---|---|
id | integer | optional | Client defined request id |
Response
Name | Type | Description |
---|---|---|
id | integer | Client defined request id |
timestamp | integer | Timestamp received |
Enable or disable Cancel On Disconnect (WS)
Request
{
"type":"cancel_on_disconnect",
"token":"If3Fy-o5TiOOTfvlmtryR0MTiziutYaYFkH3aRovJWWEXqCAD7CIdnbhGG5bwRqLRrGkOFEOjh0L",
"params":{
"scope":"connection",
"enable":true
}
}
Response
{
"type":"cancel_on_disconnect",
"result":{
"code":0,
"message":"",
"data":""
}
}
When a COD-Enabled websocket connection is dropped, all open orders of the user will be canceled. Differences between rest API account_configs/cod and this interface:
- COD based on rest API, ALL open orders of the user will be cancelled only when ALL private connections are disconnected.
- COD based on websocket RPC, as long as a single COD-enabled websocket connection is dropped, ALL open orders of the user will be canceled.
- The two interfaces are configured independently, they won't affect each other.
Request Information
Request Type | Scope |
---|---|
cancel_on_disconnect | private |
Parameters
Name | Type | Required | Description |
---|---|---|---|
scope | string | optional | COD scope, currently only support connection |
enable | bool | required | true=enable COD ,false=disable COD |
Response
None
Constant definitions
Account Mode
Account mode | Description |
---|---|
classic | Classic mode |
um | Unified margin mode |
migrating-to-um | Migrating from classic to um (transient state) |
migrating-to-classic | Migrating from um to classic (transient state) |
Risk mode
Mode | Description |
---|---|
regular | Regular account |
portfolio_margin | Determines margin requirements base on future & option portfolio |
Instrument Category
Category | Description |
---|---|
option | Options |
future | Future (include perpetual) |
Option type
Option type | Description |
---|---|
call | Call option |
put | Put option |
Order side
Order side | Description |
---|---|
buy | Buy |
sell | Sell |
Order type
OrderType | Description |
---|---|
limit | Limit order |
market | Market order |
stop-limit | Stop limit order |
stop-market | Stop market order |
trigger-limit | Trigger limit order |
trigger-market | Trigger market order |
Order status
Status | Description |
---|---|
pending | Order initial state |
open | Order active state |
filled | Order fully filled |
cancelled | Order is cancelled |
StopOrder status
Status | Description |
---|---|
open | Enhanced stop Order is active |
triggered | Enhanced stop order is triggered |
cancelled | Enhanced stop order is cancelled without being triggered |
Order time in force
Status | Description |
---|---|
gtc | Good till cancel |
fok | Fill or kill |
ioc | Immediate or cancel |
Order auto price type
- Option only
Type | Description |
---|---|
usd | Place order with usd price |
implv | Place order with imply volatility |
Transaction log type
Tx log type | Description |
---|---|
deposit | Make deposit |
bad-deposit | Deposit failed |
withdraw | Make withdrawal |
withdraw-revert | Withdraw revert |
trade | Trading(buy/sell) |
delivery | Delivery |
settlement | Settlement |
bankruptcy | Account bankruptcy |
socialized-fund | Socialized-fund |
Withdrawal state
State | Description |
---|---|
original | Request accepted, original state |
pending | Pending |
rejected | Withdraw rejected |
confirmed | Once over 1 confirmation on chain |
Deposit state
State | Description |
---|---|
mempool | Transaction in the mempool |
pending | KYT Pending |
rejected | Deposit rejected |
confirmed | Once over 1 confirmation on chain |
unconfirmed | Transaction was packed |
rollback | Transaction was rolled back |
Order source
Order source | Description |
---|---|
api | From API |
web | From Web GUI |
app | From mobile app |
Errors
Error Handling
A clarification of bit.com trading APIs:
When calling the trading APIs of bit.com to, e.g. placing, editing, cancelling orders, the caller will get one of the following four types of results:
- A response indicating the request was successful
- A response indicating the request had been rejected
- A response indicating failed to get the processing result of the request
- Failed to receive a response (should be handled similarly to type 3, see below)
A result of type 3. happens when the frontend web servers of bit.com failed to receive a response from the matching engine in time (due to a network issue or a timeout). The response can be in the form of
- A HTTP response with status "504 - Gateway Timeout", when the failure was at the gateway layer.
- A HTTP response with status "200 - OK", but the JSON error code =
18500000
(Rpc timeout) - Other forms of network errors if the failure was even before the gateway of bit.com.
When a result of type 3 happens, it is unknown to the caller whether the sent request has been received/processed/rejected by the matching engine. Therefore, the caller has to make another call checking the state of the order or the account to find out.
Error code list
Bit.com API error codes:
Error Code | Description |
---|---|
0 | Success (no error) |
18100100 | General Error |
18100101 | Invalid Order Request |
18100102 | Invalid Order Side |
18100103 | Invalid Order Price |
18100104 | Invalid Order Quantity |
18100105 | Invalid Order Type |
18100106 | Invalid Time In Force |
18100107 | Get Position Error |
18100109 | Get Underlying Price Fail |
18100110 | Place Order Error |
18100111 | Marshal Order Error |
18100112 | Submit Order Request Error |
18100113 | Invalid Order ID |
18100114 | Get Order Error |
18100115 | Order Not Found |
18100116 | Submit Order Cancel Error |
18100117 | Invalid Order Status Parameter |
18100119 | Get Trade Error |
18100120 | Bad Create Option Request |
18100121 | Calc Strike Price Error |
18100122 | Create Option Error |
18100123 | Bad Update Option Request |
18100124 | Invalid Expiration |
18100125 | Get Option Error |
18100126 | Invalid Option Status |
18100127 | Update Option Error |
18100128 | Get Expiration Error |
18100129 | Invalid Delivery Price |
18100130 | Option Has Incomplete Orders |
18100131 | Bad Transfer Request |
18100132 | Invalid Transfer Quantity |
18100133 | Create Transfer Error |
18100134 | Get User Trade Error |
18100135 | Get Transfer Error |
18100137 | Get Account Error |
18100138 | Get Trades Error |
18100139 | Invalid Option Type |
18100141 | Invalid Currency |
18100142 | Get Underlying Error |
18100143 | Get Ticks Error |
18100144 | Get Mark Price Error |
18100145 | Get Portfolio Margin Error |
18100146 | Update Account Error |
18100147 | Get Transaction Log Error |
18100148 | Audit Account Error |
18100149 | Delivery Information Error |
18100150 | Exceed Max Open Order By Account |
18100151 | Exceed Max Open Order By Instrument |
18100152 | Get Open Order Count Error |
18100153 | Create Expiration Error |
18100154 | Update Access Token Error |
18100155 | Bad Delete Option Request |
18100156 | Delete Option Error |
18100157 | Bad Config Error |
18100158 | Update Config Error |
18100159 | Get Fee Rate Error |
18100160 | Invalidate Parameters Error |
18100161 | Get Orderbook Error |
18100162 | Get Index Error |
18100163 | Big Account Information Error |
18100164 | Get Uc Transfer Record Error |
18100165 | Invalid User Error |
18100166 | Insurance Account Error |
18100167 | Insurance Log Error |
18100168 | Fee Account Error |
18100169 | Fee Log Error |
18100170 | Get Delivery Error |
18100171 | Get Insurance Data Error |
18100172 | Invalid Depth Error |
18100173 | Invalid Expired Error |
18100174 | Get Orderbook Summary Error |
18100175 | Get Settlement Error |
18100176 | Get Trading View Data Error |
18100177 | Get User Error |
18100178 | Save User Error |
18100179 | Get Funding Chart Data Error |
18100180 | Invalid Order Cancel Request |
18100181 | Get Instrument Error |
18100183 | Get Future Error |
18100185 | Invalid Instrument |
18100186 | Close Position Request Error |
18100187 | Get Order Margin Error |
18100188 | Get Limit Price Error |
18100189 | Invalid Stop Price |
18100190 | Get Open Stop Order Count Error |
18100191 | Exceed Max Open Stop Order |
18100192 | Invalid Order Stop Price |
18100193 | Invalid Order Trigger Type |
18100194 | Save Stop Order Failed |
18100195 | Delete Expiration Error |
18100196 | Get Funding Rate Error |
18100197 | Bad Update Expiration Request |
18100198 | Update Expiration Error |
18100199 | Insufficient Balance Error |
18100200 | Invalid Transaction Type Error |
18100201 | Get Index Data Error |
18100202 | Invalid Argument Error |
18100204 | Invalid Page Parameter Error |
18100205 | Get Market Summary Error |
18100206 | System Account Error |
18100210 | Invalid Operator Id Error |
18100211 | Get Takeover Records Error |
18100212 | Invalid Operator User Ids |
18100213 | Start Takeover |
18100214 | Invalid Account Id |
18100215 | Exit Admin Takeover |
18100216 | Link Admin To Account |
18100217 | Unlink Admin From Account |
18100218 | Calc Portfolio Margin |
18100223 | Get Takeover Orders Error |
18100224 | Invalid Amend Order Request Error |
18100225 | Auto Price Error |
18100226 | Takeover Switch User Id Error |
18100227 | Account Is Locked Error |
18100228 | Get Bankruptcy Error |
18100229 | Filled Bankruptcy Request Error |
18100230 | Exceed Max Stop Order Error |
18100231 | Invalid Stop Order Status Error |
18100232 | Verification Code Mail Error |
18100233 | Verification Code Phone Error |
18100234 | Rpc Error: Order not active |
18100235 | Fill Bankruptcy Error |
18100236 | Invalid Order Role |
18100237 | No Block Order Permission |
18100238 | Self Trading Error |
18100239 | Illegal Valid Time Error |
18100240 | Invalid Block Order Request |
18100241 | Accept Block Order Error |
18100242 | Reject Block Order Error |
18100243 | Calculate Option Mm Error |
18100244 | Reduce Only Error |
18100245 | Block Trade Service Stop Error |
18100246 | Get Stop Trigger Price Error |
18100247 | Get Open Order Size Error |
18100248 | Get Position Size Error |
18100249 | Exceed Max Open Order By Option |
18100250 | Exceed Max Open Order By Future |
18100251 | Marketing Bonus Request Error |
18100252 | Bonus Error |
18100253 | Get Bonus Error |
18100254 | Marketing Refund Request Error |
18100255 | Refund Error |
18100256 | Get Active Error |
18100257 | Get Account Configuration Error |
18100258 | Invalid User Kyc Level Error |
18100259 | Duplicate Bonus Error |
18100260 | Calc Position Summary Error |
18100261 | Exceed Account Delta Error |
18100262 | Withdraw Request Error |
18100263 | Withdraw Error |
18100264 | Invalid User Defined String |
18100265 | Invalid Blocktrade Source |
18100266 | Send Captcha Error |
18100267 | Invalid Captcha Error |
18100268 | Invalid Number String |
18100269 | Exceed Max Position Error |
18100270 | Exceed Max Open Quantity Error |
18100271 | Get Block Order Error |
18100272 | Duplicated Blocktrade Key |
18100273 | Creat Bonus Active Error |
18100274 | Bonus Total Limit Error |
18100275 | Invalid Batch Order Request |
18100276 | Invalid Batch Order Count Request |
18100277 | Rpc New Batch Order Error |
18100278 | Fetch Db Timeout |
18100279 | Takeover Not Allowed |
18100280 | Invalid Batch Order Amend Request |
18100281 | Not Found In Open Orders |
18100282 | Rpc Batch Amend Error |
18100285 | Mmp error |
18100304 | Invalid Channel Error |
18100305 | Invalid Category Error |
18100306 | Invalid Interval Error |
18100401 | Invalid Address |
18100402 | Address Not Whitelisted |
18100403 | Invalid Fund Password |
18100404 | Withdrawal Order Not Exist |
18100405 | KYT Rejected |
18100406 | Withdraw Too Frequently |
18100407 | Withdraw Limit Exceeded |
18100408 | Withdraw Amount Less Than Minimum Amount |
18100500 | Trading permission error |
18100501 | Internal Db error |
18100502 | Internal cache error |
18100503 | Internal network error |
18200300 | Rate Limit Exceed |
18200301 | Login Error |
18200302 | Authentication Error, auth code: 17002012: no permission to access this endpoint 17002011: invalid IP address 17002010: signature error 17002014: timestamp expired 17002006: internal error 17002013: Invalid access key |
18200303 | Exceed Max Connection Error |
18300300 | Not Part In Competition |
18300301 | Register Competition Failed |
18300302 | Registered Competition |
18400300 | Cancel Only Period |
18500000 | Rpc timeout error (API result in uncertain state, see above info) |