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/time endpoint).
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
}
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 signature
Note: 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.
{
"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
Parameter
Description
Required
Type
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
Parameter
Description
Required
Type
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
}
]
}
{
"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
}]
}
{
"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
}
{
"symbol": "btc_usdt",
"listOrderID": ["11111"], // Choose one among listOrderID, listCustomID, or listPositionID, or leave all empty
"listCustomID": [""],
"listPositionID": [""],
"timestamp": 1724916869475 // Current timestamp in milliseconds
}
{
"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
}
{
"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
}
{
"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
Parameter
Description
Required
Type
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
Parameter
Description
Required
Type
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
Parameter
Description
Required
Type
symbol
Trading pair
No
string
startTime
Start time in ms (start and end interval must be within 7 days)
