U本位合约 API Documentation (v3)

·

The U-margined futures contract API provides developers with a robust and secure interface for managing digital asset trading operations. Designed for precision and efficiency, this documentation outlines essential endpoints for signing requests, executing trades, managing positions, and retrieving critical account data. Whether you're building automated trading bots or integrating advanced portfolio tools, this guide ensures seamless interaction with the platform's core functionalities.

SDK and Code Examples

To streamline development, the platform offers official SDKs in multiple programming languages, including JavaScript, Python, and C#. These SDKs are built on top of the core API and automatically handle complex tasks such as:

Using an SDK reduces development time and minimizes the risk of implementation errors. While direct API access offers maximum control, SDKs provide a cleaner, higher-level abstraction for most use cases.

console.log('U-margined contract JavaScript code example');
# -*- coding:utf-8 -*-

if __name__ == '__main__':
    print('U-margined contract Python code example')
Console.WriteLine("U-margined contract C# code example");

👉 Discover how to securely integrate trading APIs into your application

1. Signed API Request Methodology

All private API endpoints require authentication via a signed request. This ensures that only authorized users can perform actions like placing orders or transferring funds.

Step-by-Step Signing Process

  1. Generate a timestamp in milliseconds (e.g., Date.now() in JavaScript).
  2. Prepare request parameters as a JSON object.
  3. Stringify the parameters using JSON.stringify().
  4. Create the signature string by concatenating the timestamp and the stringified parameters.
  5. Generate the HMAC-MD5 signature using your secret key.

  6. Set required HTTP headers:

    • content-type: application/json
    • bibox-api-key: Your API key
    • bibox-api-sign: The generated signature
    • bibox-timestamp: The timestamp used
  7. Send the request with the JSON body containing your parameters.

A successful response includes a state field: 0 indicates success, while any other value indicates an error. Success responses contain a result field; error responses include a msg field explaining the issue.

Code Example: JavaScript

let CryptoJS = require("crypto-js");
let request = require("request");
let timestamp = Date.now();
let param = {
    "amount": "0.01",
    "symbol": "USDT",
    "type": 0
};
let strParam = JSON.stringify(param);
let strToSign = timestamp + strParam;
let apikey = "900625568558820892a8c833c33ebc8fd2701efe";
let secret = "c708ac3e70d115ec29efbee197330627d7edf842";
let sign = CryptoJS.HmacMD5(strToSign, secret).toString();

request.post({
    url: "https://api.bibox.com/v3/cbuassets/transfer",
    method: "POST",
    headers: {
        'content-type': 'application/json',
        'bibox-api-key': apikey,
        'bibox-api-sign': sign,
        'bibox-timestamp': timestamp
    },
    body: strParam
}, function (err, httpResponse, body) {
    if (err) return console.error('Request failed:', err);
    console.log(body);
});

👉 Learn how to implement secure API authentication in your trading bot

2. Fund Transfer Between Accounts

Move funds between your spot wallet and futures contract account.

Request Details

Note: You must transfer funds to your contract account before placing any orders. Attempting to trade without sufficient margin will return an "insufficient balance" error.

Response

{"state":0,"result":"352559634189422592"}

3. Placing Orders

Submit new futures orders after ensuring adequate margin is available in your contract account.

Request Details

Advanced: Attach Stop-Loss/Take-Profit

When opening a position, you can simultaneously set conditional orders:

ParameterDescription
plan_type1 for market, 2 for limit
profit_priceTake-profit trigger price
loss_priceStop-loss trigger price
exec_profit_priceLimit price for take-profit (if plan_type=2)
exec_loss_priceLimit price for stop-loss (if plan_type=2)

Response

{"state":0,"order_id":"425510999949316","client_oid":"1234567890","status":1,"cmd":"open"}

4. Canceling an Order

Cancel a single open order using its order ID.

Response

{"state":0,"result":"success","cmd":"close"}

5. Batch Order Cancellation

Cancel multiple orders in a single request.

6. Cancel All Orders for a Pair

Cancel all open orders for a specific trading pair.

7. Place Stop-Loss/Take-Profit Order

Set conditional orders based on price triggers.

Ensure the order amount does not exceed your current position size.

8. Query Stop-Loss/Take-Profit List

Retrieve all active conditional orders.

Returns detailed information including trigger prices, order status, and execution type.

9. Cancel a Stop-Loss/Take-Profit Order

Remove a specific conditional order.

10. Cancel All Stop-Loss/Take-Profit Orders

Cancel all conditional orders for a given pair.

11. Adjust Isolated Margin

Modify the margin allocated to an isolated position.

Fails if no position exists.

12. Change Position Mode and Leverage

Switch between cross-margin and isolated-margin modes and set leverage.

13. Query Account Assets

Fetch your futures account balance and margin details.

Returns available balance, frozen funds, and margin amounts.

14. Query Positions

Get real-time position data including leverage, entry price, and liquidation price.

Use fields like pp and ps to track how much of your position already has take-profit or stop-loss orders attached.

Frequently Asked Questions

How do I generate a valid API signature?

Concatenate the timestamp and JSON-formatted request body, then apply HMAC-MD5 using your secret key. Include the result in the bibox-api-sign header.

What causes an "amount parameter error"?

The order quantity must be an exact multiple of the contract's face value (e.g., 10 XRP per contract). Sending a non-multiple like 15 XRP will trigger this error.

Can I set both take-profit and stop-loss on one order?

Yes. When placing an opening order, include both profit_price and loss_price with corresponding execution parameters (exec_profit_price, etc.).

Why was my market order not fully filled?

High-leverage positions restrict how far the execution price can deviate from the index price. If the market moves too quickly, partial or no fills may occur to prevent immediate liquidation.

How do I avoid liquidation?

Monitor your margin ratio and liquidation price (pf). Reduce leverage, add margin, or close part of your position if you're approaching dangerous levels.

What time format does the API use?

All timestamps are in Unix epoch milliseconds (UTC).

Core Keywords