Public Rest API (2018-09-25)

General API Information

  • All endpoints return either a JSON object or array.

  • Data is returned in ascending order. Oldest first, newest last.

  • All time and timestamp related fields are in milliseconds.

  • HTTP 4XX return codes are used for for malformed requests; the issue is on the sender's side.

  • HTTP 429 return code is used when breaking a request rate limit.

  • HTTP 418 return code is used when an IP has been auto-banned for continuing to send requests after receiving 429 codes.

  • HTTP 5XX return codes are used for internal errors; the issue is on exchange's side. It is important to NOT treat this as a failure operation; the execution status is UNKNOWN and could have been a success.

  • Any endpoint can return an ERROR; the error payload is as follows:

{
  "code": -1121,
  "msg": "Invalid symbol."
}

  • Specific error codes and messages defined in another document.

  • For GET endpoints, parameters must be sent as a query string.

  • For POST, PUT, and DELETE endpoints, the parameters may be sent as a query string or in the request body with content type application/x-www-form-urlencoded. You may mix parameters between both the query string and request body if you wish to do so.

  • Parameters may be sent in any order.

  • If a parameter sent in both the query string and request body, the query string parameter will be used.

LIMITS

  • The /openapi/v1/exchange rateLimits array contains objects related to the exchange's REQUEST_WEIGHT and ORDER rate limits.

  • A 429 will be returned when either rate limit is violated.

  • Each route has a weight which determines for the number of requests each endpoint counts for. Heavier endpoints and endpoints that do operations on multiple symbols will have a heavier weight.

  • When a 429 is recieved, it's your obligation as an API to back off and not spam the API.

  • Repeatedly violating rate limits and/or failing to back off after receiving 429s will result in an automated IP ban (http status 418).

  • IP bans are tracked and scale in duration for repeat offenders, from 2 minutes to 3 days.

Endpoint security type

  • Each endpoint has a security type that determines the how you will interact with it.

  • API-keys are passed into the Rest API via the X-BH-APIKEY header.

  • API-keys and secret-keys are case sensitive.

  • API-keys can be configured to only access certain types of secure endpoints. For example, one API-key could be used for TRADE only, while another API-key can access everything except for TRADE routes.

  • By default, API-keys can access all secure routes.

Security Type
Description

NONE

Endpoint can be accessed freely.

TRADE

Endpoint requires sending a valid API-Key and signature.

USER_DATA

Endpoint requires sending a valid API-Key and signature.

USER_STREAM

Endpoint requires sending a valid API-Key.

MARKET_DATA

Endpoint requires sending a valid API-Key.

  • TRADE and USER_DATA endpoints are SIGNED endpoints.

SIGNED (TRADE and USER_DATA) Endpoint security

  • SIGNED endpoints require an additional parameter, signature, to be sent in the query string or request body.

  • Endpoints use HMAC SHA256 signatures. The HMAC SHA256 signature is a keyed HMAC SHA256 operation. Use your secretKey as the key and totalParams as the value for the HMAC operation.

  • The signature is not case sensitive.

  • totalParams is defined as the query string concatenated with the request body.

Timing security

  • A SIGNED endpoint also requires a parameter, timestamp, to be sent which should be the millisecond timestamp of when the request was created and sent.

  • An additional parameter, recvWindow, may be sent to specify the number of milliseconds after timestamp the request is valid for. If recvWindow is not sent, it defaults to 5000.

  • Currently, recvWindow is only used when creates order.

  • The logic is as follows:

    if (timestamp < (serverTime + 1000) && (serverTime - timestamp) <= recvWindow) {
  // process request
} else {
  // reject request
}

Serious trading is about timing. Networks can be unstable and unreliable, which can lead to requests taking varying amounts of time to reach the servers. With recvWindow, you can specify that the request must be processed within a certain number of milliseconds or be rejected by the server.

It recommended to use a small recvWindow of 5000 or less!

SIGNED Endpoint Examples for POST /openapi/v1/order

Here is a step-by-step example of how to send a vaild signed payload from the Linux command line using echo, openssl, and curl.

Key
Value

apiKey

tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW

secretKey

lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76

Parameter
Value

symbol

ETHBTC

side

BUY

type

LIMIT

timeInForce

GTC

quantity

1

price

0.1

recvWindow

5000

timestamp

1538323200000

Example 1: As a query string

  • queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000

  • HMAC SHA256 signature:

[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6

  • curl command:

(HMAC SHA256)
[linux]$ curl -H "X-BH-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'

Example 2: As a request body

  • requestBody: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000

  • HMAC SHA256 signature:

[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6

  • curl command:

(HMAC SHA256)
[linux]$ curl -H "X-BH-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order' -d 'symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC&quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=5f2750ad7589d1d40757a55342e621a44037dad23b5128cc70e18ec1d1c3f4c6'

Example 3: Mixed query string and request body

  • queryString: symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC

  • requestBody: quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000

  • HMAC SHA256 signature:

[linux]$ echo -n "symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTCquantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000" | openssl dgst -sha256 -hmac "lH3ELTNiFxCQTmi9pPcWWikhsjO04Yoqw3euoHUuOLC3GYBW64ZqzQsiOEHXQS76"
(stdin)= 885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa

  • curl command:

(HMAC SHA256)
[linux]$ curl -H "X-BH-APIKEY: tAQfOrPIZAhym0qHISRt8EFvxPemdBm5j5WMlkm3Ke9aFp0EGWC2CGM8GHV4kCYW" -X POST 'https://$HOST/openapi/v1/order?symbol=ETHBTC&side=BUY&type=LIMIT&timeInForce=GTC' -d 'quantity=1&price=0.1&recvWindow=5000&timestamp=1538323200000&signature=885c9e3dd89ccd13408b25e6d54c2330703759d7494bea6dd5a3d1fd16ba3afa'

Note that the signature is different in example 3. There is no & between "GTC" and "quantity=1".

Public API Endpoints

Terminology

  • base asset refers to the asset that is the quantity of a symbol.

  • quote asset refers to the asset that is the price of a symbol.

ENUM definitions

Symbol status:

  • TRADING

  • HALT

  • BREAK

Symbol type:

  • SPOT

Asset type:

  • CASH

  • MARGIN

Order status:

  • NEW

  • PARTIALLY_FILLED

  • FILLED

  • CANCELED

  • PENDING_CANCEL

  • REJECTED

Order types:

  • LIMIT

  • MARKET

  • LIMIT_MAKER

  • STOP_LOSS (unavailable now)

  • STOP_LOSS_LIMIT (unavailable now)

  • TAKE_PROFIT (unavailable now)

  • TAKE_PROFIT_LIMIT (unavailable now)

  • MARKET_OF_PAYOUT (unavailable now)

Order side:

  • BUY

  • SELL

Time in force:

  • GTC

  • IOC

  • FOK

Kline/Candlestick chart intervals:

m -> minutes; h -> hours; d -> days; w -> weeks; M -> months

  • 1m

  • 3m

  • 5m

  • 15m

  • 30m

  • 1h

  • 2h

  • 4h

  • 6h

  • 8h

  • 12h

  • 1d

  • 3d

  • 1w

  • 1M

Rate limiters (rateLimitType)

  • REQUESTS_WEIGHT

  • ORDERS

Rate limit intervals

  • SECOND

  • MINUTE

  • DAY

General endpoints

Test connectivity

GET /openapi/v1/ping

Test connectivity to the Rest API.

Weight: 0

Parameters: NONE

Response:

{}

Check server time

GET /openapi/v1/time

Test connectivity to the Rest API and get the current server time.

Weight: 0

Parameters: NONE

Response:

{
  "serverTime": 1538323200000
}

Exchange information

GET /openapi/v1/exchange

Current trading rules and symbol information

Weight: 0

Parameters: NONE

Response:

{
  "timezone": "UTC",
  "serverTime": 1538323200000,
  "rateLimits": [{
      "rateLimitType": "REQUESTS_WEIGHT",
      "interval": "MINUTE",
      "limit": 1500
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "limit": 20
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "limit": 350000
    }
  ],
  "brokerFilters":[],
  "symbols": [{
    "symbol": "ETHBTC",
    "status": "TRADING",
    "baseAsset": "ETH",
    "baseAssetPrecision": "0.001",
    "quoteAsset": "BTC",
    "quotePrecision": "0.01",
    "icebergAllowed": false,
    "filters": [{
      "filterType": "PRICE_FILTER",
      "minPrice": "0.00000100",
      "maxPrice": "100000.00000000",
      "tickSize": "0.00000100"
    }, {
      "filterType": "LOT_SIZE",
      "minQty": "0.00100000",
      "maxQty": "100000.00000000",
      "stepSize": "0.00100000"
    }, {
      "filterType": "MIN_NOTIONAL",
      "minNotional": "0.00100000"
    }]
  }]
}

Market Data endpoints

Order book

GET /openapi/quote/v1/depth

Weight: Adjusted based on the limit:

Limit
Weight

5, 10, 20, 50, 100

1

500

5

1000

10

Parameters:

Name
Type
Mandatory
Description

symbol

STRING

YES

limit

INT

NO

Default 100; max 100.

Caution: setting limit=0 can return a lot of data.

Response:

[PRICE, QTY]

{
  "bids": [
    [
      "3.90000000",   // PRICE
      "431.00000000"  // QTY
    ],
    [
      "4.00000000",
      "431.00000000"
    ]
  ],
  "asks": [
    [
      "4.00000200",  // PRICE
      "12.00000000"  // QTY
    ],
    [
      "5.10000000",
      "28.00000000"
    ]
  ]
}

Recent trades list

GET /openapi/quote/v1/trades

Get recent trades (up to last 500).

Weight: 1

Parameters:

Name
Type
Mandatory
Description

symbol

STRING

YES

limit

INT

NO

Default 500; max 1000.

Response:

[
  {
    "price": "4.00000100",
    "qty": "12.00000000",
    "time": 1499865549590,
    "isBuyerMaker": true
  }
]

Kline/Candlestick data

GET /openapi/quote/v1/klines

Kline/candlestick bars for a symbol. Klines are uniquely identified by their open time.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

symbol

STRING

YES

interval

ENUM

YES

startTime

LONG

NO

endTime

LONG

NO

limit

INT

NO

Default 500; max 1000.

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

Response:

[
  [
    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
  ]
]

24hr ticker price change statistics

GET /openapi/quote/v1/ticker/24hr

24 hour price change statistics. Careful when accessing this with no symbol.

Weight: 1 for a single symbol; 40 when the symbol parameter is omitted

Parameters:

Name
Type
Mandatory
Description

symbol

STRING

NO

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

Response:

{
  "time": 1538725500422,
  "symbol": "ETHBTC",
  "bestBidPrice": "4.00000200",
  "bestAskPrice": "4.00000200",
  "lastPrice": "4.00000200",
  "openPrice": "99.00000000",
  "highPrice": "100.00000000",
  "lowPrice": "0.10000000",
  "volume": "8913.30000000"
}

OR

[
  {
    "time": 1538725500422,
    "symbol": "ETHBTC",
    "lastPrice": "4.00000200",
    "openPrice": "99.00000000",
    "highPrice": "100.00000000",
    "lowPrice": "0.10000000",
    "volume": "8913.30000000"
 }
]

Symbol price ticker

GET /openapi/quote/v1/ticker/price

Latest price for a symbol or symbols.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

symbol

STRING

NO

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

Response:

{
  "price": "4.00000200"
}

OR

[
  {
    "symbol": "LTCBTC",
    "price": "4.00000200"
  },
  {
    "symbol": "ETHBTC",
    "price": "0.07946600"
  }
]

Symbol order book ticker

GET /openapi/quote/v1/ticker/bookTicker

Best price/qty on the order book for a symbol or symbols.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

symbol

STRING

NO

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

Response:

{
  "symbol": "LTCBTC",
  "bidPrice": "4.00000000",
  "bidQty": "431.00000000",
  "askPrice": "4.00000200",
  "askQty": "9.00000000"
}

OR

[
  {
    "symbol": "LTCBTC",
    "bidPrice": "4.00000000",
    "bidQty": "431.00000000",
    "askPrice": "4.00000200",
    "askQty": "9.00000000"
  },
  {
    "symbol": "ETHBTC",
    "bidPrice": "0.07946700",
    "bidQty": "9.00000000",
    "askPrice": "100000.00000000",
    "askQty": "1000.00000000"
  }
]

Account endpoints

New order (TRADE)

POST /openapi/v1/order  (HMAC SHA256)

Send in a new order.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

symbol

STRING

YES

assetType

STRING

NO

side

ENUM

YES

type

ENUM

YES

timeInForce

ENUM

NO

quantity

DECIMAL

YES

price

DECIMAL

NO

newClientOrderId

STRING

NO

A unique id for the order. Automatically generated if not sent.

stopPrice

DECIMAL

NO

Used with STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders. Unavailable

icebergQty

DECIMAL

NO

Used with LIMIT, STOP_LOSS_LIMIT, and TAKE_PROFIT_LIMIT to create an iceberg order. Unavailable

recvWindow

LONG

NO

timestamp

LONG

YES

Additional mandatory parameters based on type:

Type
Additional mandatory parameters

LIMIT

timeInForce, quantity, price

MARKET

quantity

STOP_LOSS

quantity, stopPrice

STOP_LOSS_LIMIT

timeInForce, quantity, price, stopPrice

TAKE_PROFIT

quantity, stopPrice

TAKE_PROFIT_LIMIT

timeInForce, quantity, price, stopPrice

LIMIT_MAKER

quantity, price

Other info:

  • LIMIT_MAKER are LIMIT orders that will be rejected if they would immediately match and trade as a taker.

  • STOP_LOSS and TAKE_PROFIT will execute a MARKET order when the stopPrice is reached.

  • Any LIMIT or LIMIT_MAKER type order can be made an iceberg order by sending an icebergQty.

  • Any order with an icebergQty MUST have timeInForce set to GTC.

Trigger order price rules against market price for both MARKET and LIMIT versions:

  • Price above market price: STOP_LOSS BUY, TAKE_PROFIT SELL

  • Price below market price: STOP_LOSS SELL, TAKE_PROFIT BUY

Response:

{
  "orderId": 28,
  "clientOrderId": "6k9M212T12092"
}

Test new order (TRADE)

POST /openapi/v1/order/test (HMAC SHA256)

Test new order creation and signature/recvWindow long. Creates and validates a new order but does not send it into the matching engine.

Weight: 1

Parameters:

Same as POST /openapi/v1/order

Response:

{}

Query order (USER_DATA)

GET /openapi/v1/order (HMAC SHA256)

Check an order's status.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

orderId

LONG

NO

origClientOrderId

STRING

NO

recvWindow

LONG

NO

timestamp

LONG

YES

Notes:

  • Either orderId or origClientOrderId must be sent.

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

Response:

{
  "symbol": "LTCBTC",
  "orderId": 1,
  "clientOrderId": "9t1M2K0Ya092",
  "price": "0.1",
  "origQty": "1.0",
  "executedQty": "0.0",
  "cummulativeQuoteQty": "0.0",
  "avgPrice": "0.0",
  "status": "NEW",
  "timeInForce": "GTC",
  "type": "LIMIT",
  "side": "BUY",
  "stopPrice": "0.0",
  "icebergQty": "0.0",
  "time": 1499827319559,
  "updateTime": 1499827319559,
  "isWorking": true
}

Cancel order (TRADE)

DELETE /openapi/v1/order  (HMAC SHA256)

Cancel an active order.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

orderId

LONG

NO

clientOrderId

STRING

NO

recvWindow

LONG

NO

timestamp

LONG

YES

Either orderId or clientOrderId must be sent.

Response:

{
  "symbol": "LTCBTC",
  "clientOrderId": "tU721112KM",
  "orderId": 1,
  "status": "CANCELED"
}

Current open orders (USER_DATA)

GET /openapi/v1/openOrders  (HMAC SHA256)

GET all open orders on a symbol. Careful when accessing this with no symbol.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

symbol

String

NO

orderId

LONG

NO

limit

INT

NO

Default 500; max 1000.

recvWindow

LONG

NO

timestamp

LONG

YES

Notes:

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

Response:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "t7921223K12",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "avgPrice": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true
  }
]

History orders (USER_DATA)

GET /openapi/v1/historyOrders (HMAC SHA256)

GET all orders of the account; canceled, filled or rejected.

Weight: 5

Parameters:

Name
Type
Mandatory
Description

symbol

String

NO

orderId

LONG

NO

startTime

LONG

NO

endTime

LONG

NO

limit

INT

NO

Default 500; max 1000.

recvWindow

LONG

NO

timestamp

LONG

YES

Notes:

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

Response:

[
  {
    "symbol": "LTCBTC",
    "orderId": 1,
    "clientOrderId": "987yjj2Ym",
    "price": "0.1",
    "origQty": "1.0",
    "executedQty": "0.0",
    "cummulativeQuoteQty": "0.0",
    "avgPrice": "0.0",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "stopPrice": "0.0",
    "icebergQty": "0.0",
    "time": 1499827319559,
    "updateTime": 1499827319559,
    "isWorking": true
  }
]

Account information (USER_DATA)

GET /openapi/v1/account (HMAC SHA256)

GET current account information.

Weight: 5

Parameters:

Name
Type
Mandatory
Description

recvWindow

LONG

NO

timestamp

LONG

YES

Response:

{
  "canTrade": true,
  "canWithdraw": true,
  "canDeposit": true,
  "updateTime": 123456789,
  "balances": [
    {
      "asset": "BTC",
      "free": "4723846.89208129",
      "locked": "0.00000000"
    },
    {
      "asset": "LTC",
      "free": "4763368.68006011",
      "locked": "0.00000000"
    }
  ]
}

Account trade list (USER_DATA)

GET /openapi/v1/myTrades  (HMAC SHA256)

GET trades for a specific account.

Weight: 5

Parameters:

Name
Type
Mandatory
Description

startTime

LONG

NO

endTime

LONG

NO

fromId

LONG

NO

TradeId to fetch from.

toId

LONG

NO

TradeId to fetch to.

limit

INT

NO

Default 500; max 1000.

recvWindow

LONG

NO

timestamp

LONG

YES

Notes:

  • If only fromId is set，it will get orders < that fromId in descending order.

  • If only toId is set, it will get orders > that toId in ascending order.

  • If fromId is set and toId is set, it will get orders < that fromId and > that toId in descending order.

  • If fromId is not set and toId it not set, most recent order are returned in descending order.

Response:

[
  {
    "symbol": "ETHBTC",
    "id": 28457,
    "orderId": 100234,
    "matchOrderId": 109834,
    "price": "4.00000100",
    "qty": "12.00000000",
    "commission": "10.10000000",
    "commissionAsset": "ETH",
    "time": 1499865549590,
    "isBuyer": true,
    "isMaker": false,
    "feeTokenId": "ETH",
    "fee": "0.012"
  }
]

Account deposit list (USER_DATA)

GET /openapi/v1/depositOrders  (HMAC SHA256)

GET deposit orders for a specific account.

Weight: 5

Parameters:

Name
Type
Mandatory
Description

startTime

LONG

NO

endTime

LONG

NO

fromId

LONG

NO

Deposit OrderId to fetch from. Default gets most recent deposit orders.

limit

INT

NO

Default 500; max 1000.

recvWindow

LONG

NO

timestamp

LONG

YES

Notes:

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

Response:

[
  {
	"orderId": 100234,
	"token": "EOS",
	"address": "deposit2bh",
	"addressTag": "19012584",
	"fromAddress": "clarkkent",
	"fromAddressTag": "19029901",
	"time": 1499865549590,
	"quantity": "1.01"
  }
]

User data stream endpoints

Specifics on how user data streams work is in another document.

Start user data stream (USER_STREAM)

POST /openapi/v1/userDataStream

Start a new user data stream. The stream will close after 60 minutes unless a keepalive is sent.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

recvWindow

LONG

NO

timestamp

LONG

YES

Response:

{
  "listenKey": "1A9LWJjuMwKWYP4QQPw34GRm8gz3x5AephXSuqcDef1RnzoBVhEeGE963CoS1Sgj"
}

Keepalive user data stream (USER_STREAM)

PUT /openapi/v1/userDataStream

Keepalive a user data stream to prevent a time out. User data streams will close after 60 minutes. It's recommended to send a ping about every 30 minutes.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

listenKey

STRING

YES

recvWindow

LONG

NO

timestamp

LONG

YES

Response:

{}

Close user data stream (USER_STREAM)

DELETE /openapi/v1/userDataStream

Close out a user data stream.

Weight: 1

Parameters:

Name
Type
Mandatory
Description

listenKey

STRING

YES

recvWindow

LONG

NO

timestamp

LONG

YES

Response:

{}

Sub-account list(SUB_ACCOUNT_LIST)

POST /openapi/v1/subAccount/query

Query sub-account lists

Parameters:

None

Weight: 5

Response:

[
    {
        "accountId": "122216245228131",
        "accountName": "",
        "accountType": 1,
        "accountIndex": 0 // main-account: 0, sub-account: 1
    },
    {
        "accountId": "482694560475091200",
        "accountName": "createSubAccountByCurl", // sub-account name
        "accountType": 1, // sub-account type 1. token trading 3. contract trading
        "accountIndex": 1
    },
    {
        "accountId": "422446415267060992",
        "accountName": "",
        "accountType": 3,
        "accountIndex": 0
    },
    {
        "accountId": "482711469199298816",
        "accountName": "createSubAccountByCurl",
        "accountType": 3,
        "accountIndex": 1
    },
]

Internal Account Transfer (ACCOUNT_TRANSFER)

POST /openapi/v1/transfer

Internal transfer

Weight: 1

Parameters:

Name
Typee
Mandatory
Description

fromAccountType

int

YES

source account type: 1. token trading account 2.Options account 3. Contracts account

fromAccountIndex

int

YES

sub-account index(valid when using main-account api, get sub-account indices from SUB_ACCOUNT_LIST endpoint)

toAccountType

int

YES

Target account type: 1. token trading account 2.Options account 3. Contracts account

toAccountIndex

int

YES

sub-account index(valid when using main-account api, get sub-account indices from SUB_ACCOUNT_LIST endpoint)

tokenId

STRING

YES

tokenID

amount

STRING

YES

Transfer amount

Response:

{
    "success":"true" // success
}

Explanation

  1. Either transferring or receiving account must be the main account (Token trading account)

  2. Main account api can support transferring to other account(including sub-accounts) and receiving from other accounts

  3. Sub-account API only supports transferring from current account to the main-account. Therefore fromAccountType\fromAccountIndex\toAccountType\toAccountIndex should be left empty.

Check Balance Flow (BALANCE_FLOW)

POST /openapi/v1/balance_flow

Check blance flow

Weight: 5

Parameters:

Name
Type
Mandatory
Description

accountType

int

no

Account account_type

accountIndex

int

no

Account account_index

tokenId

string

no

token_id

fromFlowId

long

no

endFlowId

long

no

startTime

long

no

Start Time

endTime

long

no

End Time

limit

integer

no

Number of entries

Response:

[
    {
        "id": "539870570957903104",
        "accountId": "122216245228131",
        "tokenId": "BTC",
        "tokenName": "BTC",
        "flowTypeValue": 51, // balance flow type
        "flowType": "USER_ACCOUNT_TRANSFER", // balance flow type name
        "flowName": "Transfer", // balance flow type Explanation
        "change": "-12.5", // change
        "total": "379.624059937852365", // total asset after change
        "created": "1579093587214"
    },
    {
        "id": "536072393645448960",
        "accountId": "122216245228131",
        "tokenId": "USDT",
        "tokenName": "USDT",
        "flowTypeValue": 7,
        "flowType": "AIRDROP",
        "flowName": "Airdrop",
        "change": "-2000",
        "total": "918662.0917630848",
        "created": "1578640809195"
    }
]

Explanation

  1. Main-account API can query balance flow for token account and other accounts(including sub-accounts, or designated accountType and accountIndex accounts)

  2. Sub-account API can only query current sub-account, therefore accountType and accountIndex is not required.

Please see the following for balance flow types

Category
Parameter Type Name
Parameter Type Id
Explanation

General Balance Flow

TRADE

1

trades

General Balance Flow

FEE

2

trading fees

General Balance Flow

TRANSFER

3

transfer

General Balance Flow

DEPOSIT

4

deposit

Derivatives

MAKER_REWARD

27

maker reward

Derivatives

PNL

28

PnL from contracts

Derivatives

SETTLEMENT

30

Settlement

Derivatives

LIQUIDATION

31

Liquidation

Derivatives

FUNDING_SETTLEMENT

32

期货等的资金费率结算

Internal Transfer

USER_ACCOUNT_TRANSFER

51

userAccountTransfer 专用，流水没有subjectExtId

OTC

OTC_BUY_COIN

65

OTC buy coin

OTC

OTC_SELL_COIN

66

OTC sell coin

OTC

OTC_FEE

73

OTC fees

OTC

OTC_TRADE

200

Old OTC balance flow

Campaign

ACTIVITY_AWARD

67

Campaign reward

Campaign

INVITATION_REFERRAL_BONUS

68

邀请返佣

Campaign

REGISTER_BONUS

69

Registration reward

Campaign

AIRDROP

70

Airdrop

Campaign

MINE_REWARD

71

Mining reward

Filters

Filters define trading rules on a symbol. Filters come in two forms: symbol filters and broker filters.

Symbol filters

PRICE_FILTER

The PRICE_FILTER defines the price rules for a symbol. There are 3 parts:

  • minPrice defines the minimum price/stopPrice allowed.

  • maxPrice defines the maximum price/stopPrice allowed.

  • tickSize defines the intervals that a price/stopPrice can be increased/decreased by.

In order to pass the price filter, the following must be true for price/stopPrice:

  • price >= minPrice

  • price <= maxPrice

  • (price-minPrice) % tickSize == 0

/exchange format:

  {
    "filterType": "PRICE_FILTER",
    "minPrice": "0.00000100",
    "maxPrice": "100000.00000000",
    "tickSize": "0.00000100"
  }

LOT_SIZE

The LOT_SIZE filter defines the quantity (aka "lots" in auction terms) rules for a symbol. There are 3 parts:

  • minQty defines the minimum quantity/icebergQty allowed.

  • maxQty defines the maximum quantity/icebergQty allowed.

  • stepSize defines the intervals that a quantity/icebergQty can be increased/decreased by.

In order to pass the lot size, the following must be true for quantity/icebergQty:

  • quantity >= minQty

  • quantity <= maxQty

  • (quantity-minQty) % stepSize == 0

/exchange format:

  {
    "filterType": "LOT_SIZE",
    "minQty": "0.00100000",
    "maxQty": "100000.00000000",
    "stepSize": "0.00100000"
  }

MIN_NOTIONAL

The MIN_NOTIONAL filter defines the minimum notional value allowed for an order on a symbol. An order's notional value is the price * quantity.

/exchange format:

  {
    "filterType": "MIN_NOTIONAL",
    "minNotional": "0.00100000"
  }

MAX_NUM_ORDERS

The MAX_NUM_ORDERS filter defines the maximum number of orders an account is allowed to have open on a symbol. Note that both "algo" orders and normal orders are counted for this filter.

/exchange format:

  {
    "filterType": "MAX_NUM_ORDERS",
    "limit": 25
  }

MAX_NUM_ALGO_ORDERS

The MAX_ALGO_ORDERS filter defines the maximum number of "algo" orders an account is allowed to have open on a symbol. "Algo" orders are STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.

/exchange format:

  {
    "filterType": "MAX_NUM_ALGO_ORDERS",
    "maxNumAlgoOrders": 5
  }

ICEBERG_PARTS

The ICEBERG_PARTS filter defines the maximum parts an iceberg order can have. The number of ICEBERG_PARTS is defined as CEIL(qty / icebergQty).

/exchange format:

  {
    "filterType": "ICEBERG_PARTS",
    "limit": 10
  }

Broker Filters

BROKER_MAX_NUM_ORDERS

The MAX_NUM_ORDERS filter defines the maximum number of orders an account is allowed to have open on the exchange. Note that both "algo" orders and normal orders are counted for this filter.

/exchange format:

  {
    "filterType": "BROKER_MAX_NUM_ORDERS",
    "limit": 1000
  }

BROKER_MAX_NUM_ALGO_ORDERS

The MAX_ALGO_ORDERS filter defines the maximum number of "algo" orders an account is allowed to have open on the exchange. "Algo" orders are STOP_LOSS, STOP_LOSS_LIMIT, TAKE_PROFIT, and TAKE_PROFIT_LIMIT orders.

/exchange format:

  {
    "filterType": "BROKER_MAX_NUM_ALGO_ORDERS",
    "limit": 200
  }

user transfer (TRANSFER)

POST /openapi/v1/user/transfer
PreviousOptions Open APINextUser Data Streams

Last updated