Interface Description

Feedback Email

Email: api@bg.exchange

request address

HTTP request address

HOST: https://api.bg.exchange/hk

WEBSOCKET request address

• WebSocket private channel (DEPRECATED): wss://ws.bg.exchange
• WebSocket public channel (DEPRECATED): wss://ws.bg.exchange/ws
• WebSocket public channel V2: wss://ws.bg.exchange/v2/ws
• WebSocket private channel V2: wss://ws.bg.exchange/v2/ws

Response Status

HTTP/1.1 400

{
  "code":1087,
  "message": "No data found"
}

HTTP/1.1 401

{
  "code":40001,
  "message": "ACCESS_KEY cannot be empty"
}

HTTP/1.1 500

{
  "code":500,
  "message":"Internal Server Error"
}

Glossary

Account Information

GET get all account balance information

Get all the trading account information of the user

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

GET HOST/v1/accounts

Authentication information

For authentication information of private information, please refer to Authentication Instructions

RESPONSE EXAMPLE

[
  {
    "available": "10.0001",
    "balance": "11.0001",
    "currency": "BTC",
    "hold": "1.0"
  }
]

GET get single account balance information

Get the trading account information specified by the user

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

GET HOST/v1/accounts/{currency}

Authentication information

For authentication information of private information, please refer to Authentication Instructions

RESPONSE EXAMPLE

{
  "available": "10.0001",
  "balance": "11.0001",
  "currency": "BTC",
  "hold": "1.0"
}

Transfer Of Funds

POST transfer from fund account to transaction account

Transfer funds from the fund account to the designated trading account

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

POST HOST/v1/deposits/accounttrue

Authentication information

For authentication information of private information, please refer to Authentication Instructions

REQUEST EXAMPLE

{
  "amount": 100,
  "currency": "HKD"
}

RESPONSE EXAMPLE

{
  "amount": 100,
  "currency": "HKD"
}

POST transfer from transaction account to fund account

Transfer the funds from the trading account to the capital account. After the transfer, you can carry out the cash withdrawal operation.

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

POST HOST/v1/withdrawals/accounttrue

Authentication information

For authentication information of private information, please refer to Authentication Instructions

REQUEST EXAMPLE

{
  "amount": 100,
  "currency": "HKD"
}

RESPONSE EXAMPLE

{
  "amount": 100,
  "currency": "HKD"
}

Product

GET get all known trading products

Get all trading product information

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/v1/products

RESPONSE EXAMPLE

[
  {
    "product": "ETH_USD",
    "base_currency": "ETH",
    "quote_currency": "USD",
    "display_name": "ETH_USD",
    "status": "on",
    "maker_fees_rate": "0.01",
    "taker_fees_rate": "0.02",
    "quote_precision": "5",
    "trade_precision": "8",
    "amount_precision": "6",
    "max_buy_price_rate": "1.000000",
    "max_sell_price_rate": "1.000000",
    "max_trade_usd_per_order": "",
    "min_trade_usd_per_order": "",
    "max_market_taker_trade_rate": "1.000000",
    "min_market_taker_trade_rate": "1.000000",
    "max_market_trade_usd_per_order": "",
    "min_market_trade_usd_per_order": ""
  }
]

product: product

base_currency: base asset name

quote_currency : quote asset name

display_name: The display name of the transaction product, which is used as the unique identifier of the transaction product when placing an order

status : trading product status - on: has been launched, the product is open for trading, and orders can be placed and traded normally. - off: offline. This product closes all transactions, and orders that already have pending orders will be automatically canceled by the system. - pause: Trading is paused, the product closes some trades, but existing pending orders will not be canceled

amount_precision: transaction currency amount unit precision

quote_precision: Quotation currency quantity unit precision

trade_precision: trade currency price unit precision

maker_fees_rate: Maker fee rate

taker_fees_rate: taker fee rate

max_buy_price_rate: The rate at which the limit buy price cannot be higher than the latest price. If the rate exceeds the rate, the order will fail.

max_sell_price_rate: The rate at which a limit sell order cannot be lower than the latest price. If the ratio is exceeded, the order will fail to be placed.

max_trade_usd_per_order: The maximum order amount per order at the limit price. The amount will be converted into USD for calculation.

min_trade_usd_per_order: The minimum order amount per order at the limit price. The amount will be converted into USD for calculation.

max_market_taker_trade_rate: The rate at which the market buy price cannot be higher than the latest price. If the rate exceeds the rate, the order will fail.

min_market_taker_trade_rate : The rate at which market taker orders cannot be lower than the latest price. If the ratio is exceeded, the order will fail to be placed.

max_market_trade_usd_per_order : The minimum order amount for a single order at the market price. The amount will be converted into USD for calculation.

min_market_trade_usd_per_order : The minimum order amount for a single order at the market price. The amount will be converted into USD for calculation.

GET Get Single Product Details

Get the specified trading product information

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/v1/products/{product}

RESPONSE EXAMPLE

[
  {
    "product": "ETH_USD",
    "base_currency": "ETH",
    "quote_currency": "USD",
    "display_name": "ETH_USD",
    "status": "on",
    "maker_fees_rate": "0.01",
    "taker_fees_rate": "0.02",
    "quote_precision": "5",
    "trade_precision": "8",
    "amount_precision": "6",
    "max_buy_price_rate": "1.000000",
    "max_sell_price_rate": "1.000000",
    "max_trade_usd_per_order": "",
    "min_trade_usd_per_order": "",
    "max_market_taker_trade_rate": "1.000000",
    "min_market_taker_trade_rate": "1.000000",
    "max_market_trade_usd_per_order": "",
    "min_market_trade_usd_per_order": ""
  }
]

product: product

base_currency: base asset name

quote_currency : quote asset name

display_name: The display name of the transaction product, which is used as the unique identifier of the transaction product when placing an order

status : trading product status - on: has been launched, the product is open for trading, and orders can be placed and traded normally. - off: offline. This product closes all transactions, and orders that already have pending orders will be automatically canceled by the system. - pause: Trading is paused, the product closes some trades, but existing pending orders will not be canceled

amount_precision: transaction currency amount unit precision

quote_precision: Quotation currency quantity unit precision

trade_precision: trade currency price unit precision

maker_fees_rate: Maker fee rate

taker_fees_rate: taker fee rate

max_buy_price_rate: The rate at which the limit buy price cannot be higher than the latest price. If the rate exceeds the rate, the order will fail.

max_sell_price_rate: The rate at which a limit sell order cannot be lower than the latest price. If the ratio is exceeded, the order will fail to be placed.

max_trade_usd_per_order: The maximum order amount per order at the limit price. The amount will be converted into USD for calculation.

min_trade_usd_per_order: The minimum order amount per order at the limit price. The amount will be converted into USD for calculation.

max_market_taker_trade_rate: The rate at which the market buy price cannot be higher than the latest price. If the rate exceeds the rate, the order will fail.

min_market_taker_trade_rate : The rate at which market taker orders cannot be lower than the latest price. If the ratio is exceeded, the order will fail to be placed.

max_market_trade_usd_per_order : The minimum order amount for a single order at the market price. The amount will be converted into USD for calculation.

min_market_trade_usd_per_order : The minimum order amount for a single order at the market price. The amount will be converted into USD for calculation.

Public Data V2

GET Kline

Get K-line data. The K-line data is grouped and returned according to the requested granularity, and the most recent 2,000 K-line data can be retrieved.

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/public/v2/products/{product}/candles

REQUEST EXAMPLE

GET /public/v2/products/ETH_USDT/candles?interval=1min&from=1639584000&to=1639584000&size=100

RESPONSE EXAMPLE

{
  "code": 200,
  "data":
  [
    {
      "id": 1690952460,
      "open": "3.5334",
      "close": "3.5334",
      "high": "3.5334",
      "low": "3.5334",
      "vol": "0",
      "count": 0,
      "filled_size": "0"
    },
    {
      "id": 1690952520,
      "open": "3.5334",
      "close": "3.5334",
      "high": "3.5334",
      "low": "3.5334",
      "vol": "0",
      "count": 0,
      "filled_size": "0"
    }
  ],
  "message": "OK"
}

GET order book

Get Order-book data. Order-book data is sorted by price from high to low, and those with the same price are sorted by time.

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/public/v2/products/{product}/orderbook

REQUEST EXAMPLE

GET /public/v2/products/ETH_USDT/orderbook?interval=0

RESPONSE EXAMPLE

{
  "code": 200,
  "data":
  {
    "bids":
    [
      [
        "5", //price
        "3.6" //quantity
      ],
      [
        "3.5334",
        "3"
      ]
    ],
    "asks":
    [],
    "seq_id": 18867339
  },
  "message": "OK"
}

GET 24-hour market data of all currency pairs

Get all product market information

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/public/v2/products/overview/tickers

REQUEST EXAMPLE

GET /public/v2/products/overview/tickers

RESPONSE EXAMPLE

{
  "code": 200,
  "data":
  [
    {
      "id": 1691132221,
      "product": "BTC_USDT",
      "open": "7.13",
      "close": "3.2713",
      "high": "7.13",
      "low": "2.9313",
      "vol": "1979.89",
      "count": 0,
      "change": "-3.8587",
      "seq_id": 22757,
      "filled_size": "6916.093957",
      "change_percent": "-0.5412"
    }
  ],
  "message": "OK"
}

GET single currency pair 24-hour market data

Obtain product market information

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/public/v2/products/{product}/ticker

REQUEST EXAMPLE

GET /public/v2/products/ETH_USDT/ticker

RESPONSE EXAMPLE

{
  "code": 200,
  "data":
  {
    "id": 1691132024,
    "product": "ETH_USDT",
    "open": "7.13",
    "close": "3.2713",
    "high": "7.13",
    "low": "2.9313",
    "vol": "1979.89",
    "count": 0,
    "change": "-3.8587",
    "seq_id": 22757,
    "filled_size": "6916.093957",
    "change_percent": "-0.5412"
  },
  "message": "OK"
}

GET single currency pair real-time transaction data

Get the latest deals list for products

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/public/v2/products/{product}/trades

REQUEST EXAMPLE

GET /public/v2/products/ETH_USDT/trades?size=1

RESPONSE EXAMPLE

{
  "code": 200,
  "data":
  [
    {
      "vol": "0.1",
      "ts": 1691029846352,
      "price": "5",
      "direction": "sell",
      "id": 17078143
    }
  ],
  "message": "OK"
}

Currency Information

GET Get all known currencies

Get information list of all currencies

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/v1/currencies

RESPONSE EXAMPLE

[
  {
    "currency": "ETH",
    "min_size": "0",
    "status": "on",
    "max_precision": "10",
    "type": "crypto",
    "deposit_status": "on",
    "withdraw_status": "on",
    "accuracy": "8",
    "details": [
      {
        "network_confirmations": "12",
        "sort_order": "3",
        "display_name": "ETH",
        "deposit_status": "on",
        "accuracy": "8",
        "withdraw_status": "on"
      }
    ]
  }
]

currency: currency name, which can uniquely identify the currency

accuracy: fiat deposit and withdrawal accuracy

max_precision : Maximum precision. Take the range in [18,-18]

• When max_precision >= 0, it means that the currency precision is max_precision digits after the decimal point;
• When max_precision < 0, it means that the precision of the currency is an integer, and the precision is the abs(max_precision) subdivision of 10

min_size: minimum deposit and withdrawal amount

status: currency status

type: Currency type, fiat is fiat currency, crypto is digital currency

details: chain information, only digital currency type will have this part of information

deposit_status: fiat deposit status

withdraw_status: fiat withdrawal status

• dispaly_name: display name
• network_confirmations: minimum number of network confirmations
• currency: currency name, which can uniquely identify the currency
• accuracy: crypto deposit and withdrawal accuracy
• deposit_status: crypto deposit status
• withdraw_status: crypto withdrawal status

GET get single currency information

Get the information of the specified currency

Speed Limit: None

Speed limit rules: None

HTTP request

GET HOST/v1/currencies/{currency}

RESPONSE EXAMPLE

[
  {
    "currency": "ETH",
    "min_size": "0",
    "status": "on",
    "max_precision": "10",
    "type": "crypto",
    "deposit_status": "on",
    "withdraw_status": "on",
    "accuracy": "8",
    "details": [
      {
        "network_confirmations": "12",
        "display_name": "ETH",
        "accuracy": "8",
        "deposit_status": "on",
        "withdraw_status": "on"
      }
    ]
  }
]

currency: currency name, which can uniquely identify the currency

accuracy: fiat deposit and withdrawal accuracy

max_precision : Maximum precision. Take the range in [18,-18]

• When max_precision >= 0, it means that the currency precision is max_precision digits after the decimal point;
• When max_precision < 0, it means that the precision of the currency is an integer, and the precision is the abs(max_precision) subdivision of 10

min_size: minimum deposit and withdrawal amount

status: currency status

type: Currency type, fiat is fiat currency, crypto is digital currency

details: chain information, only digital currency type will have this part of information

deposit_status: fiat deposit status

withdraw_status: fiat withdrawal status

• dispaly_name: display name
• network_confirmations: minimum number of network confirmations
• currency: currency name
• accuracy: crypto deposit and withdrawal accuracy
• deposit_status: crypto deposit status
• withdraw_status: crypto withdrawal status

Transactions And Orders

POST to create a new order

Orders can only be placed if your account has sufficient funds.

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

POST HOST/v1/orders

Authentication information

For authentication information of private information, please refer to Authentication Instructions

REQUEST EXAMPLE

{
  "product": "BTC_USDT",
  "side": "buy",
  "type": "limit",
  "stp": "dc",
  "price": "2.00",
  "size": "3.3000000000000000000",
  "client_oid": "QZ_2020-jj"
}

common parameters

product: Must be an existing product. For example BTC_USD. A list of products is available via products.

side: buy buys, sell sells.

type: order type

• limit: limit order
• market: market order

client_oid: Optional, default "0", user-defined order number, used for users to manage their own orders. The ID is non-unique, a string type with a length of no more than 32 characters, and must be composed of elements in uppercase and lowercase letters A-Z/a-z, numbers 0-9, underline_, and dash-, and special symbols other than those are not supported

stp: ie self trade prevention. BGE prohibits users from dealing with themselves. Users can use the stp option to specify the order processing strategy when the self-transaction scenario occurs.

• dc: ie decrease and cancel (default). When matching occurs with the same user order matching, the party with the larger quantity will be executed with the decrease command, and the party with the smaller amount will be executed with the cancel command. decrease or Or the quantity of cancel is the minimum value of the self-dealing matching of two orders.
• co: ie cancle oldest, when matching occurs with the same user order matching, the earlier pending order will be executed cancle command. New orders will continue to execute the normal transaction matching process.
• cn: that is cancle newest, when matching occurs with the same user order matching, the latest order will be executed cancle command, the earlier pending order still stays in the order book, and the normal transaction matching process will be executed.
• cb: that is cancle both, when the matching of the same user order occurs, the two matching orders will be executed cancle command.

time_in_force: optional, transaction command, currently supports GTC. The default is GTC

limit order parameters

price: item price

size: the quantity to buy or sell

market order parameters

size: expected transaction size. Require side to be sell, which means selling at the latest transaction price and expecting the maximum number of items sold.

funds: Expected transaction amount. side needs to be buy, which means buying at the latest transaction price and expecting to spend the maximum amount of assets.

RESPONSE EXAMPLE

{
  "order_id": 129149436110880967,
  "client_oid": "Order_ower_1233"
}

order_id: the order number generated by BGE

client_oid: user-defined order number

GET query a single order according to the system order number

Get the specified order information.

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

GET HOST/v1/orders/{order_id}

Authentication information

For authentication information of private information, please refer to Authentication Instructions

RESPONSE EXAMPLE

{
  "filled_size": "0.0000000000000000000",
  "filled_fees": "1.00",
  "filled_amount": "0.000000000000000000",
  "filled_average_price": "0",
  "created_at": "2021-12-14T03:19:15Z",
  "updated_at": "2022-01-04T06:57:34Z",
  "price": "2.00",
  "size": "3.3000000000000000000",
  "product": "BTC_USDT",
  "order_id": "127738628653088481",
  "funds": "0.0000000000000000000",
  "type": "limit",
  "side": "buy",
  "status": "7",
  "client_oid": "QZ_2020-jj"
}

status: transaction status, value range 0-7

• 0: order has been received
• 1: The order has been submitted
• 2: The order is partially executed
• 3: The order has been completely filled
• 4: The order is canceled
• 5: The order has been canceled
• 6: Order transaction failed
• 7: The order is reduced

GET Query a single order by user-defined order number

When the custom order corresponds to multiple system orders, only the latest system order will be returned.

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

GET HOST/v1/orders/single/{client_oid}

Authentication information

For authentication information of private information, please refer to Authentication Instructions

client_oid: When the custom order corresponds to multiple system orders, only the latest system order will be returned

RESPONSE EXAMPLE

{
  "filled_size": "0.0000000000000000000",
  "filled_fees": "1.00",
  "filled_amount": "0.000000000000000000",
  "filled_average_price": "0",
  "created_at": "2021-12-14T03:19:15Z",
  "updated_at": "2022-01-04T06:57:34Z",
  "price": "2.00",
  "size": "3.3000000000000000000",
  "product": "BTC_USDT",
  "order_id": "127738628653088481",
  "funds": "0.0000000000000000000",
  "type": "limit",
  "side": "buy",
  "status": "7",
  "client_oid": "QZ_2020-jj"
}

status: transaction status, value range 0-7

• 0: order has been received
• 1: The order has been submitted
• 2: The order is partially executed
• 3: The order has been completely filled
• 4: The order is canceled
• 5: The order has been canceled
• 6: Order transaction failed
• 7: The order is reduced

GET Get Transaction Details

Qualified transaction details can be obtained according to different query conditions

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

GET HOST/v1/fills

Authentication information

For authentication information of private information, please refer to Authentication Instructions

• If order_id exists, the transaction details of the order will be searched first, and other parameters will be ignored.
• If order_id does not exist, all transaction details of the store will be queried in pagination according to the parameter combination. Among them, the maximum value of limit is 1000, and the order details of more than 1000 items will not be queried
• If order_id exists, the query condition ignores client_oid
• When client_oid corresponds to multiple system orders, only the details of the latest system order will be returned

RESPONSE EXAMPLE

[
  {
    "product": "BTC_USDT",
    "order_id": "12808732377541664481",
    "liquidity": "maker",
    "price": "19.5600000000000000000",
    "size": "0.937686000000000000",
    "fee": "0",
    "created_at": "2022-01-04T10:17:03Z",
    "updated_at": "2022-01-04T10:17:03Z",
    "side": "sell"
  }
]

GET Get current unfinished orders

Get orders that have not been executed

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

GET HOST/v1/orders

Authentication information

For authentication information of private information, please refer to Authentication Instructions

This interface can query the details of a single order, or multiple orders based on the product

• If order_id exists, the order details will be searched first, other parameters will be ignored.
• If order_id does not exist, all order details will be queried in pagination according to the parameter combination. Among them, the maximum value of limit is 1000, and the order details of more than 1000 items will not be queried
• If order_id exists, the query condition ignores client_oid

RESPONSE EXAMPLE

[
  {
    "price": "19.5600000000000000000",
    "size": "35.447206000000000000",
    "product": "BTC_USDT",
    "order_id": "128087977541664481",
    "funds": "592.668000000000000000",
    "type": "limit",
    "side": "sell",
    "status": "2"
  }
]

status: transaction status, value range 0-7

• 0: order has been received
• 1: The order has been submitted
• 2: The order is partially executed
• 3: The order has been completely filled
• 4: The order is canceled
• 5: The order has been canceled
• 6: Order transaction failed
• 7: The order is reduced

DELETE Cancel a single order according to the system order number

Cancel the specified outstanding order

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

DELETE HOST/v1/orders/{order_id}

Authentication information

For authentication information of private information, please refer to Authentication Instructions

RESPONSE EXAMPLE

"1277087538632480481"

DELETE Cancel a single order according to the user-defined order number

A single order can be canceled. If the custom order corresponds to multiple system orders, cancel the latest order. If the cancellation application is successful, the corresponding system order number will be returned.

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

DELETE HOST/v1/orders/single/{client_oid}

Authentication information

For authentication information of private information, please refer to Authentication Instructions

RESPONSE EXAMPLE

"1277087538632480481"

A list of IDs of orders that are about to be canceled

DELETE Cancel all orders by item

This method is an asynchronous method. When the user receives the interface return, it does not mean that all orders have been canceled successfully. After BGE receives the request, it will query all unfilled orders corresponding to the commodity ID under the user account, and cancel these orders asynchronously. Users can query the transaction status of a single order through /orders/{order_id}.

Speed limit: 10 times/s

Speed limit rules: ApiKey

HTTP request

DELETE HOST/v1/orders

product: the product ID to be revoked, such as "BTC_USD"

A list of IDs of orders that are about to be canceled

WEBSOCKET

Welcome to the BGE digital currency exchange WebSocket subscription message protocol. The protocol allows you to subscribe to and receive market data, trading information and other relevant information in real time through a WebSocket connection.

Hope this document can help you quickly understand our digital currency exchange WebSocket subscription message protocol. If you have any questions or need further assistance, please do not hesitate to contact our technical support team. I wish you a happy use!

WEBSOCKET basic instructions

WebSocket is a network protocol for full-duplex communication over a single TCP connection, which provides a means of real-time data transfer between a client and a server. By using WebSocket, you can subscribe and receive real-time market data and other information from digital currency exchanges in real time.

Connection instructions

Before subscribing to messages, you need to establish a WebSocket connection. Connection instructions are as follows:

When subscribing to a public channel, use the address of the public service; when subscribing to a private channel, use the address of the private service

• Public channel: The public channel is a channel broadcast to all clients connected to the exchange, including market conditions, transaction depth and other information. For the access method, please refer to: WEBSOCKET PUBLIC V2
• Private channel: A private channel refers to a channel that only pushes personal-related information to specific clients, such as order notifications, account balances, etc. For the access method, please refer to: WEBSOCKET PRIVATE V2

Please select the corresponding service address to connect to public or private channels according to your needs.

Subscription Limits

Each connection can send up to 50 messages in 1s, otherwise the connection will be closed forcibly

In order to maintain the stability and fairness of the connection, we have set a limit on sending messages, and each connection can send up to 50 messages per second. If you send more than 50 messages within 1 second, the connection will be forcibly closed, please be aware of this limit.

keep the connection

We will send ping messages regularly, expecting you to return pong messages as a response, if you do not receive your response for more than 30s, the server will close the connection

At the same time, you need to pay attention to the following situations:

Network problems: If there are network problems, the system will automatically disconnect.

Connection timeout: If the user does not subscribe within 30 seconds after the connection is successful or the server does not push data to the user within 30 seconds after the subscription, the system will automatically disconnect.

In order to ensure the liveness of the connection, we will regularly send ping messages in JSON format to the client: {"ping": timestamp}. You need to send a {"pong": timestamp} text message promptly after receiving the ping message to indicate that the connection is alive. If we do not receive a response from you within 30 seconds, we will close the connection and recommend the following:

1. Reply a {"pong": timestamp} immediately after receiving a {"ping": timestamp} message.

2. Expect a literal string {"ping": timestamp} as heartbeat message. If not received within N seconds, issue an error or reconnect.

3. The timestamp in the pong message you reply should use the timestamp in the received ping message.

ping message example

{
    "ping": 1635065532000
}

pong message example

{
    "pong": 1635065532000
}

request error

Regardless of the private channel or public channel, when the server fails to process the request you send, the server will return a unified error message, which is convenient for the client to process.

Error messages mainly consist of two parts: error code and message. Codes are generic, but messages may vary.

For error codes and messages, please refer to: Status Code Comparison Table, Other Error Status Code Comparison Table

Error Message Response Parameter Description

Description of common error codes

1. Error code 400: Usually you need to check whether the request parameters you provide are correct, or whether there are required parameters that are not filled.

2. Error code 401: Usually you need to ensure that you have received a successful login response, and this error will occur when you subscribe to a private channel without logging in.

3. Error code 500: It is usually an internal server error. It is recommended that you try again later.

Bad request example 1 The request structure used in this example is wrong, please replace it with your actual request parameters.

{
    "event": "sub",
    "para": {
        "biz": "market",
        "type": "percent10",
        "product": "ETH_USDT"
    },
    "zip": true
}

Bad request response example 1

{
    "event": "sub",
    "code": "400",
    "msg": "Invalid request: {\"event\":\"sub\",\"para\":{\"biz\":\"market\",\"type\":\"percent10\ ",\"pairCode\":\"ETH_USDT\"},\"zip\":true}"
}

Bad request example 2 The access_key value used in this example is empty, please ensure that the required parameters are filled.

{
  "event": "login",
  "params": {
    "type": "api",
    "access_key": "",
    "access_sign": "sign",
    "access_timestamp": 14000000000
  }
}

Bad request response example 2

{
  "event": "login",
  "code": 40001,
  "msg": "ACCESS_KEY cannot be empty"
}

WEBSOCKET public channel V2

• Public channel V2 address

sequence number seq_id description

1. seq_id is a serial number of the exchange market. When a user uses one or more WebSockets to connect to the same channel, in addition to the real-time transaction data, he will receive data pushes with the same serial number, and the user needs to handle the duplication by himself. data, a seq_id can be used to build a sequence of messages, which will allow the user to detect packet loss and ordering of messages.

2. seq_id is a monotonically increasing number with a minimum value of 0.

K-line channel

Subscribe or request to get K-line (the latest K-line) data push

K-line chart interval parameters:

min -> minute; hour -> hour; day -> day; week -> week; mon -> month

• 1min
• 5min
• 15min
• 30min
• 60min
• 4 hours
• 1 day
• 1week
• 1mon

Field Description:

• id message unique id
• open the first transaction price during this K-line period
• close the last transaction price during this K-line period
• low the lowest transaction price during this K-line period
• high is the highest transaction price during this K-line period
• filled_size the transaction volume during this K-line
• vol is the trading volume during this K-line
• seq_id unique and ordered id
• count is the number of transactions during this K-line period
• interval K-line interval
• product trading pair

subscription

request example

{
    "event": "sub",
    "biz": "market",
    "type": "candles",
    "product": "BTC_USDT",
    "interval": "15min",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "candles",
    "ts": 1666851880448,
    "code": 200,
    "status": "OK",
    "event": "sub",
    "product": "BTC_USDT",
    "interval": "15min"
}

unsubscribe

request example

{
    "event": "unsub",
    "biz": "market",
    "type": "candles",
    "product": "BTC_USDT",
    "interval": "15min",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "candles",
    "ts": 1666851880448,
    "code": 200,
    "status": "OK",
    "event": "unsub",
    "product": "BTC_USDT",
    "interval": "15min"
}

Push data

Push data example

{
    "id": "1689144300",
    "biz": "market",
    "type": "candles",
    "data":
    {
        "id": 1689144300,
        "open": "3.7366",
        "close": "3.7366",
        "high": "3.7366",
        "low": "3.7366",
        "filled_size": "0",
        "vol": "0",
        "count": 0,
        "seq_id": 112588635
    },
    "product": "BTC_USDT",
    "interval": "15min"
}

request data

Parameter Description:

• id the unique id of each candlestick message
• ix timestamp of from start time
• ix timestamp of to end time
• interval K-line interval
• product trading pair

Get the K-line data request example of the specified range

{
    "event": "req",
    "biz": "market",
    "type": "candles",
    "product": "BTC_USDT",
    "interval": "15min",
    "zip": false,
    "from": 1687561511,
    "to": 1688641511
}

Get the K-line data response example in the specified range

{
    "biz": "market",
    "type": "candles",
    "product": "BTC_USDT",
    "ts": 1690252632272,
    "code": 200,
    "status": "OK",
    "data":
    [
        {
            "id": 1688398200,
            "open": "3.3706",
            "close": "3.3706",
            "high": "3.3706",
            "low": "3.3706",
            "filled_size": "0",
            "vol": "0",
            "count": 0
        },
        {
            "id": 1688399100,
            "open": "3.3706",
            "close": "3.3706",
            "high": "3.3706",
            "low": "3.3706",
            "filled_size": "0",
            "vol": "0",
            "count": 0
        }
    ],
    "event": "req",
    "interval": "15min"
}

Close channel

Subscribe to obtain real-time transaction incremental push data of products

Get the latest transaction data, and push the transaction data when there is transaction data. Each push may contain multiple transaction data.

Field Description:

• id message unique id
• ts transaction timestamp
• direction transaction direction
• price transaction price
• vol volume

subscription

request example

{
    "event": "sub",
    "biz": "market",
    "type": "fills",
    "product": "BTC_USDT",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "fills",
    "product": "BTC_USDT",
    "ts": 1690165577416,
    "code": 200,
    "status": "OK",
    "event": "sub"
}

unsubscribe

request example

{
    "event": "unsub",
    "biz": "market",
    "type": "fills",
    "product": "BTC_USDT",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "fills",
    "ts": 1666851880448,
    "code": 200,
    "status": "OK",
    "event": "unsub",
    "product": "BTC_USDT"
}

Push data

Push data example

{
    "id": "310529",
    "biz": "market",
    "type": "fills",
    "data":
    [
        {
            "vol": "0.79",
            "ts": 1689152279117,
            "price": "3.4134",
            "direction": "buy",
            "id": 310529000
        }
    ],
    "product": "BTC_USDT"
}

Deep Channel

Subscribe to obtain product order book incremental push data

Push once every 500 milliseconds at the fastest, and also push when no event is triggered, bids and asks may be empty arrays if there is no data in the handicap

OrderBook subscription interval parameters: [The current gear supports the maximum precision, the current gear supports the maximum depth]:

• 0 : [0.0000000000000000001, 150]
• 1 : [0.00001, 150]
• 2 : [0.0001, 150]
• 3 : [0.001, 150]
• 4 : [0.01, 150]
• 5 : [0.1, 150]
• 6 : [0.0000000000000000001, 20]
• 7 : [0.00001, 20]
• 8 : [0.0001, 20]
• 9 : [0.001, 20]
• 10 : [0.01, 20]
• 11 : [0.1, 20]

Explanation: interval=5, the buyer's price in bids pushed can only be accurate to one decimal place, and the maximum array size of bids is 150

Field Description:

• id message unique id
• biz line of business
• type type
• data.seq_id is ignored
• data.bids buyers
• data.bids[][0] bid price
• data.bids[][1] number of buyers
• data.asks seller
• data.asks[][0] ask price
• data.asks[][1] number of sellers
• data.product trading pair
• data.interval slots

subscription

request example

{
    "event": "sub",
    "biz": "market",
    "type": "orderbook",
    "product": "BTC_USDT",
    "interval": "0",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "orderbook",
    "ts": 1666851880448,
    "code": 200,
    "status": "OK",
    "event": "sub",
    "product": "BTC_USDT",
    "interval": 0
}

unsubscribe

request example

{
    "event": "unsub",
    "biz": "market",
    "type": "orderbook",
    "product": "BTC_USDT",
    "interval": "0",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "orderbook",
    "ts": 1666851880448,
    "code": 200,
    "status": "OK",
    "event": "unsub",
    "product": "BTC_USDT",
    "interval": 0
}

Push data

Push data example

{
    "id": "1689143926",
    "biz": "market",
    "type": "orderbook",
    "data":
    {
        "seq_id": 112588640, //ordered and unique id
        "bids": //buyer
        [
            [
                "3.7366", //price
                "0.66" //quantity
            ],
            [
                "3.6866",
                "0.98"
            ],
            [
                "3.4666",
                "0.33"
            ],
            [
                "3.3766",
                "0.76"
            ],
            [
                "3.3666",
                "0.7"
            ],
            [
                "3.1966",
                "0.75"
            ],
            [
                "3.1766",
                "0.06"
            ],
            [
                "3.0666",
                "0.91"
            ],
            [
                "3.0266",
                "0.73"
            ]
        ],
        "asks": //Seller
        [
            [
                "3.9966", //price
                "0.9" //quantity
            ]
        ]
    },
    "product": "BTC_USDT",//trading pair
    "interval": "0"
}

Deep depth channel

Subscribe to obtain product depth map incremental push data

Explanation: Each buy and sell order takes up to 200 orders within 10% of the average price, sell 1 order within 10% of the upward price fluctuation, and buy 1 order within 10% downward fluctuation

Push once every 500 milliseconds at the fastest, and also push when no event is triggered, bids and asks may be empty arrays if there is no data in the handicap

Field Description:

• id message unique id
• biz line of business
• seq_id is ignored
• type type
• data.bids buyer depth
• data.bids[][0] Bid depth price
• data.bids[][1] the number of bids in depth
• data.asks depth of asks
• data.asks[][0] deep ask price
• data.asks[][1] depth number of asks
• data.seq_id ordered and unique id
• data.product trading pair

subscription

request example

{
    "event": "sub",
    "biz": "market",
    "type": "percent10",
    "product": "BTC_USDT",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "percent10",
    "ts": 1666851880448,
    "code": 200,
    "status": "OK",
    "event": "sub",
    "product": "BTC_USDT"
}

unsubscribe

request example

{
    "event": "unsub",
    "biz": "market",
    "type": "percent10",
    "product": "BTC_USDT",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "percent10",
    "product": "BTC_USDT",
    "ts": 1690193555943,
    "code": 200,
    "status": "OK",
    "event": "unsub"
}

Push data

Push data example

{
    "id": "1689143539", //The unique id of the message
    "biz": "market",
    "seq_id": 112588640, //ordered and unique id
    "type": "percent10", //business type
    "data":
    {
        "bids": //buyer
        [
            [
                "3.8646667", //price
                "0" //quantity
            ]
        ],
        "asks": //Seller
        [
            [
                "3.8685333", //price
                "0" //quantity
            ],
            [
                "3.8704666",
                "0"
            ]
        ],
        "seq_id": 112588640
    },
    "product": "BTC_USDT"
}

Quote channel

Obtain product 24-hour ticker incremental push data

Field Description:

• id message unique id
• open started the first transaction price 24 hours ago
• close 24 hours latest transaction price
• low The lowest transaction price within 24 hours
• high The highest transaction price within 24 hours
• filled_size turnover within 24 hours
• vol volume in 24 hours
• seq_id unique and ordered id
• count 24-hour transaction count
• change 24 hour price change
• change_percent 24h price change (percentage)

subscription

request example

{
    "event": "sub",
    "biz": "market",
    "type": "ticker",
    "product": "BTC_USDT",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "ticker",
    "ts": 1666851880448,
    "code": 200,
    "status": "OK",
    "event": "sub",
    "product": "BTC_USDT"
}

unsubscribe

request example

{
    "event": "unsub",
    "biz": "market",
    "type": "ticker",
    "product": "BTC_USDT",
    "zip": false
}

Response example

{
    "biz": "market",
    "type": "ticker",
    "ts": 1689946788754,
    "code": 200,
    "status": "OK",
    "event": "unsub",
    "product": "BTC_USDT"
}

Push data

Push data example

{
    "id": "1689144487",
    "biz": "market",
    "type": "ticker",
    "product": "BTC_USDT",
    "data":
    [
        {
            "id": 1689144487,
            "seq_id": 112588640,
            "open": "3.7366",
            "close": "3.7366",
            "high": "3.7366",
            "low": "3.7366",
            "filled_size": "0",
            "vol": "0",
            "count": 0,
            "change": "0",
            "change_percent": "0"
        }
    ]
}

Request the latest market data for the specified trading pair

Get the latest market data request example for a specified trading pair

{
    "event": "req",
    "biz": "market",
    "type": "ticker",
    "product": "BTC_USDT",
    "zip": false
}

Example of getting the latest market data response for a specified trading pair

{
    "biz": "market",
    "type": "ticker",
    "ts": 1689133337870,
    "code": 200,
    "status": "OK",
    "data":
    {
        "id": 1689133336,
        "seq_id": 112588640,
        "open": "3.7366",
        "close": "3.7366",
        "high": "3.7366",
        "low": "3.7366",
        "filled_size": "0",
        "vol": "0",
        "count": 0,
        "change": "0",
        "change_percent": "0"
    },
    "event": "req",
    "product": "BTC_USDT"
}

Public channel Request field description

Response field description of public channel

List of public channel events

Public Channel Biz List

List of Public Channel Types

WEBSOCKET private channel V2

• Private channel V2 address

Private channel login authentication

Login authentication is required before subscribing to a private channel. Only authenticated users can subscribe to the user's asset information and order status change information.

Note: If no login authentication operation is performed, subscribing to a private channel will return an error message

Login request example

{
  "event": "login",
  "params": {
    "type": "api",
    "access_key": "de0535f81d51c998b7fbcf00f189f294",
    "access_sign": "sign",
    "access_timestamp": 14000000000
  }
}

Login success response example status code comparison table

{
  "ts": 1690364037503,
  "code": 200,
  "status": "OK",
  "event": "login"
}

Login failure response example Please refer to the general error description

Login request parameter description

Login response parameter description

Private channel assets

Subscriber's asset changes will be pushed only when there is data update. Currently only supports subscription by product.

Please refer to Common Request Parameter Description and General Response Parameter Description for request and response parameter description

Subscribe to asset data

Subscription request example

{
  "event": "sub",
  "biz": "exchange",
  "type": "assets",
  "product": "ETH_USDT",
  "zip": false
}

Subscription success response example

{
  "biz": "exchange",
  "type": "assets",
  "product": "ETH_USDT",
  "ts": 1690357632710,
  "code": 200,
  "status": "OK",
  "event": "sub"
}

Asset push data example, this example is just to illustrate the data structure, the actual push data may only contain asset information of one currency

{
  "biz": "exchange",
  "type": "assets",
  "product": "ETH_USDT",
  "data":
  [
    {
      "currency": "USDT",
      "available": "999970.5238",
      "hold": "29.4762"
    },
    {
      "currency": "ETH",
      "available": "999970.5238",
      "hold": "29.4762"
    }
  ]
}

Request the user's asset data for a single trading pair

Request a single trading pair asset data example

{
  "event": "req",
  "biz": "exchange",
  "type": "assets",
  "product": "BTC_USDT",
  "zip": false
}

Request a single transaction pair asset data response example

{
  "biz": "exchange",
  "type": "assets",
  "product": "BTC_USDT",
  "ts": 1690357632710,
  "code": 200,
  "status": "OK",
  "event": "req",
  "data":
  [
    {
      "currency": "USDT",
      "available": "999970.5238",
      "hold": "29.4762"
    },
    {
      "currency": "BTC",
      "available": "999970.5238",
      "hold": "29.4762"
    }
  ]
}

Private Channel Orders

The status change of the subscription user's order will be pushed only when there is data update. Currently supports order status change subscription for all trading pairs. Supports asynchronous query of the user's current entrusted order data for a single trading pair.

Please refer to Common Request Parameter Description and General Response Parameter Description for request and response parameter description

Note: The order data supports subscribing to the full amount of trading pairs. When subscribing to orders of all trading pairs at once, please note that the product parameter uses all (ignoring case)

Subscription order transaction pair order data

Subscribe to order data for all trading pairs

Subscription order trading pair order request example

{
  "event": "sub",
  "biz": "exchange",
  "type": "orders",
  "product": "ETH_USDT",
  "zip": false
}

Subscribe to all trading pairs order request example

{
  "event": "sub",
  "biz": "exchange",
  "type": "orders",
  "product": "all",
  "zip": false
}

Subscription order transaction pair order response success example

{
  "biz": "exchange",
  "type": "orders",
  "product": "ETH_USDT",
  "ts": 1690363716709,
  "code": 200,
  "status": "OK",
  "event": "sub"
}

Subscribe to all transaction pairs order response success example

{
  "biz": "exchange",
  "type": "orders",
  "product": "all",
  "ts": 1690363716709,
  "code": 200,
  "status": "OK",
  "event": "sub"
}

Subscribe to all trading pairs order data failure response example error code comparison table

{
  "biz": "exchange",
  "type": "orders",
  "product": "all",
  "ts": 1690362052646,
  "code": 500,
  "status": "FAIL",
  "event": "sub"
}

Subscription order trading pair push order data example

{
  "biz": "exchange",
  "type": "orders",
  "product": "BTC_USDT",
  "data": [
    {
      "orders_id": "179577241915696235",
      "product": "BTC_USDT",
      "side": "buy",
      "price": "3.53340000",
      "size": "1.00000000",
      "filled_amount": "0.00000000",
      "funds": "1.00000000",
      "filled_size": "0.00000000",
      "type": "limit",
      "status": "1",
      "client_oid": ""
    }
  ]
}

Subscribe to all trading pairs to push orders and send data examples

{
  "biz": "exchange",
  "type": "orders",//Note that this is different from a single trading pair
  "product": "all",//Note that this is different from a single trading pair
  "data":
  [
    //....Structure reference single transaction pair push order data example
  ]
}

*Request a single transaction pair for the current entrusted order data, if the request fails, a failed response will be returned. *

Request the user's single transaction pair current entrusted order data example

{
  "event": "req",
  "biz": "exchange",
  "type": "orders",
  "product": "BTC_USDT",
  "zip": false
}

An example of a successful response to requesting a single transaction from the user for the current entrusted order data

{
  "biz": "exchange",
  "type": "orders",
  "product": "BTC_USDT",
  "ts": 1690375715106,
  "code": 200,
  "status": "OK",
  "data":
  [
    //....Structure reference single transaction pair push order data example
  ],
  "event": "req"
}

status: transaction status, value range 0-7

• 0: order has been received
• 1: The order has been submitted
• 2: The order is partially executed
• 3: The order has been completely filled
• 4: The order is canceled
• 5: The order has been canceled
• 6: Order transaction failed
• 7: The order is reduced

Private channel general request parameter description

Private channel general response parameter description

Private channel event list

Private Channel Biz List

Private Channel Type List

Authentication information

Each user can create up to 50 APIKeys;

Do not disclose your APIKey to anyone else to avoid loss of assets. It is recommended to bind the APIKey to an IP address for better security of your account. Multiple IP addresses are separated in English, and a maximum of 10 IP addresses are supported. API not bound to an IP address is only valid for 180 days;

Please note that binding an APIKey to a third-party platform may pose security risks that you should act with caution;

To access the private information interface, the following request headers will have to be added

ACCESS-SING generation algorithm

requestPath: Consistent with the path in the documentation, e.g. /v1/products

queryString: List of request parameters. Note: Parameters needs to be orderly arranged. See remarks

params: When the request is GET or DELETE or WEBSOCKET channel for authentication, fill in ""

Sign http request

  String timestamp=OpenAPiUtils.createTimestamp();
  String sign=OpenAPiUtils.createSign(OpenAPiUtils.POST,
  "43767b4dec6e78e07c81f89af47018dc3ab57585721bf57a389f7637a9d0506b",
  "/v1/accounts",
  "",
  s,timestamp);

Sign web socket request

  String timestamp=OpenAPiUtils.createTimestamp();
  String sign=OpenAPiUtils.createSign("","43767b4dec6e78e07c81f89af47018dc3ab57585721bf57a389f7637a9d0506b","","","",timestamp);

Generation algorithm tool class

import org.apache.commons.codec.binary.Base64;
import org.apache.commons.codec.digest.HmacUtils;

public class OpenAPiUtils {
  public static final String GET = "GET";
  public static final String POST = "POST";
  public static final String DELETE = "DELETE";
  public static final Gson gson = new Gson();

  public static String createTimestamp() {
    return Instant.now().toString();
  }

  /**
   * 获取当前时间戳 例：2022-01-08T07:19:56.339Z
   * @return
   */
  public static String createTimestamp() {
    return Instant.now().toString();
  }

  /**
   * sign
   * @param method POST or GET or DELETE
   * @param secretKey for example：HKBGE-xxxxx
   * @param requestPath for example：/v1/orders
   * @param queryString Request parameters
   * @param body string empty when method is `GET`
   * @param timestamp  for example：2022-01-08T07:19:56.339Z
   * @return string
   */
  public static String createSign(String method, String secretKey, String requestPath, String queryString, String body, String timestamp) {
    String sign = "";
    method = method.toUpperCase();
    if (timestamp == null) {
      timestamp = Instant.now().toString();
    }
    if (method.equals("POST")) {
      sign = generate(timestamp, method, requestPath, queryString, body, secretKey, "HmacSHA256");
    }
    if (method.equals("GET") || method.equals("DELETE")) {
      sign = generate(timestamp, method, requestPath, queryString, "", secretKey, "HmacSHA256");
    }
    if ("".equalsIgnoreCase(method)) {
      sign = generate(timestamp, method, requestPath, queryString, "", secretKey, "HmacSHA256");
    }
    return sign;
  }

  public static String generate(final String timestamp, String method, final String requestPath,
                                String queryString, String body, final String secret, final String alg) {
    body = StringUtils.defaultIfBlank(body, StringUtils.EMPTY);
    queryString = StringUtils.isEmpty(queryString) ? "" : "?" + queryString;
    final String preHash = timestamp + method + requestPath + queryString + body;
    return encodeBase64(alg, secret, preHash);
  }

  public static String encodeBase64(final String alg, final String secret, final String data) {
    Validate.notNull(alg, "SignatureAlgorithm cannot be null.");
    Validate.notNull(data, "Signing Secret cannot be null.");
    switch (alg) {
      case "HmacMD5":
        return Base64.encodeBase64String(new HmacUtils("HmacMD5", secret).hmac(data));
      case "HmacSHA1":
        return Base64.encodeBase64String(new HmacUtils("HmacSHA1", secret).hmac(data));
      case "HmacSHA224":
        return Base64.encodeBase64String(new HmacUtils("HmacSHA224", secret).hmac(data));
      case "HmacSHA256":
        try {
          return Base64.encodeBase64String(new HmacUtils("HmacSHA256",
            secret.getBytes("UTF-8")).hmac(data.getBytes("UTF-8")));
        } catch (UnsupportedEncodingException e) {
          throw new RuntimeException(e.getMessage());
        }
      case "HmacSHA384":
        return Base64.encodeBase64String(new HmacUtils("HmacSHA384", secret).hmac(data));
      case "HmacSHA512":
        return Base64.encodeBase64String(new HmacUtils("HmacSHA512", secret).hmac(data));
      default:
        throw new IllegalArgumentException("The '" + alg.name() + "' algorithm cannot be used for signing.");
    }
  }

}