Perpetual Contract Trading
API for perpetual contract trading by regular users
Preparation for Integration
Trading Pairs
A trading pair consists of a base currency and a quote currency. For example, in the trading pair btc_usdt, btc is the base currency, and usdt is the quote currency.
Applying for an API Key
To apply for an API Key, visit the Hibt official website via mobile. Navigate to the personal settings page, locate API management, and submit your application. Upon successful creation, ensure you securely save the following information:
Access Key: The access key for API requests.
Secret Key: The secret key used for signature authentication and encryption (visible only during the application process).
Password: Required for managing APIs.
API Authentication
Public endpoints provide access to basic information and market data. These endpoints can be accessed without authentication.
Private endpoints are used for trading and account management. Each private request must be signed using your API Secret Key for verification.
REST API
https://fapi.hibt0.com/open-api
Signature Authentication
Private endpoints (used for trading and account management) require encryption with your API Key to validate that parameters or values have not been altered during transmission. Each API Key must have the appropriate permissions to access corresponding endpoints. When creating a new API Key, assign the required permissions. Before using an endpoint, ensure your API Key has the necessary permissions.
A valid request must include the following components:
Request URL: Example
https://api.hibt0.com/open-api/v2/order/open.Header - Access Key (
X-ACCESS-KEY): Your API Key's Access Key, as obtained during API Key creation.Header - Body Signature (
X-SIGNATURE): Encrypted data generated by signing the request body with your Secret Key.Timestamp (
timestamp): A field in the POST request body or GET request URL parameters representing the current millisecond timestamp. This is required for signing.Required and Optional Parameters: Each method specifies the required and optional parameters for the API call. Check the method documentation for details.
Signature: An encrypted value ensuring the integrity and authenticity of the request. **For your API Key's security, signatures expire after 5 minutes.
Mandatory Signature Parameter: Any authenticated request must include the timestamp parameter for signature generation (use the latest server time from the
v2/server/timeendpoint).
Encryption Method
Body Content of the Open Position POST Request
{
"customID": "11111", // Your custom order ID
"symbol": "btc_usdt", // Trading pair
"type": 1, // 1: Limit order, 2: Market order
"side": 1, // Direction: 1 for buy, 2 for sell
"leverage": 10, // Leverage
"price": "2660", // Order price (used for limit orders). Not required for market orders.
"amount": "0.01", // Order quantity
"triggerType": 2, // Trigger type for take-profit/stop-loss: 1 for trade price, 2 for index price. Can be omitted if not setting take-profit/stop-loss.
"spPrice": "2770", // Preset take-profit price. Not required if not setting take-profit.
"slPrice": "2450", // Preset stop-loss price. Not required if not setting stop-loss.
"isSetSp": true, // Whether to set take-profit
"isSetSl": true, // Whether to set stop-loss
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Sort the parameters in ASCII order.
amount=0.01&customID=11111&isSetSl=true&isSetSp=true&leverage=10&price=2660&side=1&slPrice=2450&spPrice=2770&symbol=btc_usdt×tamp=1724916869475&triggerType=2&type=1
Encrypt the sorted request parameters using HMAC SHA256 with the secretKey to obtain the result.
9543936a83c8b4fd0aae02a6e6fa272dc8ebc95b871f620eb23ae1a6dadffee7
import json
import hmac
import hashlib
from collections import OrderedDict
def bytes_to_hex(bytes_array):
"""Convert bytes array to hex string."""
return ''.join(['%02x' % byte for byte in bytes_array])
def generate_hmac_sha256(data, key):
"""Generate HMAC SHA256 signature for the given data and key."""
secret_key = key.encode()
message = data.encode()
signature = hmac.new(secret_key, message, hashlib.sha256).digest()
return bytes_to_hex(signature)
def get_sort(json_str):
"""Sort the JSON string by keys."""
# Parse JSON string
data = json.loads(json_str, object_pairs_hook=OrderedDict)
# Create a new dictionary to store sorted key-value pairs
sorted_data = OrderedDict()
# Sort the original dictionary keys and insert them into the new dictionary in order
for key in sorted(data.keys()):
if data[key] != "":
sorted_data[key] = data[key]
return sorted_data
def get_key(json_str, secret_key):
"""Generate a signature for the given JSON string and secret key."""
# Filter out empty string values
sortData = get_sort(json_str)
filtered_data = {k: v for k, v in sortData.items() if v != ""}
# Concatenate the signature string
sign_str = []
for k, v in filtered_data.items():
# If v is a list, convert it to a string
if isinstance(v, list):
for i in range(len(v)):
v[i] = get_sort(json.dumps(v[i], ensure_ascii=False, separators=(',', ':')))
v = json.dumps(v, ensure_ascii=False, separators=(',', ':'))
sign_str.append(f"{k}={v}")
continue
sign_str.append(f"{k}={v}")
sorted(sign_str) # Sort by dictionary order
sign_str = '&'.join(sign_str)
print("Signature string:", sign_str)
# Calculate HMAC SHA256 signature
signature = generate_hmac_sha256(sign_str, secret_key)
return signature
# print("Signature:", signature)
if __name__ == '__main__':
json_str = {"items": [{"amount": "1", "customID": "123223", "leverage": 20, "side": 1, "symbol": "eth_usdt", "type": 2}, {"amount": "0.01", "customID": "321322", "leverage": 100, "side": 1, "symbol": "btc_usdt", "type": 2}], "timestamp": 1725599130897}
g = json.dumps(json_str)
a = get_key(g, "your secret key")
print(a) # Print signatureNote: If a parameter field contains an array, convert it to a JSON string separately and then append it to the signature string.
Constructing HTTP Requests
Use X-ACCESS-KEY to store the access key information and pass it as a parameter in the header.Use X-SIGNATURE to store the generated signature information and pass it as a parameter in the header.Use X-TIMESTAMP to store the request timestamp and pass it as a parameter in the header.
Request Methods
Currently, there are only two methods: GET and POST.
GET Requests: All parameters are included in the URL path.
POST Requests: All parameters are sent in JSON format within the request body.
Response Format
{
"msg": "success",
"code": 0,
"data": ""
}Common Error Codes
21XXXX (Parameter Errors)
22XXXX (Business Errors)
210001
Invalid parameters
210004
Incorrect take-profit price
210005
Incorrect stop-loss price
210007
Only data from the past 3 months is allowed
210008
Only data within a 7-day range is allowed
210009
Only data within a 3-month range is allowed
210010
Invalid trading pair
210011
endTime exceeds the current time
210116
Invalid user
210117
Asset balance not found
220001
Data not found
220002
Timestamp expired
220003
X-ACCESS-KEY not provided
220004
API key authentication failed
220005
X-SIGNATURE not provided
220007
Access Key expired
220008
Signature verification failed
220011
Authorization expired
220012
IP address not in whitelist
220013
No query permissions
220014
No trading permissions
220015
WebSocket: Invalid event type
220017
Too many requests
210019
Unauthorized
210020
No trading or query permissions
210021
Invalid Access Key
Basic Information API
Server Time Retrieval
HTTP Request
GET /v2/server/time
Authentication: No
Request Parameters
None
Response Example
{
"code":0,
"msg":"success",
"data":{"serverTime":1724916869475} //ms
}
Retrieve All Trading Pairs
HTTP Request
GET /v2/market/symbols
Request Parameters: None
Response Example
{
"msg": "success",
"code": 0,
"data": [
{
"symbol": "", // Trading pair symbol
"supportTrade": true, // Whether trading is supported
"volumePrecision": 0, // Precision of the trading volume (number of decimal places after the decimal point)
"pricePrecision": 0, // Precision of the trading price (number of decimal places after the decimal point)
"marketMiniAmount": "", // Minimum market order quantity for the trading pair
"limitMiniAmount": "" // Minimum limit order quantity for the trading pair
}
]
}Retrieve Ticker Data for Trading Pairs
HTTP Request
GET /v2/market/tickers
Request Parameters
symbol
Trading Pair
No (returns all if not provided)
string
Response Example
{
"msg": "success",
"code": 0,
"data": [
{
"symbol": "", // Trading pair symbol
"amount": "", // Trading volume measured in the base currency (e.g., BTC)
"volume": "", // Trading volume measured in the quote currency (e.g., USDT)
"open": "", // Opening price of the last 24 hours
"close": "", // Closing price of the last 24 hours
"high": "", // Highest price of the last 24 hours
"low": "", // Lowest price of the last 24 hours
"lastPrice": "", // Latest traded price
"lastAmount": "", // Volume of the latest traded price
"lastTime": 0, // Timestamp of the latest trade
"change": 5.55 // Price change percentage
}
]
}Retrieve K-Line Data for a Specific Trading Pair
HTTP Request
GET /v2/market/candle
Request Parameters
symbol
Trading Pair
Yes
string
period
Data time granularity (interval for each candle): M1, M5, M15, M30, H1, H4, H6, D1
Yes
string
start
Start timestamp for query, in milliseconds
No
int
end
End timestamp for query, in milliseconds
No
int
count
Number of K-Line data points to return [1, 500]. Default is 200, max is 500. If start and end are provided, the actual returned count depends on the time range.
No
int
Response Example
{
"msg": "success",
"code": 0,
"data": [
{
"symbol": "", // Trading pair symbol
"amount": "", // Trading volume measured in the base currency
"volume": "", // Trading volume measured in the quote currency
"open": "", // Opening price of the current period
"close": "", // Closing price of the current period
"high": "", // Highest price of the current period
"low": "", // Lowest price of the current period
"ts": 0 // Timestamp of the start of the current period
}
]
}Retrieve Ticker Prices for Trading Pairs
HTTP Request
GET /v2/market/ticker/price
Request Parameters
symbol
Trading Pair
No (returns all pairs if omitted)
string
Response Example
{
"msg":"success",
"code":0,
"data":[
{
"symbol": "",
"price":""
}
]
}Retrieve Market Depth for a Trading Pair
HTTP Request
GET /v2/market/depth
Request Parameters
symbol
Trading Pair
Yes
string
limit
Depth levels (5, 10, 20, 50, 100, 200)
No
int
Response Example
{
"msg": "success",
"code": 0,
"data": {
"bid": [
[
"9638.0", // Bid price
"431" // Bid quantity
]
],
"ask": [
[
"9638.0", // Ask price
"431" // Ask quantity
]
]
}
}Retrieve Latest Trades for a Trading Pair
HTTP Request
GET /v2/market/deals
Request Parameters
symbol
Trading Pair
Yes
string
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"symbol": "", // Trading pair symbol
"amount": "", // Trading volume measured in the base currency
"price": "", // Trade execution price in quote currency
"side": "", // Trade direction: "sell" or "buy", where "buy" indicates a purchase and "sell" indicates a sale
"time": 0 // Current timestamp in milliseconds
}]
}Query Trading Pair Mark Price
HTTP Request
GET /v2/market/index
Request Parameters
symbol
Trading Pair
No (returns all pairs if not provided)
string
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"symbol": "", // Trading pair
"marketPrice": "" // Market price
}]
}Query Funding Rate
HTTP Request
GET /v2/market/fundingRate
Request Parameters
symbol
Trading Pair
Yes
string
startTime
Start timestamp in ms (only supports a 3-month range)
No
int64
endTime
End timestamp
No
int64
limit
Number of records (default 100, max 1000)
No
int
Response Example
{
"msg": "success",
"code": 0,
"data": [
{
"symbol": "",
"rate": "", // Funding rate
"time": 0 // Timestamp
}
]
}Query Risk Limit
HTTP Request
GET /v2/market/riskLimit
Request Parameters
symbol
Trading Pair
Yes
string
Response Example
{
"msg": "success",
"code": 0,
"data": [
{
"symbol": "", // Trading pair symbol
"minValue": "", // Minimum position value
"maxValue": "", // Maximum position value
"maxLeverage": 0, // Maximum available leverage
"maintenanceMarginRate": "" // Maintenance margin rate
}
]
}Query Latest Contract Market Data
HTTP Request
GET /v2/market/contracts
Request Parameters
symbol
Trading Pair
No (returns all if omitted)
string
Response Example
{
"msg": "success",
"code": 0,
"data": [
{
"ticker_id": "Contract ID", // Contract Identifier
"base_currency": "Base Currency", // Base Currency
"quote_currency": "Quote Currency", // Quote Currency
"last_price": "Last Price", // Last Price
"base_volume": "Base Currency Volume", // Base Currency Volume
"USD_volume": "USD Volume", // USD Volume
"quote_volume": "Quote Currency Volume", // Quote Currency Volume
"bid": "Bid Price", // Bid Price
"ask": "Ask Price", // Ask Price
"high": "High Price", // High Price
"low": "Low Price", // Low Price
"product_type": "Product Type", // Product Type
"open_interest": "Open Interest (Base Currency)", // Open Interest (Base Currency)
"open_interest_usd": "Open Interest (USD)", // Open Interest (USD)
"index_price": "Index Price", // Index Price
"creation_timestamp": 0, // Creation Timestamp
"expiry_timestamp": 0, // Expiry Timestamp
"funding_rate": "Funding Rate", // Funding Rate
"next_funding_rate": "Next Funding Rate", // Next Funding Rate
"next_funding_rate_timestamp": 0, // Next Funding Rate Timestamp
"maker_fee": "Maker Fee Rate", // Maker Fee Rate
"taker_fee": "Taker Fee Rate", // Taker Fee Rate
"contract_type": "Contract Type", // Contract Type
"contract_price": "Contract Face Value", // Contract Face Value
"contract_price_currency": "Contract Face Value Currency" // Contract Face Value Currency
}
]
}Query Contract Trading Specifications
HTTP Request
GET /v2/market/contractSpecifications
Request Parameters None
Response Example
{
"msg":"success",
"code":0,
"data":[
{
"contract_type": "okb_usdt",
"contract_price": "123.45", //Last Price
"contract_price_currency": "usdt"
}
]
}Query Contract Order Book
HTTP Request
GET /v2/market/orderBook
Request Parameters
depth
Level 1-100
No
int
symbol
Trading pair
No
string
Response Example
{
"msg":"success",
"code":0,
"data":[
{
"ticker_id": "btc_usdt", // 交易对标识符，例如 "BTCUSD"
"timestamp": 1689991200, // 时间戳（毫秒级）
"bids": [ // 买方订单列表
["10000.50", "2.3"], // [价格, 数量]
["9999.75", "1.1"]
],
"asks": [ // 卖方订单列表
["10001.00", "3.5"],
["10002.25", "0.8"]
]
}
]
}Trading API
Open Position
HTTP Request
POST /v2/order/open
Authentication Required Yes
Request Parameters
{
"customID": "11111", // Your custom order ID
"symbol": "btc_usdt", // Trading pair
"type": 1, // 1: Limit Order, 2: Market Order
"side": 1, // Direction: 1 for buy, 2 for sell
"leverage": 10, // Leverage
"price": "2660", // Order price (used for limit orders; not required for market orders)
"amount": "0.01", // Order quantity
"triggerType": 2, // Take profit/stop loss trigger type: 1: Last price, 2: Index price; optional if not setting TP/SL
"spPrice": "2770", // Preset take profit price; optional if not setting TP
"slPrice": "2450", // Preset stop loss price; optional if not setting SL
"isSetSp": true, // Whether to set take profit
"isSetSl": true, // Whether to set stop loss
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Response Example
{
"msg": "success",
"code": 0,
"data": {
"orderID": "24081233332184101100143203708" // Order ID
}
}Batch Opening Positions
HTTP Request
POST /v2/order/batchOpen
Authentication Required Yes
Request Parameters
{
"timestamp": 1724916869475, // Current timestamp in milliseconds
"items":[{
"customID": "11111", // Your custom order ID
"symbol": "btc_usdt", // Trading pair
"type": 1, // 1: Limit Order, 2: Market Order
"side": 1, // Direction: 1 for buy, 2 for sell
"leverage": 10, // Leverage
"price": "2660", // Order price (used for limit orders; not required for market orders)
"amount": "0.01", // Order quantity
"triggerType": 2, // Take profit/stop loss trigger type: 1: Last price, 2: Index price; optional if not setting TP/SL
"spPrice": "2770", // Preset take profit price; optional if not setting TP
"slPrice": "2450", // Preset stop loss price; optional if not setting SL
"isSetSp": true, // Whether to set take profit
"isSetSl": true // Whether to set stop loss
},
{
"customID": "11111", // Your custom order ID
"symbol": "btc_usdt", // Trading pair
"type": 1, // 1: Limit Order, 2: Market Order
"side": 1, // Direction: 1 for buy, 2 for sell
"leverage": 10, // Leverage
"price": "2660", // Order price (used for limit orders; not required for market orders)
"amount": "0.01", // Order quantity
"triggerType": 2, // Take profit/stop loss trigger type: 1: Last price, 2: Index price; optional if not setting TP/SL
"spPrice": "2770", // Preset take profit price; optional if not setting TP
"slPrice": "2450", // Preset stop loss price; optional if not setting SL
"isSetSp": true, // Whether to set take profit
"isSetSl": true // Whether to set stop loss
}]}
Response Example
{
"msg": "success",
"code": 0,
"data": {
"success": {
"11111": "orderID",
"2222222": "orderID"
}, // Custom order IDs mapped to their corresponding order IDs
"fail": {
"333333": "sp price error",
"44444444": "bad symbol"
} // Custom order IDs mapped to their respective error messages
}
}Cancel Order
HTTP Request
POST /v2/order/cancel
Authentication Required Yes
Request Parameters
{
"symbol": "btc_usdt",
"orderID": "22222222", // Choose one of: orderID, customID, or positionID
"customID": "",
"positionID": "",
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Response Example
{
"msg":"success",
"code":0,
"data":{
"success":{"11111":"orderID", "2222222":"orderID"}, // {"自定义订单id":"委托单id"}
"fail":{"333333":"orderID", "44444444":"orderID",} // {"自定义订单id":"委托单id"}
}
}Batch Cancel Orders
HTTP Request
POST /v2/order/batchCancel
Authentication Required Yes
Request Parameters
{
"symbol": "btc_usdt",
"listOrderID": ["11111"], // Choose one among listOrderID, listCustomID, or listPositionID, or leave all empty
"listCustomID": [""],
"listPositionID": [""],
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Response Example
{
"msg":"success",
"code":0,
"data":{
"success":{"11111":"orderID", "2222222":"orderID"}, // {"自定义订单id":"委托单id"}
"fail":{"333333":"orderID", "44444444":"orderID",} // {"自定义订单id":"委托单id"}
}
}Close Position
HTTP Request
POST /v2/order/close
Authentication Required Yes
Request Parameters
{
"amount": "0.01",
"price": "2256", // Only for limit order close
"type": 1, // 1 for Limit, 2 for Market
"positionID": "12222222222222", // Position ID
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Response Example
{
"msg": "success",
"code": 0,
"data": {
"orderID": "24081233332184101100143203708" // Order ID
}
}Close All Positions
HTTP Request
POST /v2/order/closeAll
Authentication Required Yes
Request Parameters
{
"symbol": "btc_usdt",
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Response Example
{
"msg": "success",
"code": 0,
"data": {
"listOrderID": ["24081233332184101100143203708"] // Order IDs
}
}Query Unfinished Orders
HTTP Request
GET /v2/order/unFinish
Authentication Required Yes
Request Parameters
symbol
Trading pair
No
string
orderID
Order ID // Either orderID, customID, or positionID must be provided, or none at all
No
string
customID
Custom order ID
No
string
positionID
Position ID
No
string
timestamp
Current timestamp in milliseconds
Yes
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"id": "", // Order ID
"customID": "", // Custom Order ID
"symbol": "", // Trading Pair
"type": 1, // Order Type: 1 = Limit, 2 = Market
"action": 0, // Order Event: 0 = Open, 1 = Close, 2 = Stop Loss, 3 = Take Profit, 4 = Forced Close, 5 = FOK Forced Close, 6 = ADL Reduce Position, 7 = Add Position, 8 = Reverse Open, 9 = Margin Call
"side": 1, // Trading Direction: 1 = Buy, 2 = Sell
"positionID": "", // Position ID
"price": "", // Order Price (only valid for limit orders)
"leverage": 0, // Leverage
"amount": "", // Order Quantity
"frozen": "", // Frozen Margin
"filledAmount": "", // Filled Quantity
"filledPrice": "", // Average Filled Price
"filledValue": "", // Filled Value
"triggerType": 2, // Trigger Type for Stop Loss/Take Profit: 1 = Last Price, 2 = Index Price
"spPrice": "", // Preset Take Profit Price
"slPrice": "", // Preset Stop Loss Price
"state": 1, // Order Status: 1 = Active, 2 = Filled, 3 = Cancelled, 4 = Partially Filled, 5 = Partially Filled & Cancelled, 6 = Cancelling
"profit": "", // Realized Profit/Loss (for closed orders)
"fee": "", // Original Fee
"pointFee": "", // Fee Discounted by Points/Bonuses
"pointProfit": "", // Profit/Loss Discounted by Points/Bonuses
"closePrice": "", // Liquidation Price
"triggerPrice": "", // Trigger Price
"createdAt": 0, // Creation Timestamp
"updatedAt": 0 // Last Update Timestamp
}]
}Query Details of Completed Orders
HTTP Request
GET /v2/order/finishedInfo
Authentication Required Yes
Request Parameters
symbol
Trading pair
string
orderID
Order ID // Either orderID, customID, or positionID must be provided
string
customID
Custom order ID
string
positionID
Position ID
string
timestamp
Current timestamp in milliseconds
number
Response Example
{
"msg": "success",
"code": 0,
"data": {
"id": "", // Order ID
"customID": "", // Custom Order ID
"symbol": "", // Trading Pair
"type": 1, // Order Type: 1 = Limit, 2 = Market
"action": 0, // Order Event: 0 = Open, 1 = Close, 2 = Stop Loss, 3 = Take Profit, 4 = Forced Close, 5 = FOK Forced Close, 6 = ADL Reduce Position, 7 = Add Position, 8 = Reverse Open, 9 = Margin Call
"side": 1, // Trading Direction: 1 = Buy, 2 = Sell
"positionID": "", // Position ID
"price": "", // Order Price (only valid for limit orders)
"leverage": 0, // Leverage
"amount": "", // Order Quantity
"frozen": "", // Frozen Margin
"filledAmount": "", // Filled Quantity
"filledPrice": "", // Average Filled Price
"filledValue": "", // Filled Value
"triggerType": 2, // Trigger Type for Stop Loss/Take Profit: 1 = Last Price, 2 = Index Price
"spPrice": "", // Preset Take Profit Price
"slPrice": "", // Preset Stop Loss Price
"state": 1, // Order Status: 1 = Active, 2 = Filled, 3 = Cancelled, 4 = Partially Filled, 5 = Partially Filled & Cancelled, 6 = Cancelling
"profit": "", // Realized Profit/Loss (for closed orders)
"fee": "", // Original Fee
"pointFee": "", // Fee Discounted by Points/Bonuses
"pointProfit": "", // Profit/Loss Discounted by Points/Bonuses
"closePrice": "", // Liquidation Price
"triggerPrice": "", // Trigger Price
"createdAt": 0, // Creation Timestamp
"updatedAt": 0 // Last Update Timestamp
}
}Query History of Completed Orders
HTTP Request
GET /v2/order/finished
Authentication Required Yes
Request Parameters
symbol
Trading pair
string
startTime
Start time (timestamp)
int
endTime
End time (timestamp)
int
pageIndex
Page number for pagination
int
pageSize
Number of items per page, max 50
int
timestamp
Current timestamp in milliseconds
number
Response Example
{
"msg":"success",
"code":0,
"data":{
"total":100, //总量
"page":1, //当前第几页
"data":[{
"id": "", //订单id
"customID": "", //自定义订单id
"symbol": "",//交易对
"type": 1, //订单类型 订单类型 1限价 2市价
"action": 0, //订单事件 0开仓 1平仓 2止损 3止盈 4强平 5FOK强平 6ADL减仓 7加仓 8反向开仓 9穿仓
"side": 1, //交易方向 1 buy 2 sell
"positionID": "", //仓位id
"price": "", //订单价格，限价单才有值
"leverage": 0, //杠杆
"amount": "", //下单量
"frozen": "", //冻结保证金
"filledAmount": "", //已完成量
"filledPrice": "", //成交均价
"filledValue": "",//成交价值
"triggerType": 2, //止盈止损触发类型 1成交价 2指数价
"spPrice": "", //预设止盈价
"slPrice": "", //预设止损价
"state": 1,//状态 1正常 2已完成 3撤销 4部分成交 5部分成交已撤销 6撤销中
"profit": "", //已实现盈亏（平仓订单使用）
"fee": "", //原始手续费
"pointFee": "", //积分(赠金)手续费抵扣
"pointProfit": "", //积分(赠金)盈亏抵扣
"closePrice": "", //破产价
"triggerPrice": "", //触发价
"createdAt": 0,
"updatedAt": 0
}]
}
}Add Conditional Order
HTTP Request
POST /v2/entrust/add
Authentication Required Yes
Request Parameters
{
"customID": "11111", // Custom order ID
"symbol": "btc_usdt", // Trading pair
"side": 1, // Trade direction: 1 for buy, 2 for sell
"triggerType": 1, // Trigger type: 1 for latest price, 2 for index price
"triggerPrice": "", // Trigger price
"amount": "", // Order quantity
"price": "", // Entrusted price
"leverage": 0, // Leverage
"spSlTriggerType": 0, // Take profit/stop loss trigger type: 1 for latest price, 2 for index price
"spPrice": "", // Preset take-profit price (provide if setting take profit)
"slPrice": "", // Preset stop-loss price (provide if setting stop loss)
"IsSetSp": false, // Whether to set take profit
"IsSetSl": false, // Whether to set stop loss
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Response Example
{
"msg": "success",
"code": 0,
"data": {
"id": "", // Order ID
"symbol": "", // Trading Pair
"leverage": 0, // Leverage
"triggerType": 1, // Trigger Type: 1 = Last Price, 2 = Index Price
"triggerPrice": "", // Trigger Price
"status": 2, // Status: 1 = Pending, 2 = Placed, 3 = Cancelled by User, 4 = Cancelled by System
"side": 1, // Trading Direction: 1 = Buy, 2 = Sell
"price": "", // Order Price
"startPrice": "", // Trigger Order Price
"amount": "", // Order Quantity
"spSlTriggerType": 0, // Take Profit/Stop Loss Trigger Type
"spPrice": "", // Preset Take Profit Price
"slPrice": "", // Preset Stop Loss Price
"isSetSp": false, // Is Take Profit Set
"isSetSl": false, // Is Stop Loss Set
"frozen": "", // Frozen Margin
"createdAt": 0, // Creation Timestamp
"updatedAt": 0 // Last Update Timestamp
}
}Cancel Conditional Order
HTTP Request
POST /v2/entrust/cancel
Authentication Required Yes
Request Parameters
{
"symbol": "", // Trading pair
"entrustID": "", // Entrust ID (choose either this or custom ID)
"customID": "", // Custom user ID
"timestamp": 1724916869475 // Current timestamp in milliseconds
}Response Example
{
"msg":"success",
"code":0,
"data":["委托id1"，"委托id2"] // 返回取消成功的列表
}Retrieve Unfinished Conditional Orders
HTTP Request
GET /v2/entrust/unFinish
Authentication Required Yes
Request Parameters
symbol
Trading pair
string
timestamp
Current timestamp
number
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"id": "", // Order ID
"symbol": "", // Trading Pair
"leverage": 0, // Leverage
"triggerType": 1, // Trigger Type: 1 = Last Price, 2 = Index Price
"triggerPrice": "", // Trigger Price
"status": 2, // Status: 1 = Pending, 2 = Placed, 3 = Cancelled by User, 4 = Cancelled by System
"side": 1, // Trading Direction: 1 = Buy, 2 = Sell
"price": "", // Order Price
"startPrice": "", // Trigger Order Price
"amount": "", // Order Quantity
"spSlTriggerType": 0, // Take Profit/Stop Loss Trigger Type
"spPrice": "", // Preset Take Profit Price
"slPrice": "", // Preset Stop Loss Price
"isSetSp": false, // Is Take Profit Set
"isSetSl": false, // Is Stop Loss Set
"frozen": "", // Frozen Margin
"createdAt": 0, // Creation Timestamp
"updatedAt": 0 // Last Update Timestamp
}]
}Retrieve Completed Conditional Orders List
HTTP Request
GET /v2/entrust/finished
Authentication Required Yes
Request Parameters
symbol
Trading pair
string
pageIndex
Pagination index
int
pageSize
Number of entries (maximum 50)
int
timestamp
Current timestamp
number
Response Example
{
"msg": "success",
"code": 0,
"data": {
"total": 100, // Total number of orders
"page": 1, // Current page number
"data": [{
"id": "", // Order ID
"symbol": "", // Trading pair
"leverage": 0, // Leverage
"triggerType": 1, // Trigger type: 1 = Last price, 2 = Index price
"triggerPrice": "", // Trigger price
"status": 2, // Order status: 1 = Pending, 2 = Placed, 3 = Cancelled by user, 4 = Cancelled by system
"side": 1, // Trading direction: 1 = Buy, 2 = Sell
"price": "", // Order price
"startPrice": "", // Trigger order price
"amount": "", // Order quantity
"spSlTriggerType": 0, // Take profit/stop loss trigger type
"spPrice": "", // Preset take profit price
"slPrice": "", // Preset stop loss price
"isSetSp": false, // Is take profit set
"isSetSl": false, // Is stop loss set
"frozen": "", // Frozen margin
"createdAt": 0, // Creation timestamp
"updatedAt": 0 // Last update timestamp
}]
}
}Account Interface
Retrieve Account Balance
HTTP Request
GET /v2/account/balance
Authentication Required Yes
Request Parameters None
Response Example
{
"msg": "success",
"code": 0,
"data": {
"balance": "Balance", // Account balance
"frozen": "Frozen Margin", // Frozen margin for open orders
"margin": "Position Margin", // Margin held for open positions
"point": "Points (Bonuses)", // Points or bonuses
"loans": "Loans", // Amount borrowed
"profit": "Unrealized Profit/Loss", // Unrealized profit/loss
"unProfit": "Floating Profit", // Floating profit
"unLosses": "Floating Loss", // Floating loss
"coin": "Coin" // Cryptocurrency
}
}Adjust Opening Leverage
HTTP Request
POST /v2/account/setLeverage
Authentication Required Yes
Request Parameters
{
"symbol": "", // Trading pair
"leverage": 0, // Leverage
"timestamp": 1724916869475 // Current timestamp in ms
}Response Example
{
"msg": "success",
"code": 0,
"data": {
"symbol": "", // Trading pair
"leverage": 0 // Leverage
}
}Get User Positions
HTTP Request
GET /v2/account/position
Authentication Required Yes
Request Parameters
symbol
Trading pair
No
string
positionID
Position ID
No
string
timestamp
Current timestamp in ms
Yes
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"positionID": "", // Position ID
"symbol": "", // Trading pair
"side": 0, // Position side (1: Buy, 2: Sell)
"leverage": 0, // Leverage multiple used
"price": "", // Average transaction price
"amount": "", // Position quantity
"frozenAmount": "", // Frozen quantity for liquidation
"margin": "", // Margin held for the position
"triggerType": 1, // Trigger type for take profit and stop loss: 1 = Transaction price, 2 = Index price
"spPrice": "", // Take profit price
"slPrice": "", // Stop loss price
"openProfit": "", // Unrealized profit/loss
"updatedAt": 0, // Timestamp
"spSlModel": 0, // Take profit and stop loss model: 1 = Full take profit and stop loss, 2 = Partial take profit and stop loss
"spType": 0, // Take profit type: 0 = Not set, 1 = Limit price, 2 = Market price
"slType": 0, // Stop loss type: 0 = Not set, 1 = Limit price, 2 = Market price
"spTriggerPrice": "", // Take profit trigger price
"slTriggerPrice": "", // Stop loss trigger price
"spSlPartData": [ // Partial take profit and stop loss data
{
"id": 0,
"triggerType": 1, // Trigger type for take profit and stop loss
"spPrice": "", // Take profit price
"slPrice": "", // Stop loss price
"amount": "", // Quantity for take profit and stop loss
"spType": 1, // Take profit type: 0 = Not set, 1 = Limit price, 2 = Market price
"slType": 1, // Stop loss type: 0 = Not set, 1 = Limit price, 2 = Market price
"spTriggerPrice": "", // Take profit trigger price
"slTriggerPrice": "" // Stop loss trigger price
}
]
}]
}Get Account Trade History
HTTP Request
GET /v2/account/order
Authentication Required Yes
Request Parameters
symbol
Trading pair
Yes
string
startTime
Start time in seconds
No
int64
endTime
End time in seconds
No
int64
limit
Number of entries (default: 500, max: 1000)
No
int
timestamp
Current timestamp in ms
Yes
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"id": "", // Order ID
"symbol": "", // Contract identifier
"type": 0, // Order type (1: Limit, 2: Market)
"action": 0, // Order event (0: Open, 1: Close, 2: Stop Loss, 3: Take Profit, 4: Liquidation, 5: FOK Liquidation, 6: ADL Reduction, 7: Margin Increase, 8: Opposite Position, 9: Margin Call)
"side": 0, // Trading direction (1: Buy, 2: Sell)
"positionId": "", // Position ID
"price": "", // Order price (only for Limit orders)
"leverage": 0, // Leverage multiple
"amount": "", // Order quantity
"frozen": "", // Frozen margin (OpenPrice * Amount * BaseMarginRate)
"filledAmount": "", // Filled quantity
"filledPrice": "", // Weighted average price of filled orders
"filledValue": "", // Total value of filled orders
"triggerType": 0, // Trigger type for Take Profit and Stop Loss (1: Transaction price, 2: Index price)
"spPrice": "", // Preset Take Profit price
"slPrice": "", // Preset Stop Loss price
"createdAt": 0, // Creation time
"updatedAt": 0, // Last update time
"state": 0, // Order state (1: Normal, 2: Completed, 3: Canceled, 4: Partially Filled, 5: Partially Filled & Canceled, 6: Canceling)
"profit": "", // Realized profit/loss (for closed orders)
"fee": "", // Transaction fee
"pointFee": "", // Fee deduction using points (bonuses)
"pointProfit": "", // Profit/loss deduction using points (bonuses)
"closePrice": "" // Bankruptcy price
}]
}Get Account Balance Record
HTTP Request
GET /v2/account/balanceRecord
Authentication Required Yes
Request Parameters
symbol
Trading pair
No
string
startTime
Start time in ms (interval: 30 days)
No
int64
endTime
End time in ms (interval: 30 days)
No
int64
event
Event type: 1: Deposit, 2: Deduction, 3: Transfer In, 4: Transfer Out, 9: Funding Fee, 201: Open Long, 202: Open Short, 204: Close Long, 205: Close Short, 206: Forced Liquidation
No
int
limit
Number of entries (default: 500, max: 1000)
No
int
timestamp
Current timestamp
Yes
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"id": "", // Transaction ID
"event": 0, // Type: 1: Deposit, 2: Withdrawal, 3: Transfer In, 4: Transfer Out, 9: Funding Fee, 201: Long Position Open, 202: Short Position Open, 204: Long Position Close, 205: Short Position Close, 206: Liquidation
"amount": "", // Amount representing either balance-related operations or profit/loss for trading-related operations
"coin": "", // Cryptocurrency
"fee": "", // Transaction fee
"symbol": "", // Associated trading pair
"note": "", // Remarks
"createdAt": 0 // Timestamp
}]
}Get User Forced Liquidation History
HTTP Request
GET /v2/account/orderForced
Authentication Required Yes
Request Parameters
symbol
Trading pair
No
string
startTime
Start time in ms (start and end interval must be within 7 days)
No
int64
endTime
End time in ms
No
int64
action
Forced liquidation type: 4 - Forced Liquidation, 5 - FOK Liquidation, 6 - ADL (Auto-Deleveraging), 9 - Bankruptcy
No
int
limit
Number of entries (default: 500, max: 1000)
No
int
timestamp
Current timestamp
Yes
Response Example
{
"msg": "success",
"code": 0,
"data": [{
"id": "", // Order ID
"symbol": "", // Currency pair
"type": 0, // Order type (1: Limit, 2: Market)
"action": 0, // Liquidation type: 4 - Liquidation, 5 - FOK Liquidation, 6 - ADL Auto Deleveraging, 9 - Margin Call
"side": 0, // Trading direction (1: Buy, 2: Sell)
"positionID": "", // Position ID
"price": "", // Order price (only applicable for Limit orders)
"leverage": 0, // Leverage
"amount": "", // Order quantity
"frozen": "", // Frozen margin (OpenPrice * Amount * BaseMarginRate)
"filledAmount": "", // Filled quantity
"filledPrice": "", // Weighted average filled price
"filledValue": "", // Total filled value
"triggerType": 0, // Trigger type for Take Profit and Stop Loss (1: Transaction price, 2: Index price)
"spPrice": "", // Preset Take Profit price
"slPrice": "", // Preset Stop Loss price
"createdAt": 0, // Creation time
"updatedAt": 0, // Last update time
"state": 0, // Order status (1: Normal, 2: Completed, 3: Cancelled, 4: Partially Filled, 5: Partially Filled & Cancelled, 6: Cancelling)
"profit": "", // Realized profit/loss (for closed orders)
"fee": "", // Transaction fee
"pointFee": "", // Fee deduction using points (bonuses)
"pointProfit": "", // Profit/loss deduction using points (bonuses)
"closePrice": "" // Margin call price
}]
}Contract WebSocket API
Request URL Example: wss://fapi.hibt0.com/v2/ws
API Authentication
For subscriptions that require authentication, send the authentication message first.
ignature: Simply sign the timestamp string.
{"event":"auth","accessKey":"XXX","timestamp":"XXX","signature":"XXX"}Subscribe to Topic
{"event":"sub", "topic":"Topic Content"}
Subscribe to Market Depth
Supported market depth topics: 5deep, 10deep, 20deep
Request JSON: {"event":"sub","topic":"btc_usdt.5deep"}
Response Example
{
"type":"btc_usdt.5deep",
"ts":1725356328427,
"data":{
"symbol":"btc_usdt",
"asks":["58930.89","2.51","58930.99","2.38","58931.09","2.9","58931.19","3.72","58931.29","1.41"],
"bids":["58930.71","1.44","58930.61","1.61","58930.51","2.22","58930.41","1.22","58930.31","1.94"]
}
}Subscribe to Ticker
Request JSON: {"event":"sub","topic":"btc_usdt.ticker"}
Response Example
{
"type": "btc_usdt.ticker",
"ts": 1725356998063,
"data": {
"symbol": "btc_usdt",
"amount": "473529.69", // BTC Volume
"volume": "27853751718.826", // Total USDT Value
"open": "58147.82", // 24-Hour Opening Price
"close": "58920.25",
"high": "59805.51", // 24-Hour High Price
"low": "58103.55", // 24-Hour Low Price
"lastPrice": "58920.25", // Last Traded Price
"lastAmount": "0.99", // Volume of the Last Trade
"lastTime": 1725356998061,
"change": "1.32" // 24-Hour Price Change Percentage
}
}Subscribe to Index
Request JSON: {"event":"sub","topic":"btc_usdt.index"}
Response Example
{
"type": "btc_usdt.index",
"ts": 1725357439229,
"data": {
"symbol": "btc_usdt",
"price": "58901.1",
"time": 1725357439228
}
}Subscribe to Latest Trades
Request JSON: {"event":"sub","topic":"btc_usdt.trade"}
Response Example
{
"type": "btc_usdt.trade",
"ts": 1725357599308,
"data": [
"58872.48", // Trade Price
"1", // Trade Side: 1 - Buy, 2 - Sell
"2.59", // Trade Volume (BTC)
"1725357599305" // Timestamp
]
}Subscribe to K-Line
Request JSON: {"event":"sub","topic":"btc_usdt.candle.M1"}
Supported Time Intervals:
"M1","M5","M15","M30","H1","H2","H4","H6","H12","D1","W1"Response Example
{
"type": "btc_usdt.candle.M1",
"ts": 1725357897306,
"data": [
"410.89", // Trading Volume
"24207865.8365", // Trading Volume in USDT
"58891.64", // Opening Price
"58945.88", // High Price
"58891.64", // Low Price
"58923.96", // Closing Price
"1725357840000" // Timestamp
]
}Subscribe to Plan Order Trigger Push (Authentication Required)
Request JSON: {"event":"sub","topic":"user.entrust"}
Response Example
{
"type": "user.entrust",
"ts": 1725437392251,
"data": [
{
"id": "24090408062338901100109440001",
"symbol": "btc_usdt",
"leverage": 10, // Leverage
"triggerType": 2, // Trigger Type: 1 - Last Traded Price, 2 - Mark Price
"triggerPrice": "56762", // Trigger Price
"status": 2, // Status: 1 - Pending, 2 - Placed, 3 - Cancelled by User, 4 - Cancelled by System
"side": 1, // Trade Direction: 1 - Buy, 2 - Sell
"price": "56830", // Order Price
"startPrice": "", // Trigger Order Price (not used in this context)
"amount": "0.12", // Order Quantity
"spSlTriggerType": 0, // Stop Profit/Loss Trigger Type (not specified)
"spPrice": "0", // Preset Take Profit Price
"slPrice": "0", // Preset Stop Loss Price
"isSetSp": false, // Is Take Profit Set?
"isSetSl": false, // Is Stop Loss Set?
"frozen": "", // Frozen Margin
"createdAt": 1725437183389,
"updatedAt": 1725437392240
}
]
}Subscribe to Position Change (Authentication Required)
Request JSON: {"event":"sub","topic":"user.position"}
Response Example
{
"type": "user.position",
"ts": 1725364233774,
"data": [
{
"positionID": "240903114238636010629", // Position ID
"symbol": "btc_usdt", // Trading pair
"side": 1, // Position direction: 1 - Buy, 2 - Sell
"leverage": 10, // Leverage
"price": "59066", // Average entry price
"amount": "0.21", // Position size
"frozenAmount": "0.21", // Frozen position size for liquidation
"margin": "1240.386", // Margin held for the position
"triggerType": 1, // Stop Profit/Loss trigger type
"spPrice": "", // Take Profit price (not set)
"slPrice": "", // Stop Loss price (not set)
"openProfit": "", // Unrealized profit/loss
"updatedAt": 1725364233773,
"spSlModel": 1, // Stop Profit/Loss model: 1 - Full, 2 - Partial
"spType": 0, // Take Profit type: 0 - Not set, 1 - Limit, 2 - Market
"slType": 0, // Stop Loss type: 0 - Not set, 1 - Limit, 2 - Market
"spTriggerPrice": "0", // Take Profit trigger price (not set)
"slTriggerPrice": "0", // Stop Loss trigger price (not set)
"spSlPartData": [{
"id": 0,
"triggerType": 1, // Partial Stop Profit/Loss trigger type
"spPrice": "", // Partial Take Profit price (not set)
"slPrice": "", // Partial Stop Loss price (not set)
"amount": "", // Quantity for partial Stop Profit/Loss
"spType": 0, // Partial Take Profit type: 0 - Not set, 1 - Limit, 2 - Market
"slType": 0, // Partial Stop Loss type: 0 - Not set, 1 - Limit, 2 - Market
"spTriggerPrice": "", // Partial Take Profit trigger price (not set)
"slTriggerPrice": "" // Partial Stop Loss trigger price (not set)
}] // Partial Stop Profit/Loss data
}
]
}Subscribe to Order Execution Notifications (Authentication Required)
Request JSON: `{"event":"sub","topic":"user.order"}`Response Example
{
"type": "user.order",
"ts": 1725432998830,
"data": [
{
"id": "24090406563872601100109440728", // Order ID
"customID": "", // Custom Order ID
"symbol": "btc_usdt", // Trading Pair
"type": 2, // Order Type: 1 - Limit, 2 - Market
"action": 0, // Order Action: 0 - Open Position, 1 - Close Position, 2 - Stop Loss, 3 - Take Profit, 4 - Forced Liquidation, 5 - FOK Forced Liquidation, 6 - ADL Reduction, 7 - Add Position, 8 - Reverse Open Position, 9 - Margin Call
"side": 1, // Trade Direction: 1 - Buy, 2 - Sell
"positionID": "240904065638726010729", // Position ID
"price": "0", // Order Price (only applicable for limit orders)
"leverage": 10, // Leverage
"amount": "0.2", // Order Quantity
"frozen": "1128.5496", // Frozen Margin: OpenPrice * Amount * BaseMarginRate
"filledAmount": "0", // Filled Quantity
"filledPrice": "0", // Average Filled Price
"filledValue": "", // Filled Value (not provided)
"triggerType": 1, // Stop Profit/Loss Trigger Type: 1 - Last Traded Price, 2 - Index Price
"spPrice": "0", // Preset Take Profit Price
"slPrice": "0", // Preset Stop Loss Price
"state": 0, // Order State: 1 - Active, 2 - Filled, 3 - Cancelled, 4 - Partially Filled, 5 - Partially Filled & Cancelled, 6 - Cancelling
"profit": "", // Realized Profit/Loss (for closed orders)
"fee": "", // Transaction Fee
"pointFee": "", // Fee Offset by Points/Bonuses
"pointProfit": "", // Profit/Loss Offset by Points/Bonuses
"closePrice": "", // Liquidation Price
"triggerPrice": "", // Trigger Price
"createdAt": 1725432998726,
"updatedAt": 0
}
]
}Subscribe to Account Balance Changes (Authentication Required)
Request JSON: {"event":"sub","topic":"user.balance"}
Response Example
{
"type": "user.balance",
"ts": 1725364751331,
"data": {
"balance": "4853.95", // Balance in USDT
"frozen": "0", // Margin frozen due to open orders
"margin": "1181.29", // Margin held for open positions
"point": "0", // Bonus balance
"loans": "", // Loans (not provided)
"profit": "0", // Unrealized profit and loss (sum of unProfit and unLosses)
"unProfit": "0", // Unrealized profit
"unLosses": "0", // Unrealized loss
"coin": "usdt" // Currency (USDT)
}
}Last updated