Contract

Contract

side

The side of the trade.

BUY_OPEN: open a long position.

SELL_CLOSE: close a long position.

SELL_OPEN: open a short position.

BUY_CLOSE: close a short position.

priceType

Price types.

INPUT: The system will use the price you entered exactly to fill the orders.

OPPONENT: Orders will be filled using the opposite side's best quote.

For example, if you are opening 10 contracts long, the best buy price is 10 and the best sell price is 11. You will send an order buying 10 contracts at 11. If the order, is not fully filled, the rest will be left on the orderbook.

QUEUE: Order will be send using the same side's best quote.

For example, if you are opening 10 contracts long, the best buy price is 10 and the best sell price is 11. You will be send an order buying 10 contracts at 10.

OVER: The price will be the best opposite quote + overPrice(not a fixed value).

For example, if you are opening 10 contracts long, the best buy price is 10 and the best sell price is 11, you set the overPrice at 3. You will be send an order buying 10 contracts at (11+3)=14.

MARKET: The price will be newest price * (1 ± 5%).

For example, if you are opening 10 contracts long, the latest price is 10. Then you will be sending out an order buying 10 contracts at (10 * 1.05)=10.5.

timeInForce

Time in force.

GTC: Good till canceled. Meaning the order will stand unless otherwise cancelled.

IOC: Immediate or cancel. Meaning the order will be cancelled if not executed immediately. Recommended if you want to fill the entire order immediately.

FOK: Fill or kill. Meaning the order will be canceled if not immediately filled. Recommended if you want to fill as much as possible, but not necessarily all of, the order immediately.

LIMIT_MAKER: Order will be cancelled if executed immediately.

orderType

Order type.

LIMIT: Orders to be executed given a specified price or better.

STOP: Order that will be triggered once it reaches the triggerPrice.

For detailed request limit information, see brokerInfo.

Rate limiters (rateLimitType)

  • REQUESTS_WEIGHT

  • ORDERS

Rate limit intervals

  • SECOND

  • MINUTE

  • DAY

For example:

{
"rateLimitType": "ORDERS",
"interval": "SECOND",
"limit": 20
}

Public

Security Type: None

Endpoints under Public section can be accessed freely without requiring any API-key or signatures.

get
Get Broker Trading information (Contracts)

https://api.hbtc.com/openapi/v1/brokerInfo
Get current contract trading rules.
Request
Response
Request
Query Parameters
type
optional
string
Trade section information. Possible values include token, options, and contracts, If the parameter is not sent, all trading information will be returned.
Response
200: OK
Successfully retrieved broker trading information.
{
"timezone":"UTC",
"serverTime":"1570701444309",
"brokerFilters":[],
"rateLimits":[
{
"rateLimitType":"ORDERS",
"interval":"SECOND",
"limit":20
},
{"rateLimitType":"ORDERS",
"interval":"DAY",
"limit":350000
},{
"rateLimitType":"REQUEST_WEIGHT",
"interval":"MINUTE",
"limit":1500
}],
"contracts":[
{
"filters":[
{"minPrice":"0.01",
"maxPrice":"100000.00000000",
"tickSize":"0.01",
"filterType":"PRICE_FILTER"
},
{
"minQty":"1",
"maxQty":"100000.00000000",
"stepSize":"1",
"filterType":"LOT_SIZE"
},{
"minNotional":"0.000001",
"filterType":"MIN_NOTIONAL"
}],
"exchangeId":"301",
"symbol":"BTC-PERP-REV",
"symbolName":"BTC-PERP-REV",
"status":"TRADING",
"baseAsset":"BTC-PERP-REV",
"baseAssetPrecision":"1",
"quoteAsset":"USDT",
"quoteAssetPrecision":"0.01",
"icebergAllowed":false,
"inverse":true,
"index":"BTCUSDT",
"marginToken":"TBTC",
"marginPrecision":"0.00000001",
"contractMultiplier":"1.0",
"riskLimits":[
{
"riskLimitId":"200000001",
"quantity":"1000000.0",
"initialMargin":"0.01",
"maintMargin":"0.005"
},
{
"riskLimitId":"200000002",
"quantity":"2000000.0",
"initialMargin":"0.02",
"maintMargin":"0.01"
},
{
"riskLimitId":"200000003",
"quantity":"3000000.0",
"initialMargin":"0.03",
"maintMargin":"0.015"
},
{
"riskLimitId":"200000004",
"quantity":"4000000.0",
"initialMargin":"0.04",
"maintMargin":"0.02"
}
]
}
]
}

Response:

name

type

example

description

timezone

string

UTC

Timezone of timestamp

serverTime

long

1554887652929

Retrieves the current time on server (in ms).

In the rateLimits field: Order api request limit will be displayed.

name

type

example

description

rateLimitType

string

ORDERS

Rate Limit type

interval

string

SECOND

Rate Limit interval

limit

string

1500

Rate Limit value within the interval.

In the contracts field: All actively trading contracts will be displayed.

name

type

example

description

symbol

string

BTCUSD

Name of the contract.

status

string

TRADING

Status of the contract.

baseAsset

string

BTCUSD

Base Asset of the trading pair. In the case with contracts, the contract itself is the base asset.

baseAssetPrecision

float

0.001

Precision of the contract quantity (baseAsset).

quoteAsset

string

USDT

Quote asset for the contract. Meaning the contract is quoted in that currency.

quoteAssetPrecision

float

0.001

Precision of the contract price (quoteAsset).

marginToken

string

BTC

Token used to settle funding and calculate PNL(profit and loss)

marginPrecision

float

0.0001

Precision of users' position margin.

inverse

bool

true

Whether the contract is inverse.

index

string

BTCUSDT

Index symbol of the underlying asset. Index price can be accessed at the index endpoint. For instance, BTC-PERP-REV uses BTCUSDT for index price.

contractMultiplier

string

true

The multiplier of contract.

icebergAllowed

string

false

Whether iceberg orders are allowed.

For filters in contracts field:

name

type

example

description

filterType

string

PRICE_FILTER

Type of the filter.

minPrice

float

0.001

Minimum price allowed

maxPrice

float

100000.00000000

Maximum price allowed

tickSize

float

0.001

Precision of the contract price.

minQty

float

0.01

Minimum quantity allowed

maxQty

float

100000.00000000

Maximum quantity allowed

stepSize

float

0.001

Precision of the contract quantity

minNotional

float

1

Minimum trade size (quantity * price)

In the riskLimits filed:

name

type

example

description

quantity

float

100

Positions below this amount follows the following requirement.

initialMargin

float

0.1

Initial margin rate requirement.

maintMargin

float

0.03

Minimum maintenance margin rate requirement.

  • Weight: 0

get
Get Contract Infomation

https://api.hbtc.com/openapi/v1/contracts
Return all information regarding contracts
Request
Response
Request
Response
200: OK
[
{
"symbol": "BTC-PERP-REV",
"symbolName": "BTC-PERP-REV",
"baseToken": "BTC-PERP-REV",
"quoteToken": "TBTC",
"lastPrice": "11660.3",
"baseVolume": "13024344",
"quoteVolume": "1043.667478029211300416",
"bid": "11660.9",
"ask": "11661.8",
"high": "11730.1",
"low": "11567.1",
"productType": "futures",
"openInterest": "23980794",
"indexPrice": "11655.7166666666666667",
"index": "BTCUSDT",
"indexBaseToken": "USD",
"startTs": "1598786974",
"endTs": "1598873374",
"fundingRate": "0.000038494841395324",
"nextFundingRate": "0.000088260431150408",
"nextFundingRateTs": 1598875200
},...
]

get
Insurance (PENDING)

https://api.hbtc.com/openapi/contract/v1/insurance
Get current insurance funding
Request
Response
Request
Query Parameters
symbol
optional
string
Input specific symbol to return the corresponding records. If not entered, records for all symbols will be returned. E.g. BTCUSDT
fromId
optional
number
Pagination, return records which id < fromId
toId
optional
number
Pagination, return records which id > toId. If toId is given, toId cannot be 0.
limit
optional
integer
Number of entries returned. Default to 20.
Response
200: OK
Successfully retrieved insurance funding.
{
"BTC":[
{
"id": 1552272184833,
"timestamp": 155227218483,
"value": 23.23,
"unit": "BTC"
},...
],...
}

Response:

name

type

example

description

id

long

1552272184833

The ID of the record.

timestamp

long

155227218483

current server timestamp.

value

float

23.23

Balance of the insurance fund.

unit

string

BTC

Unit of the balance..

  • Weight: 0

get
Funding Rate (PENDING)

https://api.hbtc.com/openapi/contract/v1/fundingRate
Get current funding rate.
Request
Response
Request
Query Parameters
symbol
optional
string
The contract to be returned, If not send, records for all symbols will be returned. E.g. BTCUSDT
state
optional
string
Get current or past funding rate.
from
optional
number
Timestamp to start
endTime
optional
number
Timestamp to end
limit
optional
integer
Number of entries returned. Default to 20.
Response
200: OK
Successfully retrieved funding rate information
[
{
'symbol': 'BTC-PERP-REV',
'intervalStart': '1570708800000',
'intervalEnd': '1570737600000',
'rate': '-0.000048567445464006'
},...
]

Response:

name

type

example

description

symbol

string

BTCUSD

Name of the contracts

intervalStart

long

1554710400000

Timestamp when the interval started.

intervalEnd

long

1554710400000

Timestamp when the interval ended.

rate

float

0.00321

The funding rate of this interval.

index

float

10076.34

Index price at the time of settlement.

  • Weight: 0

Market

Security Type: None

Endpoints under Market section can be accessed freely without requiring any API-key or signatures.

get
Index

https://api.hbtc.com/openapi/quote/v1/contract/index
Underlying asset index price.
Request
Response
Request
Query Parameters
symbols
optional
string
Underlying asset symbol. If this parameter is not sent, all symbols will be returned. E.g. BTCUSDT
Response
200: OK
Successfully retrieved index price(s).
{
"index":{
"BTCUSDT":"8243.21666667",
"OKBUSDT":"1.482",
"BNBUSDT":"31.2658",
"HTUSDT":"3.1209",...
},
"edp":{
"BTCUSDT":"8258.98505556",
"OKBUSDT":"1.48578333",
"BNBUSDT":"31.48741917",
"HTUSDT":"3.14308",...
}
}

Response:

name

type

example

description

index

float

8342.73

The index price of the instrument.

EDP

float

8432.32

The EDP (estimated delivery price of the contract). The average price of the index in the last 10 minutes. This will be the price on which the contract is going to be settled.

get
Depth

https://api.hbtc.com/openapi/quote/v1/contract/depth
This endpoint retrieve contract market depth data. This endpoint updates every 3s.
Request
Response
Request
Query Parameters
symbol
required
string
The contract name for which to retrieve the order book.. E.g. BTC-PERP-REV
limit
optional
integer
The number of entries to return for bids and asks. Default 100; Max 100.
Response
200: OK
Successfully retrieved market depth data
{
"time": 1555049455783,
"bids": [
["78.82", "0.526"],//[Price, Quantity]
["77.24", "1.22"],
["76.65", "1.043"],
["76.58", "1.34"],
["75.67", "1.52"],
["75.12", "0.635"],
["75.02", "0.72"],
["75.01", "0.672"],
["73.73", "1.282"],
["73.58", "1.116"],
["73.45", "0.471"],
["73.44", "0.483"],
["72.32", "0.383"],
["72.26", "1.283"],
["72.11", "0.703"],
["70.61", "0.454"]],
"asks": [
["122.96", "0.381"],//[Price, Quantity]
["144.46", "1"],
["155.55", "0.065"],
["160.16", "0.052"],
["200", "0.775"],
["249", "0.17"],
["250", "1"],
["300", "1"],
["400", "1"],
["499", "1"]]
}

Response:

name

type

example

description

time

long

1550829103981

Current timestamp (ms)

bids

list

(see below)

List of all bids, best bids first. See below for entry details.

asks

list

(see below)

List of all asks, best asks first. See below for entry details.

The fields bids and asks are lists of orderbook price level entries, sorted from best to worst.

name

type

example

description

''

float

123.10

price level

''

float

300

The total quantity of orders for this price level

https://api.hbtc.com/openapi/quote/v1/contract/depth/merged
This endpoint retrieve contract market depth data. This endpoint updates every 0.5s.
Request
Response
Request
Query Parameters
symbol
required
string
The contract name for which to retrieve the order book.. E.g. BTC-PERP-REV
limit
optional
integer
The number of entries to return for bids and asks. Default 40; Max 40.
Response
200: OK
Successfully retrieved market depth data
{
"time": 1555049455783,
"bids": [
["78.82", "0.526"],//[Price, Quantity]
["77.24", "1.22"],
["76.65", "1.043"],
["76.58", "1.34"],
["75.67", "1.52"],
["75.12", "0.635"],
["75.02", "0.72"],
["75.01", "0.672"],
["73.73", "1.282"],
["73.58", "1.116"],
["73.45", "0.471"],
["73.44", "0.483"],
["72.32", "0.383"],
["72.26", "1.283"],
["72.11", "0.703"],
["70.61", "0.454"]],
"asks": [
["122.96", "0.381"],//[Price, Quantity]
["144.46", "1"],
["155.55", "0.065"],
["160.16", "0.052"],
["200", "0.775"],
["249", "0.17"],
["250", "1"],
["300", "1"],
["400", "1"],
["499", "1"]]
}

Response:

name

type

example

description

time

long

1550829103981

Current timestamp (ms)

bids

list

(see below)

List of all bids, best bids first. See below for entry details.

asks

list

(see below)

List of all asks, best asks first. See below for entry details.

The fields bids and asks are lists of orderbook price level entries, sorted from best to worst.

name

type

example

description

''

float

123.10

price level

''

float

300

The total quantity of orders for this price level

get
Recent Trades List

https://api.hbtc.com/openapi/quote/v1/contract/trades
Get the latest trades that have occurred for a specific contract.
Request
Response
Request
Query Parameters
symbol
required
string
Symbol Name. E.g. BTC-PERP-REV
limit
optional
integer
Number of trades returned. Default 500; Max 1000
Response
200: OK
Successfully retrieved recent trades
[
{
"price": "4.00000100",
"qty": "12.00000000",
"time": 1499865549590,
"isBuyerMaker": true
},...
]

Response:

name

type

example

description

price

float

0.055

The price of the trade

time

long

1537797044116

Current timestamp (ms)

qty

float

5

The quantity traded

isBuyerMaker

string

true

true= Order is a buy order when created, false = Order is a sell order when created

get
Kline/candlestick data

https://api.hbtc.com/openapi/quote/v1/klines
This endpoint retrieves kline data
Request
Response
Request
Query Parameters
symbol
required
string
Symbol Name. E.g. BTC-PERP-REV
interval
required
string
Interval of the Kline. Possible values include: 1m,5m,15m,30m,1h,1d,1w,1M
endTime
optional
number
Timestamp to the last datapoint.
limit
optional
integer
Default 500; Max 1000
Response
200: OK
Successfully retrieved kline data
[
[
1499040000000, // Open time
"0.01634790", // Open
"0.80000000", // High
"0.01575800", // Low
"0.01577100", // Close
"148976.11427815", // Volume
1499644799999, // Close time
"2434.19055334", // Quote asset volume
308, // Number of trades
"1756.87402397", // Taker buy base asset volume
"28.46694368" // Taker buy quote asset volume
]
]

Response:

name

type

example

description

''

long

1538728740000

Open Time

''

float

36.00000

Open

''

float

36.00000

High

''

float

36.00000

Low

''

float

36.00000

Close

''

float

148976.11427815

Trade volume amount

''

long

1538728740000

Close time

''

float

2434.19055334

Quote asset volume

''

integer

308

Number of trades

''

float

1756.87402397

Taker buy base asset volume

''

float

28.46694368

Taker buy quote asset volume

  • If startTime and endTime are not sent, the most recent klines are returned.

  • If the symbol is not sent, tickers for all symbols will be returned in an array.

  • base asset means the quantity is expressed as the amount of contracts that were received by the buyer.

    quote asset means the amount of tokens paid to acquire the contracts.

get
24hrs ticker price change statistics

https://api.hbtc.com/openapi/quote/v1/contract/ticker/24hr
24 hour price change statistics. Careful when accessing this no symbol.
Request
Response
Request
Path Parameters
symbol
optional
string
Symbol Name. E.g. BTC-SWAP
Response
200: OK
Successfully retrieved ticker statistics
## Single ticker
{
"time":1579424880100,
"symbol":"BTC-SWAP",
"bestBidPrice":"9079.1",
"bestAskPrice":"9079.5",
"volume":"61684269",
"quoteVolume":"553667621070",
"openInterest":"213245355",
"lastPrice":"9077.5",
"highPrice":"9179.8",
"lowPrice":"8840.8",
"openPrice":"8861.7"
}
## Multiple ticker info when symbol is omiited
[
{
"time":1579422004248,
"symbol":"BTC-SWAP-USDT",
"volume":"102696523",
"quoteVolume":"918742352316.6",
"openInterest":"213245355",
"lastPrice":"9092.9",
"highPrice":"9180.2",
"lowPrice":"8817.7",
"openPrice":"8817.7"
},...
]

Response:

name

type

example

description

time

long

1538728740000

Open Time

symbol

string

BTC-SWAP

Contract Name

bestBidPrice

float

4.000002000

Best Bid Price

bestAskPrice

float

4.000002000

Best Ask Price

lastPrice

float

4.000002000

Last Price

openPrice

float

99.0000000

Open Price

highPrice

float

100.0000000

High Price

lowPrice

float

0.10000000

Low Price

volume

float

8913.300000

Trade Volume

openInterest

float

21324243142

Open Interets

  • If the symbol is not sent, tickers for all symbols will be returned in an array.

Trade

Security Type: USER_DATA/TRADE

Endpoints under Trade require an API-key and a signature.

post
New Order

https://api.hbtc.com/openapi/contract/v1/order
Places order for a contract. This API endpoint requires your request to be signed.
Request
Response
Request
Headers
X-BH-APIKEY
optional
string
Your API key
Query Parameters
clientOrderId
required
string
A unique ID of the order (user defined)
symbol
required
string
Name of the contract
side
required
string
Direction of the order. Possible values include BUY_OPEN, SELL_OPEN, BUY_CLOSE, and SELL_CLOSE
orderType
required
string
The order type, possible type include: LIMIT, STOP
quantity
required
number
The number of contracts trading. For MARKET buy orders, quantity is the equivalent of amount.
leverage
required
string
Leverage of the order(NOT REQUIRED for *_CLOSE" orders)
price
optional
number
Price of the order. REQUIRED for (LIMIT & INPUT) orders.
priceType
optional
string
The price type, possible types include: INPUT(Default), OPPONENT, QUEUE, OVER, and MARKET.
triggerPrice
optional
number
The price at which the trigger order will be executed.
timeInForce
optional
string
Time in force for LIMIT orders. Possible values include GTC(Default),FOK,IOC,LIMIT_MAKER
Body Parameters
signature
required
string
Authentication is needed for this endpoint
timestamp
required
integer
Current unix timestamp(ms)
recvWindow
optional
integer
RecvWindow for this request.
Response
200: OK
Order successfully placed.
{
'time': '1570759718825',
'updateTime': '0',
'orderId': '469961015902208000',
'clientOrderId': '6423344174',
'symbol': 'BTC-PERP-REV',
'price': '8200',
'leverage': '12.08',
'origQty': '5',
'executedQty': '0',
'avgPrice': '0',
'marginLocked': '0.00005047',
'orderType': 'LIMIT',
'side': 'BUY_OPEN',
'fees': [],
'timeInForce': 'GTC',
'status': 'NEW',
'priceType': 'INPUT'
}

Response:

Name

type

example

description

time

long

1570759718825

Timestamp when the order is created.

updateTime

long

1551062936784

Last time this order was updated

orderId

integer

469961015902208000

ID of the order.

clientOrderId

string

213443

A unique ID of the order.

symbol

string

BTC-PERP-REV

Name of the contract.

price

float

8200

Price of the order.

leverage

float

4

Leverage of the order.

origQty

float

1.01

Quantity ordered

executedQty

float

1.01

Quantity of orders that has been executed

avgPrice

float

4754.24

Average price of filled orders.

marginLocked

float

200

Amount of margin locked for this order. This includes the actually margin needed plus fees to open and close the position.

orderType

string

YES

The order type, possible types: LIMIT, STOP

priceType

string

INPUT

The price type. Possible values include INPUT, OPPONENT, QUEUE, OVER, and MARKET.

side

string

BUY

Direction of the order. Possible values include BUY_OPEN, SELL_OPEN, BUY_CLOSE, and SELL_CLOSE.

status

string

NEW

The state of the order.Possible values include NEW, PARTIALLY_FILLED, FILLED, CANCELED, and REJECTED.

timeInForce

string

GTC

Time in force. Possible values include GTC,FOK,IOC, and LIMIT_MAKER

fees

Fees incurred for this order.

  • Notes:

    • For Market Orders, you need to set orderType as LIMIT AND priceType as MARKET.

    • You can get contracts' price, quantity precision configuration data in the brokerInfo endpoint.

    • If your balance does not meet the margin requirement (which is the minimum margin requirement + open position fee + close position fee), "insufficient balance" error message will be returned.

    • For detailed information regarding various price types and order types. Please refer to the explanation section in the end.

  • Weight: 1

get
Query Order

https://api.hbtc.com/openapi/contract/v1/getOrder
Get details on a specific order, regardless of order state.
Request
Response
Request
Headers
X-BH-APIKEY
required
string
Your API key
Query Parameters
orderType
required
string
The order type, possible types: LIMIT, STOP
orderId
optional
string
Order Id. E.g. 507904211109878016
clientOrderId
optional
string
Client Order Id. A unique ID of the order (user defined). E.g. 12094ahsihsiad
Body Parameters
signature
required
string
Authentication is needed for this endpoint
timestamp
required
integer
Current unix timestamp(ms)
recvWindow
optional
integer
RecvWindow for this request.
Response
200: OK
Successfully retrieved order information
{
'time': '1570760254539',
'updateTime': '0',
'orderId': '469965509788581888',
'clientOrderId': '1570760253946',
'symbol': 'BTC-PERP-REV',
'price': '8502.34',
'leverage': '20',
'origQty': '222',
'executedQty': '0',
'avgPrice': '0',
'marginLocked': '0.00130552',
'orderType': 'LIMIT',
'side': 'BUY_OPEN',
'fees': [],
'timeInForce': 'GTC',
'status': 'NEW',
'priceType': 'INPUT'
}

Response:

Name

type

example

description

time

long

1551062936784

Timestamp when the order is created.

updateTime

long

1551062936784

Last time this order was updated

orderId

integer

891

ID of the order.

clientOrderId

string

213443

A unique ID of the order.

symbol

string

BTC-PERP-REV

Name of the contracts.

price

float

4765.29

Price of the order.

leverage

float

4

Leverage of the order.

origQty

float

1.01

Quantity ordered

executedQty

float

1.01

Quantity of orders that has been executed

avgPrice

float

4754.24

Average price of filled orders.

marginLocked

float

200

Amount of margin locked for this order. This includes the actually margin needed plus fees to open and close the position.

orderType

string

LIMIT

The order type, possible types: LIMIT and STOP.

priceType

string

INPUT

The price type. Possible values include INPUT, OPPONENT, QUEUE, OVER, and MARKET.

side

string

BUY_OPEN

Direction of the order. Possible values include BUY_OPEN, SELL_OPEN, BUY_CLOSE, and SELL_CLOSE.

status

string

NEW

The state of the order.Possible values include NEW, PARTIALLY_FILLED, FILLED, CANCELED, and REJECTED.

timeInForce

string

GTC

Time in force. Possible values include GTC,FOK,IOC, and LIMIT_MAKER.

fees

Fees incurred for this order.

  • Weight: 1

  • Either orderId or clientOrderId must be sent

  • For some historical orders cummulativeQuoteQty will be < 0, meaning the data is not available at this time.

delete
Cancel Order

https://api.hbtc.com/openapi/contract/v1/order/cancel
Cancel an active order
Request
Response
Request
Headers
X-BH-APIKEY
required
string
Your API key
Query Parameters
orderType
required
string
The order type, possible types: LIMIT and STOP.
orderId
optional
string
Order Id. E.g. 507904211109878016
clientOrderId
optional
string
Client Order Id. A unique ID of the order (user defined). E.g. 12094ahsihsiad
Body Parameters
signature
required
string
Authentication is needed for this endpoint
timestamp
required
integer
Current unix timestamp(ms)
recvWindow
optional
integer
RecvWindow for this request.
Response
200: OK
Successfully cancelled the order.
{
'time': '1570759718825',
'updateTime': '0',
'orderId': '469961015902208000',
'clientOrderId': '6423344174',
'symbol': 'BTC-PERP-REV',
'price': '8200',
'leverage': '12.08',
'origQty': '5',
'executedQty': '0',
'avgPrice': '0',
'marginLocked': '0',
'orderType': 'LIMIT',
'side': 'BUY_OPEN',
'fees': [],
'timeInForce': 'GTC',
'status': 'CANCELED',
'priceType': 'INPUT' //status will always be `CANCELED` for cancel request
}

Response:

Name

type

example

description

time

long

1551062936784

Timestamp when the order is created.

updateTime

long

1551062936784

Last time this order was updated

orderId

integer

891

ID of the order.

clientOrderId

string

213443

A unique ID of the order.

symbol

string

BTC-PERP-REV

Name of the contract.

price

float

4765.29

Price of the order.

leverage

float

4

Leverage of the order.

origQty

float

1.01

Quantity ordered

executedQty

float

1.01

Quantity of orders that has been executed

avgPrice

float

4754.24

Average price of filled orders.

marginLocked

float

200

Amount of margin locked for this order. This includes the actually margin needed plus fees to open and close the position.

orderType

string

LIMIT

The order type, possible types: LIMIT and STOP.

priceType

string

INPUT

The price type. Possible values include INPUT, OPPONENT, QUEUE, OVER, and MARKET.

side

string

BUY_OPEN

Direction of the order. Possible values include BUY_OPEN, BUY_CLOSE, SELL_OPEN and SELL_CLOSE

status

string

NEW

The state of the order.Possible values include NEW, PARTIALLY_FILLED, FILLED, CANCELED, and REJECTED.

timeInForce

string

GTC

Time in force. Possible values include GTC,FOK,IOC, and LIMIT_MAKER

fees

Fees incurred for this order.

In the fees field:

Name

type

example

description

feeToken

string

USDT

Fee token kind.

fee

float

0

Actual transaction fees occurred.

  • Weight: 1

  • Either orderId or clientOrderId must be sent

delete
Batch Cancel

https://api.hbtc.com/openapi/contract/v1/order/batchCancel
Cancel orders en masse. (PENDING: batch cancel for STOP orders)
Request
Response
Request
Headers
X-BH-APIKEY
required
string
Your API key
Query Parameters
symbol
optional
string
Contract Name. E.g. BTC-PERP-REV
Body Parameters
signature
required
string
Authentication is needed for this endpoint
timestamp
required
integer
Current unix timestamp(ms)
recvWindow
optional
integer
RecvWindow for this request.
Response
200: OK
Successfully sent out cancel request.
{
'message':'success',
'timestamp':1541161088303
}

Response:

Name

type

example

description

message

string

success

The message response of the cancel request.

timestamp

long

1541161088303

The timestamp when the response is returned.

get
Current Open Orders

https://api.hbtc.com/openapi/contract/v1/openOrders
Get all open orders on a symbol. Careful when accessing this with no symbols.
Request
Response
Request
Headers
X-BH-APIKEY
required
string
Your API key
Query Parameters
orderType
optional
string
The order type, possible types: LIMIT and STOP.
symbol
optional
string
Symbol to return open orders for. If not sent, orders of all contracts will be returned.
orderId
optional
string
Order Id
limit
optional
integer
Default 20; Max 1000
Body Parameters
signature
required
string
Authentication is needed for this endpoint
timestamp
required
integer
Current unix timestamp(ms)
recvWindow
optional
integer
RecvWindow for this request.
Response
200: OK
Successfully retrieved current open orders
[
{
'time': '1570760254539',
'updateTime': '0',
'orderId': '469965509788581888',
'clientOrderId': '1570760253946',
'symbol': 'BTC-PERP-REV',
'price': '8502.34',
'leverage': '20',
'origQty': '222',
'executedQty': '0',
'avgPrice': '0',
'marginLocked': '0.00130552',
'orderType': 'LIMIT',
'side': 'BUY_OPEN',
'fees': [],
'timeInForce': 'GTC',
'status': 'NEW',
'priceType': 'INPUT'
},...
]

Response:

Name

type

example

description

time

long

1551062936784

Timestamp when the order is created.

updateTime

long

1551062936784

Last time this order was updated

orderId

integer

891

ID of the order.

clientOrderId

string

213443

A unique ID of the order.

symbol

string

BTC-PERP-REV

Name of the contracts.

price

float

4765.29

Price of the order.

leverage

float

4

Leverage of the order.

origQty

float

1.01

Quantity ordered

executedQty

float

1.01

Quantity of orders that has been executed

avgPrice

float

4754.24

Average price of filled orders.

marginLocked

float

200

Amount of margin locked for this order. This includes the actually margin needed plus fees to open and close the position.

orderType

string

LIMIT

The order type, possible types: LIMIT and STOP.

priceType

string

INPUT

The price type. Possible values include INPUT, OPPONENT, QUEUE, OVER, and MARKET.

side

string

BUY_OPEN

Direction of the order. Possible values include BUY_OPEN, SELL_OPEN, BUY_CLOSE, and SELL_CLOSE.

status

string

NEW

The state of the order.Possible values include NEW, PARTIALLY_FILLED, FILLED, CANCELED, and REJECTED.

timeInForce

string

GTC

Time in force. Possible values include GTC,FOK,IOC, and LIMIT_MAKER.

fees

Fees incurred for this order.

  • Weight: 1

  • If orderId is set, it will get orders < that orderId. Otherwise most recent orders are returned.

get
History Orders

https://api.hbtc.com/openapi/contract/v1/historyOrders
Get all history orders. Careful when accessing this with no symbol.
Request
Response
Request
Headers
X-BH-APIKEY
required
string
Your API key
Query Parameters
orderType
optional
string
The order type, possible types: LIMIT, STOP
symbol
optional
string
Symbol Name. E.g. BTC-PERP-REV
orderId
optional
integer
Order Id. E.g. 507904211109878016
limit
optional
integer
Default 500; Max 1000
Body Parameters
signature
required
string
Authentication is needed for this endpoint
timestamp
required
integer
Current unix timestamp(ms)
recvWindow
optional
integer
RecvWindow for this request.
Response
200: OK
Successfully retrieved history orders.
[
{
'time': '1570759718825',
'updateTime': '0',
'orderId': '469961015902208000',
'clientOrderId': '6423344174',
'symbol': 'BTC-PERP-REV',
'price': '8200',
'leverage': '12.08',
'origQty': '5',
'executedQty': '0',
'avgPrice': '0',
'marginLocked': '0',
'orderType': 'LIMIT',
'side': 'BUY_OPEN',
'fees': [],
'timeInForce': 'GTC',
'status': 'CANCELED',
'priceType': 'INPUT'
},...
]

Response:

Name

type

example

description

time

long

1551062936784

Timestamp when the order is created.

updateTime

long

1551062936784

Last time this order was updated

orderId

integer

891

ID of the order.

clientOrderId

string

213443

A unique ID of the order.

symbol

string

BTC-PERP-REV

Name of the contracts.

price

float

4765.29

Price of the order.

leverage

float

4

Leverage of the order.

origQty

float

1.01

Quantity ordered

executedQty

float

1.01

Quantity of orders that has been executed

avgPrice

float

4754.24

Average price of filled orders.

marginLocked

float

200

Amount of margin locked for this order. This includes the actually margin needed plus fees to open and close the position.

orderType

string

LIMIT

The order type, possible types: LIMIT and STOP.

priceType

string

INPUT

The price type. Possible values include INPUT, OPPONENT, QUEUE, OVER, and MARKET.

side

string

BUY_OPEN

Direction of the order. Possible values include BUY_OPEN, SELL_OPEN, BUY_CLOSE, and SELL_CLOSE.

status

string

NEW

The state of the order.Possible values include NEW, PARTIALLY_FILLED, FILLED, CANCELED, and REJECTED.

timeInForce

string

GTC

Time in force. Possible values include GTC,FOK,IOC, and LIMIT_MAKER.

fees

Fees incurred for this order.

  • Weight: 5

  • If orderId is set, it will get orders < that orderId. Otherwise most recent orders are returned.

get
Trades

https://api.hbtc.com/openapi/contract/v1/myTrades
Get historical trades.
Request
Response
Request
Headers
X-BH-APIKEY
required
string
Your API key
Query Parameters
symbol
optional
string
Symbol Name. E.g. BTC-PERP-REV
fromId
optional
integer
Trade Id to fetch from
toId
optional
integer
Trade Id to fetch to
limit
optional
integer
Default 20; Max 1000
Body Parameters
signature
required
string
Authentication is needed for this endpoint
timestamp
required
integer
Current unix timestamp(ms)
recvWindow
optional
integer
RecvWindow for this request.
Response
200: OK
Successfully retrieved historical trades.
[
{
'time': '1570760582848',
'tradeId': '469968263995080704',
'orderId': '469968263793737728',
'accountId': '456552319339779840',
'symbolId': 'BTC-PERP-REV',
'price': '8531.17',
'quantity': '100',
'feeTokenId': 'TBTC',
'fee': '0.00000586',
'type': 'LIMIT',
'side': 'BUY_OPEN'
},...
]

Response: