NAV
中文
shell ruby python javascript

Change Log

Effective Time (Beijing Time UTC+8) API Update Type Description
2026-07-08 * Add Contract API release

General Info

Base URL

Response Example

{
  "success": true,
  "code": 0,
  "data": {
    "symbol": "BTC_USDT",
    "fairPrice": 8000,
    "timestamp": 1587442022003
  }
}

or

{
  "success": false,
  "code":500,
  "message": "Internal system error!"
}

The API accepts GET, POST, or DELETE requests. POST requests must use Content-Type: application/json.

Parameters are sent as JSON (camelCase naming) for POST requests; GET requests send parameters as request params (snake_case naming separated by '_').

Authentication

Java Example

/**
 * Get GET request parameter string
 *
 * @param param GET/DELETE request parameter map
 * @return
 */
public static String getRequestParamString(Map<String, String> param) {
    if (MapUtils.isEmpty(param)) {
        return "";
    }
    StringBuilder sb = new StringBuilder(1024);
    SortedMap<String, String> map = new TreeMap<>(param);
    for (Map.Entry<String, String> entry : map.entrySet()) {
        String key = entry.getKey();
        String value = StringUtils.isBlank(entry.getValue()) ? "" : entry.getValue();
        sb.append(key).append('=').append(urlEncode(value)).append('&');
    }
    sb.deleteCharAt(sb.length() - 1);
    return sb.toString();
}

public static String urlEncode(String s) {
    try {
        return URLEncoder.encode(s, "UTF-8").replaceAll("\\+", "%20");
    } catch (UnsupportedEncodingException e) {
        throw new IllegalArgumentException("UTF-8 encoding not supported!");
    }
}

/**
 * Sign
 */
public static String sign(SignVo signVo) {
    if (signVo.getRequestParam() == null) {
        signVo.setRequestParam("");
    }
    String str = signVo.getAccessKey() + signVo.getReqTime() + signVo.getRequestParam();
    return actualSignature(str, signVo.getSecretKey());
}

public static String actualSignature(String inputStr, String key) {
    Mac hmacSha256;
    try {
        hmacSha256 = Mac.getInstance("HmacSHA256");
        SecretKeySpec secKey =
                new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
        hmacSha256.init(secKey);
    } catch (NoSuchAlgorithmException e) {
        throw new RuntimeException("No such algorithm: " + e.getMessage());
    } catch (InvalidKeyException e) {
        throw new RuntimeException("Invalid key: " + e.getMessage());
    }
    byte[] hash = hmacSha256.doFinal(inputStr.getBytes(StandardCharsets.UTF_8));
    return Hex.encodeHexString(hash);
}

@Getter
@Setter
public static class SignVo {
    private String reqTime;
    private String accessKey;
    private String secretKey;
    private String requestParam; // GET request params sorted by dictionary order, joined with &; POST uses JSON string
}
  1. Public endpoints do not require a signature.

  2. For private endpoints, include ApiKey, Request-Time, and Signature in the request header. Content-Type must be application/json. Recv-Window is optional. Signature is the signed string. Signing rules are as follows:

1) Obtain the request parameter string for signing. Use an empty string ("") when there are no parameters:

For GET/DELETE requests, concatenate business parameters in dictionary order separated by &, then obtain the signing target string. (In batch APIs, if parameter values contain special characters such as commas, URL encode them when signing.)

For POST requests, the signing parameter is the JSON string (no dictionary sorting required).

2) After obtaining the parameter string, concatenate the signing target string as: accessKey + timestamp + parameter string

3) Sign the target string using HMAC SHA256, then include the signature in the request header

Notes:

1) Business parameters with null values are excluded from signing. Path parameters are also excluded. For GET requests, null parameters appended to the URL are parsed as "" on the server. For POST requests, omit null parameters or set them to "" when signing, otherwise signature verification will fail.

2) Place the Request-Time value used for signing in the Request-Time header, the signature string in the Signature header, and the API Key Access Key in the ApiKey header. Pass other business parameters as usual.

3) The signature string does not need to be Base64 encoded.

Timing Security

All signed endpoints require the Request-Time header — a timestamp string in milliseconds. The server validates the request time window upon receipt. If req_time is more than 10 seconds (default) before or after server time (customizable via the optional Recv-Window header, max 60; recv_window above 30 seconds is not recommended), the request is considered invalid.

Create API Key

Users can create an API key in the OURBIT account center. It consists of two parts: Access Key (API access key) and Secret Key (used for signature calculation and verification).

These two keys are closely related to account security. Never disclose them to anyone.

Trade API

APIs under the [Trade API] module require authentication.

Get All Historical Orders

Response Example

{
    "success": false,
    "code": 0,
    "message": "",
    "data": [{
            "orderId": 0,
            "symbol": "",
            "positionId": 0,
            "price": 0.0,
            "vol": 0.0,
            "leverage": 0,
            "side": 0,
            "category": 0,
            "orderType": 0,
            "dealAvgPrice": 0.0,
            "dealVol": 0.0,
            "orderMargin": 0.0,
            "takerFee": 0.0,
            "makerFee": 0.0,
            "profit": 0.0,
            "feeCurrency": "",
            "openType": 0,
            "state": 0,
            "externalOid": "",
            "errorCode": 0,
            "usedMargin": 0.0,
            "createTime": "",
            "updateTime": "",
        }

    ]
}

Permission Required: Futures trading read permission

Request Parameters:

Parameter Type Required Description
symbol string false Contract symbol
states string false Order status: 1 pending, 2 incomplete, 3 completed, 4 cancelled, 5 invalid; multiple values separated by ','
category int false Order category: 1 limit order, 2 liquidation managed order, 4 ADL reduction; multiple values separated by ','
start_time long false Start time. The time range between start and end time cannot exceed 180 days per query. Returns data from the last 7 days by default if not specified.
end_time long false End time. The time range between start and end time cannot exceed 180 days per query.
side int false Order side: 1 open long, 2 close short, 3 open short, 4 close long
page_num int true Current page number, default 1
page_size int true Page size, default 20, max 100

Response Parameters:

Parameter Type Description
code integer Status code
message string Error description (if any)
orderId long Order ID
symbol string Contract symbol
positionId long Position ID
price decimal Order price
vol decimal Order quantity
leverage long Leverage
side int Order side: 1 open long, 2 close short, 3 open short, 4 close long
category int Order category: 1 limit order, 2 liquidation managed order, 4 ADL reduction
orderType int 1: limit order, 2: Post Only (maker only), 3: IOC (immediate or cancel), 4: FOK (fill or kill), 5: market order, 6: market-to-limit
dealAvgPrice decimal Average fill price
dealVol decimal Filled quantity
orderMargin decimal Order margin
takerFee decimal Taker fee
makerFee decimal Maker fee
profit decimal Realized PnL
feeCurrency string Fee currency
openType int Open type: 1 isolated, 2 cross
state int Order status: 1 pending, 2 incomplete, 3 completed, 4 cancelled, 5 invalid
errorCode int Error code: 0 normal, 1 parameter error, 2 insufficient balance, 3 position does not exist, 4 insufficient available position, 5 long order price below liquidation price / short order price above liquidation price, 6 long liquidation price above fair price / short liquidation price below fair price
externalOid string External order ID
usedMargin decimal Used margin
createTime date Created time
updateTime date Updated time

Get Historical Deals

Response Example

{
    "symbol": "ETH_USDT",
    "side": 3,
    "vol": 56,
    "price": 1783.96,
    "fee": 0.19980352,
    "feeCurrency": "USDT",
    "profit": 0,
    "orderId": "",
    "timestamp": 1783305295000,
    "positionMode": 1,
    "taker": true
}

Permission Required: Futures trading read permission

Request Parameters:

Parameter Type Required Description
symbol string false Contract symbol
start_time long false Start time. The time range between start and end time cannot exceed 180 days per query. Returns data from the last 7 days by default if not specified.
end_time long false End time. The time range between start and end time cannot exceed 180 days per query.
page_num int true Current page number, default 1
page_size int true Page size, default 20, max 100

Response Parameters:

Parameter Type Description
symbol string Contract symbol
side int Order side: 1 open long, 2 close short, 3 open short, 4 close long
vol int Filled contracts
category int Order category: 1 limit order, 2 liquidation managed order, 3 managed close order, 4 ADL reduction
price decimal Fill price
profit decimal Profit and loss
feeCurrency string Fee currency
taker bool Whether taker

Error Codes

Error Code Examples

Each endpoint may throw exceptions.

The following are possible error codes returned by endpoints.

Error Code Description
0 Success
9999 Common exception
500 Internal error
501 System busy
401 Unauthorized
402 API key expired
406 IP not in whitelist
506 Unknown request source
510 Too many requests
511 Endpoint access forbidden
513 Invalid request (Open API request time > server time + 2s or < server time - 10s)
600 Parameter error
601 Data parse error
602 Signature verification failed
603 Duplicate request
701 Account read permission required
702 Account write permission required
703 Trading read permission required
704 Trading write permission required
1000 Account does not exist
1001 Contract does not exist
1002 Contract not enabled
1003 Risk limit tier error
1004 Amount error
2001 Order side error
2002 Open type error
2003 Buy order price too high
2004 Sell order price too low
2005 Insufficient balance
2006 Leverage error
2007 Order price error
2008 Insufficient closable quantity
2009 Position does not exist or already closed
2011 Order quantity error
2013 Cancel order count exceeds maximum limit
2014 Batch order count exceeds limit
2015 Price or quantity precision error
2016 Trigger order exceeds maximum order count
2018 Exceeds maximum reducible margin
2019 Active open orders exist
2021 Order leverage does not match existing position leverage
2022 Position type error
2023 Position exists with leverage greater than new tier maximum
2024 Order exists with leverage greater than new tier maximum
2025 Current position size exceeds new tier maximum allowed
2026 Cross margin does not support leverage modification
2027 Only one of cross or isolated margin allowed per direction
2028 Exceeds maximum order quantity
2029 Order type error
2030 External order ID too long (max 32 characters)
2031 Exceeds maximum position size for current risk limit
2032 Order price below long liquidation price
2033 Order price above short liquidation price
2034 Batch query count exceeds limit
2035 Unsupported market order tier
3001 Trigger order price type error
3002 Trigger order trigger type error
3003 Execution cycle error
3004 Trigger price error
4001 Unsupported currency
2036 Order count exceeds limit, please contact support
2037 Trading too frequent, please try again later
2038 Exceeds maximum allowed position size, please contact support!
5001 Take-profit and stop-loss prices cannot both be empty
5002 Take-profit/stop-loss order does not exist or is closed
5003 Invalid take-profit/stop-loss price
5004 Total TP/SL order quantity exceeds closable position size
6001 Trading forbidden
6002 Opening positions forbidden
6003 Time range error
6004 Symbol and status are required
6005 Trading pair not open