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!"
}
- https://futures.ourbit.com
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
}
Public endpoints do not require a signature.
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": "",
}
]
}
- GET
api/v1/private/order/list/history_orders
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
}
- GET
api/v1/private/order/list/order_deals
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 |